@atomiqlabs/chain-evm 2.1.12 → 2.1.14

package/README.md

@@ -0,0 +1,75 @@
+# @atomiqlabs/chain-evm
+
+`@atomiqlabs/chain-evm` is the EVM integration package for the Atomiq protocol.
+
+Within the Atomiq stack, this library provides the EVM-side building blocks used for Bitcoin-aware swaps and SPV-backed vault flows on supported EVM-compatible chains. It includes:
+
+- chain initializers for Atomiq-supported EVM networks
+- the `EVMChainInterface` used to talk to chain RPCs
+- BTC relay, escrow swap, and SPV vault contract wrappers
+- browser and server-side EVM signer helpers
+- event utilities for tracking swap and vault activity
+
+This package is intended for direct protocol integrations and for higher-level Atomiq SDK layers that need EVM chain support.
+
+## Installation
+
+Install the package with its `ethers` peer dependency:
+
+```bash
+npm install @atomiqlabs/chain-evm ethers
+```
+
+## Node-only Classes
+
+The default package entrypoint stays browser-safe and does not export classes that depend on Node's `fs` module.
+
+Import backend-only utilities from the dedicated `node` subpath:
+
+```ts
+import {EVMChainEvents, EVMPersistentSigner} from "@atomiqlabs/chain-evm/node";
+```
+
+## Supported Chains
+
+The package currently exports chain initializers for:
+
+- Botanix via `BotanixInitializer`
+- Citrea via `CitreaInitializer`
+- Alpen via `AlpenInitializer`
+- GOAT Network via `GoatInitializer`
+
+Canonical deployments currently defined in this package:
+
+| Chain | Canonical deployments included |
+| --- | --- |
+| Botanix | `MAINNET`, `TESTNET` |
+| Citrea | `MAINNET`, `TESTNET4` |
+| Alpen | `TESTNET`, `TESTNET4` |
+| GOAT Network | `TESTNET`, `TESTNET4` |
+
+For Alpen and GOAT Network, `MAINNET` chain types exist in the API, but default mainnet contract addresses are not populated in this package yet. In those cases, pass explicit contract addresses if you want to use non-canonical deployments.
+
+## SDK Example
+
+Initialize the atomiq SDK with Citrea network support:
+
+```ts
+import {CitreaInitializer, CitreaInitializerType} from "@atomiqlabs/chain-evm";
+import {BitcoinNetwork, SwapperFactory, TypedSwapper} from "@atomiqlabs/sdk";
+
+//Define chains that you want to support here
+const chains = [CitreaInitializer] as const;
+type SupportedChains = typeof chains; //It's helpful that we also get the type of the chains array
+
+const Factory = new SwapperFactory<SupportedChains>(chains); //Create swapper factory
+
+const swapper: TypedSwapper<SupportedChains> = Factory.newSwapper({
+  chains: {
+    CITREA: {
+      rpcUrl: citreaRpc, //You can also pass JsonApiProvider object here
+    }
+  },
+  bitcoinNetwork: BitcoinNetwork.MAINNET //or BitcoinNetwork.TESTNET3, BitcoinNetwork.TESTNET4 - this also sets the deployment to use for EVM chains
+});
+```

package/dist/chains/EVMOptions.d.ts

@@ -0,0 +1,66 @@
+import { JsonRpcApiProvider } from "ethers";
+import { EVMConfiguration, EVMRetryPolicy } from "../evm/chain/EVMChainInterface";
+import { ChainSwapType } from "@atomiqlabs/base";
+import { EVMFees } from "../evm/chain/modules/EVMFees";
+/**
+ * Generic options for an EVM chain
+ *
+ * @category Chain Interface
+ */
+export type EVMOptions<C extends string, F extends EVMFees = EVMFees> = {
+    /**
+     * EVM RPC URL or {@link JsonRpcApiProvider} object to use for EVM network access
+     */
+    rpcUrl: string | JsonRpcApiProvider;
+    /**
+     * Retry policy for the RPC calls
+     */
+    retryPolicy?: EVMRetryPolicy;
+    /**
+     * Network type for the EVM chain
+     */
+    chainType?: C;
+    /**
+     * Contract address of the Escrow Manager contract, uses canonical deployment by default
+     */
+    swapContract?: string;
+    /**
+     * Optional Escrow Manager contract deployment height, which acts as genesis when querying events
+     */
+    swapContractDeploymentHeight?: number;
+    /**
+     * Contract address of the BTC Relay contract, uses canonical deployment by default
+     */
+    btcRelayContract?: string;
+    /**
+     * Optional BTC Relay contract deployment height, which acts as genesis when querying events
+     */
+    btcRelayDeploymentHeight?: number;
+    /**
+     * Contract address of the UTXO-controlled vault (SPV Vault manager) contract, uses canonical deployment by default
+     */
+    spvVaultContract?: string;
+    /**
+     * Optional UTXO-controlled vault (SPV Vault manager) contract deployment height, which acts as genesis when querying events
+     */
+    spvVaultDeploymentHeight?: number;
+    /**
+     * Contract addresses of the refund and claim handlers, uses canonical deployment by default
+     */
+    handlerContracts?: {
+        refund?: {
+            timelock?: string;
+        };
+        claim?: {
+            [type in ChainSwapType]?: string;
+        };
+    };
+    /**
+     * EVM network fee API
+     */
+    fees?: F;
+    /**
+     * EVM configuration
+     */
+    evmConfig?: Partial<Omit<EVMConfiguration, "safeBlockTag" | "finalizedBlockTag" | "finalityCheckStrategy">>;
+};

package/dist/chains/EVMOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/chains/alpen/AlpenInitializer.d.ts

@@ -1,43 +1,16 @@
-import { BaseTokenType, BitcoinNetwork, BitcoinRpc, ChainData, ChainInitializer, ChainSwapType } from "@atomiqlabs/base";
-import { JsonRpcApiProvider } from "ethers";
-import { EVMConfiguration, EVMRetryPolicy } from "../../evm/chain/EVMChainInterface";
-import { EVMFees } from "../../evm/chain/modules/EVMFees";
+import { BaseTokenType, BitcoinNetwork, BitcoinRpc, ChainData, ChainInitializer } from "@atomiqlabs/base";
 import { AlpenChainType } from "./AlpenChainType";
+import { EVMOptions } from "../EVMOptions";
 /**
  * Token assets available on Alpen
  * @category Networks/Alpen
  */
 export type AlpenAssetsType = BaseTokenType<"BTC">;
-/**
- * Default Alpen token assets configuration
- * @category Networks/Alpen
- */
-export declare const AlpenAssets: AlpenAssetsType;
 /**
  * Configuration options for initializing Alpen chain
  * @category Networks/Alpen
  */
-export type AlpenOptions = {
-    rpcUrl: string | JsonRpcApiProvider;
-    retryPolicy?: EVMRetryPolicy;
-    chainType?: "MAINNET" | "TESTNET" | "TESTNET4";
-    swapContract?: string;
-    swapContractDeploymentHeight?: number;
-    btcRelayContract?: string;
-    btcRelayDeploymentHeight?: number;
-    spvVaultContract?: string;
-    spvVaultDeploymentHeight?: number;
-    handlerContracts?: {
-        refund?: {
-            timelock?: string;
-        };
-        claim?: {
-            [type in ChainSwapType]?: string;
-        };
-    };
-    fees?: EVMFees;
-    evmConfig?: Partial<Omit<EVMConfiguration, "safeBlockTag" | "finalizedBlockTag" | "finalityCheckStrategy">>;
-};
+export type AlpenOptions = EVMOptions<"MAINNET" | "TESTNET" | "TESTNET4">;
 /**
  * Initialize Alpen chain integration
  * @category Networks/Alpen

package/dist/chains/alpen/AlpenInitializer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AlpenInitializer = exports.initializeAlpen = exports.AlpenAssets = void 0;
+exports.AlpenInitializer = exports.initializeAlpen = void 0;
 const base_1 = require("@atomiqlabs/base");
 const ethers_1 = require("ethers");
 const EVMChainInterface_1 = require("../../evm/chain/EVMChainInterface");
@@ -88,7 +88,7 @@ const chainTypeMapping = {
  * Default Alpen token assets configuration
  * @category Networks/Alpen
  */
-exports.AlpenAssets = {
+const AlpenAssets = {
     BTC: {
         address: "0x0000000000000000000000000000000000000000",
         decimals: 18,
@@ -156,6 +156,6 @@ exports.AlpenInitializer = {
     chainId: "ALPEN",
     chainType: null,
     initializer: initializeAlpen,
-    tokens: exports.AlpenAssets,
+    tokens: AlpenAssets,
     options: null
 };

package/dist/chains/botanix/BotanixInitializer.d.ts

@@ -1,43 +1,16 @@
-import { BaseTokenType, BitcoinNetwork, BitcoinRpc, ChainData, ChainInitializer, ChainSwapType } from "@atomiqlabs/base";
-import { JsonRpcApiProvider } from "ethers";
-import { EVMConfiguration, EVMRetryPolicy } from "../../evm/chain/EVMChainInterface";
-import { EVMFees } from "../../evm/chain/modules/EVMFees";
+import { BaseTokenType, BitcoinNetwork, BitcoinRpc, ChainData, ChainInitializer } from "@atomiqlabs/base";
 import { BotanixChainType } from "./BotanixChainType";
+import { EVMOptions } from "../EVMOptions";
 /**
  * Token assets available on Botanix
  * @category Networks/Botanix
  */
 export type BotanixAssetsType = BaseTokenType<"BTC">;
-/**
- * Default Botanix token assets configuration
- * @category Networks/Botanix
- */
-export declare const BotanixAssets: BotanixAssetsType;
 /**
  * Configuration options for initializing Botanix chain
  * @category Networks/Botanix
  */
-export type BotanixOptions = {
-    rpcUrl: string | JsonRpcApiProvider;
-    retryPolicy?: EVMRetryPolicy;
-    chainType?: "MAINNET" | "TESTNET";
-    swapContract?: string;
-    swapContractDeploymentHeight?: number;
-    btcRelayContract?: string;
-    btcRelayDeploymentHeight?: number;
-    spvVaultContract?: string;
-    spvVaultDeploymentHeight?: number;
-    handlerContracts?: {
-        refund?: {
-            timelock?: string;
-        };
-        claim?: {
-            [type in ChainSwapType]?: string;
-        };
-    };
-    fees?: EVMFees;
-    evmConfig?: Partial<Omit<EVMConfiguration, "safeBlockTag" | "finalizedBlockTag" | "finalityCheckStrategy">>;
-};
+export type BotanixOptions = EVMOptions<"MAINNET" | "TESTNET">;
 /**
  * Initialize Botanix chain integration
  * @category Networks/Botanix

package/dist/chains/botanix/BotanixInitializer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BotanixInitializer = exports.initializeBotanix = exports.BotanixAssets = void 0;
+exports.BotanixInitializer = exports.initializeBotanix = void 0;
 const base_1 = require("@atomiqlabs/base");
 const ethers_1 = require("ethers");
 const EVMChainInterface_1 = require("../../evm/chain/EVMChainInterface");
@@ -66,7 +66,7 @@ const chainTypeMapping = {
  * Default Botanix token assets configuration
  * @category Networks/Botanix
  */
-exports.BotanixAssets = {
+const BotanixAssets = {
     BTC: {
         address: "0x0000000000000000000000000000000000000000",
         decimals: 18,
@@ -138,6 +138,6 @@ exports.BotanixInitializer = {
     chainId: "BOTANIX",
     chainType: null,
     initializer: initializeBotanix,
-    tokens: exports.BotanixAssets,
+    tokens: BotanixAssets,
     options: null
 };

package/dist/chains/citrea/CitreaBtcRelay.d.ts

@@ -1,5 +1,10 @@
 import { EVMBtcRelay } from "../../evm/btcrelay/EVMBtcRelay";
 import { BtcBlock } from "@atomiqlabs/base";
+/**
+ * Citrea BTC relay wrapper with fee estimation that includes Citrea state-diff costs.
+ *
+ * @category Networks/Citrea
+ */
 export declare class CitreaBtcRelay<B extends BtcBlock> extends EVMBtcRelay<B> {
     static StateDiffSize: {
         STATE_DIFF_PER_BLOCKHEADER: number;

package/dist/chains/citrea/CitreaBtcRelay.js

@@ -5,6 +5,11 @@ const EVMBtcRelay_1 = require("../../evm/btcrelay/EVMBtcRelay");
 const Utils_1 = require("../../utils/Utils");
 const CitreaFees_1 = require("./CitreaFees");
 const logger = (0, Utils_1.getLogger)("CitreaBtcRelay: ");
+/**
+ * Citrea BTC relay wrapper with fee estimation that includes Citrea state-diff costs.
+ *
+ * @category Networks/Citrea
+ */
 class CitreaBtcRelay extends EVMBtcRelay_1.EVMBtcRelay {
     /**
      * Estimate required synchronization fee (worst case) to synchronize btc relay to the required blockheight
@@ -23,7 +28,7 @@ class CitreaBtcRelay extends EVMBtcRelay_1.EVMBtcRelay {
             return 0n;
         const numTxs = Math.ceil(blockheightDelta / this.maxHeadersPerTx);
         const synchronizationFee = (BigInt(blockheightDelta) * await this.getFeePerBlock(feeRate))
-            + CitreaFees_1.CitreaFees.getGasFee(EVMBtcRelay_1.EVMBtcRelay.GasCosts.GAS_BASE_MAIN * numTxs, feeRate, CitreaBtcRelay.StateDiffSize.STATE_DIFF_BASE * numTxs);
+            + CitreaFees_1.CitreaFees.getGasFee(EVMBtcRelay_1.EVMBtcRelay._GasCosts.GAS_BASE_MAIN * numTxs, feeRate, CitreaBtcRelay.StateDiffSize.STATE_DIFF_BASE * numTxs);
         logger.debug("estimateSynchronizeFee(): required blockheight: " + requiredBlockheight +
             " blockheight delta: " + blockheightDelta + " fee: " + synchronizationFee.toString(10));
         return synchronizationFee;
@@ -35,7 +40,7 @@ class CitreaBtcRelay extends EVMBtcRelay_1.EVMBtcRelay {
      */
     async getFeePerBlock(feeRate) {
         feeRate ?? (feeRate = await this.Chain.Fees.getFeeRate());
-        return CitreaFees_1.CitreaFees.getGasFee(EVMBtcRelay_1.EVMBtcRelay.GasCosts.GAS_PER_BLOCKHEADER, feeRate, CitreaBtcRelay.StateDiffSize.STATE_DIFF_PER_BLOCKHEADER);
+        return CitreaFees_1.CitreaFees.getGasFee(EVMBtcRelay_1.EVMBtcRelay._GasCosts.GAS_PER_BLOCKHEADER, feeRate, CitreaBtcRelay.StateDiffSize.STATE_DIFF_PER_BLOCKHEADER);
     }
 }
 exports.CitreaBtcRelay = CitreaBtcRelay;

package/dist/chains/citrea/CitreaFees.d.ts

@@ -3,9 +3,9 @@ import { EVMFees } from "../../evm/chain/modules/EVMFees";
  * @category Networks/Citrea
  */
 export declare class CitreaFees extends EVMFees {
-    static readonly StateDiffSize: {
-        APPROVE_DIFF_SIZE: number;
-    };
+    /**
+     * @internal
+     */
     protected readonly logger: import("../../utils/Utils").LoggerType;
     private _blockFeeCache?;
     /**
@@ -17,8 +17,6 @@ export declare class CitreaFees extends EVMFees {
     private __getFeeRate;
     /**
      * Gets the gas price with caching, format: <gas price in Wei>;<transaction version: v1/v3>
-     *
-     * @private
      */
     getFeeRate(): Promise<string>;
     /**

package/dist/chains/citrea/CitreaFees.js

@@ -9,6 +9,9 @@ const Utils_1 = require("../../utils/Utils");
 class CitreaFees extends EVMFees_1.EVMFees {
     constructor() {
         super(...arguments);
+        /**
+         * @internal
+         */
         this.logger = (0, Utils_1.getLogger)("CitreaFees: ");
     }
     /**
@@ -26,8 +29,6 @@ class CitreaFees extends EVMFees_1.EVMFees {
     }
     /**
      * Gets the gas price with caching, format: <gas price in Wei>;<transaction version: v1/v3>
-     *
-     * @private
      */
     async getFeeRate() {
         if (this._blockFeeCache == null || Date.now() - this._blockFeeCache.timestamp > this.MAX_FEE_AGE) {
@@ -63,6 +64,3 @@ class CitreaFees extends EVMFees_1.EVMFees {
     }
 }
 exports.CitreaFees = CitreaFees;
-CitreaFees.StateDiffSize = {
-    APPROVE_DIFF_SIZE: 40,
-};

package/dist/chains/citrea/CitreaInitializer.d.ts

@@ -1,43 +1,17 @@
-import { BaseTokenType, BitcoinNetwork, BitcoinRpc, ChainData, ChainInitializer, ChainSwapType } from "@atomiqlabs/base";
-import { JsonRpcApiProvider } from "ethers";
-import { EVMConfiguration, EVMRetryPolicy } from "../../evm/chain/EVMChainInterface";
+import { BaseTokenType, BitcoinNetwork, BitcoinRpc, ChainData, ChainInitializer } from "@atomiqlabs/base";
 import { CitreaChainType } from "./CitreaChainType";
 import { CitreaFees } from "./CitreaFees";
+import { EVMOptions } from "../EVMOptions";
 /**
  * Token assets available on Citrea
  * @category Networks/Citrea
  */
 export type CitreaAssetsType = BaseTokenType<"CBTC" | "WBTC" | "USDC">;
-/**
- * Default Citrea token assets configuration
- * @category Networks/Citrea
- */
-export declare const CitreaAssets: CitreaAssetsType;
 /**
  * Configuration options for initializing Citrea chain
  * @category Networks/Citrea
  */
-export type CitreaOptions = {
-    rpcUrl: string | JsonRpcApiProvider;
-    retryPolicy?: EVMRetryPolicy;
-    chainType?: "MAINNET" | "TESTNET4";
-    swapContract?: string;
-    swapContractDeploymentHeight?: number;
-    btcRelayContract?: string;
-    btcRelayDeploymentHeight?: number;
-    spvVaultContract?: string;
-    spvVaultDeploymentHeight?: number;
-    handlerContracts?: {
-        refund?: {
-            timelock?: string;
-        };
-        claim?: {
-            [type in ChainSwapType]?: string;
-        };
-    };
-    fees?: CitreaFees;
-    evmConfig?: Partial<Omit<EVMConfiguration, "safeBlockTag" | "finalizedBlockTag" | "finalityCheckStrategy">>;
-};
+export type CitreaOptions = EVMOptions<"MAINNET" | "TESTNET4", CitreaFees>;
 /**
  * Initialize Citrea chain integration
  * @category Networks/Citrea

package/dist/chains/citrea/CitreaInitializer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CitreaInitializer = exports.initializeCitrea = exports.CitreaAssets = void 0;
+exports.CitreaInitializer = exports.initializeCitrea = void 0;
 const base_1 = require("@atomiqlabs/base");
 const ethers_1 = require("ethers");
 const EVMChainInterface_1 = require("../../evm/chain/EVMChainInterface");
@@ -67,7 +67,7 @@ const chainTypeMapping = {
  * Default Citrea token assets configuration
  * @category Networks/Citrea
  */
-exports.CitreaAssets = {
+const CitreaAssets = {
     CBTC: {
         address: "0x0000000000000000000000000000000000000000",
         decimals: 18,
@@ -148,6 +148,6 @@ exports.CitreaInitializer = {
     chainId: "CITREA",
     chainType: null,
     initializer: initializeCitrea,
-    tokens: exports.CitreaAssets,
+    tokens: CitreaAssets,
     options: null
 };

package/dist/chains/citrea/CitreaSpvVaultContract.d.ts

@@ -1,6 +1,11 @@
 import { EVMSpvVaultContract } from "../../evm/spv_swap/EVMSpvVaultContract";
 import { EVMSpvWithdrawalData } from "../../evm/spv_swap/EVMSpvWithdrawalData";
 import { EVMSpvVaultData } from "../../evm/spv_swap/EVMSpvVaultData";
+/**
+ * Citrea SPV vault wrapper with fee estimation adjusted by expected state-diff size.
+ *
+ * @category Networks/Citrea
+ */
 export declare class CitreaSpvVaultContract extends EVMSpvVaultContract<"CITREA"> {
     static readonly StateDiffSize: {
         BASE_DIFF_SIZE: number;

package/dist/chains/citrea/CitreaSpvVaultContract.js

@@ -6,6 +6,11 @@ const EVMSpvVaultData_1 = require("../../evm/spv_swap/EVMSpvVaultData");
 const ethers_1 = require("ethers");
 const CitreaFees_1 = require("./CitreaFees");
 const EVMAddresses_1 = require("../../evm/chain/modules/EVMAddresses");
+/**
+ * Citrea SPV vault wrapper with fee estimation adjusted by expected state-diff size.
+ *
+ * @category Networks/Citrea
+ */
 class CitreaSpvVaultContract extends EVMSpvVaultContract_1.EVMSpvVaultContract {
     calculateStateDiff(signer, tokenStateChanges) {
         let stateDiffSize = 0;
@@ -21,7 +26,7 @@ class CitreaSpvVaultContract extends EVMSpvVaultContract_1.EVMSpvVaultContract {
         return stateDiffSize;
     }
     async getClaimFee(signer, vault, data, feeRate) {
-        vault ?? (vault = EVMSpvVaultData_1.EVMSpvVaultData.randomVault());
+        vault ?? (vault = EVMSpvVaultData_1.EVMSpvVaultData._randomVault());
         feeRate ?? (feeRate = await this.Chain.Fees.getFeeRate());
         const tokenStateChanges = new Set();
         let diffSize = CitreaSpvVaultContract.StateDiffSize.BASE_DIFF_SIZE;
@@ -49,7 +54,7 @@ class CitreaSpvVaultContract extends EVMSpvVaultContract_1.EVMSpvVaultContract {
         return gasFee + CitreaFees_1.CitreaFees.getGasFee(0, feeRate, diffSize);
     }
     async getFrontFee(signer, vault, data, feeRate) {
-        vault ?? (vault = EVMSpvVaultData_1.EVMSpvVaultData.randomVault());
+        vault ?? (vault = EVMSpvVaultData_1.EVMSpvVaultData._randomVault());
         feeRate ?? (feeRate = await this.Chain.Fees.getFeeRate());
         const tokenStateChanges = new Set();
         let diffSize = CitreaSpvVaultContract.StateDiffSize.BASE_DIFF_SIZE;

package/dist/chains/citrea/CitreaSwapContract.d.ts

@@ -1,5 +1,10 @@
 import { EVMSwapContract } from "../../evm/swaps/EVMSwapContract";
 import { EVMSwapData } from "../../evm/swaps/EVMSwapData";
+/**
+ * Citrea swap contract wrapper with fee estimation adjusted by expected state-diff size.
+ *
+ * @category Networks/Citrea
+ */
 export declare class CitreaSwapContract extends EVMSwapContract<"CITREA"> {
     static readonly StateDiffSize: {
         BASE_DIFF_SIZE: number;
@@ -11,12 +16,12 @@ export declare class CitreaSwapContract extends EVMSwapContract<"CITREA"> {
     };
     private calculateStateDiff;
     /**
-     * Get the estimated solana fee of the commit transaction
+     * Returns estimated fee of the commit transaction, including Citrea state-diff overhead.
      */
     getCommitFee(signer: string, swapData: EVMSwapData, feeRate?: string): Promise<bigint>;
     getClaimFee(signer: string, swapData: EVMSwapData, feeRate?: string): Promise<bigint>;
     /**
-     * Get the estimated solana transaction fee of the refund transaction
+     * Returns estimated fee of the refund transaction, including Citrea state-diff overhead.
      */
     getRefundFee(signer: string, swapData: EVMSwapData, feeRate?: string): Promise<bigint>;
 }

package/dist/chains/citrea/CitreaSwapContract.js

@@ -3,6 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CitreaSwapContract = void 0;
 const EVMSwapContract_1 = require("../../evm/swaps/EVMSwapContract");
 const CitreaFees_1 = require("./CitreaFees");
+/**
+ * Citrea swap contract wrapper with fee estimation adjusted by expected state-diff size.
+ *
+ * @category Networks/Citrea
+ */
 class CitreaSwapContract extends EVMSwapContract_1.EVMSwapContract {
     calculateStateDiff(signer, tokenStateChanges) {
         let stateDiffSize = 0;
@@ -18,7 +23,7 @@ class CitreaSwapContract extends EVMSwapContract_1.EVMSwapContract {
         return stateDiffSize;
     }
     /**
-     * Get the estimated solana fee of the commit transaction
+     * Returns estimated fee of the commit transaction, including Citrea state-diff overhead.
      */
     async getCommitFee(signer, swapData, feeRate) {
         feeRate ?? (feeRate = await this.Chain.Fees.getFeeRate());
@@ -34,7 +39,7 @@ class CitreaSwapContract extends EVMSwapContract_1.EVMSwapContract {
             tokenStateChanges.add(signer.toLowerCase() + ":" + swapData.getDepositToken().toLowerCase());
         }
         diffSize += this.calculateStateDiff(signer, tokenStateChanges);
-        const gasFee = await this.Init.getInitFee(swapData, feeRate);
+        const gasFee = await this._Init.getInitFee(swapData, feeRate);
         return gasFee + CitreaFees_1.CitreaFees.getGasFee(0, feeRate, diffSize);
     }
     async getClaimFee(signer, swapData, feeRate) {
@@ -56,11 +61,11 @@ class CitreaSwapContract extends EVMSwapContract_1.EVMSwapContract {
             tokenStateChanges.add(swapData.getClaimer().toLowerCase() + ":" + swapData.getDepositToken().toLowerCase());
         }
         diffSize += this.calculateStateDiff(signer, tokenStateChanges);
-        const gasFee = await this.Claim.getClaimFee(swapData, feeRate);
+        const gasFee = await this._Claim.getClaimFee(swapData, feeRate);
         return gasFee + CitreaFees_1.CitreaFees.getGasFee(0, feeRate, diffSize);
     }
     /**
-     * Get the estimated solana transaction fee of the refund transaction
+     * Returns estimated fee of the refund transaction, including Citrea state-diff overhead.
      */
     async getRefundFee(signer, swapData, feeRate) {
         feeRate ?? (feeRate = await this.Chain.Fees.getFeeRate());
@@ -81,7 +86,7 @@ class CitreaSwapContract extends EVMSwapContract_1.EVMSwapContract {
             tokenStateChanges.add(swapData.getClaimer().toLowerCase() + ":" + swapData.getDepositToken().toLowerCase());
         }
         diffSize += this.calculateStateDiff(signer, tokenStateChanges);
-        const gasFee = await this.Refund.getRefundFee(swapData, feeRate);
+        const gasFee = await this._Refund.getRefundFee(swapData, feeRate);
         return gasFee + CitreaFees_1.CitreaFees.getGasFee(0, feeRate, diffSize);
     }
 }

package/dist/chains/citrea/CitreaTokens.d.ts

@@ -1,4 +1,9 @@
 import { EVMTokens } from "../../evm/chain/modules/EVMTokens";
+/**
+ * Citrea-specific token module that augments fee estimation with state-diff costs.
+ *
+ * @category Networks/Citrea
+ */
 export declare class CitreaTokens extends EVMTokens {
     static readonly StateDiffSize: {
         APPROVE_DIFF_SIZE: number;

package/dist/chains/citrea/CitreaTokens.js

@@ -3,6 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CitreaTokens = void 0;
 const EVMTokens_1 = require("../../evm/chain/modules/EVMTokens");
 const CitreaFees_1 = require("./CitreaFees");
+/**
+ * Citrea-specific token module that augments fee estimation with state-diff costs.
+ *
+ * @category Networks/Citrea
+ */
 class CitreaTokens extends EVMTokens_1.EVMTokens {
     async getApproveFee(feeRate) {
         feeRate ?? (feeRate = await this.root.Fees.getFeeRate());

package/dist/chains/goat/GoatInitializer.d.ts

@@ -1,43 +1,16 @@
-import { BaseTokenType, BitcoinNetwork, BitcoinRpc, ChainData, ChainInitializer, ChainSwapType } from "@atomiqlabs/base";
-import { JsonRpcApiProvider } from "ethers";
-import { EVMConfiguration, EVMRetryPolicy } from "../../evm/chain/EVMChainInterface";
-import { EVMFees } from "../../evm/chain/modules/EVMFees";
+import { BaseTokenType, BitcoinNetwork, BitcoinRpc, ChainData, ChainInitializer } from "@atomiqlabs/base";
 import { GoatChainType } from "./GoatChainType";
+import { EVMOptions } from "../EVMOptions";
 /**
  * Token assets available on GOAT Network
  * @category Networks/GOAT
  */
 export type GoatAssetsType = BaseTokenType<"BTC" | "PBTC" | "_PBTC_DEV">;
-/**
- * Default GOAT Network token assets configuration
- * @category Networks/GOAT
- */
-export declare const GoatAssets: GoatAssetsType;
 /**
  * Configuration options for initializing GOAT Network chain
  * @category Networks/GOAT
  */
-export type GoatOptions = {
-    rpcUrl: string | JsonRpcApiProvider;
-    retryPolicy?: EVMRetryPolicy;
-    chainType?: "MAINNET" | "TESTNET" | "TESTNET4";
-    swapContract?: string;
-    swapContractDeploymentHeight?: number;
-    btcRelayContract?: string;
-    btcRelayDeploymentHeight?: number;
-    spvVaultContract?: string;
-    spvVaultDeploymentHeight?: number;
-    handlerContracts?: {
-        refund?: {
-            timelock?: string;
-        };
-        claim?: {
-            [type in ChainSwapType]?: string;
-        };
-    };
-    fees?: EVMFees;
-    evmConfig?: Partial<Omit<EVMConfiguration, "safeBlockTag" | "finalizedBlockTag" | "finalityCheckStrategy">>;
-};
+export type GoatOptions = EVMOptions<"MAINNET" | "TESTNET" | "TESTNET4">;
 /**
  * Initialize GOAT Network chain integration
  * @category Networks/GOAT