@veridex/sdk 1.1.5 → 1.1.7

package/dist/index-qyOqd8tx.d.mts

@@ -0,0 +1,517 @@
+import * as _veridex_platform_events from '@veridex/platform-events';
+import { Environment, AtomicAmount, SponsorshipQuote, ChargeAuthorization } from '@veridex/platform-events';
+import { D as DispatchDestinationV3 } from './types-CdlEbixV.mjs';
+
+/**
+ * Veridex Protocol SDK - Relayer Client
+ *
+ * Client for interacting with the Veridex relayer service.
+ * The relayer automatically submits VAAs to destination chains.
+ *
+ * Features:
+ * - Submit VAA for relay
+ * - Check relay status
+ * - Get supported routes
+ * - Fee estimation
+ */
+
+/**
+ * Relay request status
+ */
+type RelayStatus = 'pending' | 'processing' | 'submitted' | 'confirmed' | 'failed';
+/**
+ * Relay request result
+ */
+interface RelayRequest {
+    /** Unique relay request ID */
+    id: string;
+    /** VAA sequence number */
+    sequence: bigint;
+    /** Source chain Wormhole ID */
+    sourceChain: number;
+    /** Destination chain Wormhole ID */
+    destinationChain: number;
+    /** Relay status */
+    status: RelayStatus;
+    /** Source transaction hash */
+    sourceTxHash: string;
+    /** Destination transaction hash (when completed) */
+    destinationTxHash?: string;
+    /** Timestamp when request was created */
+    createdAt: number;
+    /** Timestamp when request was last updated */
+    updatedAt: number;
+    /** Error message if failed */
+    error?: string;
+    /** Gas used on destination chain */
+    gasUsed?: bigint;
+    /** Fee paid */
+    feePaid?: bigint;
+}
+/**
+ * Supported route information
+ */
+interface RelayRoute {
+    /** Source chain Wormhole ID */
+    sourceChain: number;
+    /** Destination chain Wormhole ID */
+    destinationChain: number;
+    /** Whether the route is active */
+    active: boolean;
+    /** Estimated relay time in seconds */
+    estimatedTimeSeconds: number;
+    /** Base fee in destination chain native token */
+    baseFee: bigint;
+    /** Fee per gas unit */
+    gasPrice: bigint;
+    /** Maximum gas limit */
+    maxGas: bigint;
+}
+/**
+ * Relayer service info
+ */
+interface RelayerInfo {
+    /** Relayer name/identifier */
+    name: string;
+    /** Relayer version */
+    version: string;
+    /** Supported chains */
+    supportedChains: number[];
+    /** Available routes */
+    routes: RelayRoute[];
+    /** Whether the relayer is online */
+    online: boolean;
+    /** Current queue depth */
+    queueDepth: number;
+}
+/**
+ * Request body for submitting a signed action to the relayer (gasless)
+ * Uses full WebAuthn data for authenticateAndDispatch
+ */
+interface SubmitSignedActionRequest {
+    /** WebAuthn authenticatorData (hex) */
+    authenticatorData: string;
+    /** WebAuthn clientDataJSON (raw string) */
+    clientDataJSON: string;
+    /** Index of "challenge":"..." in clientDataJSON */
+    challengeIndex: number;
+    /** Index of "type":"..." in clientDataJSON */
+    typeIndex: number;
+    /** P-256 signature r component (hex) */
+    r: string;
+    /** P-256 signature s component (hex) */
+    s: string;
+    /** P-256 public key X coordinate (hex) */
+    publicKeyX: string;
+    /** P-256 public key Y coordinate (hex) */
+    publicKeyY: string;
+    /** Target chain Wormhole ID */
+    targetChain: number;
+    /** Destination chain in the Veridex namespace */
+    veridexChainId: number;
+    /** Exact destination execution contract as bytes32 */
+    executor: string;
+    /** Minimum assurance tier committed by the signature */
+    minTier: number;
+    /** Action payload (hex) */
+    actionPayload: string;
+    /** User nonce as a decimal uint64 string */
+    nonce: string;
+}
+/**
+ * Response from submitting a signed action
+ */
+interface SubmitActionResult {
+    /** Whether the submission was successful */
+    success: boolean;
+    /** Transaction hash on Hub chain */
+    txHash?: string;
+    /** Wormhole sequence number */
+    sequence?: string;
+    /** Error message if failed */
+    error?: string;
+    /** Human-readable message */
+    message?: string;
+}
+/**
+ * Query submission request (Issue #11/#12)
+ * For optimistic execution via Wormhole Query proofs (~5-7s vs ~120s)
+ */
+interface SubmitQueryRequest {
+    /** Target spoke chain Wormhole ID */
+    targetChain: number;
+    /** User's key hash */
+    userKeyHash: string;
+    /** Serialized transaction for spoke chain */
+    serializedTx: string;
+    /** Query proof with Guardian signatures */
+    queryProof: {
+        /** Raw query response bytes */
+        queryResponse: string;
+        /** Guardian signatures */
+        signatures: string;
+    };
+    /** Whether to fallback to VAA if Query fails */
+    fallbackToVaa?: boolean;
+    /** Optional metadata */
+    metadata?: {
+        /** User's preferred execution path */
+        preferredPath?: 'query' | 'vaa';
+        /** Transaction value in USD (for routing decisions) */
+        estimatedValueUSD?: number;
+    };
+}
+/**
+ * Query submission result (Issue #11/#12)
+ */
+interface SubmitQueryResult {
+    /** Whether submission succeeded */
+    success: boolean;
+    /** Transaction hash on spoke chain */
+    txHash?: string;
+    /** Execution path used */
+    path: 'query' | 'vaa';
+    /** Latency in milliseconds */
+    latencyMs?: number;
+    /** Error message if failed */
+    error?: string;
+    /** Whether fallback to VAA occurred */
+    fellBack?: boolean;
+}
+/**
+ * Fee quote for a relay
+ */
+interface RelayFeeQuote {
+    /** Source chain Wormhole ID */
+    sourceChain: number;
+    /** Destination chain Wormhole ID */
+    destinationChain: number;
+    /** Estimated fee in source chain native token */
+    feeInSourceToken: bigint;
+    /** Estimated fee in destination chain native token */
+    feeInDestinationToken: bigint;
+    /** Estimated gas on destination */
+    estimatedGas: bigint;
+    /** Quote expiration timestamp */
+    expiresAt: number;
+    /** Quote ID for submission */
+    quoteId: string;
+}
+/**
+ * Configuration for RelayerClient
+ */
+interface RelayerClientConfig {
+    /** Base URL of the relayer service */
+    baseUrl: string;
+    /** API key for authentication (optional) */
+    apiKey?: string;
+    /** Timeout for requests in ms */
+    timeoutMs?: number;
+    /** Max retries for failed requests */
+    maxRetries?: number;
+}
+type RegisteredAppStatus = 'active' | 'suspended' | 'revoked';
+type RegisteredAppTrustLevel = 'verified' | 'registered' | 'pending';
+interface RegisteredAppSummary {
+    id: string;
+    name: string;
+    origin: string;
+    trustLevel: RegisteredAppTrustLevel;
+    status: RegisteredAppStatus;
+    requestCount: number;
+    createdAt: number;
+    lastUsedAt?: number;
+}
+interface RegisteredAppDetail extends RegisteredAppSummary {
+    description?: string;
+    apiKey?: string;
+    activeSessionCount?: number;
+}
+interface RelayerAppSession {
+    id: string;
+    keyHash: string;
+    appOrigin: string;
+    sessionPublicKey: string;
+    permissions: string[];
+    expiresAt: number;
+    createdAt: number;
+    revoked: boolean;
+    active: boolean;
+}
+interface CredentialMetadataRecord {
+    credentialId: string;
+    keyHash: string;
+    displayName: string;
+    platformHint: string;
+    backupEligible: boolean | null;
+    backupState: boolean | null;
+    isRoot: boolean;
+    status: 'active' | 'revoked';
+    lastUsedAt: number | null;
+    useCount: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Client for the Veridex relayer service
+ */
+declare class RelayerClient {
+    private baseUrl;
+    private config;
+    constructor(config: RelayerClientConfig);
+    getDispatchDestination(targetChain: number): Promise<DispatchDestinationV3>;
+    getUserNonce(userKeyHash: string): Promise<bigint>;
+    /**
+     * Submit a VAA for relay to destination chain
+     */
+    submitRelay(vaaBase64: string, sourceChain: number, destinationChain: number, sourceTxHash: string, sequence: bigint, feeQuoteId?: string): Promise<RelayRequest>;
+    /**
+     * Submit a signed action to the relayer for gasless execution
+     *
+     * This allows users to execute transfers without paying gas themselves.
+     * The relayer will submit the transaction to the Hub chain and pay the gas.
+     * The relayer then automatically relays the VAA to the destination spoke chain.
+     *
+     * @param request - The signed action request with passkey signature
+     * @returns Result including Hub tx hash and Wormhole sequence
+     */
+    submitSignedAction(request: SubmitSignedActionRequest): Promise<SubmitActionResult>;
+    /**
+     * Submit a Query-based transaction for optimistic execution (Issue #11/#12)
+     *
+     * Uses Wormhole Cross-Chain Queries (CCQ) to achieve ~5-7 second latency
+     * vs ~120+ seconds for traditional VAA flow.
+     *
+     * Flow:
+     * 1. Client fetches Hub state via queryHubState() from SDK
+     * 2. Client constructs and signs transaction
+     * 3. Client submits Query proof + tx to this endpoint
+     * 4. Relayer validates format and submits to spoke chain
+     * 5. Spoke chain verifies Guardian signatures on-chain
+     *
+     * @param request - Query submission with Guardian-signed proof
+     * @returns Result including spoke tx hash and execution path
+     */
+    submitQuery(request: SubmitQueryRequest): Promise<SubmitQueryResult>;
+    /**
+     * Get relay request status
+     */
+    getRelayStatus(requestId: string): Promise<RelayRequest>;
+    /**
+     * Get relay status by source transaction hash
+     */
+    getRelayBySourceTx(sourceTxHash: string): Promise<RelayRequest | null>;
+    /**
+     * Get relay status by sequence number
+     */
+    getRelayBySequence(sourceChain: number, sequence: bigint): Promise<RelayRequest | null>;
+    /**
+     * Cancel a pending relay request
+     */
+    cancelRelay(requestId: string): Promise<boolean>;
+    /**
+     * Poll for relay completion
+     */
+    waitForRelay(requestId: string, timeoutMs?: number, pollingIntervalMs?: number, onProgress?: (status: RelayStatus) => void): Promise<RelayRequest>;
+    /**
+     * Get fee quote for a relay
+     */
+    getFeeQuote(sourceChain: number, destinationChain: number, estimatedGas?: bigint): Promise<RelayFeeQuote>;
+    /**
+     * Get relayer service info
+     */
+    getInfo(): Promise<RelayerInfo>;
+    /**
+     * Get supported routes
+     */
+    getRoutes(): Promise<RelayRoute[]>;
+    /**
+     * Check if a route is supported
+     */
+    isRouteSupported(sourceChain: number, destinationChain: number): Promise<boolean>;
+    /**
+     * Check relayer health
+     */
+    healthCheck(): Promise<boolean>;
+    listApps(): Promise<RegisteredAppSummary[]>;
+    getApp(appId: string): Promise<RegisteredAppDetail>;
+    updateAppStatus(appId: string, status: RegisteredAppStatus): Promise<void>;
+    updateAppTrustLevel(appId: string, trustLevel: RegisteredAppTrustLevel): Promise<void>;
+    listAppSessions(appId: string, options?: {
+        includeRevoked?: boolean;
+    }): Promise<RelayerAppSession[]>;
+    revokeAppSessions(appId: string, sessionId?: string): Promise<number>;
+    listCredentialMetadata(keyHash: string): Promise<CredentialMetadataRecord[]>;
+    /**
+     * Get all pending relay requests for a user
+     */
+    getPendingRelays(userKeyHash: string): Promise<RelayRequest[]>;
+    /**
+     * Get relay history for a user
+     */
+    getRelayHistory(userKeyHash: string, limit?: number, offset?: number): Promise<RelayRequest[]>;
+    /**
+     * SDK version for telemetry
+     */
+    private static readonly SDK_VERSION;
+    /**
+     * Make an HTTP request to the relayer
+     */
+    private fetch;
+    /**
+     * Sleep helper
+     */
+    private sleep;
+}
+/**
+ * Create a RelayerClient instance
+ */
+declare function createRelayerClient(config: RelayerClientConfig): RelayerClient;
+
+type SponsorshipFeeLeg = _veridex_platform_events.SponsorshipQuote['feeLegs'][number];
+
+interface ExecutionAttempt {
+    id: string;
+    executionId: string;
+    attemptNumber: number;
+    chain: string;
+    transport: string;
+    status: string;
+    transactionHash?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    startedAt: string;
+    submittedAt?: string;
+    completedAt?: string;
+}
+interface ExecutionRecord {
+    id: string;
+    tenantId: string;
+    appId: string;
+    environment: Environment;
+    status: string;
+    actionHash: string;
+    sourceNetwork: string;
+    destinationNetwork: string;
+    targetChain: number;
+    attempts?: ExecutionAttempt[];
+    receipts?: unknown[];
+    nonceLeases?: unknown[];
+}
+interface ReconciliationIssue {
+    id: string;
+    executionId: string;
+    reason: string;
+    status: 'open' | 'resolved';
+    details?: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+    resolvedAt?: number;
+}
+interface GatewayTarget {
+    network: string;
+    facilitatorUrl: string;
+    payTo: string;
+    asset: string;
+    defaultPrice: AtomicAmount;
+}
+interface GatewayConfigData {
+    schemaVersion: 'veridex.gateway-config/v1';
+    appId: string;
+    environment: Environment;
+    name: string;
+    state: 'draft' | 'active' | 'paused' | 'disabled';
+    targets: GatewayTarget[];
+    schemes: Array<'exact' | 'upto' | 'batch-settlement'>;
+    upstreamUrl: string;
+    publicBaseUrl: string;
+    allowedMethods: Array<'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'>;
+    updatedBy: string;
+}
+interface GatewayConfigResource {
+    id: string;
+    name: string;
+    version: number;
+    data: GatewayConfigData;
+}
+interface PlatformClientConfig {
+    executionBaseUrl: string;
+    controlPlaneBaseUrl?: string;
+    apiKey: string;
+    tenantId: string;
+    appId: string;
+    environment: Environment;
+    controlPlaneToken?: string;
+    timeoutMs?: number;
+}
+
+declare class PlatformClient {
+    readonly tenantId: string;
+    readonly appId: string;
+    readonly environment: 'test' | 'live';
+    private readonly executionBaseUrl;
+    private readonly controlPlaneBaseUrl?;
+    private readonly apiKey;
+    private readonly controlPlaneToken?;
+    private readonly timeoutMs;
+    constructor(config: PlatformClientConfig);
+    quote(action: SubmitSignedActionRequest, idempotencyKey: string): Promise<{
+        quote: SponsorshipQuote;
+        simulation: Record<string, string | number>;
+    }>;
+    reserve(quote: SponsorshipQuote, executionId: string, idempotencyKey: string, chargeAuthorization?: ChargeAuthorization): Promise<{
+        executionId: string;
+        reservations: unknown[];
+    }>;
+    submitSponsored(action: SubmitSignedActionRequest, executionId: string): Promise<{
+        success: boolean;
+        transactionHash?: string;
+        sequence?: string;
+        actualSponsoredCost?: string;
+    }>;
+    getExecution(executionId: string): Promise<{
+        execution: ExecutionRecord;
+    }>;
+    listExecutionAttempts(executionId: string): Promise<{
+        attempts: ExecutionAttempt[];
+    }>;
+    cancelExecution(executionId: string, reason?: string): Promise<{
+        execution: ExecutionRecord;
+    }>;
+    listExecutions(limit?: number): Promise<{
+        executions: unknown[];
+    }>;
+    listReconciliationIssues(): Promise<{
+        issues: ReconciliationIssue[];
+    }>;
+    listChainCapabilities(): Promise<{
+        capabilities: unknown[];
+    }>;
+    getSponsorshipPolicy(): Promise<Record<string, unknown>>;
+    putSponsorshipPolicy(policy: Record<string, unknown>): Promise<Record<string, unknown>>;
+    listGateways(): Promise<GatewayConfigResource[]>;
+    createGateway(config: Omit<GatewayConfigData, 'appId' | 'environment' | 'updatedBy'>): Promise<GatewayConfigResource>;
+    updateGateway(gatewayId: string, config: Omit<GatewayConfigData, 'appId' | 'environment' | 'updatedBy'>): Promise<GatewayConfigResource>;
+    listFinancialSummary(): Promise<Record<string, unknown>>;
+    fund(amount: string, asset: string, idempotencyKey: string): Promise<Record<string, unknown>>;
+    refund(transactionId: string, reason: string, idempotencyKey: string): Promise<Record<string, unknown>>;
+    listPayments(): Promise<{
+        payments: unknown[];
+    }>;
+    listCharges(): Promise<{
+        charges: unknown[];
+    }>;
+    listInvoices(): Promise<{
+        invoices: unknown[];
+    }>;
+    listBazaarResources(query?: string): Promise<{
+        resources: unknown[];
+    }>;
+    publishResource(resourceId: string): Promise<Record<string, unknown>>;
+    createChargeAuthorization(authorization: ChargeAuthorization): Promise<Record<string, unknown>>;
+    private assertQuoteScope;
+    private execution;
+    private controlPlane;
+}
+
+export { type CredentialMetadataRecord as C, type ExecutionAttempt as E, type GatewayConfigData as G, PlatformClient as P, RelayerClient as R, type SponsorshipFeeLeg as S, type RegisteredAppSummary as a, type RegisteredAppDetail as b, type RegisteredAppStatus as c, type RegisteredAppTrustLevel as d, type RelayerAppSession as e, type ExecutionRecord as f, type GatewayConfigResource as g, type PlatformClientConfig as h, type ReconciliationIssue as i, createRelayerClient as j, type RelayStatus as k, type RelayRequest as l, type RelayRoute as m, type RelayerInfo as n, type RelayFeeQuote as o, type RelayerClientConfig as p, type SubmitSignedActionRequest as q, type SubmitActionResult as r, type SubmitQueryRequest as s, type SubmitQueryResult as t, type GatewayTarget as u };