@circle-fin/app-kit 1.11.0 → 1.12.1

package/unifiedBalance.d.cts

@@ -739,6 +739,8 @@ declare enum Blockchain {
     World_Chain_Sepolia = "World_Chain_Sepolia",
     XDC = "XDC",
     XDC_Apothem = "XDC_Apothem",
+    X_Layer = "X_Layer",
+    X_Layer_Testnet = "X_Layer_Testnet",
     ZKSync_Era = "ZKSync_Era",
     ZKSync_Sepolia = "ZKSync_Sepolia"
 }
@@ -2602,6 +2604,18 @@ interface TokenActionMap {
          */
         walletAddress?: string | undefined;
     };
+    /**
+     * Get the on-chain name of the token contract.
+     *
+     * This is a read-only operation. For USDC the value is also the EIP-712
+     * domain name, which permit and authorize signing flows need.
+     */
+    name: ActionParameters & {
+        /**
+         * The contract address of the token.
+         */
+        tokenAddress: string;
+    };
 }
 
 /**
@@ -3431,6 +3445,30 @@ declare class ActionRegistry {
     executeAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>, context: ResolvedOperationContext): Promise<PreparedChainRequest>;
 }
 
+/**
+ * Canonical list of actions that do not prepare or submit transactions.
+ *
+ * @internal
+ */
+declare const READ_ACTION_KEYS: readonly ["token.allowance", "token.balanceOf", "token.name", "native.balanceOf", "usdc.allowance", "usdc.balanceOf", "usdc.name", "gateway.v1.isDelegate", "gateway.v1.withdrawingBalance", "gateway.v1.withdrawalBlock", "gateway.v1.signBurnIntents"];
+/**
+ * Action keys that execute without preparing or submitting a transaction.
+ *
+ * @remarks
+ * Derive this type from the canonical runtime list so compile-time and runtime
+ * classification cannot drift. `gateway.v1.signBurnIntents` is included
+ * because the action system models off-chain signing as a read action: it does
+ * not prepare a chain request.
+ *
+ * @example
+ * ```typescript
+ * import type { ReadActionKey } from '@core/adapter'
+ *
+ * const action: ReadActionKey = 'token.allowance'
+ * ```
+ */
+type ReadActionKey = (typeof READ_ACTION_KEYS)[number];
+
 /**
  * Defines the capabilities of an adapter, including address handling patterns and supported chains.
  *
@@ -3599,6 +3637,69 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * ```
      */
     prepareAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>, ctx: OperationContext<TAdapterCapabilities>): Promise<PreparedChainRequest>;
+    /**
+     * Execute a non-transaction action without routing through transaction preparation.
+     *
+     * @remarks
+     * Use this seam for balance, allowance, contract-state, and other actions
+     * classified as reads. It never calls {@link Adapter.prepareAction}, so
+     * transaction authorization wrappers only observe actions that can produce a
+     * signable chain request.
+     *
+     * @typeParam TActionKey - The read action key.
+     * @param action - The read action to execute.
+     * @param params - The parameters for the read action.
+     * @param ctx - The operation context.
+     * @returns The raw action response.
+     * @throws {KitError} When the key is not a read action or no handler is registered.
+     * @throws Error When the operation context or action handler fails.
+     *
+     * @example
+     * ```typescript
+     * import { Ethereum } from '@core/chains'
+     *
+     * const balance = await adapter.readAction(
+     *   'token.balanceOf',
+     *   { tokenAddress, walletAddress },
+     *   { chain: Ethereum },
+     * )
+     * ```
+     *
+     * @internal
+     */
+    readAction<TActionKey extends ReadActionKey>(action: TActionKey, params: ActionPayload<TActionKey>, ctx: OperationContext<TAdapterCapabilities>): Promise<unknown>;
+    /**
+     * Read the current token allowance a delegate holds over an owner's tokens.
+     *
+     * @remarks
+     * Perform a network read through {@link Adapter.readAction}. This method
+     * never routes through {@link Adapter.prepareAction}. On chains without an
+     * allowance model, such as Solana, return the maximum uint256 value.
+     *
+     * @param params - The token to query and the delegate whose allowance is being read.
+     * @param ctx - Operation context with compile-time validated address requirements.
+     * @returns A promise resolving to the current allowance in the token's base units.
+     * @throws {KitError} When the adapter does not register a `token.allowance` handler.
+     * @throws Error When the operation context or action handler fails.
+     *
+     * @example
+     * ```typescript
+     * import type { Adapter } from '@core/adapter'
+     * import { Ethereum } from '@core/chains'
+     *
+     * declare const adapter: Adapter
+     *
+     * const allowance = await adapter.getTokenAllowance(
+     *   {
+     *     tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+     *     delegate: '0x1111111111111111111111111111111111111111',
+     *   },
+     *   { chain: Ethereum },
+     * )
+     * console.log(allowance) // 1000000n
+     * ```
+     */
+    getTokenAllowance(params: ActionPayload<'token.allowance'>, ctx: OperationContext<TAdapterCapabilities>): Promise<bigint>;
     /**
      * Prepares a transaction for future gas estimation and execution.
      *
@@ -3785,6 +3886,37 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
     abstract getTokenDecimals(tokenAddress: string, chain: ChainDefinition): Promise<number>;
 }
 
+/**
+ * Simplified error information structure for logging and events.
+ *
+ * @remarks
+ * This lightweight type is used for error reporting in events, logs, and
+ * observability systems. It provides essential error context without the
+ * full ErrorDetails structure. Used across retry mechanisms, adapters,
+ * and other subsystems that need to record error information.
+ *
+ * @example
+ * ```typescript
+ * import { ErrorInfo } from '@core/errors'
+ *
+ * const info: ErrorInfo = {
+ *   name: 'NETWORK_TIMEOUT',
+ *   message: 'Request timed out after 5000ms',
+ *   code: 3002
+ * }
+ * ```
+ */
+interface ErrorInfo {
+    /** Error name (e.g., 'TypeError', 'KitError', 'NETWORK_TIMEOUT'). */
+    name: string;
+    /** Error message describing what went wrong. */
+    message: string;
+    /** Optional error code if the error has one (e.g., KitError codes). */
+    code?: number;
+    /** Error category (e.g., INPUT, RPC, ONCHAIN, BALANCE, NETWORK, UNKNOWN). Only set for KitError instances. */
+    type?: string;
+}
+
 /**
  * A type-safe event emitter for managing action-based event subscriptions.
  *
@@ -4025,37 +4157,6 @@ declare module './types' {
     }
 }
 
-/**
- * Simplified error information structure for logging and events.
- *
- * @remarks
- * This lightweight type is used for error reporting in events, logs, and
- * observability systems. It provides essential error context without the
- * full ErrorDetails structure. Used across retry mechanisms, adapters,
- * and other subsystems that need to record error information.
- *
- * @example
- * ```typescript
- * import { ErrorInfo } from '@core/errors'
- *
- * const info: ErrorInfo = {
- *   name: 'NETWORK_TIMEOUT',
- *   message: 'Request timed out after 5000ms',
- *   code: 3002
- * }
- * ```
- */
-interface ErrorInfo {
-    /** Error name (e.g., 'TypeError', 'KitError', 'NETWORK_TIMEOUT'). */
-    name: string;
-    /** Error message describing what went wrong. */
-    message: string;
-    /** Optional error code if the error has one (e.g., KitError codes). */
-    code?: number;
-    /** Error category (e.g., INPUT, RPC, ONCHAIN, BALANCE, NETWORK, UNKNOWN). Only set for KitError instances. */
-    type?: string;
-}
-
 /**
  * Runtime array of token identifiers supported by the Gateway v1 provider.
  *

package/unifiedBalance.d.mts

@@ -739,6 +739,8 @@ declare enum Blockchain {
     World_Chain_Sepolia = "World_Chain_Sepolia",
     XDC = "XDC",
     XDC_Apothem = "XDC_Apothem",
+    X_Layer = "X_Layer",
+    X_Layer_Testnet = "X_Layer_Testnet",
     ZKSync_Era = "ZKSync_Era",
     ZKSync_Sepolia = "ZKSync_Sepolia"
 }
@@ -2602,6 +2604,18 @@ interface TokenActionMap {
          */
         walletAddress?: string | undefined;
     };
+    /**
+     * Get the on-chain name of the token contract.
+     *
+     * This is a read-only operation. For USDC the value is also the EIP-712
+     * domain name, which permit and authorize signing flows need.
+     */
+    name: ActionParameters & {
+        /**
+         * The contract address of the token.
+         */
+        tokenAddress: string;
+    };
 }
 
 /**
@@ -3431,6 +3445,30 @@ declare class ActionRegistry {
     executeAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>, context: ResolvedOperationContext): Promise<PreparedChainRequest>;
 }
 
+/**
+ * Canonical list of actions that do not prepare or submit transactions.
+ *
+ * @internal
+ */
+declare const READ_ACTION_KEYS: readonly ["token.allowance", "token.balanceOf", "token.name", "native.balanceOf", "usdc.allowance", "usdc.balanceOf", "usdc.name", "gateway.v1.isDelegate", "gateway.v1.withdrawingBalance", "gateway.v1.withdrawalBlock", "gateway.v1.signBurnIntents"];
+/**
+ * Action keys that execute without preparing or submitting a transaction.
+ *
+ * @remarks
+ * Derive this type from the canonical runtime list so compile-time and runtime
+ * classification cannot drift. `gateway.v1.signBurnIntents` is included
+ * because the action system models off-chain signing as a read action: it does
+ * not prepare a chain request.
+ *
+ * @example
+ * ```typescript
+ * import type { ReadActionKey } from '@core/adapter'
+ *
+ * const action: ReadActionKey = 'token.allowance'
+ * ```
+ */
+type ReadActionKey = (typeof READ_ACTION_KEYS)[number];
+
 /**
  * Defines the capabilities of an adapter, including address handling patterns and supported chains.
  *
@@ -3599,6 +3637,69 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * ```
      */
     prepareAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>, ctx: OperationContext<TAdapterCapabilities>): Promise<PreparedChainRequest>;
+    /**
+     * Execute a non-transaction action without routing through transaction preparation.
+     *
+     * @remarks
+     * Use this seam for balance, allowance, contract-state, and other actions
+     * classified as reads. It never calls {@link Adapter.prepareAction}, so
+     * transaction authorization wrappers only observe actions that can produce a
+     * signable chain request.
+     *
+     * @typeParam TActionKey - The read action key.
+     * @param action - The read action to execute.
+     * @param params - The parameters for the read action.
+     * @param ctx - The operation context.
+     * @returns The raw action response.
+     * @throws {KitError} When the key is not a read action or no handler is registered.
+     * @throws Error When the operation context or action handler fails.
+     *
+     * @example
+     * ```typescript
+     * import { Ethereum } from '@core/chains'
+     *
+     * const balance = await adapter.readAction(
+     *   'token.balanceOf',
+     *   { tokenAddress, walletAddress },
+     *   { chain: Ethereum },
+     * )
+     * ```
+     *
+     * @internal
+     */
+    readAction<TActionKey extends ReadActionKey>(action: TActionKey, params: ActionPayload<TActionKey>, ctx: OperationContext<TAdapterCapabilities>): Promise<unknown>;
+    /**
+     * Read the current token allowance a delegate holds over an owner's tokens.
+     *
+     * @remarks
+     * Perform a network read through {@link Adapter.readAction}. This method
+     * never routes through {@link Adapter.prepareAction}. On chains without an
+     * allowance model, such as Solana, return the maximum uint256 value.
+     *
+     * @param params - The token to query and the delegate whose allowance is being read.
+     * @param ctx - Operation context with compile-time validated address requirements.
+     * @returns A promise resolving to the current allowance in the token's base units.
+     * @throws {KitError} When the adapter does not register a `token.allowance` handler.
+     * @throws Error When the operation context or action handler fails.
+     *
+     * @example
+     * ```typescript
+     * import type { Adapter } from '@core/adapter'
+     * import { Ethereum } from '@core/chains'
+     *
+     * declare const adapter: Adapter
+     *
+     * const allowance = await adapter.getTokenAllowance(
+     *   {
+     *     tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+     *     delegate: '0x1111111111111111111111111111111111111111',
+     *   },
+     *   { chain: Ethereum },
+     * )
+     * console.log(allowance) // 1000000n
+     * ```
+     */
+    getTokenAllowance(params: ActionPayload<'token.allowance'>, ctx: OperationContext<TAdapterCapabilities>): Promise<bigint>;
     /**
      * Prepares a transaction for future gas estimation and execution.
      *
@@ -3785,6 +3886,37 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
     abstract getTokenDecimals(tokenAddress: string, chain: ChainDefinition): Promise<number>;
 }
 
+/**
+ * Simplified error information structure for logging and events.
+ *
+ * @remarks
+ * This lightweight type is used for error reporting in events, logs, and
+ * observability systems. It provides essential error context without the
+ * full ErrorDetails structure. Used across retry mechanisms, adapters,
+ * and other subsystems that need to record error information.
+ *
+ * @example
+ * ```typescript
+ * import { ErrorInfo } from '@core/errors'
+ *
+ * const info: ErrorInfo = {
+ *   name: 'NETWORK_TIMEOUT',
+ *   message: 'Request timed out after 5000ms',
+ *   code: 3002
+ * }
+ * ```
+ */
+interface ErrorInfo {
+    /** Error name (e.g., 'TypeError', 'KitError', 'NETWORK_TIMEOUT'). */
+    name: string;
+    /** Error message describing what went wrong. */
+    message: string;
+    /** Optional error code if the error has one (e.g., KitError codes). */
+    code?: number;
+    /** Error category (e.g., INPUT, RPC, ONCHAIN, BALANCE, NETWORK, UNKNOWN). Only set for KitError instances. */
+    type?: string;
+}
+
 /**
  * A type-safe event emitter for managing action-based event subscriptions.
  *
@@ -4025,37 +4157,6 @@ declare module './types' {
     }
 }
 
-/**
- * Simplified error information structure for logging and events.
- *
- * @remarks
- * This lightweight type is used for error reporting in events, logs, and
- * observability systems. It provides essential error context without the
- * full ErrorDetails structure. Used across retry mechanisms, adapters,
- * and other subsystems that need to record error information.
- *
- * @example
- * ```typescript
- * import { ErrorInfo } from '@core/errors'
- *
- * const info: ErrorInfo = {
- *   name: 'NETWORK_TIMEOUT',
- *   message: 'Request timed out after 5000ms',
- *   code: 3002
- * }
- * ```
- */
-interface ErrorInfo {
-    /** Error name (e.g., 'TypeError', 'KitError', 'NETWORK_TIMEOUT'). */
-    name: string;
-    /** Error message describing what went wrong. */
-    message: string;
-    /** Optional error code if the error has one (e.g., KitError codes). */
-    code?: number;
-    /** Error category (e.g., INPUT, RPC, ONCHAIN, BALANCE, NETWORK, UNKNOWN). Only set for KitError instances. */
-    type?: string;
-}
-
 /**
  * Runtime array of token identifiers supported by the Gateway v1 provider.
  *

package/unifiedBalance.d.ts

@@ -739,6 +739,8 @@ declare enum Blockchain {
     World_Chain_Sepolia = "World_Chain_Sepolia",
     XDC = "XDC",
     XDC_Apothem = "XDC_Apothem",
+    X_Layer = "X_Layer",
+    X_Layer_Testnet = "X_Layer_Testnet",
     ZKSync_Era = "ZKSync_Era",
     ZKSync_Sepolia = "ZKSync_Sepolia"
 }
@@ -2602,6 +2604,18 @@ interface TokenActionMap {
          */
         walletAddress?: string | undefined;
     };
+    /**
+     * Get the on-chain name of the token contract.
+     *
+     * This is a read-only operation. For USDC the value is also the EIP-712
+     * domain name, which permit and authorize signing flows need.
+     */
+    name: ActionParameters & {
+        /**
+         * The contract address of the token.
+         */
+        tokenAddress: string;
+    };
 }
 
 /**
@@ -3431,6 +3445,30 @@ declare class ActionRegistry {
     executeAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>, context: ResolvedOperationContext): Promise<PreparedChainRequest>;
 }
 
+/**
+ * Canonical list of actions that do not prepare or submit transactions.
+ *
+ * @internal
+ */
+declare const READ_ACTION_KEYS: readonly ["token.allowance", "token.balanceOf", "token.name", "native.balanceOf", "usdc.allowance", "usdc.balanceOf", "usdc.name", "gateway.v1.isDelegate", "gateway.v1.withdrawingBalance", "gateway.v1.withdrawalBlock", "gateway.v1.signBurnIntents"];
+/**
+ * Action keys that execute without preparing or submitting a transaction.
+ *
+ * @remarks
+ * Derive this type from the canonical runtime list so compile-time and runtime
+ * classification cannot drift. `gateway.v1.signBurnIntents` is included
+ * because the action system models off-chain signing as a read action: it does
+ * not prepare a chain request.
+ *
+ * @example
+ * ```typescript
+ * import type { ReadActionKey } from '@core/adapter'
+ *
+ * const action: ReadActionKey = 'token.allowance'
+ * ```
+ */
+type ReadActionKey = (typeof READ_ACTION_KEYS)[number];
+
 /**
  * Defines the capabilities of an adapter, including address handling patterns and supported chains.
  *
@@ -3599,6 +3637,69 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * ```
      */
     prepareAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>, ctx: OperationContext<TAdapterCapabilities>): Promise<PreparedChainRequest>;
+    /**
+     * Execute a non-transaction action without routing through transaction preparation.
+     *
+     * @remarks
+     * Use this seam for balance, allowance, contract-state, and other actions
+     * classified as reads. It never calls {@link Adapter.prepareAction}, so
+     * transaction authorization wrappers only observe actions that can produce a
+     * signable chain request.
+     *
+     * @typeParam TActionKey - The read action key.
+     * @param action - The read action to execute.
+     * @param params - The parameters for the read action.
+     * @param ctx - The operation context.
+     * @returns The raw action response.
+     * @throws {KitError} When the key is not a read action or no handler is registered.
+     * @throws Error When the operation context or action handler fails.
+     *
+     * @example
+     * ```typescript
+     * import { Ethereum } from '@core/chains'
+     *
+     * const balance = await adapter.readAction(
+     *   'token.balanceOf',
+     *   { tokenAddress, walletAddress },
+     *   { chain: Ethereum },
+     * )
+     * ```
+     *
+     * @internal
+     */
+    readAction<TActionKey extends ReadActionKey>(action: TActionKey, params: ActionPayload<TActionKey>, ctx: OperationContext<TAdapterCapabilities>): Promise<unknown>;
+    /**
+     * Read the current token allowance a delegate holds over an owner's tokens.
+     *
+     * @remarks
+     * Perform a network read through {@link Adapter.readAction}. This method
+     * never routes through {@link Adapter.prepareAction}. On chains without an
+     * allowance model, such as Solana, return the maximum uint256 value.
+     *
+     * @param params - The token to query and the delegate whose allowance is being read.
+     * @param ctx - Operation context with compile-time validated address requirements.
+     * @returns A promise resolving to the current allowance in the token's base units.
+     * @throws {KitError} When the adapter does not register a `token.allowance` handler.
+     * @throws Error When the operation context or action handler fails.
+     *
+     * @example
+     * ```typescript
+     * import type { Adapter } from '@core/adapter'
+     * import { Ethereum } from '@core/chains'
+     *
+     * declare const adapter: Adapter
+     *
+     * const allowance = await adapter.getTokenAllowance(
+     *   {
+     *     tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+     *     delegate: '0x1111111111111111111111111111111111111111',
+     *   },
+     *   { chain: Ethereum },
+     * )
+     * console.log(allowance) // 1000000n
+     * ```
+     */
+    getTokenAllowance(params: ActionPayload<'token.allowance'>, ctx: OperationContext<TAdapterCapabilities>): Promise<bigint>;
     /**
      * Prepares a transaction for future gas estimation and execution.
      *
@@ -3785,6 +3886,37 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
     abstract getTokenDecimals(tokenAddress: string, chain: ChainDefinition): Promise<number>;
 }
 
+/**
+ * Simplified error information structure for logging and events.
+ *
+ * @remarks
+ * This lightweight type is used for error reporting in events, logs, and
+ * observability systems. It provides essential error context without the
+ * full ErrorDetails structure. Used across retry mechanisms, adapters,
+ * and other subsystems that need to record error information.
+ *
+ * @example
+ * ```typescript
+ * import { ErrorInfo } from '@core/errors'
+ *
+ * const info: ErrorInfo = {
+ *   name: 'NETWORK_TIMEOUT',
+ *   message: 'Request timed out after 5000ms',
+ *   code: 3002
+ * }
+ * ```
+ */
+interface ErrorInfo {
+    /** Error name (e.g., 'TypeError', 'KitError', 'NETWORK_TIMEOUT'). */
+    name: string;
+    /** Error message describing what went wrong. */
+    message: string;
+    /** Optional error code if the error has one (e.g., KitError codes). */
+    code?: number;
+    /** Error category (e.g., INPUT, RPC, ONCHAIN, BALANCE, NETWORK, UNKNOWN). Only set for KitError instances. */
+    type?: string;
+}
+
 /**
  * A type-safe event emitter for managing action-based event subscriptions.
  *
@@ -4025,37 +4157,6 @@ declare module './types' {
     }
 }
 
-/**
- * Simplified error information structure for logging and events.
- *
- * @remarks
- * This lightweight type is used for error reporting in events, logs, and
- * observability systems. It provides essential error context without the
- * full ErrorDetails structure. Used across retry mechanisms, adapters,
- * and other subsystems that need to record error information.
- *
- * @example
- * ```typescript
- * import { ErrorInfo } from '@core/errors'
- *
- * const info: ErrorInfo = {
- *   name: 'NETWORK_TIMEOUT',
- *   message: 'Request timed out after 5000ms',
- *   code: 3002
- * }
- * ```
- */
-interface ErrorInfo {
-    /** Error name (e.g., 'TypeError', 'KitError', 'NETWORK_TIMEOUT'). */
-    name: string;
-    /** Error message describing what went wrong. */
-    message: string;
-    /** Optional error code if the error has one (e.g., KitError codes). */
-    code?: number;
-    /** Error category (e.g., INPUT, RPC, ONCHAIN, BALANCE, NETWORK, UNKNOWN). Only set for KitError instances. */
-    type?: string;
-}
-
 /**
  * Runtime array of token identifiers supported by the Gateway v1 provider.
  *