feat: added jotbot-generated code documentation

package.json

@@ -1,9 +1,5 @@
 {
-  "workspaces": [
-    "src",
-    "examples/*"
-  ],
-  "private": true,
+  "name": "@arbitrum/orbit-sdk",
   "type": "module",
   "scripts": {
     "prebuild": "rm -rf ./src/dist",

src/abi/sequencerInboxABI.ts

@@ -1,3 +1,8 @@
+/**
+ * Variable "sequencerInboxABI" defines the ABI for the Sequencer Inbox
+ * contract, including error types, events, and functions such as adding a
+ * sequencer L2 batch and setting valid keysets.
+ */
 export const sequencerInboxABI = [
   { inputs: [], name: 'AlreadyInit', type: 'error' },
   {

src/arbAggregatorPrepareTransactionRequest.ts

@@ -17,6 +17,16 @@ export type ArbAggregatorEncodeFunctionDataParameters<
   TFunctionName extends ArbAggregatorPrepareTransactionRequestFunctionName,
 > = EncodeFunctionDataParameters<ArbAggregatorAbi, TFunctionName>;
 
+/**
+ * Encodes function data for the ArbAggregator contract function specified by the given function name.
+ *
+ * @template TFunctionName - The name of the function to encode data for.
+ * @param {ArbAggregatorEncodeFunctionDataParameters<TFunctionName>} params - The parameters for encoding function data.
+ * @param {string} params.functionName - The name of the function to encode data for.
+ * @param {Array<any>} params.args - The arguments to pass to the function.
+ * @param {Array<any>} params.abi - The ABI of the contract.
+ * @returns {string} The encoded function data.
+ */
 function arbAggregatorEncodeFunctionData<
   TFunctionName extends ArbAggregatorPrepareTransactionRequestFunctionName,
 >({ functionName, abi, args }: ArbAggregatorEncodeFunctionDataParameters<TFunctionName>) {
@@ -33,6 +43,18 @@ type ArbAggregatorPrepareFunctionDataParameters<
   upgradeExecutor: Address | false;
   abi: ArbAggregatorAbi;
 };
+
+/**
+ * Prepares function data for the ArbAggregator contract function specified by the given function name.
+ *
+ * @template TFunctionName - The name of the function to prepare data for.
+ * @param {ArbAggregatorPrepareFunctionDataParameters<TFunctionName>} params - The parameters for preparing function data.
+ * @param {string} params.functionName - The name of the function to prepare data for.
+ * @param {Array<any>} params.args - The arguments to pass to the function.
+ * @param {Array<any>} params.abi - The ABI of the contract.
+ * @param {Address|false} params.upgradeExecutor - The address of the upgrade executor or false if not applicable.
+ * @returns {Object} The prepared function data including the target address, encoded data, and value.
+ */
 function arbAggregatorPrepareFunctionData<
   TFunctionName extends ArbAggregatorPrepareTransactionRequestFunctionName,
 >(params: ArbAggregatorPrepareFunctionDataParameters<TFunctionName>) {
@@ -68,6 +90,33 @@ export type ArbAggregatorPrepareTransactionRequestParameters<
 > = Omit<ArbAggregatorPrepareFunctionDataParameters<TFunctionName>, 'abi'> & {
   account: Address;
 };
+
+/**
+ * Prepares a transaction request for the ArbAggregator contract function specified by the given function name.
+ * It generates the necessary data and value for the transaction based on the input parameters and prepares the
+ * transaction request using the provided client and account information.
+ *
+ * @template TFunctionName - The name of the function to prepare the transaction request for.
+ * @template TChain - The type of the chain.
+ * @param {PublicClient<Transport, TChain>} client - The public client used to prepare the transaction request.
+ * @param {ArbAggregatorPrepareTransactionRequestParameters<TFunctionName>} params - The parameters for preparing the transaction request.
+ * @param {string} params.functionName - The name of the function to prepare the transaction request for.
+ * @param {Array<any>} params.args - The arguments to pass to the function.
+ * @param {Address|false} params.upgradeExecutor - The address of the upgrade executor or false if not applicable.
+ * @param {Address} params.account - The account address to use for the transaction.
+ * @returns {Promise<Object>} The prepared transaction request including the chain ID.
+ * @throws {Error} If the client.chain is undefined.
+ *
+ * @example
+ * const client = new PublicClient(...);
+ * const params = {
+ *   functionName: 'someFunction',
+ *   args: [arg1, arg2],
+ *   upgradeExecutor: '0xExecutorAddress',
+ *   account: '0xAccountAddress',
+ * };
+ * const request = await arbAggregatorPrepareTransactionRequest(client, params);
+ */
 export async function arbAggregatorPrepareTransactionRequest<
   TFunctionName extends ArbAggregatorPrepareTransactionRequestFunctionName,
   TChain extends Chain | undefined,

src/arbAggregatorReadContract.ts

@@ -13,6 +13,25 @@ export type ArbAggregatorReadContractParameters<TFunctionName extends ArbAggrega
 export type ArbAggregatorReadContractReturnType<TFunctionName extends ArbAggregatorFunctionName> =
   ReadContractReturnType<ArbAggregatorAbi, TFunctionName>;
 
+/**
+ * Reads data from the ArbAggregator smart contract and returns the specified
+ * result.
+ *
+ * @template TChain - The type of the blockchain chain.
+ * @template TFunctionName - The name of the function to read from the contract.
+ * @param {PublicClient<Transport, TChain>} client - The public client to interact with the blockchain.
+ * @param {ArbAggregatorReadContractParameters<TFunctionName>} params - The parameters for reading the contract.
+ * @param {TFunctionName} params.functionName - The name of the function to call on the contract.
+ * @param {Array<any>} [params.args] - The arguments to pass to the contract function.
+ * @returns {Promise<ArbAggregatorReadContractReturnType<TFunctionName>>} - The result from the contract function.
+ * @example
+ * const client = new PublicClient(...);
+ * const result = await arbAggregatorReadContract(client, {
+ *   functionName: 'getTotalStaked',
+ *   args: [],
+ * });
+ * console.log(result);
+ */
 export function arbAggregatorReadContract<
   TChain extends Chain | undefined,
   TFunctionName extends ArbAggregatorFunctionName,

src/arbGasInfoReadContract.ts

@@ -7,12 +7,29 @@ export type ArbGasInfoAbi = typeof arbGasInfo.abi;
 export type ArbGasInfoFunctionName = GetFunctionName<ArbGasInfoAbi>;
 
 export type ArbGasInfoReadContractParameters<TFunctionName extends ArbGasInfoFunctionName> = {
+  /**
+   * The name of the function to be called on the ArbGasInfo contract.
+   */
   functionName: TFunctionName;
 } & GetFunctionArgs<ArbGasInfoAbi, TFunctionName>;
 
 export type ArbGasInfoReadContractReturnType<TFunctionName extends ArbGasInfoFunctionName> =
   ReadContractReturnType<ArbGasInfoAbi, TFunctionName>;
 
+/**
+ * Reads data from the ArbGasInfo contract on a specified chain and returns the
+ * result.
+ *
+ * @template TChain - The type of the chain, can be a specific chain or undefined.
+ * @template TFunctionName - The name of the function to be called on the ArbGasInfo contract.
+ *
+ * @param {PublicClient<Transport, TChain>} client - The public client to interact with the blockchain.
+ * @param {ArbGasInfoReadContractParameters<TFunctionName>} params - The parameters for reading the contract.
+ * @param {string} params.functionName - The name of the function to be called.
+ * @param {Array<any>} [params.args] - The arguments to be passed to the function.
+ *
+ * @returns {Promise<ArbGasInfoReadContractReturnType<TFunctionName>>} - The result of the contract call.
+ */
 export function arbGasInfoReadContract<
   TChain extends Chain | undefined,
   TFunctionName extends ArbGasInfoFunctionName,

src/arbOwnerPrepareTransactionRequest.ts

@@ -17,6 +17,16 @@ export type ArbOwnerEncodeFunctionDataParameters<
   TFunctionName extends ArbOwnerPrepareTransactionRequestFunctionName,
 > = EncodeFunctionDataParameters<ArbOwnerAbi, TFunctionName>;
 
+/**
+ * Encodes function data for the ArbOwner contract.
+ *
+ * @template TFunctionName - The name of the function to encode.
+ * @param {ArbOwnerEncodeFunctionDataParameters<TFunctionName>} params - The parameters for encoding the function data.
+ * @param {string} params.functionName - The name of the function to encode.
+ * @param {Array<any>} params.args - The arguments for the function.
+ * @param {Array<any>} params.abi - The ABI of the contract.
+ * @returns {string} The encoded function data.
+ */
 function arbOwnerEncodeFunctionData<
   TFunctionName extends ArbOwnerPrepareTransactionRequestFunctionName,
 >({ functionName, abi, args }: ArbOwnerEncodeFunctionDataParameters<TFunctionName>) {
@@ -27,12 +37,24 @@ function arbOwnerEncodeFunctionData<
   });
 }
 
-type ArbOwnerPrepareFunctionDataParameters<
+export type ArbOwnerPrepareFunctionDataParameters<
   TFunctionName extends ArbOwnerPrepareTransactionRequestFunctionName,
 > = ArbOwnerEncodeFunctionDataParameters<TFunctionName> & {
   upgradeExecutor: Address | false;
   abi: ArbOwnerAbi;
 };
+
+/**
+ * Prepares function data for the ArbOwner contract, optionally using an upgrade executor.
+ *
+ * @template TFunctionName - The name of the function to prepare data for.
+ * @param {ArbOwnerPrepareFunctionDataParameters<TFunctionName>} params - The parameters for preparing the function data.
+ * @param {string} params.functionName - The name of the function to prepare data for.
+ * @param {Array<any>} params.args - The arguments for the function.
+ * @param {Array<any>} params.abi - The ABI of the contract.
+ * @param {Address|false} params.upgradeExecutor - The address of the upgrade executor or false if not using an upgrade executor.
+ * @returns {Object} The prepared function data including the target address, data, and value.
+ */
 function arbOwnerPrepareFunctionData<
   TFunctionName extends ArbOwnerPrepareTransactionRequestFunctionName,
 >(params: ArbOwnerPrepareFunctionDataParameters<TFunctionName>) {
@@ -67,6 +89,20 @@ export type ArbOwnerPrepareTransactionRequestParameters<
   account: Address;
 };
 
+/**
+ * Prepares a transaction request for executing a function on the ArbOwner contract.
+ *
+ * @template TFunctionName - The name of the function to execute.
+ * @template TChain - The type of the chain.
+ * @param {PublicClient<Transport, TChain>} client - The public client to use for the transaction.
+ * @param {ArbOwnerPrepareTransactionRequestParameters<TFunctionName>} params - The parameters for preparing the transaction request.
+ * @param {string} params.functionName - The name of the function to execute.
+ * @param {Array<any>} params.args - The arguments for the function.
+ * @param {Address|false} params.upgradeExecutor - The address of the upgrade executor or false if not using an upgrade executor.
+ * @param {Address} params.account - The address of the account to use for the transaction.
+ * @returns {Promise<Object>} The prepared transaction request including the chain ID.
+ * @throws Will throw an error if the client chain is undefined.
+ */
 export async function arbOwnerPrepareTransactionRequest<
   TFunctionName extends ArbOwnerPrepareTransactionRequestFunctionName,
   TChain extends Chain | undefined,

src/arbOwnerReadContract.ts

@@ -7,12 +7,28 @@ export type ArbOwnerPublicAbi = typeof arbOwnerPublic.abi;
 export type ArbOwnerPublicFunctionName = GetFunctionName<ArbOwnerPublicAbi>;
 
 export type ArbOwnerReadContractParameters<TFunctionName extends ArbOwnerPublicFunctionName> = {
+  /**
+   * The name of the function to call on the contract.
+   */
   functionName: TFunctionName;
 } & GetFunctionArgs<ArbOwnerPublicAbi, TFunctionName>;
 
 export type ArbOwnerReadContractReturnType<TFunctionName extends ArbOwnerPublicFunctionName> =
   ReadContractReturnType<ArbOwnerPublicAbi, TFunctionName>;
 
+/**
+ * Reads data from a contract owned by an arbitrary owner.
+ *
+ * @template TChain - The type of the blockchain chain.
+ * @template TFunctionName - The name of the function to call on the contract.
+ *
+ * @param {PublicClient<Transport, TChain>} client - The public client to use for reading the contract.
+ * @param {ArbOwnerReadContractParameters<TFunctionName>} params - The parameters for reading the contract.
+ * @param {TFunctionName} params.functionName - The name of the function to call on the contract.
+ * @param {Array} [params.args] - The arguments to pass to the function.
+ *
+ * @returns {Promise<ArbOwnerReadContractReturnType<TFunctionName>>} - The result of reading the contract.
+ */
 export function arbOwnerReadContract<
   TChain extends Chain | undefined,
   TFunctionName extends ArbOwnerPublicFunctionName,

src/chains.ts

@@ -57,6 +57,13 @@ const nitroTestnodeL3 = defineChain({
   testnet: true,
 });
 
+/**
+ * The `chains` variable contains an array of various blockchain configurations,
+ * including mainnet, testnet, and local nitro-testnode chains. Each chain
+ * object includes information such as network name, native currency details,
+ * RPC URLs, and testnet status. It provides a convenient way to access and
+ * reference different blockchain configurations within the application.
+ */
 export const chains = [
   // mainnet
   mainnet,

src/constants.ts

@@ -1,5 +1,21 @@
 import { parseEther } from 'viem';
 
+/**
+ * Represents the default retryables fees for rollup transactions.
+ *
+ * This constant returns an Ether value representing the default fees
+ * for retryable transactions in rollups.
+ *
+ * @constant {bigint} createRollupDefaultRetryablesFees
+ */
 export const createRollupDefaultRetryablesFees = parseEther('0.125');
 
+/**
+ * Represents the default fees for retryable transactions in the TokenBridge.
+ *
+ * This constant returns an Ether value representing the default fees
+ * for retryable transactions in the TokenBridge.
+ *
+ * @constant {bigint} createTokenBridgeDefaultRetryablesFees
+ */
 export const createTokenBridgeDefaultRetryablesFees = parseEther('0.02');

src/contracts.ts

@@ -11,32 +11,64 @@ import {
 } from './generated';
 import { sequencerInboxABI, rollupAdminLogicABI } from './abi';
 
+/**
+ * ERC-20 token contract configuration.
+ * @property {Array} abi - The ABI of the ERC-20 token contract.
+ */
 export const erc20 = {
   abi: erc20ABI,
 };
 
+/**
+ * Arbitrum owner configuration.
+ * @property {Object} arbOwnerConfig - The configuration object for the Arbitrum owner.
+ * @property {string} address - The address of the Arbitrum owner.
+ */
 export const arbOwner = {
   ...arbOwnerConfig,
   address: Object.values(arbOwnerConfig.address)[0],
 } as const;
 
+/**
+ * Gas information configuration for the Arbitrum network.
+ * @property {Object} arbGasInfoConfig - The configuration object for Arbitrum gas information.
+ * @property {string} address - The address for gas information.
+ */
 export const arbGasInfo = {
   ...arbGasInfoConfig,
   address: Object.values(arbGasInfoConfig.address)[0],
 } as const;
 
+/**
+ * Public configuration for the Arbitrum owner's address.
+ * @property {Object} arbOwnerPublicConfig - The configuration object for the Arbitrum owner's public address.
+ * @property {string} address - The public address of the Arbitrum owner.
+ */
 export const arbOwnerPublic = {
   ...arbOwnerPublicConfig,
   address: Object.values(arbOwnerPublicConfig.address)[0],
 } as const;
 
+/**
+ * Aggregator configuration for retrieving data from a specified source.
+ * @property {Object} arbAggregatorConfig - The configuration object for the Arbitrum aggregator.
+ * @property {string} address - The address of the aggregator.
+ */
 export const arbAggregator = {
   ...arbAggregatorConfig,
   address: Object.values(arbAggregatorConfig.address)[0],
 } as const;
 
+/**
+ * Rollup creator configuration.
+ * @property {Object} rollupCreatorConfig - The configuration object for the rollup creator.
+ */
 export const rollupCreator = rollupCreatorConfig;
 
+/**
+ * Executor for upgrades, calls, and role management.
+ * @property {Array} abi - The ABI for the upgrade executor contract.
+ */
 export const upgradeExecutor = {
   abi: parseAbi([
     'function execute(address upgrade, bytes upgradeCallData)',
@@ -93,19 +125,6 @@ const tokenBridgeCreatorABI = [
     anonymous: false,
     inputs: [
       { indexed: true, internalType: 'address', name: 'inbox', type: 'address' },
-      {
-        components: [
-          { internalType: 'address', name: 'router', type: 'address' },
-          { internalType: 'address', name: 'standardGateway', type: 'address' },
-          { internalType: 'address', name: 'customGateway', type: 'address' },
-          { internalType: 'address', name: 'wethGateway', type: 'address' },
-          { internalType: 'address', name: 'weth', type: 'address' },
-        ],
-        indexed: false,
-        internalType: 'struct L1DeploymentAddresses',
-        name: 'l1',
-        type: 'tuple',
-      },
       {
         components: [
           { internalType: 'address', name: 'router', type: 'address' },
@@ -199,15 +218,29 @@ const tokenBridgeCreatorABI = [
   },
 ] as const;
 
+/**
+ * Token bridge creator configuration and ABI.
+ * @property {Object} tokenBridgeCreatorConfig - The configuration object for the token bridge creator.
+ * @property {Array} abi - The ABI for the token bridge creator contract.
+ */
 export const tokenBridgeCreator = {
   ...tokenBridgeCreatorConfig,
   abi: tokenBridgeCreatorABI,
 } as const;
 
+/**
+ * Sequencer inbox contract configuration.
+ * @property {Array} abi - The ABI of the sequencer inbox contract.
+ */
 export const sequencerInbox = {
   abi: sequencerInboxABI,
 };
 
+/**
+ * Rollup Admin Logic contract configuration.
+ * @property {Array} abi - The ABI of the Rollup Admin Logic contract.
+ */
 export const rollupAdminLogic = {
   abi: rollupAdminLogicABI,
 };
+