@provablehq/aleo-bridge-sdk 0.8.0-rc.0

package/dist/createBridgeClient-CjHY-JvW.d.ts

@@ -0,0 +1,779 @@
+import { TransactionInput, Client } from '@provablehq/veil-core';
+import { Address, Hex, Hash } from 'viem';
+
+/** Identifies the protocol that carries a bridge transfer. */
+type BridgeProtocol = 'xreserve' | 'hyperlane';
+/** Identifies the deployment environment selected by a bridge client. */
+type BridgeEnvironment = 'mainnet' | 'testnet';
+/** Identifies the transaction model used by a chain. */
+type BridgeChainFamily = 'aleo' | 'evm' | 'solana';
+/**
+ * Describes a chain known to the protocol bridge registry.
+ *
+ * @property id Stable SDK identifier used by assets and routes.
+ * @property displayName Human-readable chain name.
+ * @property family Transaction model used to prepare transfer steps.
+ * @property environment Deployment environment containing the chain.
+ * @property nativeCurrencySymbol Symbol used to pay transaction fees.
+ * @property protocolDomains Protocol-specific domain identifiers when known.
+ */
+type ProtocolBridgeChain = {
+    id: string;
+    displayName: string;
+    family: BridgeChainFamily;
+    environment: BridgeEnvironment;
+    nativeCurrencySymbol: string;
+    protocolDomains?: Partial<Record<BridgeProtocol, string | number>> | undefined;
+};
+/** Identifies how an asset exists on its chain. */
+type BridgeAssetKind = 'native' | 'token';
+/**
+ * Locates a token on its chain.
+ *
+ * @property kind Namespace containing the identifier.
+ * @property value Contract, program, mint, or native-denom identifier.
+ * @property tokenId Optional token identifier within a shared token program.
+ */
+type BridgeAssetLocator = {
+    kind: 'aleo-program' | 'evm-contract' | 'solana-mint' | 'native';
+    value: string;
+    tokenId?: string | undefined;
+};
+/**
+ * Describes one chain-specific representation of a bridgeable asset.
+ *
+ * @property id Stable registry identifier, scoped to one chain.
+ * @property chainId Chain carrying this representation.
+ * @property symbol Display symbol.
+ * @property name Human-readable asset name.
+ * @property decimals Number of decimal places accepted in display amounts.
+ * @property kind Whether the representation is native currency or a token.
+ * @property locator Onchain identifier when the deployment is known.
+ * @property addressValidationRegex Optional recipient validation expression.
+ */
+type ProtocolBridgeAsset = {
+    id: string;
+    chainId: string;
+    symbol: string;
+    name: string;
+    decimals: number;
+    kind: BridgeAssetKind;
+    locator?: BridgeAssetLocator | undefined;
+    addressValidationRegex?: string | undefined;
+};
+/** Reports whether a route has enough reviewed metadata for execution. */
+type BridgeRouteAvailability = 'active' | 'metadata-required' | 'disabled';
+/**
+ * Describes one directional protocol route.
+ *
+ * @property id Stable route identifier.
+ * @property protocol Protocol responsible for delivery.
+ * @property environment Deployment environment containing both endpoints.
+ * @property sourceAssetId Registry id of the debited asset.
+ * @property destinationAssetId Registry id of the delivered asset.
+ * @property availability Readiness for transaction execution.
+ * @property deploymentId Upstream protocol deployment identifier when known.
+ * @property source Reference used to audit the route metadata.
+ * @property metadata Protocol-specific non-secret configuration.
+ */
+type ProtocolBridgeRoute = {
+    id: string;
+    protocol: BridgeProtocol;
+    environment: BridgeEnvironment;
+    sourceAssetId: string;
+    destinationAssetId: string;
+    availability: BridgeRouteAvailability;
+    deploymentId?: string | undefined;
+    source?: string | undefined;
+    metadata?: Readonly<Record<string, string | number | boolean>> | undefined;
+};
+/**
+ * Stores reviewed bridge chains, assets, and directional routes.
+ *
+ * @property version Caller-visible version used to pin and audit configuration.
+ * @property chains Chain metadata referenced by assets.
+ * @property assets Chain-specific assets referenced by routes.
+ * @property routes Directional protocol routes.
+ * @property sources Upstream registries and documentation used to build the snapshot.
+ */
+type BridgeRegistry = {
+    version: string;
+    chains: readonly ProtocolBridgeChain[];
+    assets: readonly ProtocolBridgeAsset[];
+    routes: readonly ProtocolBridgeRoute[];
+    sources?: readonly string[] | undefined;
+};
+/** Identifies the signer or service responsible for a transfer step. */
+type BridgeStepExecutor = 'aleo-wallet' | 'evm-wallet' | 'solana-wallet' | 'protocol';
+/** Identifies a resumable operation in a protocol transfer. */
+type BridgeExecutionStepKind = 'approve' | 'deposit' | 'burn' | 'dispatch' | 'wait-attestation' | 'mint' | 'withdraw' | 'wait-delivery' | 'confirm-delivery';
+/**
+ * Describes one ordered operation in a prepared transfer.
+ *
+ * @property key Stable step key within the plan.
+ * @property kind Operation the executor performs.
+ * @property chainId Chain on which the operation occurs, when applicable.
+ * @property executor Wallet or protocol service responsible for the operation.
+ * @property description Human-readable consequence of the step.
+ * @property irreversible Whether submitting the step commits funds to the protocol flow.
+ */
+type BridgeExecutionStep = {
+    key: string;
+    kind: BridgeExecutionStepKind;
+    chainId?: string | undefined;
+    executor: BridgeStepExecutor;
+    description: string;
+    irreversible: boolean;
+};
+/**
+ * Describes a fee associated with a transfer plan.
+ *
+ * @property kind Fee category.
+ * @property chainId Chain charging the fee.
+ * @property assetId Asset used to pay the fee when known.
+ * @property amount Decimal fee amount when available.
+ * @property estimated Whether the amount can change before submission.
+ */
+type BridgeFee = {
+    kind: 'network' | 'protocol' | 'relayer';
+    chainId: string;
+    assetId?: string | undefined;
+    amount?: string | undefined;
+    estimated: boolean;
+};
+/** Identifies how much live protocol information a transfer quote contains. */
+type BridgeQuoteStatus = 'not-queried' | 'estimated' | 'confirmed';
+/** Selects the Aleo destination transition used for an xReserve mint. */
+type AleoMintMode = 'public' | 'record' | 'private';
+/**
+ * Captures protocol fees and expected delivery for a directional route.
+ *
+ * @property routeId Directional route the quote prices.
+ * @property protocol Protocol responsible for delivery.
+ * @property amountIn Decimal source amount.
+ * @property amountOut Expected decimal destination amount after known fees.
+ * @property fees Network, protocol, and relayer fee components.
+ * @property status Whether protocol endpoints have supplied live values.
+ * @property expiresAt Expiration time for protocol-bound fee data when present.
+ */
+type BridgeTransferQuote = {
+    routeId: string;
+    protocol: BridgeProtocol;
+    amountIn: string;
+    amountOut?: string | undefined;
+    fees: BridgeFee[];
+    status: BridgeQuoteStatus;
+    expiresAt?: string | undefined;
+};
+/**
+ * Parameters for preparing a protocol bridge transfer.
+ *
+ * @property routeId Directional route selected from `getRoutes`.
+ * @property amount Decimal source amount in display units.
+ * @property recipient Destination-chain recipient.
+ * @property sender Optional source-chain sender used by future fee and approval planning.
+ * @property mintMode Aleo mint transition selected for xReserve delivery. Defaults to `public`.
+ * @property privateMintSecretNonce Aleo scalar literal committed into a private-mint hook. Defaults to `0scalar`; applies only to `private` mode and must remain available for the destination transaction.
+ * @property privateRecipient Deprecated alias for `mintMode: 'private'`. Defaults to false.
+ */
+type PrepareTransferParameters = {
+    routeId: string;
+    amount: string;
+    recipient: string;
+    sender?: string | undefined;
+    mintMode?: AleoMintMode | undefined;
+    privateMintSecretNonce?: string | undefined;
+    /** @deprecated Use `mintMode: 'private'`; retained for compatibility through the next major release. */
+    privateRecipient?: boolean | undefined;
+};
+/**
+ * Captures a locally prepared, non-fund-moving bridge transfer.
+ *
+ * @property registryVersion Registry snapshot used to build the plan.
+ * @property protocol Protocol responsible for delivery.
+ * @property route Directional route selected by the caller.
+ * @property sourceAsset Asset debited by the source transaction.
+ * @property destinationAsset Asset delivered on the destination chain.
+ * @property amountIn Decimal source amount.
+ * @property amountOut Expected decimal destination amount when determinable without a live fee query.
+ * @property recipient Destination-chain recipient.
+ * @property sender Optional source-chain sender.
+ * @property mintMode Aleo destination transition selected by the caller.
+ * @property privateMintSecretNonce Aleo scalar literal committed into a private-mint hook. Present only for private xReserve mints and sensitive until submission.
+ * @property privateRecipient Whether the destination requests private Aleo delivery.
+ * @property fees Known fee categories; amounts remain absent until protocol quoting is implemented.
+ * @property steps Ordered operations required to complete the transfer.
+ */
+type BridgeTransferPlan = {
+    registryVersion: string;
+    protocol: BridgeProtocol;
+    route: ProtocolBridgeRoute;
+    sourceAsset: ProtocolBridgeAsset;
+    destinationAsset: ProtocolBridgeAsset;
+    amountIn: string;
+    amountOut?: string | undefined;
+    recipient: string;
+    sender?: string | undefined;
+    mintMode: AleoMintMode;
+    privateMintSecretNonce?: string | undefined;
+    privateRecipient: boolean;
+    quote: BridgeTransferQuote;
+    fees: BridgeFee[];
+    steps: BridgeExecutionStep[];
+};
+/** Identifies the normalized lifecycle state of a protocol transfer. */
+type BridgeTransferStatus = 'PREPARED' | 'SOURCE_APPROVAL_PENDING' | 'SOURCE_SUBMISSION_PENDING' | 'SOURCE_CONFIRMING' | 'ATTESTATION_PENDING' | 'DELIVERY_PENDING' | 'DESTINATION_CONFIRMING' | 'COMPLETED' | 'FAILED' | 'EXPIRED';
+/**
+ * Captures protocol-neutral transfer progress and protocol-native state.
+ *
+ * @property id Stable transfer or message identifier.
+ * @property protocol Protocol responsible for delivery.
+ * @property status Normalized lifecycle state.
+ * @property sourceTxId Source-chain transaction identifier when submitted.
+ * @property destinationTxId Destination-chain transaction identifier when submitted.
+ * @property messageId Hyperlane message identifier when applicable.
+ * @property protocolState Protocol-native progress fields retained for diagnostics and resumption.
+ */
+type BridgeTransferReceipt = {
+    id: string;
+    protocol: BridgeProtocol;
+    status: BridgeTransferStatus;
+    sourceTxId?: string | undefined;
+    destinationTxId?: string | undefined;
+    messageId?: string | undefined;
+    protocolState: Readonly<Record<string, unknown>>;
+};
+
+/** Filters the protocol asset catalog. */
+type GetProtocolAssetsParameters = {
+    environment?: BridgeEnvironment | undefined;
+    chainId?: string | undefined;
+    symbol?: string | undefined;
+};
+/** Filters directional protocol routes. */
+type GetProtocolRoutesParameters = {
+    environment?: BridgeEnvironment | undefined;
+    protocol?: BridgeProtocol | undefined;
+    sourceChainId?: string | undefined;
+    destinationChainId?: string | undefined;
+    symbol?: string | undefined;
+    includeUnavailable?: boolean | undefined;
+};
+/**
+ * Lists chain-specific assets from a protocol bridge registry.
+ *
+ * Pure and local. Filters match identifiers and symbols case-insensitively.
+ *
+ * @param registry Reviewed registry snapshot.
+ * @param params Optional environment, chain, and symbol filters.
+ * @returns Matching assets in registry order.
+ *
+ * @example
+ * const usdcx = getProtocolAssets(registry, { symbol: 'USDCx' })
+ */
+declare function getProtocolAssets(registry: BridgeRegistry, params?: GetProtocolAssetsParameters): ProtocolBridgeAsset[];
+/**
+ * Lists directional routes from a protocol bridge registry.
+ *
+ * Pure and local. Routes marked `disabled` are omitted unless
+ * `includeUnavailable` is true; `metadata-required` routes remain visible so
+ * applications can distinguish known protocol support from execution readiness.
+ *
+ * @param registry Reviewed registry snapshot.
+ * @param params Optional protocol, environment, endpoint, and symbol filters.
+ * @returns Matching directional routes in registry order.
+ *
+ * @example
+ * const outbound = getProtocolRoutes(registry, { sourceChainId: 'aleo' })
+ */
+declare function getProtocolRoutes(registry: BridgeRegistry, params?: GetProtocolRoutesParameters): ProtocolBridgeRoute[];
+
+/**
+ * Supplies a fetch-compatible HTTP response for Circle attestation requests.
+ *
+ * @property ok Whether the response status is successful.
+ * @property status Numeric HTTP status used to distinguish pending attestations.
+ * @property json Parses the response body as JSON.
+ */
+type XReserveHttpResponse = {
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+};
+/** Sends an HTTP request without coupling the bridge client to a runtime global. */
+type XReserveHttpTransport = (url: string, init?: {
+    signal?: AbortSignal;
+}) => Promise<XReserveHttpResponse>;
+/**
+ * Captures reviewed Ethereum-to-Aleo xReserve deployment values.
+ *
+ * @property xReserveContract Ethereum contract receiving deposits.
+ * @property sourceChainId Expected EIP-155 wallet chain id.
+ * @property sourceDomain Circle domain included in the deposit nonce.
+ * @property remoteDomain Aleo Circle domain passed to `depositToRemote`.
+ * @property remoteTokenBytes32 Aleo USDCx token identifier in Circle wire form.
+ * @property minimumAmountAtomic Smallest supported deposit in USDC base units.
+ * @property maxFeeAtomic Maximum Circle fee in USDC base units.
+ * @property bridgeProgram Aleo program handling public and record mints.
+ * @property wrapperProgram Aleo program handling private wrapper mints.
+ * @property attestationBaseUrl Circle endpoint prefix for individual message hashes.
+ */
+type EvmXReserveRouteMetadata = {
+    xReserveContract: Address;
+    sourceChainId: number;
+    sourceDomain: number;
+    remoteDomain: number;
+    remoteTokenBytes32: Hex;
+    minimumAmountAtomic: bigint;
+    maxFeeAtomic: bigint;
+    bridgeProgram: string;
+    wrapperProgram: string;
+    attestationBaseUrl: string;
+};
+/**
+ * Selects a prepared xReserve transfer for live balance and allowance checks.
+ *
+ * @property plan Pure plan returned by `prepareTransfer`.
+ */
+type QuoteEvmXReserveTransferParameters = {
+    plan: BridgeTransferPlan;
+};
+/**
+ * Captures atomic values and allowance state required by an xReserve deposit.
+ *
+ * @property routeId Reviewed route used for the quote.
+ * @property xReserveContract Contract receiving the deposit.
+ * @property tokenAddress USDC contract approved and deposited.
+ * @property sourceChainId Expected EIP-155 wallet chain id.
+ * @property remoteDomain Aleo Circle domain supplied to the contract.
+ * @property remoteRecipientBytes32 User or wrapper address in wire form.
+ * @property amountAtomic Deposit amount in USDC base units.
+ * @property maxFeeAtomic Maximum Circle fee in USDC base units.
+ * @property hookData Fixed 65-byte Aleo mint instruction.
+ * @property balanceAtomic Connected account balance in USDC base units.
+ * @property allowanceAtomic Current xReserve allowance in USDC base units.
+ * @property approvalRequired Whether execution must submit an approval first.
+ */
+type EvmXReserveTransferQuote = {
+    routeId: string;
+    xReserveContract: Address;
+    tokenAddress: Address;
+    sourceChainId: number;
+    remoteDomain: number;
+    remoteRecipientBytes32: Hex;
+    amountAtomic: bigint;
+    maxFeeAtomic: bigint;
+    hookData: Hex;
+    balanceAtomic: bigint;
+    allowanceAtomic: bigint;
+    approvalRequired: boolean;
+};
+/**
+ * Configures an Ethereum-to-Aleo xReserve deposit submission.
+ *
+ * @property plan Pure plan returned by `prepareTransfer`.
+ * @property pollingIntervalMs Delay between receipt checks. Defaults to 1,000 milliseconds.
+ * @property confirmationTimeoutMs Maximum receipt wait per transaction. Defaults to 120,000 milliseconds.
+ */
+type ExecuteEvmXReserveTransferParameters = {
+    plan: BridgeTransferPlan;
+    pollingIntervalMs?: number | undefined;
+    confirmationTimeoutMs?: number | undefined;
+};
+/**
+ * Captures wallet transactions and resumable xReserve progress after execution.
+ *
+ * @property receipt Protocol-neutral status plus Circle payload identifiers.
+ * @property approvalTxIds ERC-20 approvals submitted before the deposit.
+ */
+type EvmXReserveTransferExecution = {
+    receipt: BridgeTransferReceipt;
+    approvalTxIds: Hash[];
+};
+/**
+ * Selects a Circle attestation by its 32-byte message hash.
+ *
+ * @property routeId Route supplying the environment-specific Circle endpoint.
+ * @property messageHash Keccak-256 hash returned by deposit execution.
+ * @property signal Optional cancellation signal. Defaults to no cancellation.
+ */
+type GetXReserveAttestationParameters = {
+    routeId: string;
+    messageHash: Hash;
+    signal?: AbortSignal | undefined;
+};
+/** Reports whether Circle has produced the signature for an xReserve message. */
+type XReserveAttestationResult = {
+    status: 'pending';
+    messageHash: Hash;
+} | {
+    status: 'complete';
+    messageHash: Hash;
+    payload: Hex;
+    attestation: Hex;
+};
+
+/**
+ * Submits one Aleo program execution through an application-provided wallet client.
+ *
+ * The shape is compatible with Veil wallet clients and connected Aleo wallet adapters.
+ *
+ * @property executeTransaction Prompts the wallet to prove, sign, and broadcast a program call.
+ */
+type AleoBridgeExecutor = {
+    executeTransaction: (params: {
+        program: string;
+        function: string;
+        inputs: TransactionInput[];
+        privateFee?: boolean | undefined;
+        imports?: string[] | undefined;
+    }) => Promise<string | {
+        transactionId: string;
+    }>;
+};
+/**
+ * Configures submission of the user-authorized USDCx wrapper mint.
+ *
+ * @property plan Original private-mint transfer plan.
+ * @property deposit Confirmed EVM deposit receipt carrying the canonical payload.
+ * @property attestation Completed Circle payload and signature response.
+ * @property privateFee Whether the Aleo wallet should pay its fee privately. Defaults to false.
+ */
+type ExecuteXReservePrivateMintParameters = {
+    plan: BridgeTransferPlan;
+    deposit: BridgeTransferReceipt;
+    attestation: XReserveAttestationResult;
+    privateFee?: boolean | undefined;
+};
+/**
+ * Captures the submitted wrapper transaction and resumable destination state.
+ *
+ * @property transactionId Aleo transaction id returned by the connected wallet.
+ * @property receipt Transfer state retaining source, Circle, and destination identifiers.
+ */
+type XReservePrivateMintExecution = {
+    transactionId: string;
+    receipt: BridgeTransferReceipt;
+};
+/** Selects which deployed USDCx burn transition the Aleo wallet calls. */
+type XReserveBurnMode = 'private' | 'public' | 'public-as-signer';
+/**
+ * Describes one validated Aleo USDCx burn call without submitting it.
+ *
+ * @property routeId Aleo-to-Ethereum xReserve route used for the burn.
+ * @property mode Transition variant selected by the caller.
+ * @property program Deployed bridge or wrapper program receiving the transaction.
+ * @property function Exact burn transition invoked by the wallet.
+ * @property inputs Ordered Aleo literals and wallet record requests.
+ * @property amountAtomic Burn amount in USDCx base units.
+ * @property nativeDomain Circle Ethereum destination domain, fixed to 0.
+ * @property nativeRecipientBytes32 Ethereum recipient left-padded to 32 bytes.
+ */
+type XReserveBurnCall = {
+    routeId: string;
+    mode: XReserveBurnMode;
+    program: string;
+    function: 'burn_public_as_signer' | 'burn_public' | 'private_burn';
+    inputs: TransactionInput[];
+    amountAtomic: bigint;
+    nativeDomain: number;
+    nativeRecipientBytes32: `0x${string}`;
+};
+/**
+ * Configures an Aleo USDCx burn destined for Ethereum USDC.
+ *
+ * @property plan Aleo-to-Ethereum plan returned by `prepareTransfer`.
+ * @property mode Burn transition to submit. Defaults to `private`.
+ * @property userRecord Wallet record request or encoded USDCx token record. Required only for `private`.
+ * @property merkleProof Encoded `[MerkleProof; 2]` Aleo literal. Required only for `private`.
+ * @property privateFee Whether the Aleo wallet should pay its fee privately. Defaults to false.
+ */
+type ExecuteXReserveBurnParameters = {
+    plan: BridgeTransferPlan;
+    mode?: XReserveBurnMode | undefined;
+    userRecord?: TransactionInput | undefined;
+    merkleProof?: string | undefined;
+    privateFee?: boolean | undefined;
+};
+/**
+ * Captures the submitted Aleo burn and the service-managed delivery state.
+ *
+ * @property transactionId Aleo transaction id returned by the connected wallet.
+ * @property receipt Transfer state retained while the Aleo attestation service forwards the burn to Circle.
+ */
+type XReserveBurnExecution = {
+    transactionId: string;
+    receipt: BridgeTransferReceipt;
+};
+/**
+ * Describes one locally constructed Aleo Hyperlane transfer call.
+ *
+ * @property routeId Directional Hyperlane route used to construct the call.
+ * @property program Aleo Warp Route program receiving the transaction.
+ * @property function Exact Warp Route transition invoked by the wallet.
+ * @property inputs Seven ordered Aleo literals expected by the selected transfer transition.
+ * @property amountAtomic Source amount expressed in the Aleo token's base units.
+ * @property usesPlaceholderConfiguration Whether unresolved deployment values make the call unsafe to submit.
+ * @property placeholderFields Registry fields that must be replaced before submission is enabled.
+ */
+type AleoHyperlaneTransferRemoteCall = {
+    routeId: string;
+    program: string;
+    function: 'transfer_remote' | 'transfer_remote_as_signer';
+    inputs: TransactionInput[];
+    amountAtomic: bigint;
+    usesPlaceholderConfiguration: boolean;
+    placeholderFields: readonly string[];
+};
+/**
+ * Configures construction or submission of an Aleo Hyperlane withdrawal.
+ *
+ * @property plan Aleo-origin Hyperlane plan returned by `prepareTransfer`.
+ * @property mode Whether the program burns from `self.caller` or the EOA-bound `self.signer`. Defaults to `caller`.
+ * @property privateFee Whether the Aleo wallet should pay its fee privately. Defaults to false.
+ */
+type ExecuteAleoHyperlaneTransferRemoteParameters = {
+    plan: BridgeTransferPlan;
+    mode?: 'caller' | 'signer' | undefined;
+    privateFee?: boolean | undefined;
+};
+/**
+ * Captures a submitted Aleo Hyperlane dispatch.
+ *
+ * @property transactionId Aleo transaction id returned by the connected wallet.
+ * @property receipt Resumable receipt awaiting Hyperlane delivery.
+ */
+type AleoHyperlaneTransferRemoteExecution = {
+    transactionId: string;
+    receipt: BridgeTransferReceipt;
+};
+
+/**
+ * Sends JSON-RPC requests through an injected or application-provided EVM wallet.
+ *
+ * The shape is compatible with EIP-1193 providers exposed by wallets such as
+ * MetaMask and Phantom. The bridge package never reads a runtime global.
+ *
+ * @property request Executes one EIP-1193 request, which may prompt the wallet for transaction approval.
+ * @property account Optional connected account. When omitted, the executor resolves the first `eth_accounts` entry.
+ */
+type EvmBridgeExecutor = {
+    request: (args: {
+        method: string;
+        params?: readonly unknown[] | Record<string, unknown> | undefined;
+    }) => Promise<unknown>;
+    account?: Address | undefined;
+};
+/**
+ * Groups optional chain executors supplied to a bridge client.
+ *
+ * @property evm EIP-1193 executor used by Ethereum bridge actions when present.
+ * @property aleo Wallet client used only for user-authorized Aleo transactions such as private USDCx minting.
+ */
+type BridgeExecutors = {
+    evm?: EvmBridgeExecutor | undefined;
+    aleo?: AleoBridgeExecutor | undefined;
+};
+/** Identifies the Ethereum Hyperlane router's collateral model. */
+type EvmHyperlaneRouterType = 'native' | 'collateral';
+/**
+ * Captures the reviewed metadata required to dispatch an Ethereum Warp Route transfer.
+ *
+ * @property routerAddress Contract receiving `transferRemote`.
+ * @property sourceChainId EIP-155 chain id expected from the connected wallet.
+ * @property destinationDomain Hyperlane domain passed to `transferRemote` as a uint32.
+ * @property routerType Whether the router locks native ETH or ERC-20 collateral.
+ * @property tokenAddress ERC-20 collateral contract. Required for collateral routers.
+ * @property destinationRouter Protocol-native identifier of the enrolled Aleo router.
+ * @property mailboxAddress Ethereum Hyperlane Mailbox used by the reviewed deployment.
+ * @property interchainGasPaymaster Ethereum gas-paymaster identifier used by the reviewed deployment.
+ * @property interchainSecurityModule Route-specific ISM, or the zero address when the Mailbox default applies.
+ * @property registryCommit Hyperlane Registry commit containing the deployment snapshot.
+ * @property requiresApprovalReset Whether a non-zero ERC-20 allowance must be reset before changing it.
+ */
+type EvmHyperlaneRouteMetadata = {
+    routerAddress: Address;
+    sourceChainId: number;
+    destinationDomain: number;
+    routerType: EvmHyperlaneRouterType;
+    tokenAddress?: Address | undefined;
+    destinationRouter: string;
+    mailboxAddress: Address;
+    interchainGasPaymaster: Address;
+    interchainSecurityModule: Address;
+    registryCommit: string;
+    requiresApprovalReset?: boolean | undefined;
+};
+/**
+ * Selects a prepared Ethereum Hyperlane transfer for live fee quoting.
+ *
+ * @property plan Pure transfer plan returned by `prepareTransfer`.
+ * @property recipientBytes32 Aleo recipient in the exact 32-byte encoding expected by the enrolled Warp Route.
+ */
+type QuoteEvmHyperlaneTransferParameters = {
+    plan: BridgeTransferPlan;
+    recipientBytes32: Hex;
+};
+/**
+ * Captures the atomic values required by an Ethereum Warp Route transaction.
+ *
+ * @property routeId Route whose deployment and amount were quoted.
+ * @property routerAddress Contract that supplied the quote.
+ * @property sourceChainId EIP-155 chain id on which submission must occur.
+ * @property destinationDomain Hyperlane destination domain supplied to the router.
+ * @property recipientBytes32 Wire-format destination recipient.
+ * @property amountAtomic Asset amount passed to `transferRemote`.
+ * @property nativeValueAtomic Total `msg.value` required by the router.
+ * @property nativeFeeAtomic Native fee above the bridged amount for native routes, or the full native fee for collateral routes.
+ * @property tokenAmountAtomic ERC-20 amount requiring allowance for collateral routes.
+ * @property tokenAddress ERC-20 collateral contract for collateral routes.
+ */
+type EvmHyperlaneTransferQuote = {
+    routeId: string;
+    routerAddress: Address;
+    sourceChainId: number;
+    destinationDomain: number;
+    recipientBytes32: Hex;
+    amountAtomic: bigint;
+    nativeValueAtomic: bigint;
+    nativeFeeAtomic: bigint;
+    tokenAmountAtomic?: bigint | undefined;
+    tokenAddress?: Address | undefined;
+};
+/**
+ * Configures an Ethereum Hyperlane submission.
+ *
+ * The action requotes immediately before submission. ERC-20 allowance is
+ * checked first and only insufficient allowances generate approval calls.
+ *
+ * @property plan Pure transfer plan returned by `prepareTransfer`.
+ * @property recipientBytes32 Aleo recipient in the exact 32-byte encoding expected by the enrolled Warp Route.
+ * @property pollingIntervalMs Delay between transaction-receipt checks. Defaults to 1,000 milliseconds.
+ * @property confirmationTimeoutMs Maximum time to wait for each approval or dispatch receipt. Defaults to 120,000 milliseconds; a timeout returns resumable pending state.
+ */
+type ExecuteEvmHyperlaneTransferParameters = {
+    plan: BridgeTransferPlan;
+    recipientBytes32: Hex;
+    pollingIntervalMs?: number | undefined;
+    confirmationTimeoutMs?: number | undefined;
+};
+/**
+ * Captures wallet transactions and resumable Hyperlane progress after execution.
+ *
+ * @property receipt Protocol-neutral transfer state, including the source transaction and message id when confirmed.
+ * @property approvalTxIds ERC-20 approval transactions submitted before dispatch.
+ */
+type EvmHyperlaneTransferExecution = {
+    receipt: BridgeTransferReceipt;
+    approvalTxIds: Hash[];
+};
+
+/**
+ * Carries registry defaults from client construction into bound actions.
+ *
+ * @property environment Environment applied when an action omits its filter.
+ * @property registry Reviewed snapshot supplying chains, assets, and routes.
+ * @property executors Optional wallet capabilities injected at construction.
+ * @property xReserveHttpTransport Optional HTTP capability for Circle attestation lookups.
+ */
+type BridgeActionsConfig = {
+    environment: BridgeEnvironment;
+    registry: BridgeRegistry;
+    executors?: BridgeExecutors | undefined;
+    xReserveHttpTransport?: XReserveHttpTransport | undefined;
+};
+/**
+ * Lists the protocol-oriented actions bound to a bridge client.
+ *
+ * @property getAssets Lists chain-specific registry assets without network access.
+ * @property getRoutes Lists directional registry routes without network access.
+ * @property prepareTransfer Validates inputs and returns a non-fund-moving execution plan.
+ * @property quoteEvmHyperlaneTransfer Reads live Ethereum Warp Route fees without signing.
+ * @property executeEvmHyperlaneTransfer Approves collateral when needed, then signs and dispatches through the Ethereum wallet.
+ * @property quoteEvmXReserveTransfer Reads USDC balance and allowance and derives Circle deposit inputs.
+ * @property executeEvmXReserveTransfer Approves USDC when needed and submits the Circle deposit.
+ * @property getXReserveAttestation Fetches one Circle attestation by message hash.
+ * @property executeXReservePrivateMint Prompts the Aleo wallet for the wrapper private mint.
+ * @property executeXReserveBurn Prompts the Aleo wallet for one of the reviewed USDCx burn transitions.
+ * @property buildAleoHyperlaneTransferRemoteCall Constructs the seven-input Aleo Warp Route call without wallet access.
+ * @property executeAleoHyperlaneTransferRemote Submits only fully reviewed, non-placeholder Aleo Warp Route calls.
+ */
+type BridgeActions = {
+    getAssets: (params?: GetProtocolAssetsParameters) => ProtocolBridgeAsset[];
+    getRoutes: (params?: GetProtocolRoutesParameters) => ProtocolBridgeRoute[];
+    prepareTransfer: (params: PrepareTransferParameters) => BridgeTransferPlan;
+    quoteEvmHyperlaneTransfer: (params: QuoteEvmHyperlaneTransferParameters) => Promise<EvmHyperlaneTransferQuote>;
+    executeEvmHyperlaneTransfer: (params: ExecuteEvmHyperlaneTransferParameters) => Promise<EvmHyperlaneTransferExecution>;
+    quoteEvmXReserveTransfer: (params: QuoteEvmXReserveTransferParameters) => Promise<EvmXReserveTransferQuote>;
+    executeEvmXReserveTransfer: (params: ExecuteEvmXReserveTransferParameters) => Promise<EvmXReserveTransferExecution>;
+    getXReserveAttestation: (params: GetXReserveAttestationParameters) => Promise<XReserveAttestationResult>;
+    executeXReservePrivateMint: (params: ExecuteXReservePrivateMintParameters) => Promise<XReservePrivateMintExecution>;
+    executeXReserveBurn: (params: ExecuteXReserveBurnParameters) => Promise<XReserveBurnExecution>;
+    buildAleoHyperlaneTransferRemoteCall: (params: ExecuteAleoHyperlaneTransferRemoteParameters) => AleoHyperlaneTransferRemoteCall;
+    executeAleoHyperlaneTransferRemote: (params: ExecuteAleoHyperlaneTransferRemoteParameters) => Promise<AleoHyperlaneTransferRemoteExecution>;
+};
+/**
+ * Binds registry discovery and transfer planning to a client.
+ *
+ * Discovery and planning are pure and local. EVM actions use the optional
+ * executor injected through the configuration and fail before network access
+ * when it is absent.
+ *
+ * @param client Client receiving the action layer.
+ * @param config Registry and default environment selected at construction.
+ * @returns Bound protocol bridge actions.
+ *
+ * @example
+ * const actions = bridgeActions(client, { environment: 'mainnet', registry })
+ */
+declare function bridgeActions(_client: Client, config: BridgeActionsConfig): BridgeActions;
+
+/**
+ * Configures a protocol bridge client.
+ *
+ * @property environment Routes and assets exposed by default. Defaults to `mainnet`.
+ * @property registry Reviewed protocol deployment snapshot. Defaults to {@link DEFAULT_BRIDGE_REGISTRY}.
+ * @property executors Optional wallet capabilities used by fund-moving protocol actions.
+ * @property xReserveHttpTransport Optional fetch-compatible transport used for Circle attestation requests.
+ * @property key Client identifier. Defaults to `bridge`.
+ * @property name Human-readable client name. Defaults to `Bridge Client`.
+ */
+type BridgeClientConfig = {
+    environment?: BridgeEnvironment | undefined;
+    registry?: BridgeRegistry | undefined;
+    executors?: BridgeExecutors | undefined;
+    xReserveHttpTransport?: XReserveHttpTransport | undefined;
+    key?: string | undefined;
+    name?: string | undefined;
+};
+type BridgeClientState = {
+    environment: BridgeEnvironment;
+    registry: BridgeRegistry;
+};
+/**
+ * Exposes protocol bridge discovery, planning, and configured execution actions.
+ *
+ * The client retains Veil's `extend()` composition model. Its base transport
+ * is reserved for protocol executors. Discovery and planning remain pure and
+ * local; execution actions require the corresponding injected capability.
+ */
+type BridgeClient = Client<BridgeActions & BridgeClientState>;
+/**
+ * Creates a protocol-oriented bridge client for xReserve and Hyperlane.
+ *
+ * Discovery and transfer planning read the configured registry without network
+ * access. An injected EVM executor enables Ethereum Hyperlane quote and execution
+ * actions without exposing private keys to the client. An injected Aleo wallet
+ * client enables user-authorized private USDCx mints and USDCx burns.
+ *
+ * @param config Optional environment, registry, executors, and client identity.
+ * @returns A bridge client exposing discovery, planning, and configured protocol actions.
+ * @throws BridgeError When the supplied registry has invalid references.
+ *
+ * @example
+ * const bridge = createBridgeClient({ environment: 'testnet' })
+ * const routes = bridge.getRoutes({ protocol: 'xreserve' })
+ */
+declare function createBridgeClient(config?: BridgeClientConfig): BridgeClient;
+
+export { type XReserveHttpResponse as $, type AleoBridgeExecutor as A, type BridgeRegistry as B, type BridgeExecutionStep as C, type BridgeExecutionStepKind as D, type EvmBridgeExecutor as E, type BridgeExecutors as F, type GetXReserveAttestationParameters as G, type BridgeFee as H, type BridgeProtocol as I, type BridgeQuoteStatus as J, type BridgeRouteAvailability as K, type BridgeStepExecutor as L, type BridgeTransferQuote as M, type BridgeTransferReceipt as N, type BridgeTransferStatus as O, type PrepareTransferParameters as P, type QuoteEvmHyperlaneTransferParameters as Q, type EvmHyperlaneRouteMetadata as R, type EvmHyperlaneRouterType as S, type EvmXReserveRouteMetadata as T, type GetProtocolAssetsParameters as U, type GetProtocolRoutesParameters as V, type ProtocolBridgeAsset as W, type XReserveHttpTransport as X, type ProtocolBridgeChain as Y, type ProtocolBridgeRoute as Z, type XReserveBurnMode as _, type BridgeTransferPlan as a, bridgeActions as a0, createBridgeClient as a1, getProtocolAssets as a2, getProtocolRoutes as a3, type ExecuteEvmHyperlaneTransferParameters as b, type EvmHyperlaneTransferExecution as c, type EvmHyperlaneTransferQuote as d, type ExecuteEvmXReserveTransferParameters as e, type EvmXReserveTransferExecution as f, type XReserveAttestationResult as g, type QuoteEvmXReserveTransferParameters as h, type EvmXReserveTransferQuote as i, type ExecuteXReservePrivateMintParameters as j, type XReservePrivateMintExecution as k, type ExecuteXReserveBurnParameters as l, type XReserveBurnCall as m, type XReserveBurnExecution as n, type ExecuteAleoHyperlaneTransferRemoteParameters as o, type AleoHyperlaneTransferRemoteCall as p, type AleoHyperlaneTransferRemoteExecution as q, type BridgeEnvironment as r, type AleoMintMode as s, type BridgeActions as t, type BridgeActionsConfig as u, type BridgeAssetKind as v, type BridgeAssetLocator as w, type BridgeChainFamily as x, type BridgeClient as y, type BridgeClientConfig as z };