Withdrawals

Withdrawals work quite differently from deposits and follow a very complex architecture on the L1 and L2 to make sure they work in all possible scenarios.

They generally commence in three stages:

1. User-sent L2 withdrawal transaction is sequenced and executed
2. Withdrawal is part of the next settlement
3. Withdrawals get unrolled onto the L1 iteratively.
4. Withdrawals get claimed by the user

Steps 3. and 4. might be a bit confusing, so let’s walk through that mechanism in detail:

Because of Mina’s account update limit, the process to get all L2 withdrawal onto the L1’s ledger is by iteratively unrolling them. This happens in batches of 6 and can be executed by anyone (doesn’t have to be the sequencer, but will be in most cases).

Now, because of the way that the L1’s zkapps protocol is designed, we have to use an extra step before the tokens are actually in the user’s wallet. During this step, every users gets their withdrawal minted as a special custom token on the L1. This custom token is managed by the protokit bridging contract and does two things: It mints customs tokens during the unrolling, and it lets users redeem those custom tokens for the real tokens. This claiming step is done by each user individually at their own pace. Further reasoning and design choices can be found in this page’s references

Implementing withdrawals

The protokit library already offers a pre-built Withdrawals runtime module, that provides a implementation for token withdrawals.

On the other side, the default BridgingContract offers processing of token withdrawals on the L1 side.

Withdrawing tokens

Once the Withdrawals runtime module is wired up and the BridgeContract is deployed on the L1, users can start withdrawing their tokens back from the L2 to the L1.

A withdrawal is always a two-step flow for the end user:

1. Withdraw on the L2 — the user sends an L2 transaction to the Withdrawals runtime module, which burns the balance on the appchain and enqueues a withdrawal message. After the next settlement and the subsequent unrolling batches, the withdrawal arrives on the L1 as a balance of the bridge’s custom token held by the recipient.
2. Redeem on the L1 — once the withdrawal has been unrolled onto the L1, the user sends an L1 transaction to the BridgeContract that burns the custom token and releases the real tokens (MINA or a fungible token) into their wallet.

You can trigger both steps either from the protokit CLI or programmatically by calling the BridgingModule directly.

# Initiate token withdrawal from the L2 back to the L1
pnpm protokit bridge withdraw <tokenId> <fromPrivateKey> <amount>

# Redeem the tokens on the L1
pnpm protokit bridge redeem <tokenId> <toKey> <amount>

// Inputs for the withdrawal
const withdrawTokenId = TokenId.default;
const l2SenderPrivateKey = PrivateKey.fromBase58("");
const l1RecipientPrivateKey = PrivateKey.fromBase58("");
const withdrawAmount = 100 * 1e9; // 100 MINA
const l1Fee = 0.1 * 1e9; // 0.1 MINA
 
// Resolve modules
const settlementModuleWd = clientAppChain.sequencer.resolveOrFail(
  "SettlementModule",
  SettlementModule
);
const bridgingModuleWd = clientAppChain.sequencer.resolveOrFail(
  "BridgingModule",
  BridgingModule
);
const bridgeContract =
  await bridgingModuleWd.getBridgeContract(withdrawTokenId);
 
// Step 1 — Withdraw on the L2
// Sends an L2 transaction to the `Withdrawals` runtime module that burns
// the balance on the appchain and enqueues a withdrawal message.
const l2Tx = await clientAppChain.transaction(
  l2SenderPrivateKey.toPublicKey(),
  async () => {
    const withdrawals = clientAppChain.runtime.resolve("Withdrawals");
    await withdrawals.withdraw(
      l1RecipientPrivateKey.toPublicKey(),
      ProtokitUInt64.from(withdrawAmount),
      withdrawTokenId
    );
  }
);
await l2Tx.sign();
await l2Tx.send();
 
// IMPORTANT!
// Always wait here until the Sequencer has settled and unrolled the withdrawal action onto the L1!
 
// Step 2 — Redeem on the L1
// After the withdrawal has been unrolled onto the L1 (the recipient now holds
// the bridge's custom token), redeem it for the real tokens.
const redeemTx = await Mina.transaction(
  {
    sender: l1RecipientPrivateKey.toPublicKey(),
    fee: l1Fee,
  },
  async () => {
    const au = AccountUpdate.createSigned(
      l1RecipientPrivateKey.toPublicKey(),
      tokenId
    );
    au.balance.addInPlace(UInt64.from(amount));
 
    await bridgeContract.redeem(au);
 
    if (isCustomToken) {
      await new FungibleToken(
        tokenOwnerPrivateKey.toPublicKey()
      )!.approveAccountUpdate(bridgeContract.self);
    }
  }
);
 
settlementModuleWd.utils.signTransaction(redeemTx, {
  signingPublicKeys: [l1RecipientPrivateKey.toPublicKey()],
});
 
const { hash: redeemHash } = await appChain.sequencer
  .resolveOrFail("TransactionSender", MinaTransactionSender)
  .proveAndSendTransaction(redeemTx, "included");
 
console.log(`Withdrawal redeemed! L1 tx hash: ${redeemHash}`);

References