@atomiqlabs/chain-evm 2.1.12 → 2.1.14

package/src/evm/spv_swap/EVMSpvVaultContract.ts

@@ -39,16 +39,28 @@ function decodeUtxo(utxo: string): {txHash: string, vout: bigint} {
     }
 }
 
+/**
+ * Packs vault owner and vault id into compact `owner+vaultId` event key format.
+ *
+ * @category Swaps
+ */
 export function packOwnerAndVaultId(owner: string, vaultId: bigint): string {
     if(owner.length!==42) throw new Error("Invalid owner address");
     return owner.toLowerCase() + BigIntBufferUtils.toBuffer(vaultId, "be", 12).toString("hex");
 }
 
+/**
+ * Unpacks compact `owner+vaultId` event key format into owner and vault id.
+ *
+ * @category Swaps
+ */
 export function unpackOwnerAndVaultId(data: string): [string, bigint] {
     return [getAddress(data.substring(0, 42)), BigInt("0x"+data.substring(42, 66))];
 }
 
 /**
+ * EVM SPV vault (UTXO-controlled vault) contract representation.
+ *
  * @category Swaps
  */
 export class EVMSpvVaultContract<ChainId extends string>
@@ -61,7 +73,7 @@ export class EVMSpvVaultContract<ChainId extends string>
         EVMSpvVaultData
     >
 {
-    public static readonly GasCosts = {
+    private static readonly GasCosts = {
         DEPOSIT_BASE: 15_000 + 21_000,
         DEPOSIT_ERC20: 40_000,
 
@@ -79,12 +91,12 @@ export class EVMSpvVaultContract<ChainId extends string>
     };
 
     readonly chainId: ChainId;
+    public readonly claimTimeout: number = 180;
 
-    readonly btcRelay: EVMBtcRelay<any>;
-    readonly bitcoinRpc: BitcoinRpc<any>;
-    readonly claimTimeout: number = 180;
+    private readonly btcRelay: EVMBtcRelay<any>;
+    private readonly bitcoinRpc: BitcoinRpc<any>;
 
-    readonly logger = getLogger("EVMSpvVaultContract: ");
+    private readonly logger = getLogger("EVMSpvVaultContract: ");
 
     constructor(
         chainInterface: EVMChainInterface<ChainId>,
@@ -100,20 +112,20 @@ export class EVMSpvVaultContract<ChainId extends string>
     }
 
     //Transactions
-    protected async Open(signer: string, vault: EVMSpvVaultData, feeRate: string): Promise<TransactionRequest> {
+    private async Open(signer: string, vault: EVMSpvVaultData, feeRate: string): Promise<TransactionRequest> {
         const {txHash, vout} = decodeUtxo(vault.getUtxo());
 
         const tokens = vault.getTokenData();
         if(tokens.length!==2) throw new Error("Must specify exactly 2 tokens for vault!");
 
-        const tx = await this.contract.open.populateTransaction(vault.vaultId, vault.getVaultParamsStruct(), txHash, vout);
+        const tx = await this.contract.open.populateTransaction(vault.vaultId, vault._getVaultParamsStruct(), txHash, vout);
         tx.from = signer;
         EVMFees.applyFeeRate(tx, EVMSpvVaultContract.GasCosts.OPEN, feeRate);
 
         return tx;
     }
 
-    protected async Deposit(signer: string, vault: EVMSpvVaultData, rawAmounts: bigint[], feeRate: string): Promise<TransactionRequest> {
+    private async Deposit(signer: string, vault: EVMSpvVaultData, rawAmounts: bigint[], feeRate: string): Promise<TransactionRequest> {
         let totalGas = EVMSpvVaultContract.GasCosts.DEPOSIT_BASE;
         let value = 0n;
         if(vault.token0.token.toLowerCase()===this.Chain.getNativeCurrencyAddress().toLowerCase()) {
@@ -129,7 +141,7 @@ export class EVMSpvVaultContract<ChainId extends string>
         }
 
         const tx = await this.contract.deposit.populateTransaction(
-            vault.owner, vault.vaultId, vault.getVaultParamsStruct(),
+            vault.owner, vault.vaultId, vault._getVaultParamsStruct(),
             rawAmounts[0], rawAmounts[1] ?? 0n, { value }
         );
         tx.from = signer;
@@ -138,7 +150,7 @@ export class EVMSpvVaultContract<ChainId extends string>
         return tx;
     }
 
-    protected async Front(
+    private async Front(
         signer: string, vault: EVMSpvVaultData, data: EVMSpvWithdrawalData, withdrawalSequence: number, feeRate: string
     ): Promise<TransactionRequest> {
         let value = 0n;
@@ -149,7 +161,7 @@ export class EVMSpvVaultContract<ChainId extends string>
             value += (frontingAmount[1] ?? 0n) * vault.token1.multiplier;
 
         const tx = await this.contract.front.populateTransaction(
-            vault.owner, vault.vaultId, vault.getVaultParamsStruct(),
+            vault.owner, vault.vaultId, vault._getVaultParamsStruct(),
             withdrawalSequence, data.getTxHash(), data.serializeToStruct(),
             { value }
         );
@@ -159,12 +171,12 @@ export class EVMSpvVaultContract<ChainId extends string>
         return tx;
     }
 
-    protected async Claim(
+    private async Claim(
         signer: string, vault: EVMSpvVaultData, data: EVMSpvWithdrawalData,
         blockheader: EVMBtcStoredHeader, merkle: Buffer[], position: number, feeRate: string
     ): Promise<TransactionRequest> {
         const tx = await this.contract.claim.populateTransaction(
-            vault.owner, vault.vaultId, vault.getVaultParamsStruct(), "0x"+data.btcTx.hex,
+            vault.owner, vault.vaultId, vault._getVaultParamsStruct(), "0x"+data.btcTx.hex,
             blockheader.serializeToStruct(), merkle, position
         )
 
@@ -191,7 +203,7 @@ export class EVMSpvVaultContract<ChainId extends string>
         if(tokenData.length!==2) throw new Error("Must specify 2 tokens in tokenData!");
 
         const vaultParams = {
-            btcRelayContract: this.btcRelay.contractAddress,
+            btcRelayContract: this.btcRelay._contractAddress,
             token0: tokenData[0].token,
             token1: tokenData[1].token,
             token0Multiplier: tokenData[0].multiplier,
@@ -239,7 +251,7 @@ export class EVMSpvVaultContract<ChainId extends string>
             promises.push(this.getFronterAddress(owner, vaultId, withdrawal).then(val => {
                 result[withdrawal.getTxId()] = val;
             }));
-            if(promises.length>=this.Chain.config.maxParallelCalls) {
+            if(promises.length>=this.Chain._config.maxParallelCalls) {
                 await Promise.all(promises);
                 promises = [];
             }
@@ -260,7 +272,7 @@ export class EVMSpvVaultContract<ChainId extends string>
 
         const vaultParams = await this.vaultParamsCache.getOrComputeAsync(vaultState.spvVaultParametersCommitment, async () => {
             const blockheight = Number(vaultState.openBlockheight);
-            const events = await this.Events.getContractBlockEvents(
+            const events = await this._Events.getContractBlockEvents(
                 ["Opened"],
                 [
                     "0x"+owner.substring(2).padStart(64, "0"),
@@ -277,7 +289,7 @@ export class EVMSpvVaultContract<ChainId extends string>
             return foundEvent.args.params;
         });
 
-        if(vaultParams.btcRelayContract.toLowerCase()!==this.btcRelay.contractAddress.toLowerCase()) return null;
+        if(vaultParams.btcRelayContract.toLowerCase()!==this.btcRelay._contractAddress.toLowerCase()) return null;
 
         return new EVMSpvVaultData(owner, vaultId, vaultState, vaultParams);
     }
@@ -294,7 +306,7 @@ export class EVMSpvVaultContract<ChainId extends string>
                 result[owner] ??= {};
                 result[owner][vaultId.toString(10)] = val;
             }));
-            if(promises.length>=this.Chain.config.maxParallelCalls) {
+            if(promises.length>=this.Chain._config.maxParallelCalls) {
                 await Promise.all(promises);
                 promises = [];
             }
@@ -325,7 +337,7 @@ export class EVMSpvVaultContract<ChainId extends string>
                 result[owner] ??= {};
                 result[owner][vaultId.toString(10)] = val;
             }));
-            if(promises.length>=this.Chain.config.maxParallelCalls) {
+            if(promises.length>=this.Chain._config.maxParallelCalls) {
                 await Promise.all(promises);
                 promises = [];
             }
@@ -339,7 +351,7 @@ export class EVMSpvVaultContract<ChainId extends string>
      */
     async getAllVaults(owner?: string): Promise<EVMSpvVaultData[]> {
         const openedVaults = new Map<string, SpvVaultParametersStructOutput>();
-        await this.Events.findInContractEventsForward(
+        await this._Events.findInContractEventsForward(
             ["Opened", "Closed"],
             owner==null ? null : [
                 "0x"+owner.substring(2).padStart(64, "0")
@@ -358,7 +370,7 @@ export class EVMSpvVaultContract<ChainId extends string>
         const vaults: EVMSpvVaultData[] = [];
         let promises: Promise<void>[] = [];
         for(let [identifier, vaultParams] of openedVaults.entries()) {
-            if(vaultParams.btcRelayContract.toLowerCase()!==this.btcRelay.contractAddress.toLowerCase()) continue;
+            if(vaultParams.btcRelayContract.toLowerCase()!==this.btcRelay._contractAddress.toLowerCase()) continue;
 
             const [owner, vaultIdStr] = identifier.split(":");
 
@@ -368,7 +380,7 @@ export class EVMSpvVaultContract<ChainId extends string>
                 }
             }))
 
-            if(promises.length>=this.Chain.config.maxParallelCalls) {
+            if(promises.length>=this.Chain._config.maxParallelCalls) {
                 await Promise.all(promises);
                 promises = [];
             }
@@ -444,14 +456,14 @@ export class EVMSpvVaultContract<ChainId extends string>
 
         let result: SpvWithdrawalState | null;
         if(scStartHeight==null) {
-            result = await this.Events.findInContractEvents(
+            result = await this._Events.findInContractEvents(
                 events, keys,
                 async (event) => {
                     return this.parseWithdrawalEvent(event);
                 }
             );
         } else {
-            result = await this.Events.findInContractEventsForward(
+            result = await this._Events.findInContractEventsForward(
                 events, keys,
                 async (event) => {
                     const result = this.parseWithdrawalEvent(event);
@@ -481,8 +493,8 @@ export class EVMSpvVaultContract<ChainId extends string>
 
         const events: ["Fronted", "Claimed", "Closed"] = ["Fronted", "Claimed", "Closed"];
 
-        for(let i=0;i<withdrawalTxs.length;i+=this.Chain.config.maxLogTopics) {
-            const checkWithdrawalTxs = withdrawalTxs.slice(i, i+this.Chain.config.maxLogTopics);
+        for(let i=0;i<withdrawalTxs.length;i+=this.Chain._config.maxLogTopics) {
+            const checkWithdrawalTxs = withdrawalTxs.slice(i, i+this.Chain._config.maxLogTopics);
             const checkWithdrawalTxsMap = new Map(checkWithdrawalTxs.map(val => [val.withdrawal.getTxId() as string, val.withdrawal]));
 
             let scStartHeight = null;
@@ -497,7 +509,7 @@ export class EVMSpvVaultContract<ChainId extends string>
             const keys = [null, null, checkWithdrawalTxs.map(withdrawal => hexlify(Buffer.from(withdrawal.withdrawal.getTxId(), "hex").reverse()))];
 
             if(scStartHeight==null) {
-                await this.Events.findInContractEvents(
+                await this._Events.findInContractEvents(
                     events, keys,
                     async (event) => {
                         const _event = event as TypedEventLog<SpvVaultManager["filters"]["Fronted" | "Claimed" | "Closed"]>;
@@ -514,7 +526,7 @@ export class EVMSpvVaultContract<ChainId extends string>
                     }
                 );
             } else {
-                await this.Events.findInContractEventsForward(
+                await this._Events.findInContractEventsForward(
                     events, keys,
                     async (event) => {
                         const _event = event as TypedEventLog<SpvVaultManager["filters"]["Fronted" | "Claimed" | "Closed"]>;
@@ -560,7 +572,7 @@ export class EVMSpvVaultContract<ChainId extends string>
         const {height: latestBlockheight} = await this.Chain.getFinalizedBlock();
         const withdrawals: { [btcTxId: string]: SpvWithdrawalClaimedState | SpvWithdrawalFrontedState } = {};
 
-        await this.Events.findInContractEventsForward(
+        await this._Events.findInContractEventsForward(
             ["Claimed", "Fronted"],
             [null, recipient],
             async (_event) => {
@@ -591,6 +603,12 @@ export class EVMSpvVaultContract<ChainId extends string>
     fromOpReturnData(data: Buffer): { recipient: string; rawAmounts: bigint[]; executionHash?: string } {
         return EVMSpvVaultContract.fromOpReturnData(data);
     }
+
+    /**
+     * Parses withdrawal params from OP_RETURN data.
+     *
+     * @param data Data as specified in the OP_RETURN output of the transaction
+     */
     static fromOpReturnData(data: Buffer): { recipient: string; rawAmounts: bigint[]; executionHash?: string } {
         let rawAmount0: bigint = 0n;
         let rawAmount1: bigint = 0n;
@@ -623,6 +641,14 @@ export class EVMSpvVaultContract<ChainId extends string>
     toOpReturnData(recipient: string, rawAmounts: bigint[], executionHash?: string): Buffer {
         return EVMSpvVaultContract.toOpReturnData(recipient, rawAmounts, executionHash);
     }
+
+    /**
+     * Serializes withdrawal params to OP_RETURN data.
+     *
+     * @param recipient Recipient of the withdrawn tokens
+     * @param rawAmounts Raw amount of tokens to withdraw
+     * @param executionHash Optional execution hash of the actions to execute
+     */
     static toOpReturnData(recipient: string, rawAmounts: bigint[], executionHash?: string): Buffer {
         if(!EVMAddresses.isValidAddress(recipient)) throw new Error("Invalid recipient specified");
         if(rawAmounts.length < 1) throw new Error("At least 1 amount needs to be specified");
@@ -769,7 +795,7 @@ export class EVMSpvVaultContract<ChainId extends string>
         }
 
         const requiredApprovalTxns = await Promise.all(
-            Object.keys(requiredApprovals).map(token => this.Chain.Tokens.checkAndGetApproveTx(signer, token, requiredApprovals[token], this.contractAddress, feeRate))
+            Object.keys(requiredApprovals).map(token => this.Chain.Tokens.checkAndGetApproveTx(signer, token, requiredApprovals[token], this._contractAddress, feeRate))
         );
         requiredApprovalTxns.forEach(tx => tx!=null && txs.push(tx));
 
@@ -813,7 +839,7 @@ export class EVMSpvVaultContract<ChainId extends string>
         }
 
         const requiredApprovalTxns = await Promise.all(
-            Object.keys(requiredApprovals).map(token => this.Chain.Tokens.checkAndGetApproveTx(signer, token, requiredApprovals[token], this.contractAddress, feeRate))
+            Object.keys(requiredApprovals).map(token => this.Chain.Tokens.checkAndGetApproveTx(signer, token, requiredApprovals[token], this._contractAddress, feeRate))
         );
         requiredApprovalTxns.forEach(tx => tx!=null && txs.push(tx));
 
@@ -841,6 +867,13 @@ export class EVMSpvVaultContract<ChainId extends string>
         return [tx];
     }
 
+    /**
+     * Returns an estimated gas amount for a claim transaction.
+     *
+     * @param signer Signer address executing the claim
+     * @param vault Vault data used to determine transfer paths
+     * @param data Parsed withdrawal data
+     */
     getClaimGas(signer: string, vault?: EVMSpvVaultData, data?: EVMSpvWithdrawalData): number {
         let totalGas = EVMSpvVaultContract.GasCosts.CLAIM_BASE;
 
@@ -863,6 +896,13 @@ export class EVMSpvVaultContract<ChainId extends string>
         return totalGas;
     }
 
+    /**
+     * Returns an estimated gas amount for a front-liquidity transaction.
+     *
+     * @param signer Signer address executing the front action
+     * @param vault Vault data used to determine transfer paths
+     * @param data Parsed withdrawal data
+     */
     getFrontGas(signer: string, vault: EVMSpvVaultData, data?: EVMSpvWithdrawalData): number {
         let totalGas = EVMSpvVaultContract.GasCosts.FRONT_BASE;
 
@@ -891,7 +931,7 @@ export class EVMSpvVaultContract<ChainId extends string>
      * @inheritDoc
      */
     async getFrontFee(signer: string, vault?: EVMSpvVaultData, withdrawalData?: EVMSpvWithdrawalData, feeRate?: string): Promise<bigint> {
-        vault ??= EVMSpvVaultData.randomVault();
+        vault ??= EVMSpvVaultData._randomVault();
         feeRate ??= await this.Chain.Fees.getFeeRate();
         let totalFee = EVMFees.getGasFee(this.getFrontGas(signer, vault, withdrawalData), feeRate);
         if(withdrawalData==null || (withdrawalData.rawAmounts[0]!=null && withdrawalData.rawAmounts[0]>0n)) {

package/src/evm/spv_swap/EVMSpvVaultData.ts

@@ -16,6 +16,11 @@ import {AbiCoder, keccak256} from "ethers";
 import {EVMAddresses} from "../chain/modules/EVMAddresses";
 import type {AddressLike, BigNumberish, BytesLike} from "ethers/lib.esm";
 
+/**
+ * Computes the vault parameter commitment hash used by the on-chain SPV vault state.
+ *
+ * @category Swaps
+ */
 export function getVaultParamsCommitment(vaultParams: SpvVaultParametersStruct) {
     return keccak256(AbiCoder.defaultAbiCoder().encode(
         ["address", "address", "address", "uint192", "uint192", "uint256"],
@@ -23,12 +28,19 @@ export function getVaultParamsCommitment(vaultParams: SpvVaultParametersStruct)
     ));
 }
 
+/**
+ * Decodes UTXO reference (`txid:vout`) from the on-chain SPV vault state struct.
+ *
+ * @category Swaps
+ */
 export function getVaultUtxoFromState(state: SpvVaultStateStruct): string {
     const txHash = Buffer.from(hexlify(state.utxoTxHash).substring(2), "hex");
     return txHash.reverse().toString("hex")+":"+BigInt(state.utxoVout).toString(10);
 }
 
 /**
+ * Represents the state of the EVM SPV vault (UTXO-controlled vault).
+ *
  * @category Swaps
  */
 export class EVMSpvVaultData extends SpvVaultData<EVMSpvWithdrawalData> {
@@ -102,6 +114,9 @@ export class EVMSpvVaultData extends SpvVaultData<EVMSpvWithdrawalData> {
         }
     }
 
+    /**
+     * @inheritDoc
+     */
     getBalances(): SpvVaultTokenBalance[] {
         return [
             {...this.token0, scaledAmount: this.token0.rawAmount * this.token0.multiplier},
@@ -109,34 +124,58 @@ export class EVMSpvVaultData extends SpvVaultData<EVMSpvWithdrawalData> {
         ];
     }
 
+    /**
+     * @inheritDoc
+     */
     getConfirmations(): number {
         return this.confirmations;
     }
 
+    /**
+     * @inheritDoc
+     */
     getOwner(): string {
         return this.owner;
     }
 
+    /**
+     * @inheritDoc
+     */
     getTokenData(): SpvVaultTokenData[] {
         return [this.token0, this.token1];
     }
 
+    /**
+     * @inheritDoc
+     */
     getUtxo(): string {
         return this.isOpened() ? this.utxo : this.initialUtxo!;
     }
 
+    /**
+     * @inheritDoc
+     */
     getVaultId(): bigint {
         return this.vaultId;
     }
 
+    /**
+     * @inheritDoc
+     */
     getWithdrawalCount(): number {
         return this.withdrawCount;
     }
 
+    /**
+     * @inheritDoc
+     */
     isOpened(): boolean {
         return this.utxo!=="0000000000000000000000000000000000000000000000000000000000000000:0";
     }
 
+    /**
+     * @inheritDoc
+     */
     serialize(): any {
         return {
             type: "EVM",
@@ -161,6 +200,9 @@ export class EVMSpvVaultData extends SpvVaultData<EVMSpvWithdrawalData> {
         }
     }
 
+    /**
+     * @inheritDoc
+     */
     updateState(withdrawalTxOrEvent: SpvVaultClaimEvent | SpvVaultCloseEvent | SpvVaultOpenEvent | SpvVaultDepositEvent | EVMSpvWithdrawalData): void {
         if(withdrawalTxOrEvent instanceof SpvVaultClaimEvent) {
             if(withdrawalTxOrEvent.withdrawCount <= this.withdrawCount) return;
@@ -194,11 +236,19 @@ export class EVMSpvVaultData extends SpvVaultData<EVMSpvWithdrawalData> {
         }
     }
 
+    /**
+     * @inheritDoc
+     */
     getDepositCount(): number {
         return this.depositCount;
     }
 
-    getVaultParamsStruct(): SpvVaultParametersStruct {
+    /**
+     * Serializes this spv vault data to a struct object which can be passed to the ether.js functions
+     *
+     * @internal
+     */
+    _getVaultParamsStruct(): SpvVaultParametersStruct {
         return {
             btcRelayContract: this.relayContract,
             token0: this.token0.token,
@@ -209,7 +259,12 @@ export class EVMSpvVaultData extends SpvVaultData<EVMSpvWithdrawalData> {
         }
     }
 
-    static randomVault(): EVMSpvVaultData {
+    /**
+     * Returns a dummy random vault that can be used for e.g. fee estimation
+     *
+     * @internal
+     */
+    static _randomVault(): EVMSpvVaultData {
         const spvVaultParams = {
             btcRelayContract: EVMAddresses.randomAddress(),
             token0: EVMAddresses.randomAddress(),

package/src/evm/spv_swap/EVMSpvWithdrawalData.ts

@@ -5,6 +5,9 @@ import {BitcoinVaultTransactionDataStruct} from "./SpvVaultContractTypechain";
 import {AbiCoder, keccak256, ZeroHash} from "ethers";
 
 /**
+ * Represents parsed withdrawal data used for claiming assets from the EVM SPV vault
+ *  (UTXO-controlled vault).
+ *
  * @category Swaps
  */
 export class EVMSpvWithdrawalData extends SpvWithdrawalTransactionData {
@@ -43,10 +46,16 @@ export class EVMSpvWithdrawalData extends SpvWithdrawalTransactionData {
         )).substring(2);
     }
 
+    /**
+     * @inheritDoc
+     */
     getTxHash(): string {
         return "0x"+Buffer.from(this.btcTx.txid, "hex").reverse().toString("hex");
     }
 
+    /**
+     * @inheritDoc
+     */
     getFrontingAmount(): bigint[] {
         return [this.rawAmounts[0] + this.getExecutionFee()[0], this.rawAmounts[1]];
     }
@@ -61,6 +70,9 @@ export class EVMSpvWithdrawalData extends SpvWithdrawalTransactionData {
         };
     }
 
+    /**
+     * Serializes the withdrawal data to the EVM contract struct representation.
+     */
     serializeToStruct(): BitcoinVaultTransactionDataStruct {
         const callerFee = this.getCallerFee();
         const frontingFee = this.getFrontingFee();