@provablehq/aleo-bridge-sdk 0.8.0-rc.0 → 0.9.0-rc.1

package/README.md

@@ -211,10 +211,11 @@ xReserve entries include Circle's published Ethereum/Sepolia USDC contracts,
 Aleo domain, and USDCx program identifiers. Ethereum-to-Aleo ETH, WBTC, and USDT
 routes pin router, domain, ISM, token, Mailbox, and gas-payment metadata to
 Hyperlane Registry commit `2621c16f2db1ccb46643265c110dac5ca2c7c51a` and are
-active. Reverse and other Hyperlane routes remain `metadata-required` until
-their deployment metadata is complete and reviewed.
+active. The reviewed Aleo-origin ETH, WBTC, USDT, and SOL withdrawal routes are
+also active (reviewed 2026-08-26); other Hyperlane routes remain
+`metadata-required` until their deployment metadata is complete and reviewed.
 
-### Aleo-origin Hyperlane placeholders
+### Aleo-origin Hyperlane withdrawals
 
 The Aleo-origin ETH, WBTC, USDT, SOL, and USAD routes expose the complete
 `transfer_remote` call shape for these programs:
@@ -225,14 +226,22 @@ The Aleo-origin ETH, WBTC, USDT, SOL, and USAD routes expose the complete
 - `hyp_warp_token_sol_v2.aleo`
 - `hyp_warp_token_usad_v2.aleo`
 
-**These routes contain dummy development values and are not executable.** They
-remain `metadata-required`, carry `aleoPlaceholderConfiguration: true`, and
+The ETH, WBTC, USDT, and SOL routes are active. Every static field is reviewed;
+the one dynamic value — the interchain gas paymaster's hook payment — is read
+live from `hyp_hook_manager.aleo/destination_gas_configs` by
+`quoteAleoHyperlaneGasPayment` and passed to execution as
+`gasPaymentMicrocredits`. The on-chain hook asserts the payment exactly equals
+its own recomputed quote, so a stale quote aborts at finalization without
+moving funds, and `executeAleoHyperlaneTransferRemote` throws before wallet
+access when no quote is supplied.
+
+**The USAD route contains dummy development values and is not executable.** It
+remains `metadata-required`, carries `aleoPlaceholderConfiguration: true`, and
 `executeAleoHyperlaneTransferRemote` throws before calling the wallet. Use
-`buildAleoHyperlaneTransferRemoteCall` only to inspect and integrate the ABI
-until the configuration below has been reviewed and replaced.
+`buildAleoHyperlaneTransferRemoteCall` only to inspect and integrate its ABI
+until the configuration has been reviewed and replaced.
 
-Except for the verified ETH, WBTC, USDT, and SOL route data described below,
-the current dummy values are:
+For USAD, the current dummy values are:
 
 - `token_type`: `0u8`; `token_id`: `0field`
 - `token_owner`, `ism`, `hook`, and all four allowance spenders: the same
@@ -246,8 +255,7 @@ The WBTC route is partially populated from mainnet
 [`hyp_warp_token_wbtc_v2.aleo`](https://explorer.provable.com/program/hyp_warp_token_wbtc_v2.aleo),
 edition `0`. Its `app_metadata[true]` token type, owner, ISM, hook, token ID,
 and `8u8` local/remote decimals are verified and are not placeholders. Its
-first hook allowance amount remains unresolved, so the route is still
-non-executable.
+first hook allowance amount is the live gas quote supplied at execution time.
 
 The WBTC Ethereum remote router is also verified: domain `1u32`, recipient
 `0x20CDC85778b732073F7EecEF3DF25c0d310f8772` left-padded to `[u8; 32]`, and
@@ -262,8 +270,8 @@ The ETH route is populated from current mainnet app metadata and the reviewed
 Its Ethereum router is `0x38D447694f5c1f773ae3132cf93bF30B7Ec1Fa5A`,
 left-padded to `[u8; 32]`, with domain `1u32` and gas `44000u128`. The
 transaction's `8174147u64` first allowance is an observed dispatch quote and is
-not stored as a route-wide cap. As with WBTC, only the first hook allowance
-amount remains unresolved. Ethereum recipient limbs are derived from
+not stored as a route-wide cap. As with WBTC, the first hook allowance amount
+is quoted live at execution time. Ethereum recipient limbs are derived from
 `plan.recipient`.
 
 The USDT route uses current edition `1` app metadata and the verified Ethereum
@@ -293,10 +301,11 @@ default ISM, dispatch proxy, owner, and the nonce/process count observed during
 the 2026-08-17 review. The nonce and process count are mutable observations and
 are not transaction inputs.
 
-Before enabling submission, replace and verify every field still reported by
-`placeholderFields` for that route. Implement the dynamic hook credit quote for
-ETH, WBTC, USDT, and SOL. Then remove `aleoPlaceholderConfiguration` and change
-the route availability to `active` in a reviewed registry snapshot.
+Before enabling USAD submission, replace and verify every field still reported
+by `placeholderFields` for that route. Then remove
+`aleoPlaceholderConfiguration` and change the route availability to `active` in
+a reviewed registry snapshot, as the 2026-08-26 review did for ETH, WBTC, USDT,
+and SOL.
 
 ## Exports
 
@@ -321,5 +330,5 @@ fund-moving wallet actions.
 ## Next implementation phases
 
 1. Add protocol delivery tracking for relayer-driven xReserve and Hyperlane mints.
-2. Replace and review the Aleo-origin Hyperlane placeholders, then add destination confirmation.
+2. Replace and review the Aleo-origin USAD placeholders, then add destination confirmation for withdrawals.
 3. Add injected Solana execution and gated protocol testnets.

package/dist/agent/index.d.ts

@@ -1,6 +1,6 @@
 import { AgentTool } from '@provablehq/veil-core/agent';
 export { AgentTool, AgentToolHandler, AgentToolSchema } from '@provablehq/veil-core/agent';
-import { y as BridgeClient } from '../createBridgeClient-CjHY-JvW.js';
+import { C as BridgeClient } from '../createBridgeClient-BwVZIJl1.js';
 import '@provablehq/veil-core';
 import 'viem';
 

package/dist/{createBridgeClient-CjHY-JvW.d.ts → createBridgeClient-BwVZIJl1.d.ts}

@@ -505,6 +505,35 @@ type XReserveBurnExecution = {
     transactionId: string;
     receipt: BridgeTransferReceipt;
 };
+/**
+ * Configures one live Hyperlane hook gas payment quote.
+ *
+ * @property routeId Aleo-origin Hyperlane route whose destination gas is quoted.
+ */
+type QuoteAleoHyperlaneGasPaymentParameters = {
+    routeId: string;
+};
+/**
+ * Captures one live destination gas quote for an Aleo-origin Hyperlane transfer.
+ *
+ * The on-chain hook asserts that the paid amount exactly equals the quote it
+ * recomputes at finalization, so the caller should quote shortly before submission.
+ *
+ * @property routeId Route the quote applies to.
+ * @property gasLimit Destination gas limit charged by the route, after the on-chain 50000 zero-limit fallback.
+ * @property gasOverhead Destination gas overhead added by the interchain gas paymaster.
+ * @property gasPrice Destination gas price reported by the on-chain oracle.
+ * @property exchangeRate Destination-to-Aleo exchange rate reported by the on-chain oracle.
+ * @property paymentMicrocredits Exact hook payment in microcredits (u64) the transfer must allow.
+ */
+type AleoHyperlaneGasQuote = {
+    routeId: string;
+    gasLimit: bigint;
+    gasOverhead: bigint;
+    gasPrice: bigint;
+    exchangeRate: bigint;
+    paymentMicrocredits: bigint;
+};
 /**
  * Describes one locally constructed Aleo Hyperlane transfer call.
  *
@@ -531,11 +560,13 @@ type AleoHyperlaneTransferRemoteCall = {
  * @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.
+ * @property gasPaymentMicrocredits Live hook payment in microcredits (u64) from `quoteAleoHyperlaneGasPayment`. Optional for inspection-only call construction; required for execution.
  */
 type ExecuteAleoHyperlaneTransferRemoteParameters = {
     plan: BridgeTransferPlan;
     mode?: 'caller' | 'signer' | undefined;
     privateFee?: boolean | undefined;
+    gasPaymentMicrocredits?: bigint | undefined;
 };
 /**
  * Captures a submitted Aleo Hyperlane dispatch.
@@ -675,12 +706,14 @@ type EvmHyperlaneTransferExecution = {
  * @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.
+ * @property aleoPublicClient Optional Aleo public client for on-chain reads such as Hyperlane gas quotes.
  */
 type BridgeActionsConfig = {
     environment: BridgeEnvironment;
     registry: BridgeRegistry;
     executors?: BridgeExecutors | undefined;
     xReserveHttpTransport?: XReserveHttpTransport | undefined;
+    aleoPublicClient?: Client | undefined;
 };
 /**
  * Lists the protocol-oriented actions bound to a bridge client.
@@ -696,6 +729,7 @@ type BridgeActionsConfig = {
  * @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 quoteAleoHyperlaneGasPayment Reads the live interchain gas paymaster quote through the injected Aleo public client.
  * @property executeAleoHyperlaneTransferRemote Submits only fully reviewed, non-placeholder Aleo Warp Route calls.
  */
 type BridgeActions = {
@@ -710,6 +744,7 @@ type BridgeActions = {
     executeXReservePrivateMint: (params: ExecuteXReservePrivateMintParameters) => Promise<XReservePrivateMintExecution>;
     executeXReserveBurn: (params: ExecuteXReserveBurnParameters) => Promise<XReserveBurnExecution>;
     buildAleoHyperlaneTransferRemoteCall: (params: ExecuteAleoHyperlaneTransferRemoteParameters) => AleoHyperlaneTransferRemoteCall;
+    quoteAleoHyperlaneGasPayment: (params: QuoteAleoHyperlaneGasPaymentParameters) => Promise<AleoHyperlaneGasQuote>;
     executeAleoHyperlaneTransferRemote: (params: ExecuteAleoHyperlaneTransferRemoteParameters) => Promise<AleoHyperlaneTransferRemoteExecution>;
 };
 /**
@@ -735,6 +770,7 @@ declare function bridgeActions(_client: Client, config: BridgeActionsConfig): Br
  * @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 aleoPublicClient Optional Aleo public client used for on-chain reads such as Hyperlane gas quotes.
  * @property key Client identifier. Defaults to `bridge`.
  * @property name Human-readable client name. Defaults to `Bridge Client`.
  */
@@ -743,6 +779,7 @@ type BridgeClientConfig = {
     registry?: BridgeRegistry | undefined;
     executors?: BridgeExecutors | undefined;
     xReserveHttpTransport?: XReserveHttpTransport | undefined;
+    aleoPublicClient?: Client | undefined;
     key?: string | undefined;
     name?: string | undefined;
 };
@@ -776,4 +813,4 @@ type BridgeClient = Client<BridgeActions & BridgeClientState>;
  */
 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 };
+export { type ProtocolBridgeRoute as $, type AleoBridgeExecutor as A, type BridgeRegistry as B, type BridgeClient as C, type BridgeClientConfig as D, type EvmBridgeExecutor as E, type BridgeExecutionStep as F, type GetXReserveAttestationParameters as G, type BridgeExecutionStepKind as H, type BridgeExecutors as I, type BridgeFee as J, type BridgeProtocol as K, type BridgeQuoteStatus as L, type BridgeRouteAvailability as M, type BridgeStepExecutor as N, type BridgeTransferQuote as O, type PrepareTransferParameters as P, type QuoteEvmHyperlaneTransferParameters as Q, type BridgeTransferReceipt as R, type BridgeTransferStatus as S, type EvmHyperlaneRouteMetadata as T, type EvmHyperlaneRouterType as U, type EvmXReserveRouteMetadata as V, type GetProtocolAssetsParameters as W, type XReserveHttpTransport as X, type GetProtocolRoutesParameters as Y, type ProtocolBridgeAsset as Z, type ProtocolBridgeChain as _, type BridgeTransferPlan as a, type XReserveBurnMode as a0, type XReserveHttpResponse as a1, bridgeActions as a2, createBridgeClient as a3, getProtocolAssets as a4, getProtocolRoutes as a5, 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 QuoteAleoHyperlaneGasPaymentParameters as r, type AleoHyperlaneGasQuote as s, type BridgeEnvironment as t, type AleoMintMode as u, type BridgeActions as v, type BridgeActionsConfig as w, type BridgeAssetKind as x, type BridgeAssetLocator as y, type BridgeChainFamily as z };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-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 { 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 QuoteAleoHyperlaneGasPaymentParameters, s as AleoHyperlaneGasQuote, t as BridgeEnvironment, u as AleoMintMode } from './createBridgeClient-BwVZIJl1.js';
+export { v as BridgeActions, w as BridgeActionsConfig, x as BridgeAssetKind, y as BridgeAssetLocator, z as BridgeChainFamily, C as BridgeClient, D as BridgeClientConfig, F as BridgeExecutionStep, H as BridgeExecutionStepKind, I as BridgeExecutors, J as BridgeFee, K as BridgeProtocol, L as BridgeQuoteStatus, M as BridgeRouteAvailability, N as BridgeStepExecutor, O as BridgeTransferQuote, R as BridgeTransferReceipt, S as BridgeTransferStatus, T as EvmHyperlaneRouteMetadata, U as EvmHyperlaneRouterType, V as EvmXReserveRouteMetadata, W as GetAssetsParameters, Y as GetRoutesParameters, Z as ProtocolBridgeAsset, _ as ProtocolBridgeChain, $ as ProtocolBridgeRoute, a0 as XReserveBurnMode, a1 as XReserveHttpResponse, a2 as bridgeActions, a3 as createBridgeClient, a4 as getAssets, a5 as getRoutes } from './createBridgeClient-BwVZIJl1.js';
+import { Client } from '@provablehq/veil-core';
 import { Hex, Address, Hash } from 'viem';
-import '@provablehq/veil-core';
 
 /**
  * Prepares the ordered operations for a protocol bridge transfer.
@@ -175,17 +175,42 @@ declare function buildXReserveBurnCall(registry: BridgeRegistry, params: Execute
  */
 declare function executeXReserveBurn(registry: BridgeRegistry, executor: AleoBridgeExecutor, params: ExecuteXReserveBurnParameters): Promise<XReserveBurnExecution>;
 
+/**
+ * Quotes the exact Hyperlane hook payment for one Aleo-origin transfer.
+ *
+ * Reads the interchain gas paymaster's destination gas configuration from
+ * `hyp_hook_manager.aleo` through the supplied Aleo public client and applies
+ * the same formula the hook enforces at finalization:
+ * `(gas_limit + gas_overhead) * gas_price * exchange_rate / 10^10`.
+ * The hook asserts exact equality with its own recomputation, so quote shortly
+ * before submission and requote after any delay. Hits the network; does not sign.
+ *
+ * @param registry Reviewed route snapshot supplying the hook and domain identifiers.
+ * @param client Aleo public client whose transport serves the mapping read.
+ * @param params Aleo-origin Hyperlane route to quote.
+ * @returns The oracle components and the exact payment in microcredits (u64).
+ * @throws BridgeError When the route is not an Aleo-origin Hyperlane route, the
+ *   on-chain configuration is missing or unpriced, or the payment overflows u64.
+ *
+ * @example
+ * const quote = await quoteAleoHyperlaneGasPayment(registry, publicClient, {
+ *   routeId: 'hyperlane:aleo/eth->ethereum/eth',
+ * })
+ */
+declare function quoteAleoHyperlaneGasPayment(registry: BridgeRegistry, client: Client, params: QuoteAleoHyperlaneGasPaymentParameters): Promise<AleoHyperlaneGasQuote>;
 /**
  * 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.
+ * Routes still under review produce non-executable calls containing conspicuous
+ * placeholder deployment values, keeping the seven-input ABI inspectable while
+ * preventing those values from being mistaken for live data. Active routes
+ * embed the supplied live gas payment as the hook allowance; without one the
+ * call reports `aleoAllowanceAmount0` as unresolved.
  *
  * @param registry Reviewed route snapshot supplying the Aleo Warp Route configuration.
- * @param params Prepared Aleo-origin Hyperlane plan.
+ * @param params Prepared Aleo-origin Hyperlane plan and optional live gas payment.
  * @returns Exact program, transition, and ordered Aleo inputs.
- * @throws BridgeError When the plan or route metadata is inconsistent.
+ * @throws BridgeError When the plan or route metadata is inconsistent, or the gas payment is not a positive u64.
  *
  * @example
  * const call = buildAleoHyperlaneTransferRemoteCall(registry, { plan })
@@ -194,15 +219,17 @@ declare function buildAleoHyperlaneTransferRemoteCall(registry: BridgeRegistry,
 /**
  * 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.
+ * Submission requires an active reviewed route with no placeholder values and
+ * a live hook gas payment from `quoteAleoHyperlaneGasPayment`. The on-chain
+ * hook asserts the payment exactly equals its own recomputed quote, so a stale
+ * quote aborts at finalization without moving funds.
  *
  * @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.
+ * @param params Prepared Aleo-origin Hyperlane plan, fee preference, and live gas payment.
  * @returns The Aleo transaction id and resumable Hyperlane receipt.
- * @throws BridgeError When configuration is placeholder, invalid, or the wallet returns no id.
+ * @throws BridgeError When configuration is placeholder or inactive, the gas
+ *   payment is absent, or the wallet returns no id.
  */
 declare function executeAleoHyperlaneTransferRemote(registry: BridgeRegistry, executor: AleoBridgeExecutor, params: ExecuteAleoHyperlaneTransferRemoteParameters): Promise<AleoHyperlaneTransferRemoteExecution>;
 
@@ -418,4 +445,4 @@ declare class BridgeError extends Error {
  */
 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 };
+export { AleoBridgeExecutor, AleoHyperlaneGasQuote, AleoHyperlaneTransferRemoteCall, AleoHyperlaneTransferRemoteExecution, AleoMintMode, BridgeEnvironment, BridgeError, BridgeRegistry, BridgeTransferPlan, DEFAULT_BRIDGE_REGISTRY, EvmBridgeExecutor, EvmHyperlaneTransferExecution, EvmHyperlaneTransferQuote, EvmXReserveTransferExecution, EvmXReserveTransferQuote, ExecuteAleoHyperlaneTransferRemoteParameters, ExecuteEvmHyperlaneTransferParameters, ExecuteEvmXReserveTransferParameters, ExecuteXReserveBurnParameters, ExecuteXReservePrivateMintParameters, GetXReserveAttestationParameters, PrepareTransferParameters, QuoteAleoHyperlaneGasPaymentParameters, 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, quoteAleoHyperlaneGasPayment, quoteEvmHyperlaneTransfer, quoteEvmXReserveTransfer, solanaAddressToAleoHyperlaneRecipient, validateBridgeRegistry, xReserveHexToAleoBytes };

package/dist/index.js

@@ -955,6 +955,9 @@ async function executeXReserveBurn(registry, executor2, params) {
   };
 }
 
+// src/actions/aleoHyperlane.ts
+import { parsePlaintextValue, readContract } from "@provablehq/veil-core";
+
 // src/utils/hyperlane.ts
 import bs58 from "bs58";
 import { getAddress as getAddress4, hexToBytes as hexToBytes2, isAddress as isAddress4, padHex as padHex2 } from "viem";
@@ -987,6 +990,9 @@ function solanaAddressToAleoHyperlaneRecipient(address) {
 }
 
 // src/actions/aleoHyperlane.ts
+var MAX_U64 = (1n << 64n) - 1n;
+var GAS_QUOTE_SCALE = 10000000000n;
+var ZERO_GAS_LIMIT_FALLBACK = 50000n;
 var PLACEHOLDER_FIELDS = [
   "aleoTokenType",
   "aleoTokenOwner",
@@ -1061,13 +1067,52 @@ function validatedRoute2(registry, params) {
   if (!program.endsWith(".aleo")) throw new BridgeError(`Aleo Warp Route program is invalid: ${route2.id}`);
   return { route: route2, program, destinationChain };
 }
-function allowance(route2, index) {
-  return `{ spender: ${metadataString(route2, `aleoAllowanceSpender${index}`)}, amount: ${metadataString(route2, `aleoAllowanceAmount${index}`)}u64 }`;
+function allowance(route2, index, amountOverride) {
+  const amount = amountOverride ?? metadataString(route2, `aleoAllowanceAmount${index}`);
+  return `{ spender: ${metadataString(route2, `aleoAllowanceSpender${index}`)}, amount: ${amount}u64 }`;
+}
+function gasConfigBigint(config, field, routeId) {
+  const value = config[field];
+  if (typeof value !== "bigint" || value < 0n) throw new BridgeError(`Hyperlane gas configuration field ${field} is invalid: ${routeId}`);
+  return value;
+}
+async function quoteAleoHyperlaneGasPayment(registry, client, params) {
+  const route2 = registry.routes.find((entry) => entry.id === params.routeId);
+  if (!route2 || route2.protocol !== "hyperlane") throw new BridgeError(`Hyperlane route is not configured: ${params.routeId}`);
+  const sourceAsset = registry.assets.find((asset) => asset.id === route2.sourceAssetId);
+  const sourceChain = registry.chains.find((chain) => chain.id === sourceAsset?.chainId);
+  if (sourceChain?.family !== "aleo") throw new BridgeError(`Hyperlane gas quotes require an Aleo source asset: ${params.routeId}`);
+  const hookManager = metadataString(route2, "aleoHookManagerProgram");
+  const igp = metadataString(route2, "aleoMailboxDefaultHook");
+  const destination = metadataNumber(route2, "aleoDestinationDomain");
+  const gasLimitMetadata = BigInt(metadataString(route2, "aleoRemoteRouterGas"));
+  const literal = await readContract(client, {
+    programId: hookManager,
+    mapping: "destination_gas_configs",
+    key: `{ igp: ${igp}, destination: ${destination}u32 }`
+  });
+  if (literal == null) throw new BridgeError(`Hyperlane destination gas configuration is missing on chain: ${params.routeId}`);
+  const config = parsePlaintextValue(literal);
+  if (typeof config !== "object" || Array.isArray(config)) throw new BridgeError(`Hyperlane destination gas configuration is malformed: ${params.routeId}`);
+  const gasOverhead = gasConfigBigint(config, "gas_overhead", route2.id);
+  const exchangeRate = gasConfigBigint(config, "exchange_rate", route2.id);
+  const gasPrice = gasConfigBigint(config, "gas_price", route2.id);
+  if (exchangeRate === 0n || gasPrice === 0n) throw new BridgeError(`Hyperlane destination gas configuration is unpriced: ${params.routeId}`);
+  const gasLimit = gasLimitMetadata === 0n ? ZERO_GAS_LIMIT_FALLBACK : gasLimitMetadata;
+  const paymentMicrocredits = (gasLimit + gasOverhead) * gasPrice * exchangeRate / GAS_QUOTE_SCALE;
+  if (paymentMicrocredits <= 0n || paymentMicrocredits > MAX_U64) {
+    throw new BridgeError(`Hyperlane hook payment does not fit a positive u64: ${paymentMicrocredits}`);
+  }
+  return { routeId: route2.id, gasLimit, gasOverhead, gasPrice, exchangeRate, paymentMicrocredits };
 }
 function buildAleoHyperlaneTransferRemoteCall(registry, params) {
   if (params.mode != null && params.mode !== "caller" && params.mode !== "signer") {
     throw new BridgeError(`Unsupported Aleo Hyperlane transfer mode: ${String(params.mode)}`);
   }
+  const gasPayment = params.gasPaymentMicrocredits;
+  if (gasPayment != null && (gasPayment <= 0n || gasPayment > MAX_U64)) {
+    throw new BridgeError(`gasPaymentMicrocredits must be a positive u64: ${gasPayment}`);
+  }
   const { route: route2, program, destinationChain } = validatedRoute2(registry, params);
   const amountAtomic = parseDecimalAmount(params.plan.amountIn, params.plan.sourceAsset.decimals);
   const destination = metadataNumber(route2, "aleoDestinationDomain");
@@ -1078,7 +1123,7 @@ function buildAleoHyperlaneTransferRemoteCall(registry, params) {
   const remoteRouter = `{ domain: ${destination}u32, recipient: ${metadataString(route2, "aleoRemoteRouterRecipient")}, gas: ${metadataString(route2, "aleoRemoteRouterGas")}u128 }`;
   const recipientLimbs = destinationChain.family === "evm" ? evmAddressToAleoHyperlaneRecipient(params.plan.recipient) : destinationChain.family === "solana" ? solanaAddressToAleoHyperlaneRecipient(params.plan.recipient) : void 0;
   const recipient = recipientLimbs ? `[${recipientLimbs[0]}u128, ${recipientLimbs[1]}u128]` : metadataString(route2, "aleoRecipient");
-  const allowances = `[${[0, 1, 2, 3].map((index) => allowance(route2, index)).join(", ")}]`;
+  const allowances = `[${[0, 1, 2, 3].map((index) => allowance(route2, index, index === 0 ? gasPayment?.toString() : void 0)).join(", ")}]`;
   const usesPlaceholderConfiguration = route2.metadata?.aleoPlaceholderConfiguration === true;
   let placeholderFields = route2.metadata?.aleoAppMetadataVerified === true ? PLACEHOLDER_FIELDS.filter((field) => !APP_METADATA_FIELDS.has(field)) : PLACEHOLDER_FIELDS;
   if (route2.metadata?.aleoMailboxStateVerified === true) {
@@ -1096,6 +1141,9 @@ function buildAleoHyperlaneTransferRemoteCall(registry, params) {
   if (recipientLimbs) {
     placeholderFields = placeholderFields.filter((field) => field !== "aleoRecipient");
   }
+  if (gasPayment != null) {
+    placeholderFields = placeholderFields.filter((field) => field !== "aleoAllowanceAmount0");
+  }
   const functionName = params.mode === "signer" ? "transfer_remote_as_signer" : "transfer_remote";
   return {
     routeId: route2.id,
@@ -1112,7 +1160,7 @@ function buildAleoHyperlaneTransferRemoteCall(registry, params) {
     ],
     amountAtomic,
     usesPlaceholderConfiguration,
-    placeholderFields: usesPlaceholderConfiguration ? placeholderFields : []
+    placeholderFields: usesPlaceholderConfiguration ? placeholderFields : gasPayment == null ? ["aleoAllowanceAmount0"] : []
   };
 }
 async function executeAleoHyperlaneTransferRemote(registry, executor2, params) {
@@ -1124,6 +1172,9 @@ async function executeAleoHyperlaneTransferRemote(registry, executor2, params) {
   if (route2?.availability !== "active") {
     throw new BridgeError(`Aleo Hyperlane route is not active: ${call.routeId}`);
   }
+  if (params.gasPaymentMicrocredits == null) {
+    throw new BridgeError(`Aleo Hyperlane execution requires a live hook gas payment; call quoteAleoHyperlaneGasPayment first: ${call.routeId}`);
+  }
   const result = await executor2.executeTransaction({
     program: call.program,
     function: call.function,
@@ -1160,6 +1211,10 @@ function bridgeActions(_client, config) {
     if (!config.executors?.aleo) throw new BridgeError("An Aleo executor is required for Aleo bridge transactions");
     return config.executors.aleo;
   };
+  const aleoPublicClient = () => {
+    if (!config.aleoPublicClient) throw new BridgeError("An Aleo public client is required for Hyperlane gas quotes");
+    return config.aleoPublicClient;
+  };
   return {
     getAssets: (params = {}) => getProtocolAssets(config.registry, {
       ...params,
@@ -1178,6 +1233,7 @@ function bridgeActions(_client, config) {
     executeXReservePrivateMint: async (params) => executeXReservePrivateMint(config.registry, aleoExecutor(), params),
     executeXReserveBurn: async (params) => executeXReserveBurn(config.registry, aleoExecutor(), params),
     buildAleoHyperlaneTransferRemoteCall: (params) => buildAleoHyperlaneTransferRemoteCall(config.registry, params),
+    quoteAleoHyperlaneGasPayment: async (params) => quoteAleoHyperlaneGasPayment(config.registry, aleoPublicClient(), params),
     executeAleoHyperlaneTransferRemote: async (params) => executeAleoHyperlaneTransferRemote(config.registry, aleoExecutor(), params)
   };
 }
@@ -1270,6 +1326,8 @@ var ALEO_PLACEHOLDER_ADDRESS = "aleo1kypwp5m7qtk9mwazgcpg0tq8aal23mnrvwfvug65qgc
 var ALEO_PLACEHOLDER_BYTES32 = `[${Array.from({ length: 32 }, () => "0u8").join(", ")}]`;
 var ALEO_MAILBOX_METADATA = {
   aleoMailboxStateVerified: true,
+  aleoHookManagerProgram: "hyp_hook_manager.aleo",
+  aleoHookManagerProgramSource: "https://explorer.provable.com/program/hyp_hook_manager.aleo",
   aleoMailboxProgram: "hyp_mailbox.aleo",
   aleoMailboxProgramEdition: 0,
   aleoMailboxProgramSource: ALEO_MAILBOX_PROGRAM_SOURCE,
@@ -1443,6 +1501,10 @@ var ALEO_SOL_REMOTE_ROUTER = {
   aleoAllowanceAmount2: "0",
   aleoAllowanceAmount3: "0"
 };
+var ALEO_WITHDRAWAL_ACTIVATION = {
+  aleoPlaceholderConfiguration: false,
+  aleoWithdrawalReviewedAt: "2026-08-26"
+};
 function route(id, protocol, environment, sourceAssetId, destinationAssetId, availability, deploymentId, metadata2) {
   return {
     id,
@@ -1494,13 +1556,13 @@ var routes = [
     attestationBaseUrl: "https://xreserve-api-testnet.circle.com/v1/attestations"
   }, "active"),
   route("hyperlane:ethereum/eth->aleo/eth", "hyperlane", "mainnet", "ethereum/eth", "aleo/eth", "active", "ETH/aleo", { ...ETH_HYPERLANE_METADATA, ...ALEO_MAILBOX_METADATA }),
-  route("hyperlane:aleo/eth->ethereum/eth", "hyperlane", "mainnet", "aleo/eth", "ethereum/eth", "metadata-required", "ETH/aleo", { ...ETH_HYPERLANE_METADATA, ...aleoHyperlanePlaceholders("hyp_warp_token_eth_v2.aleo", 1), ...ALEO_ETH_APP_METADATA, ...ALEO_ETH_REMOTE_ROUTER }),
+  route("hyperlane:aleo/eth->ethereum/eth", "hyperlane", "mainnet", "aleo/eth", "ethereum/eth", "active", "ETH/aleo", { ...ETH_HYPERLANE_METADATA, ...aleoHyperlanePlaceholders("hyp_warp_token_eth_v2.aleo", 1), ...ALEO_ETH_APP_METADATA, ...ALEO_ETH_REMOTE_ROUTER, ...ALEO_WITHDRAWAL_ACTIVATION }),
   route("hyperlane:ethereum/wbtc->aleo/wbtc", "hyperlane", "mainnet", "ethereum/wbtc", "aleo/wbtc", "active", "WBTC/aleo", { ...WBTC_HYPERLANE_METADATA, ...ALEO_MAILBOX_METADATA }),
-  route("hyperlane:aleo/wbtc->ethereum/wbtc", "hyperlane", "mainnet", "aleo/wbtc", "ethereum/wbtc", "metadata-required", "WBTC/aleo", { ...WBTC_HYPERLANE_METADATA, ...aleoHyperlanePlaceholders("hyp_warp_token_wbtc_v2.aleo", 1), ...ALEO_WBTC_APP_METADATA, ...ALEO_WBTC_REMOTE_ROUTER }),
+  route("hyperlane:aleo/wbtc->ethereum/wbtc", "hyperlane", "mainnet", "aleo/wbtc", "ethereum/wbtc", "active", "WBTC/aleo", { ...WBTC_HYPERLANE_METADATA, ...aleoHyperlanePlaceholders("hyp_warp_token_wbtc_v2.aleo", 1), ...ALEO_WBTC_APP_METADATA, ...ALEO_WBTC_REMOTE_ROUTER, ...ALEO_WITHDRAWAL_ACTIVATION }),
   route("hyperlane:ethereum/usdt->aleo/usdt", "hyperlane", "mainnet", "ethereum/usdt", "aleo/usdt", "active", "USDT/aleo", { ...USDT_HYPERLANE_METADATA, ...ALEO_MAILBOX_METADATA }),
-  route("hyperlane:aleo/usdt->ethereum/usdt", "hyperlane", "mainnet", "aleo/usdt", "ethereum/usdt", "metadata-required", "USDT/aleo", { ...USDT_HYPERLANE_METADATA, ...aleoHyperlanePlaceholders("hyp_warp_token_usdt_v2.aleo", 1), ...ALEO_USDT_APP_METADATA, ...ALEO_USDT_ETHEREUM_REMOTE_ROUTER }),
+  route("hyperlane:aleo/usdt->ethereum/usdt", "hyperlane", "mainnet", "aleo/usdt", "ethereum/usdt", "active", "USDT/aleo", { ...USDT_HYPERLANE_METADATA, ...aleoHyperlanePlaceholders("hyp_warp_token_usdt_v2.aleo", 1), ...ALEO_USDT_APP_METADATA, ...ALEO_USDT_ETHEREUM_REMOTE_ROUTER, ...ALEO_WITHDRAWAL_ACTIVATION }),
   route("hyperlane:solana/sol->aleo/sol", "hyperlane", "mainnet", "solana/sol", "aleo/sol", "metadata-required", "SOL/aleo", ALEO_MAILBOX_METADATA),
-  route("hyperlane:aleo/sol->solana/sol", "hyperlane", "mainnet", "aleo/sol", "solana/sol", "metadata-required", "SOL/aleo", { ...aleoHyperlanePlaceholders("hyp_warp_token_sol_v2.aleo", 1399811149), ...ALEO_SOL_APP_METADATA, ...ALEO_SOL_REMOTE_ROUTER }),
+  route("hyperlane:aleo/sol->solana/sol", "hyperlane", "mainnet", "aleo/sol", "solana/sol", "active", "SOL/aleo", { ...aleoHyperlanePlaceholders("hyp_warp_token_sol_v2.aleo", 1399811149), ...ALEO_SOL_APP_METADATA, ...ALEO_SOL_REMOTE_ROUTER, ...ALEO_WITHDRAWAL_ACTIVATION }),
   ...pair("hyperlane", "mainnet", "aleo/aleo", "ethereum/aleo", "metadata-required", "ALEO/aleo", ALEO_MAILBOX_METADATA),
   ...pair("hyperlane", "mainnet", "aleo/aleo", "solana/aleo", "metadata-required", "ALEO/aleo", ALEO_MAILBOX_METADATA),
   ...pair("hyperlane", "mainnet", "aleo/aleo", "base/aleo", "metadata-required", "ALEO/aleo", ALEO_MAILBOX_METADATA),
@@ -1509,7 +1571,7 @@ var routes = [
   route("hyperlane:aleo/usad->ethereum/usad", "hyperlane", "mainnet", "aleo/usad", "ethereum/usad", "metadata-required", "USAD/aleo", aleoHyperlanePlaceholders("hyp_warp_token_usad_v2.aleo", 1))
 ];
 var DEFAULT_BRIDGE_REGISTRY = Object.freeze({
-  version: "2026-08-17.aleo-sol-router.1",
+  version: "2026-08-26.aleo-withdrawals.1",
   chains: Object.freeze(chains),
   assets: Object.freeze(assets),
   routes: Object.freeze(routes),
@@ -1582,6 +1644,7 @@ function createBridgeClient(config = {}) {
     registry = DEFAULT_BRIDGE_REGISTRY,
     executors = {},
     xReserveHttpTransport,
+    aleoPublicClient,
     key = "bridge",
     name = "Bridge Client"
   } = config;
@@ -1590,7 +1653,7 @@ function createBridgeClient(config = {}) {
   return client.extend((inner) => ({
     environment,
     registry: validated,
-    ...bridgeActions(inner, { environment, registry: validated, executors, xReserveHttpTransport })
+    ...bridgeActions(inner, { environment, registry: validated, executors, xReserveHttpTransport, aleoPublicClient })
   }));
 }
 export {
@@ -1618,6 +1681,7 @@ export {
   getXReserveAttestation,
   parseDecimalAmount,
   prepareTransfer,
+  quoteAleoHyperlaneGasPayment,
   quoteEvmHyperlaneTransfer,
   quoteEvmXReserveTransfer,
   solanaAddressToAleoHyperlaneRecipient,