Cross-chain deposit flow

Here we expose a possibility to initiate cross-chain deposit that targets an
L2 chain other than the L1 chain the tBTC system is deployed on.
This is achieved by exposing the `initiateCrossChainDeposit` method
on the `DepositsService` component.

typescript/src/lib/base/index.ts

@@ -1,4 +1,8 @@
-import { chainIdFromSigner, EthereumSigner } from "../ethereum"
+import {
+  chainIdFromSigner,
+  ethereumAddressFromSigner,
+  EthereumSigner,
+} from "../ethereum"
 import { BaseL2BitcoinDepositor } from "./l2-bitcoin-depositor"
 import { BaseL2TBTCToken } from "./l2-tbtc-token"
 import { Chains, L2CrossChainContracts } from "../contracts"
@@ -9,11 +13,11 @@ export * from "./l2-tbtc-token"
 /**
  * Loads Base implementation of tBTC cross-chain contracts for the given Base
  * chain ID and attaches the given signer there.
- * @param signer Signer that should be attached to tBTC contracts.
+ * @param signer Signer that should be attached to the contracts.
  * @param chainId Base chain ID.
- * @returns Handle to tBTC cross-chain contracts.
+ * @returns Handle to the contracts.
  * @throws Throws an error if the signer's Base chain ID is other than
- *         the one used to load tBTC contracts.
+ *         the one used to load contracts.
  */
 export async function loadBaseCrossChainContracts(
   signer: EthereumSigner,
@@ -30,6 +34,8 @@ export async function loadBaseCrossChainContracts(
     { signerOrProvider: signer },
     chainId
   )
+  l2BitcoinDepositor.setDepositOwner(await ethereumAddressFromSigner(signer))
+
   const l2TbtcToken = new BaseL2TBTCToken({ signerOrProvider: signer }, chainId)
 
   return {

typescript/src/lib/base/l2-bitcoin-depositor.ts

@@ -4,12 +4,24 @@ import {
   EthersContractHandle,
 } from "../ethereum/adapter"
 import { L2BitcoinDepositor as L2BitcoinDepositorTypechain } from "../../../typechain/L2BitcoinDepositor"
-import { ChainIdentifier, Chains, L2BitcoinDepositor } from "../contracts"
-import { EthereumAddress } from "../ethereum"
+import {
+  ChainIdentifier,
+  Chains,
+  CrossChainExtraDataEncoder,
+  DepositReceipt,
+  L2BitcoinDepositor,
+} from "../contracts"
+import {
+  EthereumAddress,
+  EthereumCrossChainExtraDataEncoder,
+  packRevealDepositParameters,
+} from "../ethereum"
 
 // TODO: Uncomment once BaseL2BitcoinDepositor is available on Base mainnet.
 // import BaseL2BitcoinDepositorDeployment from "./artifacts/base/BaseL2BitcoinDepositor.json"
 import BaseSepoliaL2BitcoinDepositorDeployment from "./artifacts/baseSepolia/BaseL2BitcoinDepositor.json"
+import { BitcoinRawTxVectors } from "../bitcoin"
+import { Hex } from "../utils"
 
 /**
  * Implementation of the Base L2BitcoinDepositor handle.
@@ -19,6 +31,9 @@ export class BaseL2BitcoinDepositor
   extends EthersContractHandle<L2BitcoinDepositorTypechain>
   implements L2BitcoinDepositor
 {
+  readonly #extraDataEncoder: CrossChainExtraDataEncoder
+  #depositOwner: ChainIdentifier | undefined
+
   constructor(config: EthersContractConfig, chainId: Chains.Base) {
     let deployment: EthersContractDeployment
 
@@ -35,6 +50,8 @@ export class BaseL2BitcoinDepositor
     }
 
     super(config, deployment)
+
+    this.#extraDataEncoder = new EthereumCrossChainExtraDataEncoder()
   }
 
   // eslint-disable-next-line valid-jsdoc
@@ -44,4 +61,62 @@ export class BaseL2BitcoinDepositor
   getChainIdentifier(): ChainIdentifier {
     return EthereumAddress.from(this._instance.address)
   }
+
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @see {L2BitcoinDepositor#getDepositOwner}
+   */
+  getDepositOwner(): ChainIdentifier | undefined {
+    return this.#depositOwner
+  }
+
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @see {L2BitcoinDepositor#setDepositOwner}
+   */
+  setDepositOwner(depositOwner: ChainIdentifier | undefined) {
+    this.#depositOwner = depositOwner
+  }
+
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @see {L2BitcoinDepositor#extraDataEncoder}
+   */
+  extraDataEncoder(): CrossChainExtraDataEncoder {
+    return this.#extraDataEncoder
+  }
+
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @see {L2BitcoinDepositor#initializeDeposit}
+   */
+  async initializeDeposit(
+    depositTx: BitcoinRawTxVectors,
+    depositOutputIndex: number,
+    deposit: DepositReceipt,
+    vault?: ChainIdentifier
+  ): Promise<Hex> {
+    const { fundingTx, reveal } = packRevealDepositParameters(
+      depositTx,
+      depositOutputIndex,
+      deposit,
+      vault
+    )
+
+    if (!deposit.extraData) {
+      throw new Error("Extra data is required")
+    }
+
+    const l2DepositOwner = this.extraDataEncoder().decodeDepositOwner(
+      deposit.extraData
+    )
+
+    const tx = await this._instance.initializeDeposit(
+      fundingTx,
+      reveal,
+      `0x${l2DepositOwner.identifierHex}`
+    )
+
+    return Hex.from(tx.hash)
+  }
 }

typescript/src/lib/contracts/chain.ts

@@ -1,6 +1,6 @@
 /* eslint-disable no-unused-vars */
 /**
- * Chains supported by tBTC v2 SDK.
+ * Chains supported by tBTC v2 contracts.
  */
 export namespace Chains {
   export enum Ethereum {
@@ -16,7 +16,7 @@ export namespace Chains {
 }
 
 /**
- * Layer 2 chains supported by tBTC v2 SDK.
+ * Layer 2 chains supported by tBTC v2 contracts.
  */
 export type L2Chain = Exclude<keyof typeof Chains, "Ethereum">
 
@@ -35,7 +35,7 @@ export type ChainMapping = {
 }
 
 /**
- * List of chain mappings supported by tBTC v2 SDK.
+ * List of chain mappings supported by tBTC v2 contracts.
  */
 export const ChainMappings: ChainMapping[] = [
   {

typescript/src/lib/contracts/cross-chain.ts

@@ -1,6 +1,9 @@
 import { ChainIdentifier } from "./chain-identifier"
 import { BigNumber } from "ethers"
 import { ChainMapping, L2Chain } from "./chain"
+import { BitcoinRawTxVectors } from "../bitcoin"
+import { DepositReceipt } from "./bridge"
+import { Hex } from "../utils"
 
 /**
  * Convenience type aggregating TBTC cross-chain contracts forming a connector
@@ -67,6 +70,43 @@ export interface L2BitcoinDepositor {
    * Gets the chain-specific identifier of this contract.
    */
   getChainIdentifier(): ChainIdentifier
+
+  /**
+   * Gets the identifier that should be used as the owner of the deposits
+   * issued by this contract.
+   * @returns The identifier of the deposit owner or undefined if not set.
+   */
+  getDepositOwner(): ChainIdentifier | undefined
+
+  /**
+   * Sets the identifier that should be used as the owner of the deposits
+   * issued by this contract.
+   * @param depositOwner Identifier of the deposit owner or undefined to clear.
+   */
+  setDepositOwner(depositOwner: ChainIdentifier): void
+
+  /**
+   * @returns Extra data encoder for this contract. The encoder is used to
+   * encode and decode the extra data included in the cross-chain deposit script.
+   */
+  extraDataEncoder(): CrossChainExtraDataEncoder
+
+  /**
+   * Initializes the cross-chain deposit indirectly through the given L2 chain.
+   * @param depositTx Deposit transaction data
+   * @param depositOutputIndex Index of the deposit transaction output that
+   *        funds the revealed deposit
+   * @param deposit Data of the revealed deposit
+   * @param vault Optional parameter denoting the vault the given deposit
+   *        should be routed to
+   * @returns Transaction hash of the reveal deposit transaction.
+   */
+  initializeDeposit(
+    depositTx: BitcoinRawTxVectors,
+    depositOutputIndex: number,
+    deposit: DepositReceipt,
+    vault?: ChainIdentifier
+  ): Promise<Hex>
 }
 
 /**
@@ -78,4 +118,49 @@ export interface L1BitcoinDepositor {
    * Gets the chain-specific identifier of this contract.
    */
   getChainIdentifier(): ChainIdentifier
+
+  /**
+   * @returns Extra data encoder for this contract. The encoder is used to
+   * encode and decode the extra data included in the cross-chain deposit script.
+   */
+  extraDataEncoder(): CrossChainExtraDataEncoder
+
+  /**
+   * Initializes the cross-chain deposit directly on the given L1 chain.
+   * @param depositTx Deposit transaction data
+   * @param depositOutputIndex Index of the deposit transaction output that
+   *        funds the revealed deposit
+   * @param deposit Data of the revealed deposit
+   * @param vault Optional parameter denoting the vault the given deposit
+   *        should be routed to
+   * @returns Transaction hash of the reveal deposit transaction.
+   */
+  initializeDeposit(
+    depositTx: BitcoinRawTxVectors,
+    depositOutputIndex: number,
+    deposit: DepositReceipt,
+    vault?: ChainIdentifier
+  ): Promise<Hex>
+}
+
+/**
+ * Interface for encoding and decoding the extra data included in the
+ * cross-chain deposit script.
+ */
+export interface CrossChainExtraDataEncoder {
+  /**
+   * Encodes the given deposit owner identifier into the extra data.
+   * @param depositOwner Identifier of the deposit owner to encode.
+   *        For cross-chain deposits, the deposit owner is typically an
+   *        identifier on the L2 chain.
+   * @returns Encoded extra data.
+   */
+  encodeDepositOwner(depositOwner: ChainIdentifier): Hex
+
+  /**
+   * Decodes the extra data into the deposit owner identifier.
+   * @param extraData Extra data to decode.
+   * @returns Identifier of the deposit owner.
+   */
+  decodeDepositOwner(extraData: Hex): ChainIdentifier
 }

typescript/src/lib/ethereum/l1-bitcoin-depositor.ts

@@ -7,10 +7,14 @@ import { L1BitcoinDepositor as L1BitcoinDepositorTypechain } from "../../../type
 import {
   ChainIdentifier,
   Chains,
+  CrossChainExtraDataEncoder,
+  DepositReceipt,
   L1BitcoinDepositor,
   L2Chain,
 } from "../contracts"
-import { EthereumAddress } from "./index"
+import { EthereumAddress, packRevealDepositParameters } from "./index"
+import { BitcoinRawTxVectors } from "../bitcoin"
+import { Hex } from "../utils"
 
 // TODO: Uncomment once BaseL1BitcoinDepositor is available on Ethereum mainnet.
 // import MainnetBaseL1BitcoinDepositorDeployment from "./artifacts/mainnet/BaseL1BitcoinDepositor.json"
@@ -46,6 +50,8 @@ export class EthereumL1BitcoinDepositor
   extends EthersContractHandle<L1BitcoinDepositorTypechain>
   implements L1BitcoinDepositor
 {
+  readonly #extraDataEncoder: CrossChainExtraDataEncoder
+
   constructor(
     config: EthersContractConfig,
     chainId: Chains.Ethereum,
@@ -65,6 +71,8 @@ export class EthereumL1BitcoinDepositor
     }
 
     super(config, deployment)
+
+    this.#extraDataEncoder = new EthereumCrossChainExtraDataEncoder()
   }
 
   // eslint-disable-next-line valid-jsdoc
@@ -74,4 +82,80 @@ export class EthereumL1BitcoinDepositor
   getChainIdentifier(): ChainIdentifier {
     return EthereumAddress.from(this._instance.address)
   }
+
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @see {L1BitcoinDepositor#extraDataEncoder}
+   */
+  extraDataEncoder(): CrossChainExtraDataEncoder {
+    return this.#extraDataEncoder
+  }
+
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @see {L1BitcoinDepositor#initializeDeposit}
+   */
+  async initializeDeposit(
+    depositTx: BitcoinRawTxVectors,
+    depositOutputIndex: number,
+    deposit: DepositReceipt,
+    vault?: ChainIdentifier
+  ): Promise<Hex> {
+    const { fundingTx, reveal } = packRevealDepositParameters(
+      depositTx,
+      depositOutputIndex,
+      deposit,
+      vault
+    )
+
+    if (!deposit.extraData) {
+      throw new Error("Extra data is required")
+    }
+
+    const l2DepositOwner = this.extraDataEncoder().decodeDepositOwner(
+      deposit.extraData
+    )
+
+    const tx = await this._instance.initializeDeposit(
+      fundingTx,
+      reveal,
+      `0x${l2DepositOwner.identifierHex}`
+    )
+
+    return Hex.from(tx.hash)
+  }
+}
+
+/**
+ * Implementation of the Ethereum CrossChainExtraDataEncoder.
+ * @see {CrossChainExtraDataEncoder} for reference.
+ */
+export class EthereumCrossChainExtraDataEncoder
+  implements CrossChainExtraDataEncoder
+{
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @see {CrossChainExtraDataEncoder#encodeDepositOwner}
+   */
+  encodeDepositOwner(depositOwner: ChainIdentifier): Hex {
+    // Make sure we are dealing with an Ethereum address. If not, this
+    // call will throw.
+    const address = EthereumAddress.from(depositOwner.identifierHex)
+
+    // Extra data must be 32-byte so prefix the 20-byte address with
+    // 12 zero bytes.
+    return Hex.from(`000000000000000000000000${address.identifierHex}`)
+  }
+
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @see {CrossChainExtraDataEncoder#decodeDepositOwner}
+   */
+  decodeDepositOwner(extraData: Hex): ChainIdentifier {
+    // Cut the first 12 zero bytes of the extra data and convert the rest to
+
+    return EthereumAddress.from(
+      Hex.from(extraData.toBuffer().subarray(12)).toString()
+    )
+  }
 }