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

package/dist/index.d.ts

@@ -0,0 +1,421 @@
+import { B as BridgeRegistry, P as PrepareTransferParameters, a as BridgeTransferPlan, E as EvmBridgeExecutor, b as ExecuteEvmHyperlaneTransferParameters, c as EvmHyperlaneTransferExecution, Q as QuoteEvmHyperlaneTransferParameters, d as EvmHyperlaneTransferQuote, e as ExecuteEvmXReserveTransferParameters, f as EvmXReserveTransferExecution, X as XReserveHttpTransport, G as GetXReserveAttestationParameters, g as XReserveAttestationResult, h as QuoteEvmXReserveTransferParameters, i as EvmXReserveTransferQuote, A as AleoBridgeExecutor, j as ExecuteXReservePrivateMintParameters, k as XReservePrivateMintExecution, l as ExecuteXReserveBurnParameters, m as XReserveBurnCall, n as XReserveBurnExecution, o as ExecuteAleoHyperlaneTransferRemoteParameters, p as AleoHyperlaneTransferRemoteCall, q as AleoHyperlaneTransferRemoteExecution, r as BridgeEnvironment, s as AleoMintMode } from './createBridgeClient-CjHY-JvW.js';
+export { t as BridgeActions, u as BridgeActionsConfig, v as BridgeAssetKind, w as BridgeAssetLocator, x as BridgeChainFamily, y as BridgeClient, z as BridgeClientConfig, C as BridgeExecutionStep, D as BridgeExecutionStepKind, F as BridgeExecutors, H as BridgeFee, I as BridgeProtocol, J as BridgeQuoteStatus, K as BridgeRouteAvailability, L as BridgeStepExecutor, M as BridgeTransferQuote, N as BridgeTransferReceipt, O as BridgeTransferStatus, R as EvmHyperlaneRouteMetadata, S as EvmHyperlaneRouterType, T as EvmXReserveRouteMetadata, U as GetAssetsParameters, V as GetRoutesParameters, W as ProtocolBridgeAsset, Y as ProtocolBridgeChain, Z as ProtocolBridgeRoute, _ as XReserveBurnMode, $ as XReserveHttpResponse, a0 as bridgeActions, a1 as createBridgeClient, a2 as getAssets, a3 as getRoutes } from './createBridgeClient-CjHY-JvW.js';
+import { Hex, Address, Hash } from 'viem';
+import '@provablehq/veil-core';
+
+/**
+ * Prepares the ordered operations for a protocol bridge transfer.
+ *
+ * Pure and local: validates the route, amount, and recipient, then returns a
+ * serializable plan. It does not query fees, sign, submit, or move funds.
+ * Routes marked `metadata-required` can be planned but cannot be executed until
+ * a later protocol adapter validates their deployment metadata.
+ *
+ * @param registry Reviewed registry snapshot.
+ * @param params Route, decimal amount, recipient, and optional sender/privacy mode.
+ * @returns A resumable transfer plan with the irreversible step identified.
+ * @throws BridgeError When the route is missing or disabled, the amount is zero
+ *   or malformed, its precision exceeds either asset, or the recipient fails validation.
+ *
+ * @example
+ * const plan = prepareTransfer(registry, {
+ *   routeId: 'xreserve:ethereum/usdc->aleo/usdcx',
+ *   amount: '25',
+ *   recipient: 'aleo1...',
+ * })
+ */
+declare function prepareTransfer(registry: BridgeRegistry, params: PrepareTransferParameters): BridgeTransferPlan;
+
+/**
+ * Quotes an Ethereum-to-Aleo Hyperlane Warp Route transfer.
+ *
+ * Calls the reviewed router's `quoteTransferRemote` through the supplied EIP-1193
+ * executor. The call reads live state but does not request a signature or move funds.
+ *
+ * @param registry Reviewed deployment snapshot used to validate the prepared plan.
+ * @param executor Connected EVM provider used for the read-only contract call.
+ * @param params Prepared plan and exact 32-byte Aleo recipient encoding.
+ * @returns Atomic native payment and ERC-20 allowance requirements.
+ * @throws BridgeError When the route is not an active Ethereum source route, metadata is incomplete, the wallet is on the wrong chain, or the router returns an unusable quote.
+ *
+ * @example
+ * const quote = await quoteEvmHyperlaneTransfer(registry, executor, {
+ *   plan,
+ *   recipientBytes32: '0x20e3629764d5338f74bee96675801b1fb29d1fc68b177668f9175708bef84311',
+ * })
+ */
+declare function quoteEvmHyperlaneTransfer(registry: BridgeRegistry, executor: EvmBridgeExecutor, params: QuoteEvmHyperlaneTransferParameters): Promise<EvmHyperlaneTransferQuote>;
+/**
+ * Approves collateral when needed and dispatches an Ethereum Hyperlane transfer.
+ *
+ * Requotes immediately before submission, checks the connected chain and account,
+ * and waits for approval receipts before dispatch. USDT routes reset an existing
+ * non-zero allowance before setting a new one. Calls can prompt the wallet and move funds.
+ *
+ * @param registry Reviewed deployment snapshot used to validate the prepared plan.
+ * @param executor Connected EIP-1193 wallet used to read, sign, and submit transactions.
+ * @param params Prepared plan, wire recipient, and optional receipt polling controls.
+ * @returns Submitted transaction ids plus resumable transfer state. Receipt timeouts return a pending state and do not report failure.
+ * @throws BridgeError When validation, quoting, wallet submission, or a confirmed transaction fails.
+ *
+ * @example
+ * const execution = await executeEvmHyperlaneTransfer(registry, executor, {
+ *   plan,
+ *   recipientBytes32: '0x20e3629764d5338f74bee96675801b1fb29d1fc68b177668f9175708bef84311',
+ * })
+ */
+declare function executeEvmHyperlaneTransfer(registry: BridgeRegistry, executor: EvmBridgeExecutor, params: ExecuteEvmHyperlaneTransferParameters): Promise<EvmHyperlaneTransferExecution>;
+
+/**
+ * Reads live USDC balance and xReserve allowance for a prepared deposit.
+ *
+ * Derives the hook and wire recipient before performing read-only EVM calls. It
+ * does not request a signature or move funds.
+ *
+ * @param registry Reviewed deployment snapshot used to validate the plan.
+ * @param executor Connected EIP-1193 provider used for contract reads.
+ * @param params Prepared Ethereum-to-Aleo xReserve plan.
+ * @returns Atomic deposit values, account balance, allowance, and approval requirement.
+ * @throws BridgeError When metadata, wallet state, amount, balance, or recipient is invalid.
+ *
+ * @example
+ * const quote = await quoteEvmXReserveTransfer(registry, executor, { plan })
+ */
+declare function quoteEvmXReserveTransfer(registry: BridgeRegistry, executor: EvmBridgeExecutor, params: QuoteEvmXReserveTransferParameters): Promise<EvmXReserveTransferQuote>;
+/**
+ * Approves USDC when needed and submits a nonpayable Circle xReserve deposit.
+ *
+ * Calls the wallet for each required signature, confirms the approval before
+ * depositing, and derives the Circle message hash from the confirmed event.
+ *
+ * @param registry Reviewed deployment snapshot used to validate the plan.
+ * @param executor Connected EIP-1193 wallet used to read, sign, and submit.
+ * @param params Prepared plan and optional receipt polling controls.
+ * @returns Submitted approval ids and resumable xReserve transfer state.
+ * @throws BridgeError When validation, submission, confirmation, or event verification fails.
+ *
+ * @example
+ * const execution = await executeEvmXReserveTransfer(registry, executor, { plan })
+ */
+declare function executeEvmXReserveTransfer(registry: BridgeRegistry, executor: EvmBridgeExecutor, params: ExecuteEvmXReserveTransferParameters): Promise<EvmXReserveTransferExecution>;
+/**
+ * Fetches and validates one Circle attestation, treating HTTP 404 as pending.
+ *
+ * Performs one request through the injected transport. Completed responses are
+ * checked against the requested message hash before being returned.
+ *
+ * @param registry Reviewed snapshot supplying the Circle endpoint.
+ * @param transport Fetch-compatible HTTP capability supplied by the application.
+ * @param params Route, message hash, and optional cancellation signal.
+ * @returns Pending state or the verified payload and Circle signature.
+ * @throws BridgeError For invalid routes, HTTP failures other than 404, or malformed responses.
+ *
+ * @example
+ * const result = await getXReserveAttestation(registry, fetchTransport, { routeId, messageHash })
+ */
+declare function getXReserveAttestation(registry: BridgeRegistry, transport: XReserveHttpTransport, params: GetXReserveAttestationParameters): Promise<XReserveAttestationResult>;
+
+/**
+ * Submits the sole user-authorized Aleo mint in the inbound bridge flows.
+ *
+ * Requires a private xReserve plan and a completed Circle attestation. The
+ * wallet calls the wrapper's `private_mint` with the canonical 305-byte payload,
+ * 65-byte signature, 32-byte hash, the plan's secret nonce, and intended recipient. Hyperlane
+ * and non-private xReserve destination mints remain relayer-driven.
+ *
+ * @param registry Reviewed deployment snapshot used to resolve the wrapper program.
+ * @param executor Connected Aleo wallet client that proves, signs, and broadcasts.
+ * @param params Original plan, confirmed deposit, Circle attestation, and fee privacy choice.
+ * @returns The Aleo transaction id and destination-confirming transfer receipt.
+ * @throws BridgeError When the plan is not private, identifiers disagree, inputs have invalid widths, or the wallet returns no transaction id.
+ *
+ * @example
+ * const mint = await executeXReservePrivateMint(registry, aleoWalletClient, {
+ *   plan,
+ *   deposit: depositExecution.receipt,
+ *   attestation,
+ * })
+ */
+declare function executeXReservePrivateMint(registry: BridgeRegistry, executor: AleoBridgeExecutor, params: ExecuteXReservePrivateMintParameters): Promise<XReservePrivateMintExecution>;
+
+/**
+ * Builds one validated Aleo USDCx burn call without prompting a wallet.
+ *
+ * Pure and local: fixes Ethereum's Circle domain to `0u32`, encodes the EVM
+ * recipient as `[u8; 32]`, and selects the bridge or wrapper transition. Dynamic
+ * pause, freeze-list, and burn-limit checks remain atomic on-chain assertions.
+ *
+ * @param registry Reviewed route snapshot supplying the deployed Aleo programs and domain.
+ * @param params Prepared reverse route, burn mode, and private inputs when applicable.
+ * @returns Exact program, function, and ordered wallet inputs for the burn.
+ * @throws BridgeError When the route, amount, recipient, mode-specific inputs, or metadata is invalid.
+ *
+ * @example
+ * const call = buildXReserveBurnCall(registry, { plan, mode: 'public-as-signer' })
+ */
+declare function buildXReserveBurnCall(registry: BridgeRegistry, params: ExecuteXReserveBurnParameters): XReserveBurnCall;
+/**
+ * Prompts an Aleo wallet to submit a public, signer-bound, or private USDCx burn.
+ *
+ * The action returns after broadcast. The Aleo-operated burn attestation service
+ * observes accepted burns and forwards them to Circle without another client call.
+ *
+ * @param registry Reviewed route snapshot used to validate program and domain identifiers.
+ * @param executor Connected Aleo wallet client that proves, signs, and broadcasts.
+ * @param params Prepared reverse route, selected mode, optional record/proof, and fee privacy.
+ * @returns The Aleo transaction id and resumable source-confirming receipt.
+ * @throws BridgeError When call construction fails or the wallet returns no transaction id.
+ *
+ * @example
+ * const burn = await executeXReserveBurn(registry, aleoWalletClient, {
+ *   plan,
+ *   userRecord,
+ *   merkleProof,
+ * })
+ */
+declare function executeXReserveBurn(registry: BridgeRegistry, executor: AleoBridgeExecutor, params: ExecuteXReserveBurnParameters): Promise<XReserveBurnExecution>;
+
+/**
+ * Builds an Aleo Hyperlane `transfer_remote` call without prompting a wallet.
+ *
+ * The default registry deliberately produces non-executable calls containing
+ * conspicuous placeholder deployment values. This makes the complete seven-input
+ * ABI inspectable while preventing those values from being mistaken for live data.
+ *
+ * @param registry Reviewed route snapshot supplying the Aleo Warp Route configuration.
+ * @param params Prepared Aleo-origin Hyperlane plan.
+ * @returns Exact program, transition, and ordered Aleo inputs.
+ * @throws BridgeError When the plan or route metadata is inconsistent.
+ *
+ * @example
+ * const call = buildAleoHyperlaneTransferRemoteCall(registry, { plan })
+ */
+declare function buildAleoHyperlaneTransferRemoteCall(registry: BridgeRegistry, params: ExecuteAleoHyperlaneTransferRemoteParameters): AleoHyperlaneTransferRemoteCall;
+/**
+ * Submits a fully configured Aleo Hyperlane `transfer_remote` transaction.
+ *
+ * Default-registry calls fail before wallet access because their deployment
+ * values are placeholders. Submission becomes available only after a reviewed
+ * registry removes the placeholder flag and supplies every required value.
+ *
+ * @param registry Reviewed route snapshot supplying the Aleo Warp Route configuration.
+ * @param executor Connected Aleo wallet client that proves, signs, and broadcasts.
+ * @param params Prepared Aleo-origin Hyperlane plan and fee preference.
+ * @returns The Aleo transaction id and resumable Hyperlane receipt.
+ * @throws BridgeError When configuration is placeholder, invalid, or the wallet returns no id.
+ */
+declare function executeAleoHyperlaneTransferRemote(registry: BridgeRegistry, executor: AleoBridgeExecutor, params: ExecuteAleoHyperlaneTransferRemoteParameters): Promise<AleoHyperlaneTransferRemoteExecution>;
+
+/**
+ * Supplies the initial reviewed protocol-route snapshot.
+ *
+ * xReserve contract identifiers are populated from Circle's published
+ * mainnet and testnet tables. Hyperlane routes intentionally remain
+ * `metadata-required` until their router, domain, ISM, and token identifiers
+ * are pinned from one reviewed registry commit. Pure and local.
+ *
+ * @example
+ * const bridge = createBridgeClient({ registry: DEFAULT_BRIDGE_REGISTRY })
+ */
+declare const DEFAULT_BRIDGE_REGISTRY: BridgeRegistry;
+
+/**
+ * Validates the referential integrity of a protocol bridge registry.
+ *
+ * Pure and local. Duplicate identifiers and dangling asset/chain references
+ * throw before a client can prepare a misleading transfer plan.
+ *
+ * @param registry Registry supplied to `createBridgeClient`.
+ * @returns The validated registry unchanged.
+ * @throws BridgeError When identifiers are duplicated or references are missing.
+ *
+ * @example
+ * const registry = validateBridgeRegistry(DEFAULT_BRIDGE_REGISTRY)
+ */
+declare function validateBridgeRegistry(registry: BridgeRegistry): BridgeRegistry;
+
+/**
+ * Decodes a checksummed Aleo bech32m address into xReserve bytes32 form.
+ *
+ * Pure and local; validates the prefix, length, checksum, padding, and payload width.
+ *
+ * @param address Aleo account address to encode.
+ * @returns Exactly 32 decoded bytes as prefixed hexadecimal.
+ * @throws BridgeError When the address has invalid bech32m structure.
+ *
+ * @example
+ * const recipient = aleoAddressToBytes32('aleo1…')
+ */
+declare function aleoAddressToBytes32(address: string): Hex;
+/**
+ * Derives the Aleo account address owned by a deployed program id.
+ *
+ * Lazily loads the optional Aleo WASM SDK but performs no network access.
+ *
+ * @param programId Deployed Aleo program id whose account receives funds.
+ * @param environment Consensus environment used for address derivation.
+ * @returns The program-owned `aleo1…` account address.
+ * @throws BridgeError When the optional SDK is unavailable or derivation fails.
+ *
+ * @example
+ * const wrapper = await aleoProgramAddress('shielded_usdcx_wrapper.aleo', 'mainnet')
+ */
+declare function aleoProgramAddress(programId: string, environment: BridgeEnvironment): Promise<string>;
+/**
+ * Builds the fixed 65-byte xReserve hook for public, record, or wrapper-private minting.
+ *
+ * Public and record hooks are pure and local. Private hooks lazily load Aleo WASM
+ * to commit the intended recipient with BHP256 and the selected secret nonce.
+ *
+ * @param mode Destination mint transition selected by the caller.
+ * @param recipient Intended Aleo recipient committed by private mode.
+ * @param environment Consensus environment used by private commitment derivation.
+ * @param secretNonce Aleo scalar literal used by the private commitment. Defaults to `0scalar`.
+ * @returns A 65-byte hook whose first byte is 0, 1, or 2.
+ * @throws BridgeError When private derivation lacks the optional SDK or the secret nonce is not a valid Aleo scalar.
+ *
+ * @example
+ * const hook = await buildXReserveHookData('record', recipient, 'testnet')
+ */
+declare function buildXReserveHookData(mode: AleoMintMode, recipient: string, environment: BridgeEnvironment, secretNonce?: string): Promise<Hex>;
+/**
+ * Derives the Circle deposit nonce from source domain, transaction hash, and log index.
+ *
+ * Pure and local; follows Circle's ABI-padded nonce preimage exactly.
+ *
+ * @param sourceDomain Circle domain of the source xReserve contract.
+ * @param transactionHash Confirmed deposit transaction hash.
+ * @param logIndex Zero-based `DepositedToRemote` receipt log index.
+ * @returns The Keccak-256 deposit nonce.
+ *
+ * @example
+ * const nonce = calculateXReserveDepositNonce(0, txHash, 3)
+ */
+declare function calculateXReserveDepositNonce(sourceDomain: number, transactionHash: Hash, logIndex: number): Hash;
+/**
+ * Builds the canonical 305-byte Circle xReserve v2 deposit payload.
+ *
+ * Pure and local; rejects fields with invalid wire widths before constructing the payload.
+ *
+ * @param params Event-derived deposit values and reviewed route identifiers.
+ * @returns The exact payload submitted to Circle's attester.
+ * @throws BridgeError When a value is invalid or exceeds its wire width.
+ *
+ * @example
+ * const payload = buildXReserveDepositPayload(fields)
+ */
+declare function buildXReserveDepositPayload(params: {
+    amount: bigint;
+    remoteDomain: number;
+    remoteToken: Hex;
+    remoteRecipient: Hex;
+    localToken: Address;
+    depositor: Address;
+    maxFee: bigint;
+    nonce: Hash;
+    hookData: Hex;
+}): Hex;
+/**
+ * Hashes a canonical xReserve deposit payload for Circle attestation lookup.
+ *
+ * Pure and local; computes Keccak-256 without contacting Circle.
+ *
+ * @param payload Canonical xReserve deposit bytes.
+ * @returns The 32-byte Circle message hash.
+ *
+ * @example
+ * const messageHash = calculateXReserveMessageHash(payload)
+ */
+declare function calculateXReserveMessageHash(payload: Hex): Hash;
+/**
+ * Formats fixed-width hexadecimal bytes as an Aleo `[u8; N]` literal.
+ *
+ * Pure and local; validates the exact byte width before formatting inputs for a wallet.
+ *
+ * @param value Prefixed hexadecimal bytes to format.
+ * @param expectedBytes Required array width from the target Aleo function.
+ * @returns An Aleo array literal containing decimal `u8` values.
+ * @throws BridgeError When the input is malformed or has the wrong width.
+ *
+ * @example
+ * const hashInput = xReserveHexToAleoBytes(messageHash, 32)
+ */
+declare function xReserveHexToAleoBytes(value: Hex, expectedBytes: number): string;
+/**
+ * Encodes an Ethereum address as the 32-byte recipient required by xReserve burns.
+ *
+ * Pure and local; preserves the 20 address bytes and adds twelve leading zero bytes.
+ *
+ * @param address Checksummed or lowercase Ethereum address selected by the caller.
+ * @returns The address left-padded to exactly 32 bytes.
+ * @throws BridgeError When the address is malformed.
+ *
+ * @example
+ * const recipient = evmAddressToXReserveBytes32('0x0000000000000000000000000000000000000001')
+ */
+declare function evmAddressToXReserveBytes32(address: string): Hex;
+
+/**
+ * Encodes an Ethereum account as the two little-endian limbs used by Aleo Warp Routes.
+ *
+ * Pure and local; validates a 20-byte EVM address, left-pads it to Hyperlane
+ * bytes32 form, and interprets each 16-byte half as an Aleo `u128`.
+ *
+ * @param address Destination Ethereum account supplied by the transfer plan.
+ * @returns Two unsigned 128-bit limbs in Hyperlane message order.
+ * @throws BridgeError When the destination is not a valid 20-byte EVM address.
+ *
+ * @example
+ * const recipient = evmAddressToAleoHyperlaneRecipient('0x1e196d0a7d8189054c4db744ab3340c3f1c68b19')
+ */
+declare function evmAddressToAleoHyperlaneRecipient(address: string): readonly [bigint, bigint];
+/**
+ * Encodes a Solana account as the two little-endian limbs used by Aleo Warp Routes.
+ *
+ * Pure and local; decodes a base58 account to its 32-byte public key and
+ * interprets each 16-byte half as an Aleo `u128`.
+ *
+ * @param address Destination Solana account supplied by the transfer plan.
+ * @returns Two unsigned 128-bit limbs in Hyperlane message order.
+ * @throws BridgeError When the destination is not a base58-encoded 32-byte account.
+ *
+ * @example
+ * const recipient = solanaAddressToAleoHyperlaneRecipient('11111111111111111111111111111111')
+ */
+declare function solanaAddressToAleoHyperlaneRecipient(address: string): readonly [bigint, bigint];
+
+/**
+ * Represents protocol bridge configuration and planning failures.
+ *
+ * @example
+ * try {
+ *   bridge.prepareTransfer(params)
+ * } catch (error) {
+ *   if (error instanceof BridgeError) console.error(error.message)
+ * }
+ */
+declare class BridgeError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+
+/**
+ * Converts a decimal amount string into the asset's atomic units.
+ *
+ * Protocol inputs use display decimals (`"0.5"` ALEO), while onchain calls
+ * use atomic integers (`500000n` microcredits). String arithmetic keeps the
+ * conversion exact without floating-point rounding. Pure and local.
+ *
+ * @param amount Decimal amount as a string (e.g. `"0.5"`, `"100"`).
+ * @param decimals The asset's display decimals (e.g. 6 for ALEO/USDC, 18 for ETH).
+ * @returns The atomic amount as a bigint.
+ * @throws BridgeError When the string is not a plain decimal number, or has
+ *   more fractional digits than the asset supports (that precision cannot be
+ *   represented on chain).
+ *
+ * @example
+ * parseDecimalAmount('0.5', 6)   // 500000n
+ * parseDecimalAmount('100', 6)   // 100000000n
+ */
+declare function parseDecimalAmount(amount: string, decimals: number): bigint;
+
+export { AleoBridgeExecutor, AleoHyperlaneTransferRemoteCall, AleoHyperlaneTransferRemoteExecution, AleoMintMode, BridgeEnvironment, BridgeError, BridgeRegistry, BridgeTransferPlan, DEFAULT_BRIDGE_REGISTRY, EvmBridgeExecutor, EvmHyperlaneTransferExecution, EvmHyperlaneTransferQuote, EvmXReserveTransferExecution, EvmXReserveTransferQuote, ExecuteAleoHyperlaneTransferRemoteParameters, ExecuteEvmHyperlaneTransferParameters, ExecuteEvmXReserveTransferParameters, ExecuteXReserveBurnParameters, ExecuteXReservePrivateMintParameters, GetXReserveAttestationParameters, PrepareTransferParameters, QuoteEvmHyperlaneTransferParameters, QuoteEvmXReserveTransferParameters, XReserveAttestationResult, XReserveBurnCall, XReserveBurnExecution, XReserveHttpTransport, XReservePrivateMintExecution, aleoAddressToBytes32, aleoProgramAddress, buildAleoHyperlaneTransferRemoteCall, buildXReserveBurnCall, buildXReserveDepositPayload, buildXReserveHookData, calculateXReserveDepositNonce, calculateXReserveMessageHash, evmAddressToAleoHyperlaneRecipient, evmAddressToXReserveBytes32, executeAleoHyperlaneTransferRemote, executeEvmHyperlaneTransfer, executeEvmXReserveTransfer, executeXReserveBurn, executeXReservePrivateMint, getXReserveAttestation, parseDecimalAmount, prepareTransfer, quoteEvmHyperlaneTransfer, quoteEvmXReserveTransfer, solanaAddressToAleoHyperlaneRecipient, validateBridgeRegistry, xReserveHexToAleoBytes };