Merge pull request #154 from base-org/update-docs

Add JSDocs to actions missing them

src/actions/public/L1/getLatestProposedL2BlockNumber.ts

@@ -12,6 +12,12 @@ export type GetLatestProposedL2BlockNumberReturnType = {
   l2BlockNumber: bigint
 }
 
+/**
+ * Gets the latest proposed L2 block number from the L2 Output Oracle.
+ *
+ * @param {RawOrContractAddress} l2OutputOracle the address of the L2 Output Oracle
+ * @returns {GetLatestProposedL2BlockNumberReturnType} the latest proposed L2 block number
+ */
 export async function getLatestProposedL2BlockNumber<TChain extends Chain | undefined>(
   client: PublicClient<Transport, TChain>,
   {

src/actions/public/L1/getSecondsToFinalizable.ts

@@ -16,6 +16,15 @@ export type GetSecondsToFinalizableParameters<
   l2OutputOracle: RawOrContractAddress<_chainId>
 }
 
+/**
+ * Gets the number of seconds until a withdrawal is finalizable.
+ *
+ * @param {Hash} withdrawalHash the hash of the withdrawal
+ * @param {RawOrContractAddress} portal the address of the portal
+ * @param {RawOrContractAddress} l2OutputOracle the address of the L2 Output Oracle
+ *
+ * @returns {Promise<bigint>} the number of seconds until the withdrawal is finalizable
+ */
 export async function getSecondsToFinalizable<TChain extends Chain | undefined>(
   client: PublicClient<Transport, TChain>,
   {

src/actions/public/L1/getSecondsToNextL2Output.ts

@@ -10,6 +10,14 @@ export type GetSecondsToNextL2OutputParameters<
   _chainId = TChain extends Chain ? TChain['id'] : number,
 > = { latestL2BlockNumber: bigint; l2OutputOracle: RawOrContractAddress<_chainId> }
 
+/**
+ * Gets the number of seconds until the next L2 output is posted.
+ *
+ * @param {bigint} latestL2BlockNumber the latest L2 block number
+ * @param {RawOrContractAddress} l2OutputOracle the address of the L2 Output Oracle
+ *
+ * @returns {Promise<bigint>} the number of seconds until the next L2 output is posted
+ */
 export async function getSecondsToNextL2Output<TChain extends Chain | undefined>(
   client: PublicClient<Transport, TChain>,
   {

src/actions/public/L1/readFinalizedWithdrawals.ts

@@ -12,6 +12,14 @@ export type ReadFinalizedWithdrawalsParameters<
   _chainId = TChain extends Chain ? TChain['id'] : number,
 > = { withdrawalHash: MessagePassedEvent['withdrawalHash']; portal: RawOrContractAddress<_chainId> }
 
+/**
+ * Reads whether a withdrawal has been finalized from the Optimism Portal.
+ *
+ * @param {Hash} withdrawalHash the hash of the withdrawal
+ * @param {RawOrContractAddress} portal the address of the portal
+ *
+ * @returns {Promise<boolean>} whether the withdrawal is finalized
+ */
 export async function readFinalizedWithdrawals<TChain extends Chain | undefined>(
   client: PublicClient<Transport, TChain>,
   {

src/actions/public/L1/readProvenWithdrawals.ts

@@ -21,6 +21,14 @@ export type ProvenWithdrawal = {
 export type ReadProvenWithdrawalsReturnType = ProvenWithdrawal
 
 // Convention: use `read` if this is just 1:1 with some contract function
+/**
+ * Reads a proven withdrawal from the Optimism Portal.
+ *
+ * @param {Hash} withdrawalHash the hash of the withdrawal
+ * @param {RawOrContractAddress} portal the address of the portal
+ *
+ * @returns {Promise<ProvenWithdrawal>} the proven withdrawal
+ */
 export async function readProvenWithdrawals<TChain extends Chain | undefined>(
   client: PublicClient<Transport, TChain>,
   {

src/actions/public/L2/simulateWithdrawERC20.ts

@@ -16,6 +16,15 @@ export type SimulateWithdrawERC20ReturnType<
   TChainOverride extends Chain | undefined = undefined,
 > = SimulateContractReturnType<typeof ABI, typeof FUNCTION, TChain, TChainOverride>
 
+/**
+ * Simulates a withdrawal of ERC20 tokens to an L1 address.
+ *
+ * @param {Address} l2Token the address of the ERC20 token on L2
+ * @param {Address} to the address to withdraw to on L1
+ * @param {Bigint} amount the amount of tokens to withdraw
+ * @param {Bigint} minGasLimit the minimum gas limit for the withdrawal
+ * @param {Hex} [extraData] the extra data for the withdrawal
+ */
 export async function simulateWithdrawERC20<
   TChain extends Chain | undefined = Chain,
   TChainOverride extends Chain | undefined = Chain | undefined,

src/actions/public/L2/simulateWithdrawETH.ts

@@ -19,6 +19,14 @@ export type SimulateWithdrawETHReturnType<
   TChainOverride extends Chain | undefined = undefined,
 > = SimulateWithdrawERC20ReturnType<TChain, TChainOverride>
 
+/**
+ * Simulates a withdrawal of ETH to an L1 address.
+ *
+ * @param {Address} to the address to withdraw to on L1
+ * @param {Bigint} amount the amount of ETH to withdraw
+ * @param {Bigint} minGasLimit the minimum gas limit for the withdrawal
+ * @param {Hex} [extraData] the extra data for the withdrawal
+ */
 export async function simulateWithdrawETH<
   TChain extends Chain | undefined = Chain,
   TChainOverride extends Chain | undefined = Chain | undefined,

src/actions/wallet/L2/writeWithdrawERC20.ts

@@ -12,6 +12,17 @@ export type WriteWithdrawERC20Parameters<
   & { args: WithdrawToParameters }
   & L2WriteContractParameters<typeof ABI, typeof FUNCTION, TChain, TAccount, TChainOverride>
 
+/**
+ * Withdraws ERC20 tokens to an L1 address.
+ *
+ * @param {Address} l2Token the address of the ERC20 token on L2
+ * @param {Address} to the address to withdraw to on L1
+ * @param {Bigint} amount the amount of tokens to withdraw
+ * @param {Bigint} minGasLimit the minimum gas limit for the withdrawal
+ * @param {Hex} [extraData] the extra data for the withdrawal
+ *
+ * @returns {Promise<Hash>} the hash of the transaction
+ */
 export async function writeWithdrawERC20<
   TChain extends Chain | undefined = Chain,
   TAccount extends Account | undefined = Account | undefined,

src/actions/wallet/L2/writeWithdrawETH.ts

@@ -11,6 +11,16 @@ export type WriteWithdrawETHParameters<
   & { args: WithdrawETHParameters }
   & L2WriteContractParameters<typeof ABI, typeof FUNCTION, TChain, TAccount, TChainOverride>
 
+/**
+ * Withdraws ETH to an L1 address.
+ *
+ * @param {Address} to the address to withdraw to on L1
+ * @param {Bigint} amount the amount of ETH to withdraw
+ * @param {Bigint} minGasLimit the minimum gas limit for the withdrawal
+ * @param {Hex} [extraData] the extra data for the withdrawal
+ *
+ * @returns {Promise<Hash>} the hash of the transaction
+ */
 export async function writeWithdrawETH<
   TChain extends Chain | undefined = Chain,
   TAccount extends Account | undefined = Account | undefined,