@veridex/sdk 1.0.0-beta.1

package/dist/chains/starknet/index.d.mts

@@ -0,0 +1,172 @@
+import { S as SessionKey } from '../../types-FJL7j6gQ.mjs';
+import { C as ChainClient, a as ChainConfig, T as TransferParams, E as ExecuteParams, B as BridgeParams, W as WebAuthnSignature, D as DispatchResult, V as VaultCreationResult, R as RegisterSessionParams, b as RevokeSessionParams, S as SessionValidationResult } from '../../types-ChIsqCiw.mjs';
+import { RpcProvider } from 'starknet';
+
+/**
+ * Veridex Protocol SDK - Starknet Chain Client
+ *
+ * Production-grade implementation of ChainClient interface for Starknet.
+ * Supports custom bridge attestation, gasless execution via Hub dispatch.
+ *
+ * Security:
+ * - Native starknet::eth_signature::verify_eth_signature for validation
+ * - Custom bridge with multi-relayer threshold attestations
+ * - Replay protection via nonce verification on Hub
+ * - Bridge validates source_chain == hub_chain_id (10004 = Base Sepolia)
+ *
+ * Architecture:
+ * - Starknet actions MUST be dispatched via Hub (Base Sepolia)
+ * - Hub publishes Wormhole message → relayer monitors → relayer submits attestation
+ * - Bridge accumulates attestations → threshold reached → spoke executes
+ * - Spoke validates source_chain == hubChainId (NOT targetChain)
+ *
+ * Custom Bridge:
+ * - Bridge address: 0x2c458c1ae64556482b05cc2d3ee5b032ed114d68429dda2062c9849a5a725f8
+ * - Chain ID: 50001 (custom range 50000+, reserved for non-Wormhole chains)
+ * - Hub Chain ID: 10004 (Base Sepolia - what bridge validates as source)
+ */
+
+interface StarknetClientConfig {
+    wormholeChainId: number;
+    rpcUrl: string;
+    spokeContractAddress?: string;
+    bridgeContractAddress?: string;
+    network?: 'mainnet' | 'sepolia' | 'testnet';
+    hubRpcUrl?: string;
+    hubContractAddress?: string;
+}
+declare class StarknetClient implements ChainClient {
+    private config;
+    private provider;
+    private hubRpcUrl?;
+    private hubContractAddress?;
+    constructor(config: StarknetClientConfig);
+    getConfig(): ChainConfig;
+    getNonce(_userKeyHash: string): Promise<bigint>;
+    getMessageFee(): Promise<bigint>;
+    buildTransferPayload(params: TransferParams): Promise<string>;
+    buildExecutePayload(params: ExecuteParams): Promise<string>;
+    buildBridgePayload(params: BridgeParams): Promise<string>;
+    dispatch(signature: WebAuthnSignature, publicKeyX: bigint, publicKeyY: bigint, targetChain: number, actionPayload: string, nonce: bigint, signer: any): Promise<DispatchResult>;
+    dispatchGasless(signature: WebAuthnSignature, publicKeyX: bigint, publicKeyY: bigint, targetChain: number, actionPayload: string, nonce: bigint, relayerUrl: string): Promise<DispatchResult>;
+    computeVaultAddress(userKeyHash: string): string;
+    vaultExists(userKeyHash: string): Promise<boolean>;
+    createVault(userKeyHash: string, signer: any): Promise<VaultCreationResult>;
+    createVaultSponsored?(userKeyHash: string, sponsorPrivateKey: string, rpcUrl?: string): Promise<VaultCreationResult>;
+    /**
+     * Create a vault via the relayer (sponsored/gasless)
+     * This is the recommended way to create Starknet vaults
+     *
+     * The relayer will dispatch a vault creation action from Hub via custom bridge to Starknet spoke
+     */
+    createVaultViaRelayer(userKeyHash: string, relayerUrl: string): Promise<VaultCreationResult>;
+    /**
+     * Get vault info via relayer (includes existence check)
+     */
+    getVaultViaRelayer(userKeyHash: string, relayerUrl: string): Promise<{
+        vaultAddress: string;
+        exists: boolean;
+    }>;
+    estimateVaultCreationGas(_userKeyHash: string): Promise<bigint>;
+    getFactoryAddress(): string | undefined;
+    getImplementationAddress(): string | undefined;
+    getNativeBalance(address: string): Promise<bigint>;
+    getProvider(): RpcProvider;
+    /**
+     * Register a session key on the Hub (must be called via Hub client)
+     * Starknet spokes validate sessions via CCQ, but registration happens on Hub
+     *
+     * @throws Error - Session management must be done via Hub chain
+     */
+    registerSession(_params: RegisterSessionParams): Promise<void>;
+    /**
+     * Revoke a session key on the Hub (must be called via Hub client)
+     *
+     * @throws Error - Session management must be done via Hub chain
+     */
+    revokeSession(_params: RevokeSessionParams): Promise<void>;
+    /**
+     * Check if a session is active by querying the Hub
+     * This method queries the Hub contract directly for session validation
+     *
+     * @param userKeyHash - Hash of user's Passkey public key
+     * @param sessionKeyHash - Hash of session key to validate
+     * @returns Session validation result with expiry and limits
+     */
+    isSessionActive(userKeyHash: string, sessionKeyHash: string): Promise<SessionValidationResult>;
+    /**
+     * Get all sessions for a user from the Hub
+     *
+     * @param userKeyHash - Hash of user's Passkey public key
+     * @returns Array of all sessions (active and expired/revoked)
+     */
+    getUserSessions(userKeyHash: string): Promise<SessionKey[]>;
+    /**
+     * Get user state from Hub (comprehensive state query)
+     * Returns key hash, nonce, and last action hash for CCQ validation
+     *
+     * @param userKeyHash - Hash of user's Passkey public key
+     * @returns User state with nonce and last action hash
+     */
+    getUserState(userKeyHash: string): Promise<{
+        keyHash: string;
+        nonce: bigint;
+        lastActionHash: string;
+    }>;
+    /**
+     * Get user's last action hash from Hub
+     * Used for optimistic execution and nonce validation
+     *
+     * @param userKeyHash - Hash of user's Passkey public key
+     * @returns Last action hash (zero hash if no actions)
+     */
+    getUserLastActionHash(userKeyHash: string): Promise<string>;
+    /**
+     * Execute with query-based validation (faster than VAA, ~23s vs 60-90s)
+     * Uses Wormhole CCQ to validate Hub state, then executes on Starknet
+     *
+     * @param params Query execution parameters with CCQ response
+     * @returns Dispatch result with transaction hash
+     *
+     * @remarks
+     * Query-based execution flow:
+     * 1. Query Hub state via Wormhole CCQ
+     * 2. Validate Guardian signatures on query response
+     * 3. Execute on Starknet with validated state
+     * 4. Hub state must be < 60s stale (enforced by QueryVerifier)
+     */
+    executeWithQuery(_params: {
+        userKeyHash: string;
+        queryResponse: Uint8Array;
+        actionType: number;
+        actionPayload: Uint8Array;
+        relayerUrl?: string;
+    }): Promise<DispatchResult>;
+    private computeKeyHash;
+    private buildMessageHash;
+    /**
+     * Get vault address by owner key hash
+     *
+     * @param ownerKeyHash - Owner's passkey hash
+     * @returns Vault address on Starknet (felt252 as hex string)
+     */
+    getVaultAddress(ownerKeyHash: string): Promise<string | null>;
+    /**
+     * Check if vault exists and get basic info
+     *
+     * @param ownerKeyHash - Owner's passkey hash
+     * @returns Vault info or null if not found
+     */
+    getVaultInfo(ownerKeyHash: string): Promise<{
+        address: string;
+        ownerKeyHash: string;
+    } | null>;
+    /**
+     * Check if spoke contract is paused
+     *
+     * @returns Whether the protocol is paused
+     */
+    isProtocolPaused(): Promise<boolean>;
+}
+
+export { StarknetClient, type StarknetClientConfig };

package/dist/chains/starknet/index.d.ts

@@ -0,0 +1,172 @@
+import { S as SessionKey } from '../../types-FJL7j6gQ.js';
+import { C as ChainClient, a as ChainConfig, T as TransferParams, E as ExecuteParams, B as BridgeParams, W as WebAuthnSignature, D as DispatchResult, V as VaultCreationResult, R as RegisterSessionParams, b as RevokeSessionParams, S as SessionValidationResult } from '../../types-ChIsqCiw.js';
+import { RpcProvider } from 'starknet';
+
+/**
+ * Veridex Protocol SDK - Starknet Chain Client
+ *
+ * Production-grade implementation of ChainClient interface for Starknet.
+ * Supports custom bridge attestation, gasless execution via Hub dispatch.
+ *
+ * Security:
+ * - Native starknet::eth_signature::verify_eth_signature for validation
+ * - Custom bridge with multi-relayer threshold attestations
+ * - Replay protection via nonce verification on Hub
+ * - Bridge validates source_chain == hub_chain_id (10004 = Base Sepolia)
+ *
+ * Architecture:
+ * - Starknet actions MUST be dispatched via Hub (Base Sepolia)
+ * - Hub publishes Wormhole message → relayer monitors → relayer submits attestation
+ * - Bridge accumulates attestations → threshold reached → spoke executes
+ * - Spoke validates source_chain == hubChainId (NOT targetChain)
+ *
+ * Custom Bridge:
+ * - Bridge address: 0x2c458c1ae64556482b05cc2d3ee5b032ed114d68429dda2062c9849a5a725f8
+ * - Chain ID: 50001 (custom range 50000+, reserved for non-Wormhole chains)
+ * - Hub Chain ID: 10004 (Base Sepolia - what bridge validates as source)
+ */
+
+interface StarknetClientConfig {
+    wormholeChainId: number;
+    rpcUrl: string;
+    spokeContractAddress?: string;
+    bridgeContractAddress?: string;
+    network?: 'mainnet' | 'sepolia' | 'testnet';
+    hubRpcUrl?: string;
+    hubContractAddress?: string;
+}
+declare class StarknetClient implements ChainClient {
+    private config;
+    private provider;
+    private hubRpcUrl?;
+    private hubContractAddress?;
+    constructor(config: StarknetClientConfig);
+    getConfig(): ChainConfig;
+    getNonce(_userKeyHash: string): Promise<bigint>;
+    getMessageFee(): Promise<bigint>;
+    buildTransferPayload(params: TransferParams): Promise<string>;
+    buildExecutePayload(params: ExecuteParams): Promise<string>;
+    buildBridgePayload(params: BridgeParams): Promise<string>;
+    dispatch(signature: WebAuthnSignature, publicKeyX: bigint, publicKeyY: bigint, targetChain: number, actionPayload: string, nonce: bigint, signer: any): Promise<DispatchResult>;
+    dispatchGasless(signature: WebAuthnSignature, publicKeyX: bigint, publicKeyY: bigint, targetChain: number, actionPayload: string, nonce: bigint, relayerUrl: string): Promise<DispatchResult>;
+    computeVaultAddress(userKeyHash: string): string;
+    vaultExists(userKeyHash: string): Promise<boolean>;
+    createVault(userKeyHash: string, signer: any): Promise<VaultCreationResult>;
+    createVaultSponsored?(userKeyHash: string, sponsorPrivateKey: string, rpcUrl?: string): Promise<VaultCreationResult>;
+    /**
+     * Create a vault via the relayer (sponsored/gasless)
+     * This is the recommended way to create Starknet vaults
+     *
+     * The relayer will dispatch a vault creation action from Hub via custom bridge to Starknet spoke
+     */
+    createVaultViaRelayer(userKeyHash: string, relayerUrl: string): Promise<VaultCreationResult>;
+    /**
+     * Get vault info via relayer (includes existence check)
+     */
+    getVaultViaRelayer(userKeyHash: string, relayerUrl: string): Promise<{
+        vaultAddress: string;
+        exists: boolean;
+    }>;
+    estimateVaultCreationGas(_userKeyHash: string): Promise<bigint>;
+    getFactoryAddress(): string | undefined;
+    getImplementationAddress(): string | undefined;
+    getNativeBalance(address: string): Promise<bigint>;
+    getProvider(): RpcProvider;
+    /**
+     * Register a session key on the Hub (must be called via Hub client)
+     * Starknet spokes validate sessions via CCQ, but registration happens on Hub
+     *
+     * @throws Error - Session management must be done via Hub chain
+     */
+    registerSession(_params: RegisterSessionParams): Promise<void>;
+    /**
+     * Revoke a session key on the Hub (must be called via Hub client)
+     *
+     * @throws Error - Session management must be done via Hub chain
+     */
+    revokeSession(_params: RevokeSessionParams): Promise<void>;
+    /**
+     * Check if a session is active by querying the Hub
+     * This method queries the Hub contract directly for session validation
+     *
+     * @param userKeyHash - Hash of user's Passkey public key
+     * @param sessionKeyHash - Hash of session key to validate
+     * @returns Session validation result with expiry and limits
+     */
+    isSessionActive(userKeyHash: string, sessionKeyHash: string): Promise<SessionValidationResult>;
+    /**
+     * Get all sessions for a user from the Hub
+     *
+     * @param userKeyHash - Hash of user's Passkey public key
+     * @returns Array of all sessions (active and expired/revoked)
+     */
+    getUserSessions(userKeyHash: string): Promise<SessionKey[]>;
+    /**
+     * Get user state from Hub (comprehensive state query)
+     * Returns key hash, nonce, and last action hash for CCQ validation
+     *
+     * @param userKeyHash - Hash of user's Passkey public key
+     * @returns User state with nonce and last action hash
+     */
+    getUserState(userKeyHash: string): Promise<{
+        keyHash: string;
+        nonce: bigint;
+        lastActionHash: string;
+    }>;
+    /**
+     * Get user's last action hash from Hub
+     * Used for optimistic execution and nonce validation
+     *
+     * @param userKeyHash - Hash of user's Passkey public key
+     * @returns Last action hash (zero hash if no actions)
+     */
+    getUserLastActionHash(userKeyHash: string): Promise<string>;
+    /**
+     * Execute with query-based validation (faster than VAA, ~23s vs 60-90s)
+     * Uses Wormhole CCQ to validate Hub state, then executes on Starknet
+     *
+     * @param params Query execution parameters with CCQ response
+     * @returns Dispatch result with transaction hash
+     *
+     * @remarks
+     * Query-based execution flow:
+     * 1. Query Hub state via Wormhole CCQ
+     * 2. Validate Guardian signatures on query response
+     * 3. Execute on Starknet with validated state
+     * 4. Hub state must be < 60s stale (enforced by QueryVerifier)
+     */
+    executeWithQuery(_params: {
+        userKeyHash: string;
+        queryResponse: Uint8Array;
+        actionType: number;
+        actionPayload: Uint8Array;
+        relayerUrl?: string;
+    }): Promise<DispatchResult>;
+    private computeKeyHash;
+    private buildMessageHash;
+    /**
+     * Get vault address by owner key hash
+     *
+     * @param ownerKeyHash - Owner's passkey hash
+     * @returns Vault address on Starknet (felt252 as hex string)
+     */
+    getVaultAddress(ownerKeyHash: string): Promise<string | null>;
+    /**
+     * Check if vault exists and get basic info
+     *
+     * @param ownerKeyHash - Owner's passkey hash
+     * @returns Vault info or null if not found
+     */
+    getVaultInfo(ownerKeyHash: string): Promise<{
+        address: string;
+        ownerKeyHash: string;
+    } | null>;
+    /**
+     * Check if spoke contract is paused
+     *
+     * @returns Whether the protocol is paused
+     */
+    isProtocolPaused(): Promise<boolean>;
+}
+
+export { StarknetClient, type StarknetClientConfig };