@atomiqlabs/chain-starknet 8.0.13 → 8.1.10

package/src/starknet/StarknetInitializer.ts

@@ -71,8 +71,11 @@ export type StarknetOptions = {
     chainId?: constants.StarknetChainId,
 
     swapContract?: string,
+    swapContractDeploymentHeight?: number,
     btcRelayContract?: string,
+    btcRelayContractDeploymentHeight?: number,
     spvVaultContract?: string,
+    spvVaultContractDeploymentHeight?: number,
     handlerContracts?: {
         refund?: {
             timelock?: string
@@ -113,15 +116,15 @@ export function initializeStarknet(
     const chainInterface = new StarknetChainInterface(chainId, provider, wsChannel, Fees, options.starknetConfig);
 
     const btcRelay = new StarknetBtcRelay(
-        chainInterface, bitcoinRpc, network, options.btcRelayContract
+        chainInterface, bitcoinRpc, network, options.btcRelayContract, options.btcRelayContractDeploymentHeight
     );
 
     const swapContract = new StarknetSwapContract(
-        chainInterface, btcRelay, options.swapContract, options.handlerContracts
+        chainInterface, btcRelay, options.swapContract, options.handlerContracts, options.swapContractDeploymentHeight
     );
 
     const spvVaultContract = new StarknetSpvVaultContract(
-        chainInterface, btcRelay, bitcoinRpc, options.spvVaultContract
+        chainInterface, btcRelay, bitcoinRpc, options.spvVaultContract, options.spvVaultContractDeploymentHeight
     )
 
     const chainEvents = new StarknetChainEventsBrowser(chainInterface, swapContract, spvVaultContract);

package/src/starknet/btcrelay/StarknetBtcRelay.ts

@@ -11,7 +11,7 @@ import {StarknetBtcStoredHeader} from "./headers/StarknetBtcStoredHeader";
 import {StarknetTx} from "../chain/modules/StarknetTransactions";
 import {StarknetSigner} from "../wallet/StarknetSigner";
 import {BtcRelayAbi} from "./BtcRelayAbi";
-import {BigNumberish, hash} from "starknet";
+import {BigNumberish, constants, hash} from "starknet";
 import {StarknetFees, starknetGasAdd, starknetGasMul} from "../chain/modules/StarknetFees";
 import {StarknetChainInterface} from "../chain/StarknetChainInterface";
 import {StarknetAction} from "../chain/StarknetAction";
@@ -37,6 +37,12 @@ const btcRelayAddreses: {[network in BitcoinNetwork]?: string} = {
     [BitcoinNetwork.MAINNET]: "0x057b14a4231b82f1e525ff35a722d893ca3dd2bde0baa6cee97937c5be861dbc"
 };
 
+const btcRelayDeploymentHeights: {[network in BitcoinNetwork]?: number} = {
+    [BitcoinNetwork.TESTNET4]: 760719,
+    [BitcoinNetwork.TESTNET]: 633915,
+    [BitcoinNetwork.MAINNET]: 1278562
+};
+
 function serializeCalldata(headers: StarknetBtcHeader[], storedHeader: StarknetBtcStoredHeader, span: BigNumberish[]) {
     span.push(toHex(headers.length));
     headers.forEach(header => {
@@ -131,9 +137,16 @@ export class StarknetBtcRelay<B extends BtcBlock>
         bitcoinRpc: BitcoinRpc<B>,
         bitcoinNetwork: BitcoinNetwork,
         contractAddress: string | undefined = btcRelayAddreses[bitcoinNetwork],
+        contractDeploymentHeight?: number
     ) {
         if(contractAddress==null) throw new Error("No BtcRelay address specified!");
-        super(chainInterface, contractAddress, BtcRelayAbi);
+        super(
+            chainInterface, contractAddress, BtcRelayAbi,
+            contractDeploymentHeight ??
+            (btcRelayAddreses[bitcoinNetwork]===contractAddress
+                ? btcRelayDeploymentHeights[bitcoinNetwork]
+                : undefined)
+        );
         this.bitcoinRpc = bitcoinRpc;
     }
 
@@ -266,7 +279,7 @@ export class StarknetBtcRelay<B extends BtcBlock>
         const [storedBlockHeader, commitHash] = result;
 
         //Check if block is part of the main chain
-        const chainCommitment = await this.contract.get_commit_hash(storedBlockHeader.block_height);
+        const chainCommitment = await this.contract.get_commit_hash(storedBlockHeader.getBlockheight());
         if(BigInt(chainCommitment)!==BigInt(commitHash)) return null;
 
         logger.debug("retrieveLogAndBlockheight(): block found," +
@@ -285,11 +298,11 @@ export class StarknetBtcRelay<B extends BtcBlock>
         const [storedBlockHeader, commitHash] = result;
 
         //Check if block is part of the main chain
-        const chainCommitment = await this.contract.get_commit_hash(storedBlockHeader.block_height);
+        const chainCommitment = await this.contract.get_commit_hash(storedBlockHeader.getBlockheight());
         if(BigInt(chainCommitment)!==BigInt(commitHash)) return null;
 
         logger.debug("retrieveLogByCommitHash(): block found," +
-            " commit hash: "+commitmentHash+" blockhash: "+blockData.blockhash+" height: "+storedBlockHeader.block_height);
+            " commit hash: "+commitmentHash+" blockhash: "+blockData.blockhash+" height: "+storedBlockHeader.getBlockheight());
 
         return storedBlockHeader;
     }
@@ -312,7 +325,7 @@ export class StarknetBtcRelay<B extends BtcBlock>
 
                 const [isInBtcMainChain, btcRelayCommitHash] = await Promise.all([
                     this.bitcoinRpc.isInMainChain(blockHashHex).catch(() => false),
-                    this.contract.get_commit_hash(storedHeader.block_height)
+                    this.contract.get_commit_hash(storedHeader.getBlockheight())
                 ]);
 
                 if(!isInBtcMainChain) return null;

package/src/starknet/btcrelay/headers/StarknetBtcHeader.ts

@@ -21,13 +21,13 @@ export type StarknetBtcHeaderType = {
  */
 export class StarknetBtcHeader implements BtcHeader {
 
-    reversed_version: number;
-    previous_blockhash: number[];
-    merkle_root: number[];
-    reversed_timestamp: number;
-    nbits: number;
-    nonce: number;
-    hash?: Buffer;
+    private readonly reversed_version: number;
+    private readonly previous_blockhash: number[];
+    private readonly merkle_root: number[];
+    private readonly reversed_timestamp: number;
+    private readonly nbits: number;
+    private readonly nonce: number;
+    private readonly hash?: Buffer;
 
     /**
      * Constructs the bitcoin blockheader from a struct as returned by the starknet.js lib

package/src/starknet/btcrelay/headers/StarknetBtcStoredHeader.ts

@@ -21,12 +21,12 @@ export type StarknetBtcStoredHeaderType = {
  */
 export class StarknetBtcStoredHeader implements BtcStoredHeader<StarknetBtcHeader> {
 
-    blockheader: StarknetBtcHeader;
-    block_hash: number[];
-    chain_work: Uint256;
-    block_height: number;
-    last_diff_adjustment: number;
-    prev_block_timestamps: number[];
+    private readonly blockheader: StarknetBtcHeader;
+    private readonly block_hash: number[];
+    private readonly chain_work: Uint256;
+    private readonly block_height: number;
+    private readonly last_diff_adjustment: number;
+    private readonly prev_block_timestamps: number[];
 
     /**
      * Constructs the bitcoin stored blockheader from a struct as returned by the starknet.js lib

package/src/starknet/chain/StarknetAction.ts

@@ -7,6 +7,7 @@ export class StarknetAction {
 
     gas: StarknetGas;
     readonly mainSigner: string;
+
     private readonly root: StarknetChainInterface;
     private readonly instructions: Call[];
     private feeRate?: string;

package/src/starknet/chain/StarknetChainInterface.ts

@@ -54,8 +54,6 @@ export class StarknetChainInterface implements ChainInterface<StarknetTx, Signed
     public readonly Accounts: StarknetAccounts;
     public readonly Blocks: StarknetBlocks;
 
-    protected readonly logger = getLogger("StarknetChainInterface: ");
-
     public readonly config: StarknetConfig;
 
     constructor(

package/src/starknet/chain/modules/StarknetFees.ts

@@ -1,15 +1,24 @@
-import {getLogger, toBigInt, toHex} from "../../../utils/Utils";
+import {getLogger, toBigInt} from "../../../utils/Utils";
 import {Provider} from "starknet";
-import {StarknetTokens} from "./StarknetTokens";
 
 const MAX_FEE_AGE = 5000;
 
+/**
+ * Representation of a starknet feerate including costs for different units of gas
+ *
+ * @category Chain Interface
+ */
 export type StarknetFeeRate = {
     l1GasCost: bigint;
     l2GasCost: bigint;
     l1DataGasCost: bigint;
 };
 
+/**
+ * Representation of the starknet transaction gas limits used to create resource bounds and estimate fees
+ *
+ * @category Chain Interface
+ */
 export type StarknetGas = {
     l1Gas: number,
     l2Gas: number,
@@ -21,6 +30,8 @@ export type StarknetGas = {
  *
  * @param gas
  * @param scalar
+ *
+ * @category Chain Interface
  */
 export function starknetGasMul(gas: StarknetGas, scalar: number): StarknetGas {
     return {l1Gas: gas.l1Gas * scalar, l2Gas: gas.l2Gas * scalar, l1DataGas: gas.l1DataGas * scalar};
@@ -31,6 +42,8 @@ export function starknetGasMul(gas: StarknetGas, scalar: number): StarknetGas {
  *
  * @param a
  * @param b
+ *
+ * @category Chain Interface
  */
 export function starknetGasAdd(a: StarknetGas, b?: StarknetGas): StarknetGas {
     if(b==null) return a;

package/src/starknet/chain/modules/StarknetTransactions.ts

@@ -65,6 +65,13 @@ export function isStarknetTxDeployAccount(obj: any): obj is StarknetTxDeployAcco
 export type StarknetTx = StarknetTxInvoke | StarknetTxDeployAccount;
 export type SignedStarknetTx = StarknetTx;
 
+export type StarknetTraceCall = {
+    calldata: string[],
+    contract_address: string,
+    entry_point_selector: string,
+    calls: StarknetTraceCall[]
+};
+
 const MAX_UNCONFIRMED_TXS = 25;
 
 export class StarknetTransactions extends StarknetModule {
@@ -657,6 +664,23 @@ export class StarknetTransactions extends StarknetModule {
         return status;
     }
 
+    async traceTransaction(txId: string, blockHash?: string): Promise<StarknetTraceCall | null> {
+        let trace: any;
+        try {
+            trace = await this.provider.getTransactionTrace(txId);
+        } catch (e) {
+            this.logger.warn("getSwapDataGetter(): getter: starknet_traceTransaction not supported by the RPC: ", e);
+            if(blockHash==null) throw e;
+            const blockTraces: any[] = await this.provider.getBlockTransactionsTraces(blockHash);
+            const foundTrace = blockTraces.find(val => toHex(val.transaction_hash)===toHex(txId));
+            if(foundTrace==null) throw new Error(`Cannot find ${txId} in the block traces, block: ${blockHash}`);
+            trace = foundTrace.trace_root;
+        }
+        if(trace==null) return null;
+        if(trace.execute_invocation.revert_reason!=null) return null;
+        return trace.execute_invocation;
+    }
+
     onBeforeTxReplace(callback: (oldTx: string, oldTxId: string, newTx: string, newTxId: string) => Promise<void>): void {
         this._cbksBeforeTxReplace.push(callback);
     }

package/src/starknet/contract/StarknetContractBase.ts

@@ -8,15 +8,17 @@ import {StarknetContractEvents} from "./modules/StarknetContractEvents";
  */
 export class StarknetContractBase<T extends Abi> {
 
-    contract: TypedContractV2<T>;
+    readonly contract: TypedContractV2<T>;
 
-    public readonly Events: StarknetContractEvents<T>;
-    public readonly Chain: StarknetChainInterface;
+    readonly Events: StarknetContractEvents<T>;
+    readonly Chain: StarknetChainInterface;
+    readonly contractDeploymentHeight?: number;
 
     constructor(
         chainInterface: StarknetChainInterface,
         contractAddress: string,
-        contractAbi: T
+        contractAbi: T,
+        contractDeploymentHeight?: number
     ) {
         this.Chain = chainInterface;
         this.contract = new Contract({
@@ -25,6 +27,7 @@ export class StarknetContractBase<T extends Abi> {
             providerOrAccount: chainInterface.provider
         }).typedv2(contractAbi);
         this.Events = new StarknetContractEvents(chainInterface, this, contractAbi);
+        this.contractDeploymentHeight = contractDeploymentHeight;
     }
 
 }

package/src/starknet/contract/StarknetContractModule.ts

@@ -6,7 +6,7 @@ import {StarknetModule} from "../chain/StarknetModule";
 
 export class StarknetContractModule<TAbi extends Abi> extends StarknetModule {
 
-    readonly contract: StarknetContractBase<TAbi>;
+    protected readonly contract: StarknetContractBase<TAbi>;
 
     constructor(chainInterface: StarknetChainInterface, contract: StarknetContractBase<TAbi>) {
         super(chainInterface)

package/src/starknet/contract/modules/StarknetContractEvents.ts

@@ -18,12 +18,12 @@ export type StarknetAbiEvent<TAbi extends Abi, TEventName extends ExtractAbiEven
 
 export class StarknetContractEvents<TAbi extends Abi> extends StarknetEvents {
 
-    readonly contract: StarknetContractBase<TAbi>;
-    readonly abi: TAbi;
-    readonly knownEventNames: string[];
-    readonly abiEvents: AbiEvents;
-    readonly abiStructs: AbiStructs;
-    readonly abiEnums: AbiEnums;
+    private readonly contract: StarknetContractBase<TAbi>;
+    private readonly abi: TAbi;
+    private readonly knownEventNames: string[];
+    private readonly abiEvents: AbiEvents;
+    private readonly abiStructs: AbiStructs;
+    private readonly abiEnums: AbiEnums;
 
     constructor(chainInterface: StarknetChainInterface, contract: StarknetContractBase<TAbi>, abi: TAbi) {
         super(chainInterface);
@@ -148,7 +148,7 @@ export class StarknetContractEvents<TAbi extends Abi> extends StarknetEvents {
                 if(result!=null) return result;
             }
             return null;
-        }, startHeight, abortSignal);
+        }, Math.max(startHeight ?? 0, this.contract.contractDeploymentHeight ?? 0), abortSignal);
     }
 
 }

package/src/starknet/events/StarknetChainEventsBrowser.ts

@@ -39,13 +39,6 @@ import {Buffer} from "buffer";
 const PROCESSED_EVENTS_BACKLOG = 5000;
 const LOGS_SLIDING_WINDOW = 60;
 
-type StarknetTraceCall = {
-    calldata: string[],
-    contract_address: string,
-    entry_point_selector: string,
-    calls: StarknetTraceCall[]
-};
-
 /**
  * Current state of the starknet event listener, contains the last processed
  *  block number and transaction hash of the last processed event
@@ -57,20 +50,6 @@ export type StarknetEventListenerState = {
     lastTxHash?: string
 };
 
-function parseInitFunctionCalldata(calldata: BigNumberish[], claimHandler: IClaimHandler<any, any>): {escrow: StarknetSwapData, signature: BigNumberish[], timeout: bigint, extraData: BigNumberish[]} {
-    const escrow = StarknetSwapData.fromSerializedFeltArray(calldata, claimHandler);
-    if(calldata.length < 1) throw new Error("Calldata invalid length");
-    const signatureLen = Number(toBigInt(calldata.shift()!));
-    if(calldata.length < signatureLen + 2) throw new Error("Calldata invalid length");
-    const signature = calldata.splice(0, signatureLen);
-    const timeout = toBigInt(calldata.shift()!);
-    const extraDataLen = Number(toBigInt(calldata.shift()!));
-    if(calldata.length < extraDataLen) throw new Error("Calldata invalid length");
-    const extraData = calldata.splice(0, extraDataLen);
-    if(calldata.length!==0) throw new Error("Calldata not read fully!");
-    return {escrow, signature, timeout, extraData};
-}
-
 /**
  * Starknet on-chain event handler for front-end systems without access to fs, uses WS or long-polling to subscribe, might lose
  *  out on some events if the network is unreliable, front-end systems should take this into consideration and not
@@ -96,9 +75,6 @@ export class StarknetChainEventsBrowser implements ChainEvents<StarknetSwapData,
     protected escrowContractSubscription?: SubscriptionStarknetEventsEvent;
     protected spvVaultContractSubscription?: SubscriptionStarknetEventsEvent;
 
-    protected initFunctionName: ExtractAbiFunctionNames<EscrowManagerAbiType> = "initialize";
-    protected initEntryPointSelector = BigInt(hash.starknetKeccak(this.initFunctionName));
-
     protected stopped: boolean = true;
     protected pollIntervalSeconds: number;
 
@@ -153,34 +129,6 @@ export class StarknetChainEventsBrowser implements ChainEvents<StarknetSwapData,
         return this.processedEvents.has(eventFingerprint);
     }
 
-    /**
-     *
-     * @param call
-     * @param escrowHash
-     * @param claimHandler
-     * @private
-     */
-    private findInitSwapData(call: StarknetTraceCall, escrowHash: BigNumberish, claimHandler: IClaimHandler<any, any>): StarknetSwapData | null {
-        if(
-            BigInt(call.contract_address)===BigInt(this.starknetSwapContract.contract.address) &&
-            BigInt(call.entry_point_selector)===this.initEntryPointSelector
-        ) {
-            //Found, check correct escrow hash
-            const {escrow, extraData} = parseInitFunctionCalldata(call.calldata, claimHandler);
-            if("0x"+escrow.getEscrowHash()===toHex(escrowHash)) {
-                if(extraData.length!==0) {
-                    escrow.setExtraData(bytes31SpanToBuffer(extraData, 42).toString("hex"));
-                }
-                return escrow;
-            }
-        }
-        for(let _call of call.calls) {
-            const found = this.findInitSwapData(_call, escrowHash, claimHandler);
-            if(found!=null) return found;
-        }
-        return null;
-    }
-
     /**
      * Returns async getter for fetching on-demand initialize event swap data
      *
@@ -194,19 +142,9 @@ export class StarknetChainEventsBrowser implements ChainEvents<StarknetSwapData,
         claimHandler: IClaimHandler<any, any>
     ): () => Promise<StarknetSwapData | null> {
         return async () => {
-            let trace: any;
-            try {
-                trace = await this.provider.getTransactionTrace(event.txHash);
-            } catch (e) {
-                this.logger.warn("getSwapDataGetter(): getter: starknet_traceTransaction not supported by the RPC: ", e);
-                const blockTraces: any[] = await this.provider.getBlockTransactionsTraces(event.blockHash);
-                const foundTrace = blockTraces.find(val => toHex(val.transaction_hash)===toHex(event.txHash));
-                if(foundTrace==null) throw new Error(`Cannot find ${event.txHash} in the block traces, block: ${event.blockHash}`);
-                trace = foundTrace.trace_root;
-            }
+            const trace = await this.Chain.Transactions.traceTransaction(event.txHash, event.blockHash);
             if(trace==null) return null;
-            if(trace.execute_invocation.revert_reason!=null) return null;
-            return this.findInitSwapData(trace.execute_invocation as any, event.params.escrow_hash, claimHandler);
+            return this.starknetSwapContract.findInitSwapData(trace, event.params.escrow_hash, claimHandler);
         }
     }
 

package/src/starknet/provider/RpcProviderWithRetries.ts

@@ -10,7 +10,7 @@ import {tryWithRetries} from "../../utils/Utils";
  */
 export class Rpc09ChannelWithRetries extends RPC09.RpcChannel {
 
-    readonly retryPolicy?: {
+    private readonly retryPolicy?: {
         maxRetries?: number, delay?: number, exponential?: boolean
     };
 

package/src/starknet/spv_swap/StarknetSpvVaultContract.ts

@@ -3,7 +3,7 @@ import {
     BtcTx,
     RelaySynchronizer,
     SpvVaultContract,
-    SpvVaultTokenData,
+    SpvVaultTokenData, SpvWithdrawalClaimedState, SpvWithdrawalClosedState, SpvWithdrawalFrontedState,
     SpvWithdrawalState,
     SpvWithdrawalStateType,
     SpvWithdrawalTransactionData,
@@ -31,6 +31,11 @@ const spvVaultContractAddreses = {
     [constants.StarknetChainId.SN_MAIN]: "0x01932042992647771f3d0aa6ee526e65359c891fe05a285faaf4d3ffa373e132"
 };
 
+const spvVaultContractDeploymentHeights = {
+    [constants.StarknetChainId.SN_SEPOLIA]: 1118191,
+    [constants.StarknetChainId.SN_MAIN]: 1617295
+};
+
 const STARK_PRIME_MOD: bigint = 2n**251n + 17n * 2n**192n + 1n;
 
 function decodeUtxo(utxo: string): {txHash: bigint, vout: bigint} {
@@ -66,20 +71,27 @@ export class StarknetSpvVaultContract
 
     readonly chainId = "STARKNET";
 
-    readonly btcRelay: StarknetBtcRelay<any>;
-    readonly bitcoinRpc: BitcoinRpc<any>;
     readonly claimTimeout: number = 180;
     readonly maxClaimsPerTx: number = 10;
 
-    readonly logger = getLogger("StarknetSpvVaultContract: ");
+    private readonly btcRelay: StarknetBtcRelay<any>;
+    private readonly bitcoinRpc: BitcoinRpc<any>;
+    private readonly logger = getLogger("StarknetSpvVaultContract: ");
 
     constructor(
         chainInterface: StarknetChainInterface,
         btcRelay: StarknetBtcRelay<any>,
         bitcoinRpc: BitcoinRpc<any>,
-        contractAddress: string = spvVaultContractAddreses[chainInterface.starknetChainId]
+        contractAddress: string = spvVaultContractAddreses[chainInterface.starknetChainId],
+        contractDeploymentHeight?: number
     ) {
-        super(chainInterface, contractAddress, SpvVaultContractAbi);
+        super(
+            chainInterface, contractAddress, SpvVaultContractAbi,
+            contractDeploymentHeight ??
+            (spvVaultContractAddreses[chainInterface.starknetChainId]===contractAddress
+                ? spvVaultContractDeploymentHeights[chainInterface.starknetChainId]
+                : undefined)
+        );
         this.btcRelay = btcRelay;
         this.bitcoinRpc = bitcoinRpc;
     }
@@ -280,7 +292,7 @@ export class StarknetSpvVaultContract
         const openedVaults = new Set<string>();
         await this.Events.findInContractEventsForward(
             ["spv_swap_vault::events::Opened", "spv_swap_vault::events::Closed"],
-            owner==null ? null : [null, owner],
+            owner==null ? null : [null, null, owner],
             (event) => {
                 const owner = toHex(event.params.owner);
                 const vaultId = toBigInt(event.params.vault_id);
@@ -293,12 +305,20 @@ export class StarknetSpvVaultContract
                 return Promise.resolve(null);
             }
         );
-        const vaults: StarknetSpvVaultData[] = [];
-        for(let identifier of openedVaults.keys()) {
+
+        const fetchedVaultData = await this.getMultipleVaultData([...openedVaults.keys()].map(identifier => {
             const [owner, vaultIdStr] = identifier.split(":");
-            const vaultData = await this.getVaultData(owner, BigInt(vaultIdStr));
-            if(vaultData!=null) vaults.push(vaultData);
+            return {owner, vaultId: BigInt(vaultIdStr)}
+        }));
+
+        const vaults: StarknetSpvVaultData[] = [];
+        for(let owner in fetchedVaultData) {
+            for(let vaultIdStr in fetchedVaultData[owner]) {
+                const vault = fetchedVaultData[owner][vaultIdStr];
+                if(vault!=null) vaults.push(vault);
+            }
         }
+
         return vaults;
     }
 
@@ -338,34 +358,53 @@ export class StarknetSpvVaultContract
      * @param event
      * @private
      */
-    private parseWithdrawalEvent(event: StarknetAbiEvent<typeof SpvVaultContractAbi, "spv_swap_vault::events::Claimed" | "spv_swap_vault::events::Fronted" | "spv_swap_vault::events::Closed">): SpvWithdrawalState | null {
+    private parseWithdrawalEvent(
+        event: StarknetAbiEvent<typeof SpvVaultContractAbi, "spv_swap_vault::events::Fronted"> |
+            StarknetAbiEvent<typeof SpvVaultContractAbi, "spv_swap_vault::events::Claimed"> |
+            StarknetAbiEvent<typeof SpvVaultContractAbi, "spv_swap_vault::events::Closed">
+    ): ((SpvWithdrawalFrontedState | SpvWithdrawalClaimedState | SpvWithdrawalClosedState) & {btcTxId: string}) | null {
         switch(event.name) {
             case "spv_swap_vault::events::Fronted":
                 return {
                     type: SpvWithdrawalStateType.FRONTED,
-                    txId: event.txHash,
+                    btcTxId: bigNumberishToBuffer(event.params.btc_tx_hash, 32).reverse().toString("hex"),
                     owner: toHex(event.params.owner),
                     vaultId: toBigInt(event.params.vault_id),
                     recipient: toHex(event.params.recipient),
-                    fronter: toHex(event.params.fronting_address)
+                    fronter: toHex(event.params.caller),
+                    txId: event.txHash,
+                    getTxBlock: async() => ({
+                        blockHeight: event.blockNumber!,
+                        blockTime: await this.Chain.Blocks.getBlockTime(event.blockNumber!)
+                    })
                 };
             case "spv_swap_vault::events::Claimed":
                 return {
                     type: SpvWithdrawalStateType.CLAIMED,
-                    txId: event.txHash,
+                    btcTxId: bigNumberishToBuffer(event.params.btc_tx_hash, 32).reverse().toString("hex"),
                     owner: toHex(event.params.owner),
                     vaultId: toBigInt(event.params.vault_id),
                     recipient: toHex(event.params.recipient),
                     claimer: toHex(event.params.caller),
-                    fronter: toHex(event.params.fronting_address)
+                    fronter: toHex(event.params.fronting_address),
+                    txId: event.txHash,
+                    getTxBlock: async() => ({
+                        blockHeight: event.blockNumber!,
+                        blockTime: await this.Chain.Blocks.getBlockTime(event.blockNumber!)
+                    })
                 };
             case "spv_swap_vault::events::Closed":
                 return {
                     type: SpvWithdrawalStateType.CLOSED,
-                    txId: event.txHash,
+                    btcTxId: bigNumberishToBuffer(event.params.btc_tx_hash, 32).reverse().toString("hex"),
                     owner: toHex(event.params.owner),
                     vaultId: toBigInt(event.params.vault_id),
-                    error: bigNumberishToBuffer(event.params.error).toString()
+                    error: bigNumberishToBuffer(event.params.error).toString(),
+                    txId: event.txHash,
+                    getTxBlock: async() => ({
+                        blockHeight: event.blockNumber!,
+                        blockTime: await this.Chain.Blocks.getBlockTime(event.blockNumber!)
+                    })
                 };
             default:
                 return null;
@@ -447,6 +486,33 @@ export class StarknetSpvVaultContract
         return result;
     }
 
+    async getHistoricalWithdrawalStates(recipient: string, startBlockheight?: number): Promise<{
+        withdrawals: { [btcTxId: string]: SpvWithdrawalClaimedState | SpvWithdrawalFrontedState };
+        latestBlockheight?: number
+    }> {
+        const {height: latestBlockheight} = await this.Chain.getFinalizedBlock();
+        const withdrawals: { [btcTxId: string]: SpvWithdrawalClaimedState | SpvWithdrawalFrontedState } = {};
+
+        const eventTypes: ["spv_swap_vault::events::Fronted", "spv_swap_vault::events::Claimed"] =
+            ["spv_swap_vault::events::Fronted", "spv_swap_vault::events::Claimed"];
+
+        await this.Events.findInContractEventsForward(
+            eventTypes,
+            [null, null, null, null, recipient],
+            async (_event) => {
+                const eventResult = this.parseWithdrawalEvent(_event);
+                if(eventResult==null || eventResult.type===SpvWithdrawalStateType.CLOSED) return null;
+                withdrawals[eventResult.btcTxId] = eventResult;
+            },
+            startBlockheight
+        );
+
+        return {
+            withdrawals,
+            latestBlockheight
+        }
+    }
+
     /**
      * @inheritDoc
      */