feat: starknet core package

.changeset/few-crabs-occur.md

@@ -0,0 +1,7 @@
+---
+'@hyperlane-xyz/utils': minor
+'@hyperlane-xyz/sdk': minor
+'@hyperlane-xyz/widgets': patch
+---
+
+Added Starknet protocol support

.changeset/five-rice-sit.md

@@ -0,0 +1,5 @@
+---
+'@hyperlane-xyz/cli': minor
+---
+
+Add Starknet protocol support to the chain configuration

.changeset/nervous-ads-draw.md

@@ -0,0 +1,5 @@
+---
+'@hyperlane-xyz/starknet-core': minor
+---
+
+Added new Starknet workspace to the monorepo. This package provides core Cairo contract bindings and utilities for Hyperlane's Starknet integration

package.json

@@ -39,7 +39,8 @@
   },
   "workspaces": [
     "solidity",
-    "typescript/*"
+    "typescript/*",
+    "starknet"
   ],
   "resolutions": {
     "async": "^2.6.4",

starknet/.eslintrc

@@ -0,0 +1,6 @@
+{
+  "rules": {
+    "no-console": ["off"],
+    "no-restricted-imports": ["off"]
+  }
+}

starknet/.gitignore

@@ -0,0 +1,3 @@
+.env
+dist
+release

starknet/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@hyperlane-xyz/starknet-core",
+  "description": "Core cairo contracts for Hyperlane",
+  "version": "0.2.2",
+  "type": "module",
+  "homepage": "https://www.hyperlane.xyz",
+  "license": "Apache-2.0",
+  "scripts": {
+    "prepare-contracts": "tsx ./scripts/fetch-contracts-if-missing.ts",
+    "build-contracts": "mkdir -p dist/target && cp release/* dist/target/",
+    "build": "tsc && yarn prepare-contracts && yarn build-contracts",
+    "clean": "rm -rf ./dist ./release",
+    "lint": "eslint src --ext .ts",
+    "prettier": "prettier --write ./src ./scripts ./package.json"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "keywords": [
+    "Hyperlane",
+    "Cairo",
+    "Starknet"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "dependencies": {
+    "starknet": "6.11.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.15.0",
+    "eslint-config-prettier": "^9.1.0",
+    "prettier": "^2.8.8",
+    "tsx": "^4.7.1",
+    "typescript": "5.3.3"
+  }
+}

starknet/scripts/fetch-contracts-if-missing.ts

@@ -0,0 +1,23 @@
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+const RELEASE_DIR = join(process.cwd(), 'release');
+
+try {
+  if (existsSync(RELEASE_DIR)) {
+    console.log(
+      '[INFO] Contracts already present in src/release, skipping fetch',
+    );
+    process.exit(0);
+  }
+
+  console.log('[INFO] Fetching contracts...');
+  execSync('./scripts/fetch-contracts-release.sh', {
+    stdio: 'inherit',
+    cwd: join(process.cwd()),
+  });
+} catch (error) {
+  console.error('[ERROR]', (error as Error).message);
+  process.exit(1);
+}

starknet/scripts/fetch-contracts-release.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+
+# Strict mode configuration
+set -euo pipefail
+IFS=$'\n\t'
+
+# Constants
+readonly REPO="astraly-labs/hyperlane_starknet"
+readonly GITHUB_RELEASES_API="https://api.github.com/repos/${REPO}/releases"
+readonly TARGET_DIR="./release"
+
+# Color definitions
+declare -r COLOR_GREEN='\033[0;32m'
+declare -r COLOR_RED='\033[0;31m'
+declare -r COLOR_RESET='\033[0m'
+
+log_error() {
+    echo -e "${COLOR_RED}Error: $1${COLOR_RESET}" >&2
+}
+
+log_success() {
+    echo -e "${COLOR_GREEN}$1${COLOR_RESET}"
+}
+
+check_dependencies() {
+    local -r required_tools=("curl" "jq" "unzip")
+
+    for tool in "${required_tools[@]}"; do
+        if ! command -v "$tool" &> /dev/null; then
+            log_error "$tool is not installed"
+            exit 1
+        fi
+    done
+}
+
+get_package_version() {
+    local package_version
+    if ! package_version=$(jq -r '.version' ./package.json 2>/dev/null); then
+        log_error "Failed to read version from package.json"
+        exit 1
+    fi
+    echo "v${package_version}"
+}
+
+verify_version_exists() {
+    local version=$1
+    if ! curl --output /dev/null --silent --head --fail "${GITHUB_RELEASES_API}/tags/${version}"; then
+        log_error "Version ${version} does not exist"
+        exit 1
+    fi
+}
+
+get_release_info() {
+    local version=$1
+    local release_info
+
+    release_info=$(curl -sf "${GITHUB_RELEASES_API}/tags/${version}") || {
+        log_error "Failed to fetch release information for version ${version}"
+        exit 1
+    }
+    echo "$release_info"
+}
+
+download_and_extract() {
+    local version=$1
+    local download_url=$2
+    local base_url="${download_url%/*}"
+    local filename="${download_url##*/}"
+
+    if ! mkdir -p "$TARGET_DIR"; then
+        log_error "Failed to create target directory"
+        exit 1
+    fi
+
+    log_success "Downloading version ${version}..."
+
+    if ! curl -L "$download_url" -o "${TARGET_DIR}/release.zip"; then
+        log_error "Download failed"
+        exit 1
+    fi
+
+    if ! verify_checksum "${TARGET_DIR}/release.zip" "$base_url" "$filename"; then
+        rm -f "${TARGET_DIR}/release.zip"
+        exit 1
+    fi
+
+    if ! unzip -o "${TARGET_DIR}/release.zip" -d "${TARGET_DIR}"; then
+        log_error "Extraction failed"
+        exit 1
+    fi
+}
+
+verify_checksum() {
+    local file_path="$1"
+    local base_url="$2"
+    local filename="$3"
+    local checksum_filename
+    checksum_filename="${filename%.zip}.CHECKSUM"
+
+    local downloaded_checksum
+    downloaded_checksum="$(sha256sum "$file_path" | cut -d' ' -f1)"
+    log_success "File checksum: ${downloaded_checksum}"
+
+    local expected_checksum
+    if ! expected_checksum="$(curl -sL "${base_url}/${checksum_filename}")"; then
+        log_error "Failed to fetch checksum file"
+        return 1
+    fi
+
+    if [[ "${downloaded_checksum}" != "$(echo "${expected_checksum}" | awk '{print $1}')" ]]; then
+        log_error "Checksum verification failed"
+        return 1
+    fi
+
+    return 0
+}
+
+cleanup() {
+    rm -f "$TARGET_DIR/release.zip"
+    rm -f "$TARGET_DIR"/*.md5
+    rm -f "$TARGET_DIR"/*.sha256
+}
+
+main() {
+    trap cleanup EXIT
+
+    check_dependencies
+
+    local version
+    version=$(get_package_version)
+    log_success "Using version ${version} from package.json"
+    verify_version_exists "$version"
+
+    local release_info
+    release_info=$(get_release_info "$version")
+
+    local download_url
+    download_url=$(echo "$release_info" | jq -r '.assets[] | select(.name | startswith("hyperlane-starknet") and endswith(".zip")) | .browser_download_url')
+
+    if [[ -z "$download_url" ]]; then
+        log_error "Could not find ZIP download URL for release"
+        exit 1
+    fi
+
+    # Process download and file checksum verification and extraction
+    download_and_extract "$version" "$download_url"
+
+    log_success "Successfully downloaded and extracted version ${version}"
+}
+
+main

starknet/src/config.ts

@@ -0,0 +1,11 @@
+export const CONFIG = {
+  COMPILED_CONTRACTS_DIR: 'target',
+  CONTRACT_FILE_SUFFIXES: {
+    SIERRA_JSON: '.contract_class.json', // Sierra is the high-level representation
+    ASSEMBLY_JSON: '.compiled_contract_class.json', // Cairo assembly (CASM) is the low-level bytecode
+  },
+  CONTRACT_ERROR_CODES: {
+    FILE_NOT_FOUND: 'FILE_NOT_FOUND',
+    PARSE_ERROR: 'PARSE_ERROR',
+  },
+} as const;

starknet/src/errors.ts

@@ -0,0 +1,6 @@
+export class ContractError extends Error {
+  constructor(public readonly code: string, public readonly details?: unknown) {
+    super(`[${code}] ${details ? JSON.stringify(details) : ''}`);
+    this.name = 'ContractError';
+  }
+}

starknet/src/index.ts

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { CairoAssembly, CompiledContract } from 'starknet';
+import { fileURLToPath } from 'url';
+
+import { CONFIG } from './config.js';
+import { ContractError } from './errors.js';
+
+const currentDirectory = dirname(fileURLToPath(import.meta.url));
+const TARGET_DEV_PATH = join(currentDirectory, CONFIG.COMPILED_CONTRACTS_DIR);
+
+/**
+ * @notice Retrieves and parses the standard compiled contract data
+ * @param name The name of the contract to retrieve
+ * @returns {CompiledContract} The parsed contract data
+ * @throws {ContractError} If the file is not found, cannot be parsed
+ */
+export const getCompiledContract = (
+  name: string,
+  contractType?: ContractType,
+): CompiledContract => {
+  try {
+    return JSON.parse(
+      readFileSync(
+        findContractFile(name, 'SIERRA_JSON', contractType),
+        'utf-8',
+      ),
+    );
+  } catch (error: unknown) {
+    if (error instanceof ContractError) throw error;
+    throw new ContractError(CONFIG.CONTRACT_ERROR_CODES.PARSE_ERROR, {
+      name,
+      error: (error as Error).message,
+    });
+  }
+};
+
+/**
+ * @notice Retrieves and parses the CASM compiled contract data
+ * @param name The name of the contract to retrieve
+ * @returns {CairoAssembly} The parsed CASM contract data
+ * @throws {ContractError} If the file is not found, cannot be parsed
+ */
+export const getCompiledContractCasm = (
+  name: string,
+  contractType?: ContractType,
+): CairoAssembly => {
+  try {
+    return JSON.parse(
+      readFileSync(
+        findContractFile(name, 'ASSEMBLY_JSON', contractType),
+        'utf-8',
+      ),
+    );
+  } catch (error: unknown) {
+    if (error instanceof ContractError) throw error;
+    throw new ContractError(CONFIG.CONTRACT_ERROR_CODES.PARSE_ERROR, {
+      name,
+      error: (error as Error).message,
+    });
+  }
+};
+
+/**
+ * @notice Contract file type enum
+ */
+export enum ContractType {
+  CONTRACT = 'contracts_',
+  TOKEN = 'token_',
+  MOCK = 'mock_',
+}
+
+/**
+ * @notice Finds the path to a contract file based on predefined patterns
+ * @param name The base name of the contract to find
+ * @param suffix The type of contract file to look for (from CONFIG.CONTRACT_FILE_SUFFIXES)
+ * @param type Optional contract type prefix (defaults to CONTRACT)
+ * @returns {string} The full path to the contract file
+ * @throws {ContractError} If file is not found or the contract name is invalid
+ */
+function findContractFile(
+  name: string,
+  suffix: keyof typeof CONFIG.CONTRACT_FILE_SUFFIXES,
+  type: ContractType = ContractType.CONTRACT,
+): string {
+  const suffixPath = CONFIG.CONTRACT_FILE_SUFFIXES[suffix];
+  const path = `${TARGET_DEV_PATH}/${type}${name}${suffixPath}`;
+
+  if (!existsSync(path)) {
+    throw new ContractError(CONFIG.CONTRACT_ERROR_CODES.FILE_NOT_FOUND, {
+      name,
+      suffix,
+      path,
+    });
+  }
+
+  return path;
+}

starknet/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "importHelpers": true,
+    "noEmitHelpers": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "ts-node": {
+    "experimentalSpecifierResolution": "node",
+    "experimentalResolver": true,
+    "files": true
+  }
+}