@hyperbridge/sdk 2.4.2 → 2.5.0

package/dist/browser/index.d.ts

@@ -963,6 +963,8 @@ interface ChainConfigData {
         UniswapV4StateView?: `0x${string}`;
         /** Circle Paymaster contract address (USDC-based ERC-4337 paymaster) */
         CirclePaymaster?: `0x${string}`;
+        /** SimplexPaymaster contract address (ERC-4337 paymaster accepting USDC/USDT via Chainlink pricing) */
+        SimplexPaymaster?: `0x${string}`;
     };
     rpcEnvKey?: string;
     defaultRpcUrl?: string;
@@ -1038,6 +1040,7 @@ declare class ChainConfigService {
     getPopularTokens(chain: string): string[];
     getEntryPointV08Address(chain: string): HexString;
     getCirclePaymasterAddress(chain: string): HexString | undefined;
+    getSimplexPaymasterAddress(chain: string): HexString | undefined;
     getHyperbridgeAddress(): string;
     /**
      * Get the LayerZero Endpoint ID for the chain
@@ -1420,6 +1423,10 @@ declare function normalizeEvmChainId(chainId: number | string): {
 };
 declare function encodeStateMachineId(stateMachineId: string): HexString;
 declare function normalizeAddressForEvmBytes32(address: string): HexString;
+/**
+ * Validates an EVM address and returns its canonical lowercase representation.
+ */
+declare function normalizeEvmAddress(address: string, field?: string): HexString;
 declare function normalizeAddressForStateMachine(address: string, stateMachineId: string): HexString;
 /**
  * Retries a promise-returning operation with exponential backoff.
@@ -1871,6 +1878,23 @@ interface PhantomOrderEvent {
     tokenB: HexString;
     standardAmount: bigint;
 }
+interface PollPhantomOrdersOptions {
+    /** How often to check for a new head. Defaults to 6s, roughly one block. */
+    intervalMs?: number;
+    /**
+     * Most blocks scanned in a single poll, so a long outage catches up over several ticks instead of
+     * one unbounded scan. Defaults to 500.
+     */
+    maxBlocksPerPoll?: number;
+    /**
+     * How many blocks before the current head to start from on the first poll. Defaults to 0 (start
+     * at the head). Set this to the runtime's bid window to have a restarting process pick up orders
+     * whose window is still open.
+     */
+    lookbackBlocks?: number;
+    /** Notified when a poll fails; polling continues regardless. */
+    onError?: (err: unknown) => void;
+}
 /**
  * Service for interacting with Hyperbridge's pallet-intents coprocessor.
  * Handles bid submission and retrieval for the IntentGatewayV2 protocol.
@@ -2015,11 +2039,26 @@ declare class IntentsCoprocessor {
      */
     fetchPhantomOrder(commitment: HexString): Promise<Order | null>;
     /**
-     * Subscribes to PhantomOrderRegistered events from the intents coprocessor pallet.
-     * Calls the callback for each new phantom order as blocks arrive.
-     * Returns an unsubscribe function to stop the subscription.
+     * Reads the PhantomOrderRegistered events emitted in a single block.
+     */
+    getPhantomOrdersInBlock(blockNumber: number): Promise<PhantomOrderEvent[]>;
+    /**
+     * Polls for newly registered phantom orders, invoking the callback once per order.
+     *
+     * Each tick reads the current head and scans every block between the last one processed and that
+     * head, so the block cursor — not the connection — determines what has been seen. This replaced a
+     * system.events subscription, which was only as reliable as its socket: polkadot-js reconnects
+     * the transport but does not reliably re-establish storage subscriptions, and anything emitted
+     * while disconnected was lost silently. With a bid window measured in a handful of blocks, that
+     * meant silently missed bids.
+     *
+     * Scanning a block range is gap-free rather than merely self-healing: an outage delays orders but
+     * cannot drop them, because the cursor only advances past a block whose events were actually
+     * read. Recovery replays the backlog.
+     *
+     * Returns a function that stops polling.
      */
-    subscribePhantomOrders(callback: (event: PhantomOrderEvent) => void): Promise<() => void>;
+    pollPhantomOrders(callback: (event: PhantomOrderEvent) => void, options?: PollPhantomOrdersOptions): () => void;
 }
 
 /**
@@ -2505,6 +2544,8 @@ interface RetryConfig {
     backoffMs: number;
     logMessage?: string;
     logger?: ConsolaInstance;
+    /** Return false to stop retrying and immediately rethrow the error. */
+    shouldRetry?: (error: unknown) => boolean;
 }
 interface IsmpRequest {
     source: string;
@@ -3370,6 +3411,26 @@ interface PhantomOrderPriceSnapshotsResponse {
         }>;
     };
 }
+/**
+ * Total solver liquidity measured at one immutable Phantom price snapshot.
+ *
+ * Liquidity amounts are decimal strings formatted with the configured decimals
+ * for their respective `tokenAddress` and chain.
+ */
+interface AvailableLiquiditySnapshot {
+    totalLiquidity: string;
+    providerCount: number;
+    tokenAddress: HexString;
+    snapshotTime: Date;
+    liquidityByChain: AvailableLiquidityByChain[];
+}
+/** Liquidity for one chain/token balance group in an availability snapshot. */
+interface AvailableLiquidityByChain {
+    chain: string;
+    tokenAddress: HexString;
+    totalLiquidity: string;
+    providerCount: number;
+}
 interface TokenPrice {
     symbol: string;
     address?: string;
@@ -4592,9 +4653,9 @@ interface BundlerGasEstimate {
  * - `AWAITING_CANCEL_TRANSACTION` – the caller must sign and submit the cancel tx.
  * - `CANCEL_STARTED` – the cancel transaction was confirmed on-chain.
  * - `SOURCE_FINALIZED` – the cancel request has been finalised on the source chain.
- * - `HYPERBRIDGE_DELIVERED` – the cancel message has been delivered to Hyperbridge.
- * - `HYPERBRIDGE_FINALIZED` – the cancel message has been finalised on Hyperbridge.
- * - `CANCELLATION_COMPLETE` – the escrow has been refunded; cancellation is done.
+    * - `HYPERBRIDGE_DELIVERED` – the cancel message has been delivered to Hyperbridge.
+    * - `HYPERBRIDGE_FINALIZED` – the cancel message has been finalised on Hyperbridge.
+    * - `CANCELLATION_COMPLETE` – the escrow has been refunded; cancellation is done.
  */
 type CancelEvent = {
     status: "DESTINATION_FINALIZED";
@@ -4833,6 +4894,8 @@ declare class IntentGateway {
     private readonly gasEstimator;
     /** Quote strategies for pricing orders before placement, keyed by strategy name. */
     private readonly quoteStrategies;
+    /** Resolves order tokens to canonical Phantom snapshot market pairs. */
+    private readonly phantomSnapshotPairResolver;
     /**
      * Private constructor — use {@link IntentGateway.create} instead.
      *
@@ -4887,13 +4950,25 @@ declare class IntentGateway {
      * @throws {PhantomSnapshotUnavailableError} When an eligible cNGN pair has no snapshot.
      */
     quoteIntent(params: QuoteIntentParams): Promise<QuoteIntentResult>;
+    /**
+     * Returns the output-token liquidity measured in the latest directional
+     * Phantom snapshot for this gateway's source and destination.
+     *
+     * Pair resolution uses the same canonical Base market as {@link quoteIntent}.
+     * The snapshot itself determines the output token and chain to aggregate. The
+     * amount is in the token's smallest unit and reflects the indexer's
+     * `snapshotTime`; it is not a live reservation or fill guarantee.
+     *
+     * Requires a prior call to {@link withQueryClient}.
+     */
+    queryAvailableLiquidity(params: Pick<QuoteIntentParams, "tokenIn" | "tokenOut">): Promise<AvailableLiquiditySnapshot | undefined>;
     /**
      * Bidirectional async generator that orchestrates the full order lifecycle:
      * placement, fee estimation, bid collection, and execution.
      *
      * **Yield/receive protocol:**
-     * 1. If `order.fees` is unset or zero, estimates gas and sets same-chain
-     *    `order.fees` to twice the estimate. Cross-chain orders retain a 1% buffer
+     * 1. If `order.fees` is unset or zero, estimates gas on an internal copy and sets
+     *    same-chain fees to twice the estimate. Cross-chain orders retain a 1% buffer
      *    and include an additional 600k-gas fee uplift, while the wei cost used for
      *    the `value` field receives a 2% buffer.
      * 2. Yields `AWAITING_PLACE_ORDER` with `{ to, data, value, sessionPrivateKey }`.
@@ -4903,8 +4978,8 @@ declare class IntentGateway {
      * 4. Delegates to {@link OrderExecutor.executeOrder} and forwards all
      *    subsequent status updates until the order is filled, exhausted, or fails.
      *
-     * @param order - The order to place and execute. `order.fees` may be 0; it
-     *   will be estimated automatically if so.
+     * @param order - The order to place and execute. It is not mutated. `order.fees`
+     *   may be 0; fees are estimated automatically if so.
      * @param graffiti - Optional bytes32 tag for orderflow attribution /
      *   revenue share. Defaults to {@link DEFAULT_GRAFFITI}.
      * @param options - Optional tuning parameters:
@@ -10389,4 +10464,4 @@ declare function teleport(teleport_param: {
     extrinsics?: Array<SubmittableExtrinsic<"promise", ISubmittableResult>>;
 }): Promise<ReadableStream<HyperbridgeTxEvents>>;
 
-export { ADDRESS_ZERO, type AllStatusKey, type AssetTeleported, type AssetTeleportedResponse, type Bid, type BidStorageEntry, type BidSubmissionResult, type BlockMetadata, type BridgeParams, type BridgeStep, type BundlerGasEstimate, BundlerMethod, type BytesLikeHex, type CancelEvent, type CancelOptions, type CancelOrderOptions, type CancelQuote, type ChainConfig, type ChainConfigData, ChainConfigService, Chains, type ClientConfig, type ConfiguredAssetSymbol, CryptoUtils, DEFAULT_ADDRESS, DEFAULT_GRAFFITI, DOMAIN_TYPEHASH, DUMMY_PRIVATE_KEY, type DecodedOrderPlacedLog, type DecodedPostRequestEvent, type DecodedPostResponseEvent, type Deployment, type DispatchGet, type DispatchInfo, type DispatchPost, ERC20Method, type ERC7821Call, ERC7821_BATCH_MODE, type EstimateFillOrderParams, type EstimateGasCallData, EvmChain, type EvmChainParams, ABI as EvmHostABI, EvmLanguage, type ExecuteIntentOrderOptions, type ExecutionResult, type FillOptions, type FillOrderEstimate, type FillerBid, type FillerConfig, type GetRequestResponse, type GetRequestWithStatus, type GetResponseByRequestIdResponse, type GetResponseStorageValues, type HexString, type HostParams, HyperClientStatus, HyperFungibleToken, HyperFungibleTokenABI, type HyperbridgeTxEvents, type IBatchConsensusAndGetResponseMessage, type IBatchConsensusAndPostRequestMessage, type IChain, type IConfig, type IConsensusMessage, type IEvmChain, type IEvmConfig, type IGetRequest, type IGetRequestMessage, type IGetResponse, type IGetResponseMessage, type IHyperbridgeConfig, type IIsmpMessage, type IMessage, type IPharosConfig, type IPolkadotHubConfig, type IPostRequest, type IPostResponse, type IProof, type IRequestMessage, type ISubstrateConfig, type ITimeoutPostRequestMessage, type IndexerQueryClient, IntentGateway, ABI$1 as IntentGatewayABI, type IntentGatewayContext, type IntentGatewayParams, IntentOrderStatus, type IntentOrderStatusKey, type IntentOrderStatusUpdate, type IntentQuoteStrategy, type IntentQuoteTradeType, IntentsCoprocessor, InvalidPhantomSnapshotError, IsmpClient, type IsmpRequest, MOCK_ADDRESS, ORDER_V2_PARAM_TYPE, type Order, type OrderResponse, OrderStatus, OrderStatusChecker, type OrderStatusMetadata, type OrderWithStatus, PACKED_USEROP_TYPEHASH, PLACE_ORDER_SELECTOR, type PackedUserOperation, type Params, type PaymentInfo, type PhantomOrderEvent, type PhantomOrderPriceSnapshot, type PhantomOrderPriceSnapshotsResponse, type PhantomSnapshotIntentQuoteMetadata, type PhantomSnapshotQuoteIntentResult, PhantomSnapshotUnavailableError, PharosChain, type PharosChainParams, PolkadotHubChain, type PolkadotHubChainParams, type PostRequestStatus, type PostRequestTimeoutStatus, type PostRequestWithStatus, type QuoteIntentParams, type QuoteIntentResult, type QuoteNativeResult, type QuoteResult, type QuoteUniswapParams, type QuoteUniswapResult, REQUEST_COMMITMENTS_SLOT, REQUEST_RECEIPTS_SLOT, RESPONSE_COMMITMENTS_SLOT, RESPONSE_RECEIPTS_SLOT, type RequestBody, type RequestCommitment, RequestKind, type RequestResponse, RequestStatus, type RequestStatusKey, type RequestStatusWithMetadata, type ResponseCommitmentWithValues, type ResumeIntentOrderOptions, type RetryConfig, SELECT_SOLVER_TYPEHASH, STATE_COMMITMENTS_SLOT, type SelectBidResult, type SelectOptions, type SigningAccount, type StateMachineHeight, type StateMachineId, type StateMachineIdParams, type StateMachineResponse, type StateMachineUpdate, type StorageFacade, type SubmitBidOptions, SubstrateChain, Swap, TESTNET_CHAINS, type TeleportParams, TeleportStatus, TimeoutStatus, type TimeoutStatusKey, TokenGateway, type TokenGatewayAssetTeleportedResponse, type TokenGatewayAssetTeleportedWithStatus, type TokenInfo, type TokenPrice, type TokenPricesResponse, type Transaction, TronChain, type TronChainParams, USE_ETHERSCAN_CHAINS, type UniswapProtocol, type UniswapQuote, type UniswapQuoteToken, type UniswapTradeType, type UniswapV4IntentQuoteMetadata, type UniswapV4IntentQuoteOptions, type UniswapV4PoolConfigData, type UniswapV4PoolKey, type UniswapV4QuoteIntentResult, UnsupportedIntentQuotePairError, UnsupportedIntentQuoteStrategyError, WrappedHyperFungibleTokenABI, type XcmGatewayParams, __test, adjustDecimals, bytes20ToBytes32, bytes32ToBytes20, calculateAllowanceMappingLocation, calculateBalanceMappingLocation, chainConfigs, constructRedeemEscrowRequestBody, constructRefundEscrowRequestBody, convertCodecToIGetRequest, convertCodecToIProof, convertIGetRequestToCodec, convertIProofToCodec, convertStateIdToStateMachineId, convertStateMachineEnumToString, convertStateMachineIdToEnum, createEvmChain, createQueryClient, decodeERC7821ExecuteBatch, decodeUserOpScale, encodeERC7821ExecuteBatch, encodeISMPMessage, encodeStateMachineId, encodeUserOpScale, encodeWithdrawalRequest, estimateGasForPost, fetchPrice, fetchSourceProof, generateRootWithProof, getChainId, getConfigByStateMachineId, getContractCallInput, getContractCallInputs, getGasPriceFromEtherscan, getOrFetchStorageSlot, getOrderPlacedFromTx, getPostRequestEventFromTx, getPostResponseEventFromTx, getRequestCommitment, getStateCommitmentFieldSlot, getStateCommitmentSlot, getStorageSlot, getViemChain, hexToString, hyperbridgeAddress, maxBigInt, normalizeAddressForEvmBytes32, normalizeAddressForStateMachine, normalizeEvmChainId, normalizeStateMachineId, orderCommitment, parseStateMachineId, pharosAtlantic, pharosMainnet, polkadotAssetHubPaseo, polkadotHubMainnet, postRequestCommitment, queryAssetTeleported, queryGetRequest, queryPostRequest, quoteUniswap, requestCommitmentKey, responseCommitmentKey, retryPromise, teleport, teleportDot, transformOrderForContract, tronChainIds, tronNile };
+export { ADDRESS_ZERO, type AllStatusKey, type AssetTeleported, type AssetTeleportedResponse, type AvailableLiquidityByChain, type AvailableLiquiditySnapshot, type Bid, type BidStorageEntry, type BidSubmissionResult, type BlockMetadata, type BridgeParams, type BridgeStep, type BundlerGasEstimate, BundlerMethod, type BytesLikeHex, type CancelEvent, type CancelOptions, type CancelOrderOptions, type CancelQuote, type ChainConfig, type ChainConfigData, ChainConfigService, Chains, type ClientConfig, type ConfiguredAssetSymbol, CryptoUtils, DEFAULT_ADDRESS, DEFAULT_GRAFFITI, DOMAIN_TYPEHASH, DUMMY_PRIVATE_KEY, type DecodedOrderPlacedLog, type DecodedPostRequestEvent, type DecodedPostResponseEvent, type Deployment, type DispatchGet, type DispatchInfo, type DispatchPost, ERC20Method, type ERC7821Call, ERC7821_BATCH_MODE, type EstimateFillOrderParams, type EstimateGasCallData, EvmChain, type EvmChainParams, ABI as EvmHostABI, EvmLanguage, type ExecuteIntentOrderOptions, type ExecutionResult, type FillOptions, type FillOrderEstimate, type FillerBid, type FillerConfig, type GetRequestResponse, type GetRequestWithStatus, type GetResponseByRequestIdResponse, type GetResponseStorageValues, type HexString, type HostParams, HyperClientStatus, HyperFungibleToken, HyperFungibleTokenABI, type HyperbridgeTxEvents, type IBatchConsensusAndGetResponseMessage, type IBatchConsensusAndPostRequestMessage, type IChain, type IConfig, type IConsensusMessage, type IEvmChain, type IEvmConfig, type IGetRequest, type IGetRequestMessage, type IGetResponse, type IGetResponseMessage, type IHyperbridgeConfig, type IIsmpMessage, type IMessage, type IPharosConfig, type IPolkadotHubConfig, type IPostRequest, type IPostResponse, type IProof, type IRequestMessage, type ISubstrateConfig, type ITimeoutPostRequestMessage, type IndexerQueryClient, IntentGateway, ABI$1 as IntentGatewayABI, type IntentGatewayContext, type IntentGatewayParams, IntentOrderStatus, type IntentOrderStatusKey, type IntentOrderStatusUpdate, type IntentQuoteStrategy, type IntentQuoteTradeType, IntentsCoprocessor, InvalidPhantomSnapshotError, IsmpClient, type IsmpRequest, MOCK_ADDRESS, ORDER_V2_PARAM_TYPE, type Order, type OrderResponse, OrderStatus, OrderStatusChecker, type OrderStatusMetadata, type OrderWithStatus, PACKED_USEROP_TYPEHASH, PLACE_ORDER_SELECTOR, type PackedUserOperation, type Params, type PaymentInfo, type PhantomOrderEvent, type PhantomOrderPriceSnapshot, type PhantomOrderPriceSnapshotsResponse, type PhantomSnapshotIntentQuoteMetadata, type PhantomSnapshotQuoteIntentResult, PhantomSnapshotUnavailableError, PharosChain, type PharosChainParams, PolkadotHubChain, type PolkadotHubChainParams, type PollPhantomOrdersOptions, type PostRequestStatus, type PostRequestTimeoutStatus, type PostRequestWithStatus, type QuoteIntentParams, type QuoteIntentResult, type QuoteNativeResult, type QuoteResult, type QuoteUniswapParams, type QuoteUniswapResult, REQUEST_COMMITMENTS_SLOT, REQUEST_RECEIPTS_SLOT, RESPONSE_COMMITMENTS_SLOT, RESPONSE_RECEIPTS_SLOT, type RequestBody, type RequestCommitment, RequestKind, type RequestResponse, RequestStatus, type RequestStatusKey, type RequestStatusWithMetadata, type ResponseCommitmentWithValues, type ResumeIntentOrderOptions, type RetryConfig, SELECT_SOLVER_TYPEHASH, STATE_COMMITMENTS_SLOT, type SelectBidResult, type SelectOptions, type SigningAccount, type StateMachineHeight, type StateMachineId, type StateMachineIdParams, type StateMachineResponse, type StateMachineUpdate, type StorageFacade, type SubmitBidOptions, SubstrateChain, Swap, TESTNET_CHAINS, type TeleportParams, TeleportStatus, TimeoutStatus, type TimeoutStatusKey, TokenGateway, type TokenGatewayAssetTeleportedResponse, type TokenGatewayAssetTeleportedWithStatus, type TokenInfo, type TokenPrice, type TokenPricesResponse, type Transaction, TronChain, type TronChainParams, USE_ETHERSCAN_CHAINS, type UniswapProtocol, type UniswapQuote, type UniswapQuoteToken, type UniswapTradeType, type UniswapV4IntentQuoteMetadata, type UniswapV4IntentQuoteOptions, type UniswapV4PoolConfigData, type UniswapV4PoolKey, type UniswapV4QuoteIntentResult, UnsupportedIntentQuotePairError, UnsupportedIntentQuoteStrategyError, WrappedHyperFungibleTokenABI, type XcmGatewayParams, __test, adjustDecimals, bytes20ToBytes32, bytes32ToBytes20, calculateAllowanceMappingLocation, calculateBalanceMappingLocation, chainConfigs, constructRedeemEscrowRequestBody, constructRefundEscrowRequestBody, convertCodecToIGetRequest, convertCodecToIProof, convertIGetRequestToCodec, convertIProofToCodec, convertStateIdToStateMachineId, convertStateMachineEnumToString, convertStateMachineIdToEnum, createEvmChain, createQueryClient, decodeERC7821ExecuteBatch, decodeUserOpScale, encodeERC7821ExecuteBatch, encodeISMPMessage, encodeStateMachineId, encodeUserOpScale, encodeWithdrawalRequest, estimateGasForPost, fetchPrice, fetchSourceProof, generateRootWithProof, getChainId, getConfigByStateMachineId, getContractCallInput, getContractCallInputs, getGasPriceFromEtherscan, getOrFetchStorageSlot, getOrderPlacedFromTx, getPostRequestEventFromTx, getPostResponseEventFromTx, getRequestCommitment, getStateCommitmentFieldSlot, getStateCommitmentSlot, getStorageSlot, getViemChain, hexToString, hyperbridgeAddress, maxBigInt, normalizeAddressForEvmBytes32, normalizeAddressForStateMachine, normalizeEvmAddress, normalizeEvmChainId, normalizeStateMachineId, orderCommitment, parseStateMachineId, pharosAtlantic, pharosMainnet, polkadotAssetHubPaseo, polkadotHubMainnet, postRequestCommitment, queryAssetTeleported, queryGetRequest, queryPostRequest, quoteUniswap, requestCommitmentKey, responseCommitmentKey, retryPromise, teleport, teleportDot, transformOrderForContract, tronChainIds, tronNile };