@atomiqlabs/chain-evm 2.1.12 → 2.1.14

package/src/evm/swaps/handlers/claim/btc/IBitcoinClaimHandler.ts

@@ -8,11 +8,21 @@ import {keccak256} from "ethers";
 import {Buffer} from "buffer";
 import {EVMSwapData} from "../../../EVMSwapData";
 
+/**
+ * Common commitment fields used by all bitcoin-based claim handlers.
+ *
+ * @category Internal/Handlers
+ */
 export type BitcoinCommitmentData = {
     btcRelay: EVMBtcRelay<any>,
     confirmations: number
 }
 
+/**
+ * Common witness input for bitcoin-based claim handlers.
+ *
+ * @category Internal/Handlers
+ */
 export type BitcoinWitnessData = {
     tx: { blockhash: string, confirmations: number, txid: string, hex: string, height: number },
     requiredConfirmations: number,
@@ -23,6 +33,11 @@ export type BitcoinWitnessData = {
 
 const logger = getLogger("IBitcoinClaimHandler: ");
 
+/**
+ * Shared base implementation for bitcoin-backed claim handlers.
+ *
+ * @category Internal/Handlers
+ */
 export abstract class IBitcoinClaimHandler<C, W extends BitcoinWitnessData> implements IClaimHandler<C & BitcoinCommitmentData, W> {
 
     public readonly address: string;
@@ -38,7 +53,7 @@ export abstract class IBitcoinClaimHandler<C, W extends BitcoinWitnessData> impl
     protected serializeCommitment(data: BitcoinCommitmentData): Buffer {
         const buffer = Buffer.alloc(24);
         buffer.writeUint32BE(data.confirmations, 0);
-        Buffer.from(data.btcRelay.contractAddress.substring(2), "hex").copy(buffer, 4, 0, 20);
+        Buffer.from(data.btcRelay._contractAddress.substring(2), "hex").copy(buffer, 4, 0, 20);
         return buffer;
     }
 
@@ -68,7 +83,7 @@ export abstract class IBitcoinClaimHandler<C, W extends BitcoinWitnessData> impl
 
         if(!swapData.isClaimData(commitmentHash)) throw new Error("Invalid commit data");
 
-        const merkleProof = await btcRelay.bitcoinRpc.getMerkleProof(tx.txid, tx.blockhash);
+        const merkleProof = await btcRelay._bitcoinRpc.getMerkleProof(tx.txid, tx.blockhash);
         if(merkleProof==null) throw new Error(`Failed to generate merkle proof for tx: ${tx.txid}!`);
         logger.debug("getWitness(): merkle proof computed: ", merkleProof);
 

package/src/evm/swaps/modules/EVMLpVault.ts

@@ -4,6 +4,11 @@ import {TransactionRequest} from "ethers";
 import {EVMFees} from "../../chain/modules/EVMFees";
 import {EVMTx} from "../../chain/modules/EVMTransactions";
 
+/**
+ * LP vault helper for intermediary balances, reputation and LP deposit/withdraw transactions.
+ *
+ * @category Internal/Swaps
+ */
 export class EVMLpVault extends EVMSwapModule {
 
     private static readonly GasCosts = {
@@ -71,13 +76,13 @@ export class EVMLpVault extends EVMSwapModule {
      * @param token
      */
     public async getIntermediaryReputation(address: string, token: string): Promise<IntermediaryReputationType> {
-        const filter = Object.keys(this.contract.claimHandlersByAddress).map(claimHandler => ({owner: address, token, claimHandler}));
+        const filter = Object.keys(this.contract._claimHandlersByAddress).map(claimHandler => ({owner: address, token, claimHandler}));
         const resp = await this.swapContract.getReputation(filter);
         if(resp.length!==filter.length) throw new Error("getIntermediaryReputation(): Invalid response length");
 
         const result: any = {};
-        Object.keys(this.contract.claimHandlersByAddress).forEach((address, index) => {
-            const handler = this.contract.claimHandlersByAddress[address.toLowerCase()];
+        Object.keys(this.contract._claimHandlersByAddress).forEach((address, index) => {
+            const handler = this.contract._claimHandlersByAddress[address.toLowerCase()];
             const handlerResp = resp[index];
             result[handler.getType()] = {
                 successVolume: handlerResp[0].amount,
@@ -140,7 +145,7 @@ export class EVMLpVault extends EVMSwapModule {
 
         //Approve first
         if(token.toLowerCase()!==this.root.getNativeCurrencyAddress().toLowerCase()) {
-            const approveTx = await this.root.Tokens.checkAndGetApproveTx(signer, token, amount, this.contract.contractAddress, feeRate);
+            const approveTx = await this.root.Tokens.checkAndGetApproveTx(signer, token, amount, this.contract._contractAddress, feeRate);
             if(approveTx!=null) txs.push(approveTx);
         }
 
@@ -152,4 +157,4 @@ export class EVMLpVault extends EVMSwapModule {
         return txs;
     }
 
-}
+}

package/src/evm/swaps/modules/EVMSwapClaim.ts

@@ -10,6 +10,11 @@ import {EVMFees} from "../../chain/modules/EVMFees";
 import {EVMTx} from "../../chain/modules/EVMTransactions";
 import {EVMBtcStoredHeader} from "../../btcrelay/headers/EVMBtcStoredHeader";
 
+/**
+ * Swap claim helper for HTLC and BTC on-chain claim paths.
+ *
+ * @category Internal/Swaps
+ */
 export class EVMSwapClaim extends EVMSwapModule {
 
     private static readonly GasCosts = {
@@ -67,7 +72,7 @@ export class EVMSwapClaim extends EVMSwapModule {
             throw new SwapDataVerificationError("Not enough time to reliably pay the invoice");
         }
 
-        const claimHandler: IClaimHandler<Buffer, string> = this.contract.claimHandlersByAddress[swapData.claimHandler.toLowerCase()];
+        const claimHandler: IClaimHandler<Buffer, string> = this.contract._claimHandlersByAddress[swapData.claimHandler.toLowerCase()];
         if(claimHandler==null) throw new SwapDataVerificationError("Unknown claim handler!");
         if(claimHandler.getType()!==ChainSwapType.HTLC) throw new SwapDataVerificationError("Invalid claim handler!");
 
@@ -89,7 +94,7 @@ export class EVMSwapClaim extends EVMSwapModule {
      * @param tx bitcoin transaction that satisfies the swap condition
      * @param requiredConfirmations
      * @param vout vout of the bitcoin transaction that satisfies the swap condition
-     * @param commitedHeader commited header data from btc relay (fetched internally if null)
+     * @param commitedHeader committed header data from BTC relay (fetched internally if null)
      * @param synchronizer optional synchronizer to use in case we need to sync up the btc relay ourselves
      * @param feeRate fee rate to be used for the transactions
      */
@@ -103,7 +108,7 @@ export class EVMSwapClaim extends EVMSwapModule {
         synchronizer?: RelaySynchronizer<EVMBtcStoredHeader, EVMTx, any>,
         feeRate?: string
     ): Promise<EVMTx[]> {
-        const claimHandler: IClaimHandler<any, BitcoinOutputWitnessData | BitcoinWitnessData> = this.contract.claimHandlersByAddress[swapData.claimHandler.toLowerCase()];
+        const claimHandler: IClaimHandler<any, BitcoinOutputWitnessData | BitcoinWitnessData> = this.contract._claimHandlersByAddress[swapData.claimHandler.toLowerCase()];
         if(claimHandler==null) throw new SwapDataVerificationError("Unknown claim handler!");
         if(
             claimHandler.getType()!==ChainSwapType.CHAIN_NONCED &&
@@ -118,7 +123,7 @@ export class EVMSwapClaim extends EVMSwapModule {
             vout,
             requiredConfirmations,
             commitedHeader,
-            btcRelay: this.contract.btcRelay,
+            btcRelay: this.contract._btcRelay,
             synchronizer,
         }, feeRate);
         const claimTx = await this.Claim(signer, swapData, witness, feeRate, claimHandler.getGas(swapData));
@@ -156,7 +161,7 @@ export class EVMSwapClaim extends EVMSwapModule {
     }
 
     /**
-     * Get the estimated starknet transaction fee of the claim transaction
+     * Returns the estimated fee of the claim transaction.
      */
     public async getClaimFee(swapData: EVMSwapData, feeRate?: string): Promise<bigint> {
         feeRate ??= await this.root.Fees.getFeeRate();
@@ -164,10 +169,10 @@ export class EVMSwapClaim extends EVMSwapModule {
         //TODO: Claim with success action not supported yet!
         let gasRequired = this.getClaimGas(swapData);
 
-        const claimHandler: IClaimHandler<any, any> = this.contract.claimHandlersByAddress[swapData.claimHandler.toLowerCase()];
+        const claimHandler: IClaimHandler<any, any> = this.contract._claimHandlersByAddress[swapData.claimHandler.toLowerCase()];
         if(claimHandler!=null) gasRequired += claimHandler.getGas(swapData);
 
         return EVMFees.getGasFee(gasRequired, feeRate);
     }
 
-}
+}

package/src/evm/swaps/modules/EVMSwapInit.ts

@@ -6,6 +6,11 @@ import {EVMFees} from "../../chain/modules/EVMFees";
 import {EVMSigner} from "../../wallet/EVMSigner";
 import {EVMTx} from "../../chain/modules/EVMTransactions";
 
+/**
+ * Prefetched values used for initialization signature verification.
+ *
+ * @category Internal/Swaps
+ */
 export type EVMPreFetchVerification = {
     safeBlockTime: number
 };
@@ -31,6 +36,11 @@ const Initialize = [
     { name: "extraDataHash", type: "bytes32" }
 ];
 
+/**
+ * Swap initialization helper handling authorization signatures and init transaction construction.
+ *
+ * @category Internal/Swaps
+ */
 export class EVMSwapInit extends EVMSwapModule {
 
     private static readonly GasCosts = {
@@ -76,7 +86,7 @@ export class EVMSwapInit extends EVMSwapModule {
 
     public async preFetchForInitSignatureVerification(): Promise<EVMPreFetchVerification> {
         return {
-            safeBlockTime: await this.root.Blocks.getBlockTime(this.root.config.safeBlockTag)
+            safeBlockTime: await this.root.Blocks.getBlockTime(this.root._config.safeBlockTag)
         };
     }
 
@@ -96,7 +106,7 @@ export class EVMSwapInit extends EVMSwapModule {
     ): Promise<{prefix: string, timeout: string, signature: string}> {
         const authExpiry = Math.floor(Date.now()/1000)+authorizationTimeout;
 
-        const signature = await this.root.Signatures.signTypedMessage(this.contract.contractAddress, signer, Initialize, "Initialize", {
+        const signature = await this.root.Signatures.signTypedMessage(this.contract._contractAddress, signer, Initialize, "Initialize", {
             "swapHash": "0x"+swapData.getEscrowHash(),
             "offerer": swapData.offerer,
             "claimer": swapData.claimer,
@@ -156,11 +166,11 @@ export class EVMSwapInit extends EVMSwapModule {
 
         const currentTimestamp = BigInt(Math.floor(Date.now() / 1000));
         const timeoutBN = BigInt(timeout);
-        const isExpired = (timeoutBN - currentTimestamp) < BigInt(this.contract.authGracePeriod);
+        const isExpired = (timeoutBN - currentTimestamp) < BigInt(this.contract._authGracePeriod);
         if (isExpired) throw new SignatureVerificationError("Authorization expired!");
         if(await this.isSignatureExpired(timeout, preFetchData)) throw new SignatureVerificationError("Authorization expired!");
 
-        const valid = await this.root.Signatures.isValidSignature(this.contract.contractAddress, signature, signer, Initialize, "Initialize", {
+        const valid = await this.root.Signatures.isValidSignature(this.contract._contractAddress, signature, signer, Initialize, "Initialize", {
             "swapHash": "0x"+swapData.getEscrowHash(),
             "offerer": swapData.offerer,
             "claimer": swapData.claimer,
@@ -196,7 +206,7 @@ export class EVMSwapInit extends EVMSwapModule {
         timeout: string
     ): Promise<number> {
         const now = Date.now();
-        const timeoutExpiryTime = (parseInt(timeout)-this.contract.authGracePeriod)*1000;
+        const timeoutExpiryTime = (parseInt(timeout)-this.contract._authGracePeriod)*1000;
 
         if(timeoutExpiryTime<now) return 0;
 
@@ -272,7 +282,7 @@ export class EVMSwapInit extends EVMSwapModule {
         }
 
         const requiredApprovalTxns = await Promise.all(
-            Object.keys(requiredApprovals).map(token => this.root.Tokens.checkAndGetApproveTx(sender, token, requiredApprovals[token], this.contract.contractAddress, feeRate))
+            Object.keys(requiredApprovals).map(token => this.root.Tokens.checkAndGetApproveTx(sender, token, requiredApprovals[token], this.contract._contractAddress, feeRate))
         );
         requiredApprovalTxns.forEach(tx => tx!=null && txs.push(tx));
 
@@ -324,4 +334,4 @@ export class EVMSwapInit extends EVMSwapModule {
 
         return totalFee;
     }
-}
+}

package/src/evm/swaps/modules/EVMSwapRefund.ts

@@ -13,6 +13,11 @@ const Refund = [
     { name: "timeout", type: "uint256" }
 ];
 
+/**
+ * Swap refund helper for timeout and cooperative refund flows.
+ *
+ * @category Internal/Swaps
+ */
 export class EVMSwapRefund extends EVMSwapModule {
 
     private static readonly GasCosts = {
@@ -77,7 +82,7 @@ export class EVMSwapRefund extends EVMSwapModule {
         const authPrefix = "refund";
         const authTimeout = Math.floor(Date.now()/1000)+authorizationTimeout;
 
-        const signature = await this.root.Signatures.signTypedMessage(this.contract.contractAddress, signer, Refund, "Refund", {
+        const signature = await this.root.Signatures.signTypedMessage(this.contract._contractAddress, signer, Refund, "Refund", {
             "swapHash": "0x"+swapData.getEscrowHash(),
             "timeout": BigInt(authTimeout)
         });
@@ -100,10 +105,10 @@ export class EVMSwapRefund extends EVMSwapModule {
         const expiryTimestamp = BigInt(timeout);
         const currentTimestamp = BigInt(Math.floor(Date.now() / 1000));
 
-        const isExpired = (expiryTimestamp - currentTimestamp) < BigInt(this.contract.authGracePeriod);
+        const isExpired = (expiryTimestamp - currentTimestamp) < BigInt(this.contract._authGracePeriod);
         if(isExpired) throw new SignatureVerificationError("Authorization expired!");
 
-        const valid = await this.root.Signatures.isValidSignature(this.contract.contractAddress, signature, swapData.claimer, Refund, "Refund", {
+        const valid = await this.root.Signatures.isValidSignature(this.contract._contractAddress, signature, swapData.claimer, Refund, "Refund", {
             "swapHash": "0x"+swapData.getEscrowHash(),
             "timeout": BigInt(expiryTimestamp)
         });
@@ -131,7 +136,7 @@ export class EVMSwapRefund extends EVMSwapModule {
         feeRate?: string,
         witnessData?: T
     ): Promise<EVMTx[]> {
-        const refundHandler: IHandler<any, T> = this.contract.refundHandlersByAddress[swapData.refundHandler.toLowerCase()];
+        const refundHandler: IHandler<any, T> = this.contract._refundHandlersByAddress[swapData.refundHandler.toLowerCase()];
         if(refundHandler==null) throw new Error("Invalid refund handler");
 
         if(check && !await this.contract.isRequestRefundable(swapData.offerer.toString(), swapData)) {

package/src/evm/wallet/EVMBrowserSigner.ts

@@ -1,18 +1,57 @@
-import {Signer, TransactionRequest, TransactionResponse} from "ethers";
+import {Signer, TransactionRequest, TransactionResponse, verifyMessage} from "ethers";
 import {EVMSigner} from "./EVMSigner";
 
-
 /**
- * Browser-based EVM signer for external wallet integration
+ * Browser-based EVM signer, intended for injected/external wallets. This ensures no explicit
+ *  `signTransaction()` flow is required and transaction submission goes through `sendTransaction()`.
+ *
  * @category Wallets
  */
 export class EVMBrowserSigner extends EVMSigner {
 
-    constructor(account: Signer, address: string) {
+    private usesECDSADN?: boolean;
+
+    getReproducibleEntropy?: (appName: string) => Promise<Buffer>;
+
+    /**
+     * @param account Signer account to request signatures and send transaction through
+     * @param address Signer address
+     * @param usesECDSADN Optional flag indicating whether the signer supports signing using ECDSA-DN (deterministic
+     *  nonce) algorithm, this allows the wallet to produce reproducible entropy. Only pass `true` here if you are
+     *  100% sure that the signer supports this!
+     */
+    constructor(account: Signer, address: string, usesECDSADN?: boolean) {
         super(account, address, false);
+        this.usesECDSADN = usesECDSADN;
         this.signTransaction = undefined;
+        if(this.usesECDSADN!==false) {
+            this.getReproducibleEntropy = async (appName: string) => {
+                if(this.usesECDSADN===false) throw new Error("This wallet doesn't support generating recoverable entropy!");
+
+                const message = EVMSigner.getReproducibleEntropyMessage(appName);
+                const signature = await account.signMessage(message);
+                if(this.usesECDSADN!==true) {
+                    const secondSignature = await account.signMessage(message);
+                    if(signature!==secondSignature) {
+                        this.usesECDSADN = false;
+                        this.getReproducibleEntropy = undefined;
+                        throw new Error("This wallet doesn't support generating recoverable entropy!");
+                    }
+                    this.usesECDSADN = true;
+                }
+                if(verifyMessage(message, signature)!==address) throw new Error("Invalid wallet signature provided!");
+                return Buffer.from(signature.substring(2), "hex");
+            }
+        }
     }
 
+    /**
+     * Signs and sends the provided EVM transaction.
+     * Maps common wallet rejection errors to a consistent user-facing message.
+     *
+     * @param transaction A transaction to sign and send
+     * @param onBeforePublish Optional callback called after signing and before broadcast when available
+     */
     async sendTransaction(transaction: TransactionRequest, onBeforePublish?: (txId: string, rawTx: string) => Promise<void>): Promise<TransactionResponse> {
         try {
             return await super.sendTransaction(transaction, onBeforePublish);
@@ -23,4 +62,4 @@ export class EVMBrowserSigner extends EVMSigner {
         }
     }
 
-}
+}

package/src/evm/wallet/EVMPersistentSigner.ts

@@ -16,9 +16,15 @@ const WAIT_BEFORE_BUMP = 15*1000;
 const MIN_FEE_INCREASE_ABSOLUTE = 1n*1_000_000_000n; //1GWei
 const MIN_FEE_INCREASE_PPM = 100_000n; // +10%
 
+/**
+ * A robust EVM signer implementation with internal nonce management, automatic rebroadcasting and fee bumping.
+ * Uses Node.js `fs` to persist transaction data across restarts, so it is intended for backend runtimes.
+ *
+ * @category Wallets
+ */
 export class EVMPersistentSigner extends EVMSigner {
 
-    readonly safeBlockTag: EVMBlockTag;
+    private readonly safeBlockTag: EVMBlockTag;
 
     private pendingTxs: Map<number, {
         txs: Transaction[],
@@ -58,7 +64,7 @@ export class EVMPersistentSigner extends EVMSigner {
         this.minFeeIncreaseAbsolute = minFeeIncreaseAbsolute ?? MIN_FEE_INCREASE_ABSOLUTE;
         this.minFeeIncreasePpm = minFeeIncreasePpm ?? MIN_FEE_INCREASE_PPM;
         this.waitBeforeBump = waitBeforeBumpMillis ?? WAIT_BEFORE_BUMP;
-        this.safeBlockTag = chainInterface.config.safeBlockTag;
+        this.safeBlockTag = chainInterface._config.safeBlockTag;
         this.logger = getLogger("EVMPersistentSigner("+address+"): ");
     }
 
@@ -247,6 +253,9 @@ export class EVMPersistentSigner extends EVMSigner {
         }
     }
 
+    /**
+     * @inheritDoc
+     */
     async init(): Promise<void> {
         try {
             await fs.mkdir(this.directory)
@@ -261,6 +270,9 @@ export class EVMPersistentSigner extends EVMSigner {
         this.startFeeBumper();
     }
 
+    /**
+     * @inheritDoc
+     */
     stop(): Promise<void> {
         this.stopped = true;
         if(this.feeBumper!=null) {

package/src/evm/wallet/EVMSigner.ts

@@ -2,16 +2,46 @@ import {AbstractSigner} from "@atomiqlabs/base";
 import {getAddress, Signer, Transaction, TransactionRequest, TransactionResponse} from "ethers";
 
 /**
- * EVM signer implementation wrapping an ethers Signer
+ * EVM signer implementation wrapping an ethers {@link Signer}, for browser-based wallet use
+ *  {@link EVMBrowserSigner}.
+ *
  * @category Wallets
  */
 export class EVMSigner implements AbstractSigner {
+    /**
+     * A static message, which should be signed by the EVM wallets to generate reproducible entropy. Works when
+     *  wallets use signing with deterministic nonce, such that signature over the same message always yields the
+     *  same signature (same entropy).
+     */
+    private static readonly EVM_REPRODUCIBLE_ENTROPY_MESSAGE =
+      "Signing this messages generates a reproducible secret to be used on %APPNAME%.\n\nPLEASE DOUBLE CHECK THAT YOU"+
+      " ARE ON THE %APPNAME% WEBSITE BEFORE SIGNING THE MESSAGE, SIGNING THIS MESSAGE ON ANY OTHER WEBSITE MIGHT LEAD TO"+
+      " LOSS OF FUNDS!";
+
+    /**
+     * Returns a static message, which should be signed by the EVM wallets to generate reproducible entropy. Works when
+     *  wallets use signing with deterministic nonce, such that signature over the same message always yields the
+     *  same signature (same entropy).
+     *
+     * @param appName Application name to differentiate reproducible entropy generated across different apps
+     */
+    public static getReproducibleEntropyMessage(appName: string): string {
+        return EVMSigner.EVM_REPRODUCIBLE_ENTROPY_MESSAGE.replace(new RegExp("%APPNAME%", 'g'), appName);
+    }
+
     type = "AtomiqAbstractSigner" as const;
 
     account: Signer;
     public readonly address: string;
     public readonly isManagingNoncesInternally: boolean;
 
+    /**
+     * Constructs a signer wrapping an ethers {@link Signer}.
+     *
+     * @param account
+     * @param address
+     * @param isManagingNoncesInternally
+     */
     constructor(account: Signer, address: string, isManagingNoncesInternally: boolean = false) {
         this.account = account;
         this.address = address;
@@ -25,10 +55,16 @@ export class EVMSigner implements AbstractSigner {
         return getAddress(this.address);
     }
 
+    /**
+     * @inheritDoc
+     */
     async signTransaction?(transaction: TransactionRequest): Promise<string> {
         return this.account.signTransaction(transaction);
     }
 
+    /**
+     * @inheritDoc
+     */
     async sendTransaction(transaction: TransactionRequest, onBeforePublish?: (txId: string, rawTx: string) => Promise<void>): Promise<TransactionResponse> {
         const txResponse = await this.account.sendTransaction(transaction);
         if(onBeforePublish!=null) await onBeforePublish(txResponse.hash, Transaction.from({

package/src/index.ts

@@ -1,3 +1,74 @@
+/**
+ * # @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
+ * ```
+ *
+ * ## 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
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export * from "./chains/EVMOptions";
+
 export * from "./chains/citrea/CitreaInitializer";
 export * from "./chains/citrea/CitreaChainType";
 export * from "./chains/citrea/CitreaFees";
@@ -17,6 +88,7 @@ export {EVMBtcRelay} from "./evm/btcrelay/EVMBtcRelay";
 
 export * from "./evm/chain/EVMChainInterface";
 export * from "./evm/chain/modules/EVMFees";
+export {EVMTx, SignedEVMTx} from "./evm/chain/modules/EVMTransactions";
 
 export * from "./evm/events/EVMChainEventsBrowser";
 

package/src/node/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Node.js-only entrypoint for filesystem-backed EVM helpers.
+ *
+ * Import from `@atomiqlabs/chain-evm/node` when you need runtime features
+ * that depend on Node's `fs` module.
+ *
+ * @packageDocumentation
+ */
+export {EVMChainEvents} from "../evm/events/EVMChainEvents";
+export {EVMPersistentSigner} from "../evm/wallet/EVMPersistentSigner";

package/src/utils/Utils.ts

@@ -1,5 +1,9 @@
 
-
+/**
+ * Logger interface used across EVM modules.
+ *
+ * @category Internal/Utils
+ */
 export type LoggerType = {
     debug: (msg: string, ...args: any[]) => void,
     info: (msg: string, ...args: any[]) => void,
@@ -7,6 +11,11 @@ export type LoggerType = {
     error: (msg: string, ...args: any[]) => void,
 }
 
+/**
+ * Returns a promise that resolves after `timeoutMillis` unless aborted first.
+ *
+ * @category Internal/Utils
+ */
 export function timeoutPromise(timeoutMillis: number, abortSignal?: AbortSignal): Promise<void> {
     return new Promise((resolve, reject) => {
         const timeout = setTimeout(resolve, timeoutMillis)
@@ -17,6 +26,11 @@ export function timeoutPromise(timeoutMillis: number, abortSignal?: AbortSignal)
     });
 }
 
+/**
+ * Wraps an async executor so it runs once at a time and reuses the same promise.
+ *
+ * @category Internal/Utils
+ */
 export function onceAsync<T>(executor: () => Promise<T>): () => Promise<T> {
     let promise: Promise<T>;
 
@@ -30,6 +44,11 @@ export function onceAsync<T>(executor: () => Promise<T>): () => Promise<T> {
     }
 }
 
+/**
+ * Creates a prefixed logger that honors the global `atomiqLogLevel`.
+ *
+ * @category Internal/Utils
+ */
 export function getLogger(prefix: string): LoggerType {
     return {
         debug: (msg, ...args) => (global as any).atomiqLogLevel >= 3 && console.debug(prefix+msg, ...args),
@@ -41,6 +60,11 @@ export function getLogger(prefix: string): LoggerType {
 
 const logger = getLogger("Utils: ");
 
+/**
+ * Retries an async function using the provided retry policy.
+ *
+ * @category Internal/Utils
+ */
 export async function tryWithRetries<T>(func: () => Promise<T>, retryPolicy?: {
     maxRetries?: number, delay?: number, exponential?: boolean
 }, errorAllowed?: (e: any) => boolean, abortSignal?: AbortSignal): Promise<T> {
@@ -72,6 +96,11 @@ export async function tryWithRetries<T>(func: () => Promise<T>, retryPolicy?: {
     throw err;
 }
 
+/**
+ * Reverses byte order of a 32-bit unsigned integer.
+ *
+ * @category Internal/Utils
+ */
 export function uint32ReverseEndianness(value: number): number {
     const valueBN = BigInt(value);
     return Number(((valueBN & 0xFFn) << 24n) |
@@ -80,10 +109,20 @@ export function uint32ReverseEndianness(value: number): number {
         ((valueBN >> 24n) & 0xFFn));
 }
 
+/**
+ * Returns the greater of two bigint values.
+ *
+ * @category Internal/Utils
+ */
 export function bigIntMax(a: bigint, b: bigint) {
     return a>b ? a : b;
 }
 
+/**
+ * Ethers.js error codes considered recoverable for retry logic.
+ *
+ * @category Internal/Utils
+ */
 export const allowedEthersErrorCodes: Set<string> = new Set([
     "NOT_IMPLEMENTED", "UNSUPPORTED_OPERATION", "BAD_DATA",
     "NUMERIC_FAULT",
@@ -91,6 +130,11 @@ export const allowedEthersErrorCodes: Set<string> = new Set([
     "CALL_EXCEPTION", "NONCE_EXPIRED", "REPLACEMENT_UNDERPRICED", "TRANSACTION_REPLACED", "UNCONFIGURED_NAME", "OFFCHAIN_FAULT", "ACTION_REJECTED"
 ]);
 
+/**
+ * JSON-RPC error numbers considered recoverable for retry logic.
+ *
+ * @category Internal/Utils
+ */
 export const allowedEthersErrorNumbers: Set<number> = new Set([
     3, //Revertion during eth_getAccessList call
     -32700, //Invalid JSON
@@ -107,6 +151,11 @@ export const allowedEthersErrorNumbers: Set<number> = new Set([
     -32006 //JSON-RPC version not supported
 ]);
 
+/**
+ * RPC error messages considered recoverable for retry logic.
+ *
+ * @category Internal/Utils
+ */
 export const allowedEthersErrorMessages: Set<string> = new Set([
     "already known"
 ]);