Asset deposits and withdrawals

Asset deposits and withdrawals

Applications may want to enable users to:

  • Deposit assets on L1 to L2 (note these pre-requisites)

  • Withdraw assets from L2 to L1

For more information and use cases, see our explanatory article, Deep dive into deposits and withdrawals.

Deposit pre-requisites:

  • The user depositing the asset must be registered with XpansionChain

  • The user must own the asset on L1

  • The L1 smart contract holding the asset must be registered as a collection

📝GUIDES

  • Core SDK

  • API

  • Link SDK:

    • Deposits

    • Prepare withdrawal and complete withdrawal

Core SDK

1. Initialize the Core SDK

In order to use the Core SDK, you need to initialize it.

2. Generate signers

Enabling users to transfer assets requires a user's signature, so your application will need to create signers. See the guide on how to generate signers.

3. Deposit assets onto L2

  • Typescript Core SDK

📚SDK REFERENCE

  • deposit

The function below will deposit ETH from L1 to L2. If you wish to deposit a different asset, you can change type to either ERC20 or ERC721 and specify the asset address as an additional parameter.

(async (): Promise<void> => {
  // Create deposit
  const deposit = await client.deposit(ethSigner, {
    // ethSigner obtained from generating signer

    type: 'ETH', // There are three avaible types: ETH, ERC20, ERC721
    amount: '50000000000000000', // Amount in wei, this currently is 0.05 ETH
  });
  // console.log(deposit); // Uncomment to see the deposit object
})().catch((e) => {
  log.error(component, e);
});

Example response

{
  type: 2, // Transaction type, currently 2 means EIP-1559
  chainId: 5, // The Chain ID of the network, 5 is the Chain ID for Goerli.
  nonce: 5, // The nonce of the transaction used
  maxPriorityFeePerGas: BigNumber { _hex: '0x59682f00', _isBigNumber: true }, // Maximum fee to bribe miners into giving this transaction priority
  maxFeePerGas: BigNumber { _hex: '0x5968cf94', _isBigNumber: true }, // The maximum fee per gas that the sender is willing to pay
  gasPrice: null, // The gas price of the transaction determined by the network
  gasLimit: BigNumber { _hex: '0x013617', _isBigNumber: true }, // The maximum amount of gas that the transaction can use
  to: '0x7917eDb51ecD6CdB3F9854c3cc593F33de10c623', // The address of the recipient
  value: BigNumber { _hex: '0xb1a2bc2ec50000', _isBigNumber: true }, // The amount of ETH to send in wei
  data: '0x00aeef8a02f9a87a2eae83e024312ea33e2bec5df10cdef1470f6aaf5d5adb23f735a60002705737cd248ac819034b5de474c8f0368224f72a0fda9e031499d519992d9e000000000000000000000000000000000000000000000000000000000001ed7a', // Data included in this log
  accessList: [], // Optional list of addresses and storage keys the transaction can access
  hash: '0x357d6e1c09cf09b5746279bb77377b2353deb1c538eb18c8c9fa9e2363aa3d58', // The hash of the transaction
  v: 0, // The recovery ID of the ECDSA signature
  r: '0xc02c07ff0f80405f34917c9e300abff5da7dda319828fe1843a06f041cd3cbf5', // The first 32 bytes of the ECDSA signature
  s: '0x5c08b76a9ab9f766b82e6f273a1503d064d1604b8e071d7267a6735c5900bb1c', // The second 32 bytes of the ECDSA signature
  from: '0xF656956cA54778056f1191791876db54Aa6eb61B', // The address of the sender
  confirmations: 0, // The number of confirmations that the transaction has received
  wait: [Function (anonymous)] // A function that returns a promise that resolves when the transaction is mined
}

  • Kotlin (JVM) Core SDK

📚SDK REFERENCE

  • Deposits API

  • Swift Core SDK

📚SDK REFERENCE

  • Deposits API

  • Golang Core SDK

📚SDK REFERENCE

  • ETH deposit:

    • NewETHDeposit

    • (*ETHDeposit) Deposit

  • ERC20 deposit:

    • NewERC20Deposit

    • (*ERC20Deposit) Deposit

  • ERC721 deposit:

    • NewERC721Deposit

    • (*ERC721Deposit) Deposit

4. Withdraw assets to L1

  • Typescript Core SDK

📚SDK REFERENCE

  • prepareWithdrawal

  • completeWithdrawal

  • Kotlin (JVM) Core SDK

📚SDK REFERENCE

  • createWithdrawal

  • getSignableWithdrawal

  • Swift Core SDK

📚SDK REFERENCE

  • getSignableWithdrawal

  • createwithdrawal

  • Golang Core SDK

📚SDK REFERENCE

  • PrepareWithdrawal

  • Complete withdrawal for token types:

    • (*EthWithdrawal) CompleteWithdrawal

    • (*ERC20Withdrawal) CompleteWithdrawal

    • (*ERC721Withdrawal) CompleteWithdrawal

💻EXAMPLE

  • Withdrawal

API

  • Deposit

  • Withdrawal

Deposit

To understand what is going on under the hood with asset deposits, please see this explainer.

Steps:

  1. Get details of the deposit

  2. Generate signers

  3. Call contract method to deposit tokens

1. Get details of the deposit

💡ENDPOINT:

  • getSignableDeposit

Javascript example of depositing ETH from L1 to L2:

import fetch from 'node-fetch';

const depositDetails = {
  amount: '0.001',
  token: {
    type: 'ETH',
    data: {
      decimals: 18,
    },
  },
  user: '0x..', // Public L1 Ethereum address
};

fetch('https://api.sandbox.x.XpansionChain.com/v1/signable-deposit-details', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(depositDetails),
})
  .then((response) => {
    console.log(response);
  })
  .catch((err) => {
    console.error(err);
  });

Example response:

{
    "amount": "string", // Amount this user is depositing
    "asset_id": "string", // ID of the asset this user is depositing (applicable only to depositing ERC721)
    "nonce": 0, // Random number generated of this transaction to verify that specific values are not reused
    "stark_key": "string", // Public stark key of the depositing user
    "vault_id": 0 // ID of the vault this user is depositing to
}

The following response params are used in the depositEth contract method (see Step 3):

  • stark_key

  • vault_id

2. Generate signers

Enabling users to deposit assets requires a user's signature, so your application will need to create signers. See the guide on how to generate signers.

3. Call contract method to deposit tokens

import { Contracts, Config } from '@imtbl/core-sdk';

const config = Config.SANDBOX;

// Get instance of core contract
const contract = Contracts.Core.connect(
  config.ethConfiguration.coreContractAddress,
  ethSigner
);

// Populate and send transaction
const populatedTransaction = await contract.populateTransaction.depositEth(
  starkPublicKey, // Use `stark_key` obtained in previous step
  assetType, // "ETH", "ERC20" or "ERC721"
  vaultId // Use `vault_id` obtained in previous step
);

const transactionResponse = await ethSigner.sendTransaction(
  populatedTransaction
);

Withdrawal

To understand what is going on under the hood with asset withdrawals, please see this explainer.

Steps:

  1. Get details of the withdrawal

  2. Generate signers

  3. Create withdrawal

  4. Call contract to complete withdrawal

1. Get details of the withdrawal

💡ENDPOINT:

  • getSignableWithdrawal

Javascript example of withdrawing ETH from L2 to L1:

import fetch from 'node-fetch';

const withdrawalDetails = {
  amount: '0.001',
  token: {
    type: 'ETH',
    data: {
      decimals: 18,
    },
  },
  user: '0x..', // Public L1 Ethereum address
};

fetch('https://api.sandbox.x.XpansionChain.com/v1/signable-withdrawal-details', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(withdrawalDetails),
})
  .then((response) => {
    console.log(response);
  })
  .catch((err) => {
    console.error(err);
  });

Example response:

{
    "amount": "string",
    "asset_id": "string",
    "nonce": 0,
    "payload_hash": "string",
    "signable_message": "string",
    "stark_key": "string",
    "vault_id": 0
}

Explanation:

Response param

Description

How is it used in the createWithdrawal request? (See Step 3)

amount

Amount of token to be withdrawn to L1

As amount in the request body

asset_id

ID of the asset this user is withdrawing (applicable only to ERC721 asset type)

As asset_id in the request body

nonce

Random number generated of this transaction to verify that specific values are not reused

As nonce in the request body

payload_hash

Encoded payload hash

Used to generate the stark_signature in the request body by using the Stark (L2) signer to sign the payload_hash.

signable_message

Message to sign with L1 wallet to verity withdrawal request

Used to generate the x-imx-eth-signature header by using the Ethereum (L1) signer to sign the signable_message

stark_key

Public stark key of the withdrawing user

As stark_key in the request body

vault_id

The ID of the vault the asset belong to

As vault_id in the request body

2. Generate signers

Enabling users to withdraw assets requires a user's signature, so your application will need to create signers. See the guide on how to generate signers.

3. Create withdrawal

💡ENDPOINT:

  • createWithdrawal

Javascript example of withdrawing ETH from L2 to L1:

import fetch from 'node-fetch';

// See previous step for how to generate signers
const ethSignature = ethSigner.sign(signable_message);
const starkSignature = starkSigner.sign(payload_hash);

const withdrawalBody = {
  amount: 'string',
  asset_id: 'string',
  nonce: 'string',
  stark_key: 'string',
  stark_signature: starkSignature,
  vauld_id: 'string',
};

fetch('https://api.sandbox.x.XpansionChain.com/v1/withdrawals', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-imx-eth-address': '0x..', // Public Ethereum address of the withdrawing user
    'x-imx-eth-signature': ethSignature,
  },
  body: JSON.stringify(withdrawalBody),
})
  .then((response) => {
    console.log(response);
  })
  .catch((err) => {
    console.error(err);
  });

4. Get the assetType value

This value is required in the next step to complete the withdrawal.

import fetch from 'node-fetch';

const assetType = 'asset'; // "mintable-asset" if you are withdrawing an ERC721 token that was minted on L2 to L1 for the first time

const encodeAssetBody = {
  token: {
    data: {
      blueprint: 'string',
      id: 'string',
      token_address: 'string',
      token_id: 'string',
    },
    type: 'ETH', // Or "ERC20" or "ERC721"
  },
};

fetch(`https://api.sandbox.x.XpansionChain.com/v1/encode/${assetType}`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-imx-eth-address': '0x..', // Public Ethereum address of the withdrawing user
    'x-imx-eth-signature': ethSignature,
  },
  body: JSON.stringify(encodeAssetBody),
})
  .then((response) => {
    console.log(response);

    // Example response
    // {
    //     "asset_id": "string",
    //     "asset_type": "string"
    // }
  })
  .catch((err) => {
    console.error(err);
  });

5. Call contract to complete withdrawal

import { Contracts, Config } from '@imtbl/core-sdk';

const config = Config.SANDBOX;

// Get instance of core contract
const contract = Contracts.Core.connect(
  config.ethConfiguration.coreContractAddress,
  ethSigner
);

// Populate and send transaction
const populatedTransaction = await contract.populateTransaction.withdraw(
  starkPublicKey, // Use `stark_key` obtained in previous step
  assetType // Use the `asset_type` value returned in the response object in step 4
);

const transactionResponse = await ethSigner.sendTransaction(
  populatedTransaction
);

Last updated