@atomiqlabs/chain-evm 2.1.11 → 2.1.14

package/dist/evm/swaps/handlers/claim/ClaimHandlers.d.ts

@@ -1,10 +1,25 @@
 import { ChainSwapType } from "@atomiqlabs/base";
 import { IHandler } from "../IHandler";
+/**
+ * Base interface for claim handlers with explicit chain swap type.
+ *
+ * @category Internal/Handlers
+ */
 export interface IClaimHandler<C, W> extends IHandler<C, W> {
     getType(): ChainSwapType;
 }
+/**
+ * Claim handler constructor contract with static metadata used during handler registration.
+ *
+ * @category Internal/Handlers
+ */
 export type ClaimHandlerType = {
     gas: number;
     type: ChainSwapType;
 } & (new (address: string) => IClaimHandler<any, any>);
+/**
+ * Supported claim handler implementations for EVM swap contract initialization.
+ *
+ * @category Internal/Handlers
+ */
 export declare const claimHandlersList: ClaimHandlerType[];

package/dist/evm/swaps/handlers/claim/ClaimHandlers.js

@@ -5,6 +5,11 @@ const HashlockClaimHandler_1 = require("./HashlockClaimHandler");
 const BitcoinTxIdClaimHandler_1 = require("./btc/BitcoinTxIdClaimHandler");
 const BitcoinOutputClaimHandler_1 = require("./btc/BitcoinOutputClaimHandler");
 const BitcoinNoncedOutputClaimHandler_1 = require("./btc/BitcoinNoncedOutputClaimHandler");
+/**
+ * Supported claim handler implementations for EVM swap contract initialization.
+ *
+ * @category Internal/Handlers
+ */
 exports.claimHandlersList = [
     HashlockClaimHandler_1.HashlockClaimHandler,
     BitcoinTxIdClaimHandler_1.BitcoinTxIdClaimHandler,

package/dist/evm/swaps/handlers/claim/btc/BitcoinNoncedOutputClaimHandler.d.ts

@@ -6,6 +6,11 @@ import { BitcoinOutputWitnessData } from "./BitcoinOutputClaimHandler";
 import { Buffer } from "buffer";
 import { EVMSwapData } from "../../../EVMSwapData";
 import { EVMTx } from "../../../../chain/modules/EVMTransactions";
+/**
+ * Commitment payload for nonced output-script bitcoin claims.
+ *
+ * @category Internal/Handlers
+ */
 export type BitcoinNoncedOutputCommitmentData = {
     output: Buffer;
     amount: bigint;

package/dist/evm/swaps/handlers/claim/btc/BitcoinOutputClaimHandler.d.ts

@@ -5,10 +5,20 @@ import { BitcoinCommitmentData, BitcoinWitnessData, IBitcoinClaimHandler } from
 import { Buffer } from "buffer";
 import { EVMTx } from "../../../../chain/modules/EVMTransactions";
 import { EVMSwapData } from "../../../EVMSwapData";
+/**
+ * Commitment payload for output-script bitcoin claims.
+ *
+ * @category Internal/Handlers
+ */
 export type BitcoinOutputCommitmentData = {
     output: Buffer;
     amount: bigint;
 };
+/**
+ * Witness input for output-script bitcoin claims.
+ *
+ * @category Internal/Handlers
+ */
 export type BitcoinOutputWitnessData = BitcoinWitnessData & {
     vout: number;
 };

package/dist/evm/swaps/handlers/claim/btc/BitcoinTxIdClaimHandler.d.ts

@@ -5,6 +5,11 @@ import { BitcoinCommitmentData, BitcoinWitnessData, IBitcoinClaimHandler } from
 import { Buffer } from "buffer";
 import { EVMSwapData } from "../../../EVMSwapData";
 import { EVMTx } from "../../../../chain/modules/EVMTransactions";
+/**
+ * Commitment payload for txid-based bitcoin claims.
+ *
+ * @category Internal/Handlers
+ */
 export type BitcoinTxIdCommitmentData = {
     txId: string;
 };

package/dist/evm/swaps/handlers/claim/btc/IBitcoinClaimHandler.d.ts

@@ -7,10 +7,20 @@ import { EVMBtcStoredHeader } from "../../../../btcrelay/headers/EVMBtcStoredHea
 import { EVMTx } from "../../../../chain/modules/EVMTransactions";
 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;
@@ -24,6 +34,11 @@ export type BitcoinWitnessData = {
     commitedHeader?: EVMBtcStoredHeader;
     synchronizer?: RelaySynchronizer<EVMBtcStoredHeader, EVMTx, any>;
 };
+/**
+ * Shared base implementation for bitcoin-backed claim handlers.
+ *
+ * @category Internal/Handlers
+ */
 export declare abstract class IBitcoinClaimHandler<C, W extends BitcoinWitnessData> implements IClaimHandler<C & BitcoinCommitmentData, W> {
     readonly address: string;
     constructor(address: string);

package/dist/evm/swaps/handlers/claim/btc/IBitcoinClaimHandler.js

@@ -7,6 +7,11 @@ const Utils_1 = require("../../../../../utils/Utils");
 const ethers_1 = require("ethers");
 const buffer_1 = require("buffer");
 const logger = (0, Utils_1.getLogger)("IBitcoinClaimHandler: ");
+/**
+ * Shared base implementation for bitcoin-backed claim handlers.
+ *
+ * @category Internal/Handlers
+ */
 class IBitcoinClaimHandler {
     constructor(address) {
         this.address = address;
@@ -14,7 +19,7 @@ class IBitcoinClaimHandler {
     serializeCommitment(data) {
         const buffer = buffer_1.Buffer.alloc(24);
         buffer.writeUint32BE(data.confirmations, 0);
-        buffer_1.Buffer.from(data.btcRelay.contractAddress.substring(2), "hex").copy(buffer, 4, 0, 20);
+        buffer_1.Buffer.from(data.btcRelay._contractAddress.substring(2), "hex").copy(buffer, 4, 0, 20);
         return buffer;
     }
     getCommitment(data) {
@@ -29,7 +34,7 @@ class IBitcoinClaimHandler {
         const commitmentHash = (0, ethers_1.keccak256)(serializedCommitment);
         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/dist/evm/swaps/modules/EVMLpVault.d.ts

@@ -1,6 +1,11 @@
 import { IntermediaryReputationType } from "@atomiqlabs/base";
 import { EVMSwapModule } from "../EVMSwapModule";
 import { EVMTx } from "../../chain/modules/EVMTransactions";
+/**
+ * LP vault helper for intermediary balances, reputation and LP deposit/withdraw transactions.
+ *
+ * @category Internal/Swaps
+ */
 export declare class EVMLpVault extends EVMSwapModule {
     private static readonly GasCosts;
     /**

package/dist/evm/swaps/modules/EVMLpVault.js

@@ -3,6 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EVMLpVault = void 0;
 const EVMSwapModule_1 = require("../EVMSwapModule");
 const EVMFees_1 = require("../../chain/modules/EVMFees");
+/**
+ * LP vault helper for intermediary balances, reputation and LP deposit/withdraw transactions.
+ *
+ * @category Internal/Swaps
+ */
 class EVMLpVault extends EVMSwapModule_1.EVMSwapModule {
     /**
      * Action for withdrawing funds from the LP vault
@@ -57,13 +62,13 @@ class EVMLpVault extends EVMSwapModule_1.EVMSwapModule {
      * @param token
      */
     async getIntermediaryReputation(address, token) {
-        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 = {};
-        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,
@@ -117,7 +122,7 @@ class EVMLpVault extends EVMSwapModule_1.EVMSwapModule {
         const txs = [];
         //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);
         }

package/dist/evm/swaps/modules/EVMSwapClaim.d.ts

@@ -3,6 +3,11 @@ import { EVMSwapModule } from "../EVMSwapModule";
 import { EVMSwapData } from "../EVMSwapData";
 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 declare class EVMSwapClaim extends EVMSwapModule {
     private static readonly GasCosts;
     /**
@@ -35,7 +40,7 @@ export declare 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
      */
@@ -48,7 +53,7 @@ export declare class EVMSwapClaim extends EVMSwapModule {
     }, requiredConfirmations: number, vout: number, commitedHeader?: EVMBtcStoredHeader, synchronizer?: RelaySynchronizer<EVMBtcStoredHeader, EVMTx, any>, feeRate?: string): Promise<EVMTx[]>;
     getClaimGas(swapData: EVMSwapData): number;
     /**
-     * Get the estimated starknet transaction fee of the claim transaction
+     * Returns the estimated fee of the claim transaction.
      */
     getClaimFee(swapData: EVMSwapData, feeRate?: string): Promise<bigint>;
 }

package/dist/evm/swaps/modules/EVMSwapClaim.js

@@ -4,6 +4,11 @@ exports.EVMSwapClaim = void 0;
 const base_1 = require("@atomiqlabs/base");
 const EVMSwapModule_1 = require("../EVMSwapModule");
 const EVMFees_1 = require("../../chain/modules/EVMFees");
+/**
+ * Swap claim helper for HTLC and BTC on-chain claim paths.
+ *
+ * @category Internal/Swaps
+ */
 class EVMSwapClaim extends EVMSwapModule_1.EVMSwapModule {
     /**
      * Claim action which uses the provided witness for claiming the swap
@@ -38,7 +43,7 @@ class EVMSwapClaim extends EVMSwapModule_1.EVMSwapModule {
         if (checkExpiry && await this.contract.isExpired(swapData.claimer.toString(), swapData)) {
             throw new base_1.SwapDataVerificationError("Not enough time to reliably pay the invoice");
         }
-        const claimHandler = this.contract.claimHandlersByAddress[swapData.claimHandler.toLowerCase()];
+        const claimHandler = this.contract._claimHandlersByAddress[swapData.claimHandler.toLowerCase()];
         if (claimHandler == null)
             throw new base_1.SwapDataVerificationError("Unknown claim handler!");
         if (claimHandler.getType() !== base_1.ChainSwapType.HTLC)
@@ -57,12 +62,12 @@ class EVMSwapClaim extends EVMSwapModule_1.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
      */
     async txsClaimWithTxData(signer, swapData, tx, requiredConfirmations, vout, commitedHeader, synchronizer, feeRate) {
-        const claimHandler = this.contract.claimHandlersByAddress[swapData.claimHandler.toLowerCase()];
+        const claimHandler = this.contract._claimHandlersByAddress[swapData.claimHandler.toLowerCase()];
         if (claimHandler == null)
             throw new base_1.SwapDataVerificationError("Unknown claim handler!");
         if (claimHandler.getType() !== base_1.ChainSwapType.CHAIN_NONCED &&
@@ -75,7 +80,7 @@ class EVMSwapClaim extends EVMSwapModule_1.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));
@@ -115,13 +120,13 @@ class EVMSwapClaim extends EVMSwapModule_1.EVMSwapModule {
         return totalGas;
     }
     /**
-     * Get the estimated starknet transaction fee of the claim transaction
+     * Returns the estimated fee of the claim transaction.
      */
     async getClaimFee(swapData, feeRate) {
         feeRate ?? (feeRate = await this.root.Fees.getFeeRate());
         //TODO: Claim with success action not supported yet!
         let gasRequired = this.getClaimGas(swapData);
-        const claimHandler = this.contract.claimHandlersByAddress[swapData.claimHandler.toLowerCase()];
+        const claimHandler = this.contract._claimHandlersByAddress[swapData.claimHandler.toLowerCase()];
         if (claimHandler != null)
             gasRequired += claimHandler.getGas(swapData);
         return EVMFees_1.EVMFees.getGasFee(gasRequired, feeRate);

package/dist/evm/swaps/modules/EVMSwapInit.d.ts

@@ -2,9 +2,19 @@ import { EVMSwapModule } from "../EVMSwapModule";
 import { EVMSwapData } from "../EVMSwapData";
 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;
 };
+/**
+ * Swap initialization helper handling authorization signatures and init transaction construction.
+ *
+ * @category Internal/Swaps
+ */
 export declare class EVMSwapInit extends EVMSwapModule {
     private static readonly GasCosts;
     /**

package/dist/evm/swaps/modules/EVMSwapInit.js

@@ -25,6 +25,11 @@ const Initialize = [
     { name: "deadline", type: "uint256" },
     { name: "extraDataHash", type: "bytes32" }
 ];
+/**
+ * Swap initialization helper handling authorization signatures and init transaction construction.
+ *
+ * @category Internal/Swaps
+ */
 class EVMSwapInit extends EVMSwapModule_1.EVMSwapModule {
     /**
      * bare Init action based on the data passed in swapData
@@ -63,7 +68,7 @@ class EVMSwapInit extends EVMSwapModule_1.EVMSwapModule {
     }
     async preFetchForInitSignatureVerification() {
         return {
-            safeBlockTime: await this.root.Blocks.getBlockTime(this.root.config.safeBlockTag)
+            safeBlockTime: await this.root.Blocks.getBlockTime(this.root._config.safeBlockTag)
         };
     }
     /**
@@ -77,7 +82,7 @@ class EVMSwapInit extends EVMSwapModule_1.EVMSwapModule {
      */
     async signSwapInitialization(signer, swapData, authorizationTimeout) {
         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,
@@ -125,12 +130,12 @@ class EVMSwapInit extends EVMSwapModule_1.EVMSwapModule {
             throw new base_1.SignatureVerificationError("Invalid prefix");
         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 base_1.SignatureVerificationError("Authorization expired!");
         if (await this.isSignatureExpired(timeout, preFetchData))
             throw new base_1.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,
@@ -162,7 +167,7 @@ class EVMSwapInit extends EVMSwapModule_1.EVMSwapModule {
      */
     async getSignatureExpiry(timeout) {
         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;
         return timeoutExpiryTime;
@@ -220,7 +225,7 @@ class EVMSwapInit extends EVMSwapModule_1.EVMSwapModule {
                 requiredApprovals[swapData.depositToken.toLowerCase()] += swapData.getTotalDeposit();
             }
         }
-        const requiredApprovalTxns = await Promise.all(Object.keys(requiredApprovals).map(token => this.root.Tokens.checkAndGetApproveTx(sender, token, requiredApprovals[token], this.contract.contractAddress, feeRate)));
+        const requiredApprovalTxns = await Promise.all(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));
         txs.push(await this.Init(sender, swapData, BigInt(timeout), signature ?? "0x", feeRate));
         this.logger.debug("txsInitPayIn(): create swap init TX, swap: " + swapData.getClaimHash() +

package/dist/evm/swaps/modules/EVMSwapRefund.d.ts

@@ -2,6 +2,11 @@ import { EVMSwapModule } from "../EVMSwapModule";
 import { EVMSwapData } from "../EVMSwapData";
 import { EVMSigner } from "../../wallet/EVMSigner";
 import { EVMTx } from "../../chain/modules/EVMTransactions";
+/**
+ * Swap refund helper for timeout and cooperative refund flows.
+ *
+ * @category Internal/Swaps
+ */
 export declare class EVMSwapRefund extends EVMSwapModule {
     private static readonly GasCosts;
     /**

package/dist/evm/swaps/modules/EVMSwapRefund.js

@@ -8,6 +8,11 @@ const Refund = [
     { name: "swapHash", type: "bytes32" },
     { name: "timeout", type: "uint256" }
 ];
+/**
+ * Swap refund helper for timeout and cooperative refund flows.
+ *
+ * @category Internal/Swaps
+ */
 class EVMSwapRefund extends EVMSwapModule_1.EVMSwapModule {
     /**
      * Action for generic Refund instruction
@@ -44,7 +49,7 @@ class EVMSwapRefund extends EVMSwapModule_1.EVMSwapModule {
     async signSwapRefund(signer, swapData, authorizationTimeout) {
         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)
         });
@@ -59,10 +64,10 @@ class EVMSwapRefund extends EVMSwapModule_1.EVMSwapModule {
             throw new base_1.SignatureVerificationError("Invalid prefix");
         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 base_1.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)
         });
@@ -81,7 +86,7 @@ class EVMSwapRefund extends EVMSwapModule_1.EVMSwapModule {
      * @param witnessData
      */
     async txsRefund(signer, swapData, check, feeRate, witnessData) {
-        const refundHandler = this.contract.refundHandlersByAddress[swapData.refundHandler.toLowerCase()];
+        const refundHandler = 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/dist/evm/wallet/EVMBrowserSigner.d.ts

@@ -1,10 +1,30 @@
+/// <reference types="node" />
+/// <reference types="node" />
 import { Signer, TransactionRequest, TransactionResponse } 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 declare class EVMBrowserSigner extends EVMSigner {
-    constructor(account: Signer, address: string);
+    private usesECDSADN?;
+    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);
+    /**
+     * 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
+     */
     sendTransaction(transaction: TransactionRequest, onBeforePublish?: (txId: string, rawTx: string) => Promise<void>): Promise<TransactionResponse>;
 }

package/dist/evm/wallet/EVMBrowserSigner.js

@@ -1,16 +1,54 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EVMBrowserSigner = void 0;
+const ethers_1 = require("ethers");
 const EVMSigner_1 = require("./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
  */
 class EVMBrowserSigner extends EVMSigner_1.EVMSigner {
-    constructor(account, address) {
+    /**
+     * @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, address, usesECDSADN) {
         super(account, address, false);
+        this.usesECDSADN = usesECDSADN;
         this.signTransaction = undefined;
+        if (this.usesECDSADN !== false) {
+            this.getReproducibleEntropy = async (appName) => {
+                if (this.usesECDSADN === false)
+                    throw new Error("This wallet doesn't support generating recoverable entropy!");
+                const message = EVMSigner_1.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 ((0, ethers_1.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, onBeforePublish) {
         try {
             return await super.sendTransaction(transaction, onBeforePublish);

package/dist/evm/wallet/EVMPersistentSigner.d.ts

@@ -1,9 +1,14 @@
 import { Signer, TransactionRequest, TransactionResponse } from "ethers";
-import { EVMBlockTag } from "../chain/modules/EVMBlocks";
 import { EVMChainInterface } from "../chain/EVMChainInterface";
 import { EVMSigner } from "./EVMSigner";
+/**
+ * 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 declare class EVMPersistentSigner extends EVMSigner {
-    readonly safeBlockTag: EVMBlockTag;
+    private readonly safeBlockTag;
     private pendingTxs;
     private confirmedNonce;
     private pendingNonce;
@@ -23,7 +28,13 @@ export declare class EVMPersistentSigner extends EVMSigner {
     private checkPastTransactions;
     private startFeeBumper;
     private syncNonceFromChain;
+    /**
+     * @inheritDoc
+     */
     init(): Promise<void>;
+    /**
+     * @inheritDoc
+     */
     stop(): Promise<void>;
     private readonly sendTransactionQueue;
     sendTransaction(transaction: TransactionRequest, onBeforePublish?: (txId: string, rawTx: string) => Promise<void>): Promise<TransactionResponse>;

package/dist/evm/wallet/EVMPersistentSigner.js

@@ -10,6 +10,12 @@ const fs = require("fs/promises");
 const WAIT_BEFORE_BUMP = 15 * 1000;
 const MIN_FEE_INCREASE_ABSOLUTE = 1n * 1000000000n; //1GWei
 const MIN_FEE_INCREASE_PPM = 100000n; // +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
+ */
 class EVMPersistentSigner extends EVMSigner_1.EVMSigner {
     constructor(account, address, chainInterface, directory, minFeeIncreaseAbsolute, minFeeIncreasePpm, waitBeforeBumpMillis) {
         super(account, address, true);
@@ -25,7 +31,7 @@ class EVMPersistentSigner extends EVMSigner_1.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 = (0, Utils_1.getLogger)("EVMPersistentSigner(" + address + "): ");
     }
     async load() {
@@ -179,6 +185,9 @@ class EVMPersistentSigner extends EVMSigner_1.EVMSigner {
             this.save();
         }
     }
+    /**
+     * @inheritDoc
+     */
     async init() {
         try {
             await fs.mkdir(this.directory);
@@ -190,6 +199,9 @@ class EVMPersistentSigner extends EVMSigner_1.EVMSigner {
         await this.load();
         this.startFeeBumper();
     }
+    /**
+     * @inheritDoc
+     */
     stop() {
         this.stopped = true;
         if (this.feeBumper != null) {

package/dist/evm/wallet/EVMSigner.d.ts

@@ -1,19 +1,48 @@
 import { AbstractSigner } from "@atomiqlabs/base";
 import { Signer, 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 declare 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;
+    /**
+     * 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
+     */
+    static getReproducibleEntropyMessage(appName: string): string;
     type: "AtomiqAbstractSigner";
     account: Signer;
     readonly address: string;
     readonly isManagingNoncesInternally: boolean;
+    /**
+     * Constructs a signer wrapping an ethers {@link Signer}.
+     *
+     * @param account
+     * @param address
+     * @param isManagingNoncesInternally
+     */
     constructor(account: Signer, address: string, isManagingNoncesInternally?: boolean);
     /**
      * @inheritDoc
      */
     getAddress(): string;
+    /**
+     * @inheritDoc
+     */
     signTransaction?(transaction: TransactionRequest): Promise<string>;
+    /**
+     * @inheritDoc
+     */
     sendTransaction(transaction: TransactionRequest, onBeforePublish?: (txId: string, rawTx: string) => Promise<void>): Promise<TransactionResponse>;
 }