feat: create token bridge

.env.example

@@ -1,3 +1,4 @@
 ARBISCAN_API_KEY=
-PRIVATE_KEY=0xb6b15c8cb491557369f3c7d2c287b053eb229daa9c22138887752191c9520659
-
+NITRO_TESTNODE_DEPLOYER_PRIVATE_KEY=0xb6b15c8cb491557369f3c7d2c287b053eb229daa9c22138887752191c9520659
+NITRO_TESTNODE_L2_ROLLUP_OWNER_PRIVATE_KEY=0xdc04c5399f82306ec4b4d654a342f40e2e0620fe39950d967e1e574b32d4dd36
+NITRO_TESTNODE_L3_ROLLUP_OWNER_PRIVATE_KEY=0xecdf21cb41c65afb51f91df408b7656e2c8739a5877f2814add0afd780cc210e

.github/workflows/build-test.yml

@@ -85,14 +85,13 @@ jobs:
         uses: OffchainLabs/actions/run-nitro-test-node@main
         with:
           nitro-testnode-ref: release
-          # don't deploy the regular token bridge using arbitrum-sdk, as it will be deployed through the TokenBridgeCreator
-          no-token-bridge: true
+          # Use simple mode
+          no-simple: false
           # RollupCreator on L1 is deployed by default
           # RollupCreator on L2 is deployed with --l3node
           l3-node: true
-          # TokenBridgeCreator on L1 is deployed with --tokenbridge
-          # TokenBridgeCreator on L2 is deployed with --l3-token-bridge
-          args: --tokenbridge --l3-token-bridge
+          # L3 node with custom fee token when using --l3-fee-token
+          args: --l3-fee-token
 
       - name: Copy .env
         run: cp ./.env.example ./.env

README.md

@@ -13,6 +13,20 @@ Make sure you are using Node v18 or greater.
 yarn add @arbitrum/orbit-sdk viem
 ```
 
+## Run integration tests
+
+Clone the branch `main` of [nitro-testnode](https://github.com/OffchainLabs/nitro-testnode), and run the testnode using the following arguments:
+
+```bash
+./test-node.bash --init --tokenbridge --l3node --l3-fee-token --l3-token-bridge
+```
+
+Then, run the integration tests:
+
+```bash
+yarn test:integration
+```
+
 ## Examples
 
 See [examples](./examples).

examples/create-token-bridge-custom-fee-token/.env.example

@@ -0,0 +1,13 @@
+# Address of the Rollup contract
+ROLLUP_ADDRESS=
+
+# Private key of the account with executor privileges in the UpgradeExecutor admin contract for the chain
+# (usually, the deployer of the chain)
+ROLLUP_OWNER_PRIVATE_KEY=
+
+# Custom fee token address on the parent chain
+CUSTOM_FEE_TOKEN_ADDRESS=
+
+# Orbit chain configuration
+ORBIT_CHAIN_ID=
+ORBIT_CHAIN_RPC=

examples/create-token-bridge-custom-fee-token/index.ts

@@ -0,0 +1,147 @@
+import { Chain, createPublicClient, http, Address, defineChain } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { arbitrumSepolia } from 'viem/chains';
+import {
+  createTokenBridgeEnoughCustomFeeTokenAllowance,
+  createTokenBridgePrepareCustomFeeTokenApprovalTransactionRequest,
+  createTokenBridgePrepareTransactionRequest,
+  createTokenBridgePrepareTransactionReceipt,
+} from '@arbitrum/orbit-sdk';
+import { config } from 'dotenv';
+config();
+
+function sanitizePrivateKey(privateKey: string): `0x${string}` {
+  if (!privateKey.startsWith('0x')) {
+    return `0x${privateKey}`;
+  }
+
+  return privateKey as `0x${string}`;
+}
+
+function getBlockExplorerUrl(chain: Chain) {
+  return chain.blockExplorers?.default.url;
+}
+
+if (typeof process.env.ROLLUP_ADDRESS === 'undefined') {
+  throw new Error(`Please provide the "ROLLUP_ADDRESS" environment variable`);
+}
+
+if (typeof process.env.ROLLUP_OWNER_PRIVATE_KEY === 'undefined') {
+  throw new Error(`Please provide the "ROLLUP_OWNER_PRIVATE_KEY" environment variable`);
+}
+
+if (typeof process.env.ORBIT_CHAIN_ID === 'undefined') {
+  throw new Error(`Please provide the "ORBIT_CHAIN_ID" environment variable`);
+}
+
+if (typeof process.env.ORBIT_CHAIN_RPC === 'undefined') {
+  throw new Error(`Please provide the "ORBIT_CHAIN_RPC" environment variable`);
+}
+
+if (typeof process.env.CUSTOM_FEE_TOKEN_ADDRESS === 'undefined') {
+  throw new Error(`Please provide the "CUSTOM_FEE_TOKEN_ADDRESS" environment variable`);
+}
+
+// set the parent chain and create a public client for it
+const parentChain = arbitrumSepolia;
+const parentChainPublicClient = createPublicClient({
+  chain: parentChain,
+  transport: http(),
+});
+
+// define chain config for the orbit chain
+const orbitChain = defineChain({
+  id: Number(process.env.ORBIT_CHAIN_ID),
+  network: 'Orbit chain',
+  name: 'orbit',
+  nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: [process.env.ORBIT_CHAIN_RPC],
+    },
+    public: {
+      http: [process.env.ORBIT_CHAIN_RPC],
+    },
+  },
+  testnet: true,
+});
+const orbitChainPublicClient = createPublicClient({ chain: orbitChain, transport: http() });
+
+// load the rollup owner account
+const rollupOwner = privateKeyToAccount(sanitizePrivateKey(process.env.ROLLUP_OWNER_PRIVATE_KEY));
+
+async function main() {
+  // set the custom fee token
+  const nativeToken: Address = process.env.CUSTOM_FEE_TOKEN_ADDRESS as `0x${string}`;
+
+  // prepare transaction to approve custom fee token spend
+  const allowanceParams = {
+    nativeToken,
+    owner: rollupOwner.address,
+    publicClient: parentChainPublicClient,
+  };
+  if (!(await createTokenBridgeEnoughCustomFeeTokenAllowance(allowanceParams))) {
+    const approvalTxRequest =
+      await createTokenBridgePrepareCustomFeeTokenApprovalTransactionRequest(allowanceParams);
+
+    // sign and send the transaction
+    const approvalTxHash = await parentChainPublicClient.sendRawTransaction({
+      serializedTransaction: await rollupOwner.signTransaction(approvalTxRequest),
+    });
+
+    // get the transaction receipt after waiting for the transaction to complete
+    const approvalTxReceipt = await parentChainPublicClient.waitForTransactionReceipt({
+      hash: approvalTxHash,
+    });
+
+    console.log(
+      `Tokens approved in ${getBlockExplorerUrl(parentChain)}/tx/${
+        approvalTxReceipt.transactionHash
+      }`,
+    );
+  }
+
+  // prepare the transaction for deploying the core contracts
+  const txRequest = await createTokenBridgePrepareTransactionRequest({
+    params: {
+      rollup: process.env.ROLLUP_ADDRESS as `0x${string}`,
+      rollupOwner: rollupOwner.address,
+    },
+    parentChainPublicClient,
+    orbitChainPublicClient,
+    account: rollupOwner.address,
+  });
+
+  // sign and send the transaction
+  console.log(`Deploying the TokenBridge...`);
+  const txHash = await parentChainPublicClient.sendRawTransaction({
+    serializedTransaction: await rollupOwner.signTransaction(txRequest),
+  });
+
+  // get the transaction receipt after waiting for the transaction to complete
+  const txReceipt = createTokenBridgePrepareTransactionReceipt(
+    await parentChainPublicClient.waitForTransactionReceipt({ hash: txHash }),
+  );
+  console.log(`Deployed in ${getBlockExplorerUrl(parentChain)}/tx/${txReceipt.transactionHash}`);
+
+  // wait for retryables to execute
+  console.log(`Waiting for retryable tickets to execute on the Orbit chain...`);
+  const orbitChainRetryableReceipts = await txReceipt.waitForRetryables({
+    orbitPublicClient: orbitChainPublicClient,
+  });
+  console.log(`Retryables executed`);
+  console.log(
+    `Transaction hash for first retryable is ${orbitChainRetryableReceipts[0].transactionHash}`,
+  );
+  console.log(
+    `Transaction hash for second retryable is ${orbitChainRetryableReceipts[1].transactionHash}`,
+  );
+
+  // fetching the TokenBridge contracts
+  const tokenBridgeContracts = await txReceipt.getTokenBridgeContracts({
+    parentChainPublicClient,
+  });
+  console.log(`TokenBridge contracts:`, tokenBridgeContracts);
+}
+
+main();

examples/create-token-bridge-custom-fee-token/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "create-token-bridge-custom-fee-token",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "tsc --outDir dist && node ./dist/index.js"
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.0",
+    "typescript": "^5.2.2"
+  }
+}

examples/create-token-bridge-custom-fee-token/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["./**/*"]
+}

examples/create-token-bridge-eth/.env.example

@@ -0,0 +1,10 @@
+# Address of the Rollup contract
+ROLLUP_ADDRESS=
+
+# Private key of the account with executor privileges in the UpgradeExecutor admin contract for the chain
+# (usually, the deployer of the chain)
+ROLLUP_OWNER_PRIVATE_KEY=
+
+# Orbit chain configuration
+ORBIT_CHAIN_ID=
+ORBIT_CHAIN_RPC=

examples/create-token-bridge-eth/index.ts

@@ -0,0 +1,108 @@
+import { Chain, createPublicClient, http, defineChain } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { arbitrumSepolia } from 'viem/chains';
+import {
+  createTokenBridgePrepareTransactionReceipt,
+  createTokenBridgePrepareTransactionRequest,
+} from '@arbitrum/orbit-sdk';
+import { config } from 'dotenv';
+config();
+
+function sanitizePrivateKey(privateKey: string): `0x${string}` {
+  if (!privateKey.startsWith('0x')) {
+    return `0x${privateKey}`;
+  }
+
+  return privateKey as `0x${string}`;
+}
+
+function getBlockExplorerUrl(chain: Chain) {
+  return chain.blockExplorers?.default.url;
+}
+
+if (typeof process.env.ROLLUP_ADDRESS === 'undefined') {
+  throw new Error(`Please provide the "ROLLUP_ADDRESS" environment variable`);
+}
+
+if (typeof process.env.ROLLUP_OWNER_PRIVATE_KEY === 'undefined') {
+  throw new Error(`Please provide the "ROLLUP_OWNER_PRIVATE_KEY" environment variable`);
+}
+
+if (typeof process.env.ORBIT_CHAIN_ID === 'undefined') {
+  throw new Error(`Please provide the "ORBIT_CHAIN_ID" environment variable`);
+}
+
+if (typeof process.env.ORBIT_CHAIN_RPC === 'undefined') {
+  throw new Error(`Please provide the "ORBIT_CHAIN_RPC" environment variable`);
+}
+
+// set the parent chain and create a public client for it
+const parentChain = arbitrumSepolia;
+const parentChainPublicClient = createPublicClient({ chain: parentChain, transport: http() });
+
+// define chain config for the orbit chain
+const orbitChain = defineChain({
+  id: Number(process.env.ORBIT_CHAIN_ID),
+  network: 'Orbit chain',
+  name: 'orbit',
+  nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: [process.env.ORBIT_CHAIN_RPC],
+    },
+    public: {
+      http: [process.env.ORBIT_CHAIN_RPC],
+    },
+  },
+  testnet: true,
+});
+const orbitChainPublicClient = createPublicClient({ chain: orbitChain, transport: http() });
+
+// load the rollup owner account
+const rollupOwner = privateKeyToAccount(sanitizePrivateKey(process.env.ROLLUP_OWNER_PRIVATE_KEY));
+
+async function main() {
+  // prepare the transaction for creating the token bridge
+  const txRequest = await createTokenBridgePrepareTransactionRequest({
+    params: {
+      rollup: process.env.ROLLUP_ADDRESS as `0x${string}`,
+      rollupOwner: rollupOwner.address,
+    },
+    parentChainPublicClient,
+    orbitChainPublicClient,
+    account: rollupOwner.address,
+  });
+
+  // sign and send the transaction
+  console.log(`Deploying the TokenBridge...`);
+  const txHash = await parentChainPublicClient.sendRawTransaction({
+    serializedTransaction: await rollupOwner.signTransaction(txRequest),
+  });
+
+  // get the transaction receipt after waiting for the transaction to complete
+  const txReceipt = createTokenBridgePrepareTransactionReceipt(
+    await parentChainPublicClient.waitForTransactionReceipt({ hash: txHash }),
+  );
+  console.log(`Deployed in ${getBlockExplorerUrl(parentChain)}/tx/${txReceipt.transactionHash}`);
+
+  // wait for retryables to execute
+  console.log(`Waiting for retryable tickets to execute on the Orbit chain...`);
+  const orbitChainRetryableReceipts = await txReceipt.waitForRetryables({
+    orbitPublicClient: orbitChainPublicClient,
+  });
+  console.log(`Retryables executed`);
+  console.log(
+    `Transaction hash for first retryable is ${orbitChainRetryableReceipts[0].transactionHash}`,
+  );
+  console.log(
+    `Transaction hash for second retryable is ${orbitChainRetryableReceipts[1].transactionHash}`,
+  );
+
+  // fetching the TokenBridge contracts
+  const tokenBridgeContracts = await txReceipt.getTokenBridgeContracts({
+    parentChainPublicClient,
+  });
+  console.log(`TokenBridge contracts:`, tokenBridgeContracts);
+}
+
+main();

examples/create-token-bridge-eth/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "create-token-bridge-eth",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "tsc --outDir dist && node ./dist/index.js"
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.0",
+    "typescript": "^5.2.2"
+  }
+}

examples/create-token-bridge-eth/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["./**/*"]
+}

src/chains.ts

@@ -33,6 +33,29 @@ const nitroTestnodeL2 = defineChain({
   testnet: true,
 });
 
-export const chains = [sepolia, arbitrumSepolia, nitroTestnodeL1, nitroTestnodeL2] as const;
+// the L3 deployed as part of the nitro-testnode framework uses a custom fee token
+const nitroTestnodeL3 = defineChain({
+  id: 333333,
+  network: 'Nitro Testnode L3',
+  name: 'nitro-testnode-l3',
+  nativeCurrency: { name: 'AppTestToken', symbol: 'APP', decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: ['http://127.0.0.1:3347'],
+    },
+    public: {
+      http: ['http://127.0.0.1:3347'],
+    },
+  },
+  testnet: true,
+});
+
+export const chains = [
+  sepolia,
+  arbitrumSepolia,
+  nitroTestnodeL1,
+  nitroTestnodeL2,
+  nitroTestnodeL3,
+] as const;
 
-export { sepolia, arbitrumSepolia, nitroTestnodeL1, nitroTestnodeL2 };
+export { sepolia, arbitrumSepolia, nitroTestnodeL1, nitroTestnodeL2, nitroTestnodeL3 };