base-org/op-viem

Viem extensions for the Op Stack

op-viem's Issues

Prove Withdrawal

Need

Types.WithdrawalTransaction memory _tx,
uint256 _l2OutputIndex,
Types.OutputRootProof calldata _outputRootProof,
bytes[] calldata _withdrawalProof

current SDK has

const withdrawal = await this.toLowLevelMessage(resolved, messageIndex)
const proof = await this.getBedrockMessageProof(resolved, messageIndex)

const args = [
  [
    withdrawal.messageNonce,
    withdrawal.sender,
    withdrawal.target,
    withdrawal.value,
    withdrawal.minGasLimit,
    withdrawal.message,
  ],
  proof.l2OutputIndex,
  [
    proof.outputRootProof.version,
    proof.outputRootProof.stateRoot,
    proof.outputRootProof.messagePasserStorageRoot,
    proof.outputRootProof.latestBlockhash,
  ],
  proof.withdrawalProof,
  opts?.overrides || {},
] as const

return this.contracts.l1.OptimismPortal.populateTransaction.proveWithdrawalTransaction(
  ...args
)

getBedrockMessageProof has

const resolved = await this.toCrossChainMessage(message, messageIndex)
if (resolved.direction === MessageDirection.L1_TO_L2) {
  throw new Error(`can only generate proofs for L2 to L1 messages`)
}

const output = await this.getMessageBedrockOutput(resolved, messageIndex)
if (output === null) {
  throw new Error(`state root for message not yet published`)
}

const withdrawal = await this.toLowLevelMessage(resolved, messageIndex)
const hash = hashLowLevelMessage(withdrawal)
const messageSlot = hashMessageHash(hash)

const stateTrieProof = await makeStateTrieProof(
  this.l2Provider as ethers.providers.JsonRpcProvider,
  output.l2BlockNumber,
  this.contracts.l2.BedrockMessagePasser.address,
  messageSlot
)

const block = await (
  this.l2Provider as ethers.providers.JsonRpcProvider
).send('eth_getBlockByNumber', [
  toRpcHexString(output.l2BlockNumber),
  false,
])

return {
  outputRootProof: {
    version: ethers.constants.HashZero,
    stateRoot: block.stateRoot,
    messagePasserStorageRoot: stateTrieProof.storageRoot,
    latestBlockhash: block.hash,
  },
  withdrawalProof: stateTrieProof.storageProof,
  l2OutputIndex: output.l2OutputIndex,
}

Promote OP viem and make it more discoverable

Now that OP viem is stabileish we should start driving more users to it

Tasks

• Fork OP viem to OP repo
• Add documentation to the sdk calling out op-viem as the preferred option
• Checkin with docs team to see if there is anywhere else we can link to (this might require syncing between OP and base docs teams)
• Promote it on OP radio?
• Promote it with a dev blog post?
• Promote it with a tweet?

Missing event type actions

There is no action for getting deposits by address or getting withdrawals by address. These are utils that most folks should be using an indexer for but it's a good idea to offer an RPC only way of doing it too.

This could be an action like the current sdk:

getDepositsByAddress({
  address: Address,
  bridgeAddress: Address
  startBlock,
  endBlock
})

Alternatively we could reexport the abis for these events and document how to use them in viem. This is likely the best option because then it can be composed with all the existing viem methods like watchEvent.

The third alternative is to wrap existing viem methods

watchDepositEvents()
watchDepositEvents({bridgeAddress})
getBridgeDepositLogs({bridgeAddress, fromAddress, toAddress})

writeContractDeposit

This would have the same API as viem's writeContract but under the hood use writeSendMessage

Missing ERC20 Functionality

Context

The following functionality is missing from the ERC20 story

Major missing functionality

• Add native l2 tokens support- Native l2 tokens require using one of the bridgeERC20 methods rather than a withdraw. Withdraw is only for mintable tokens not native tokens
• Deposit token is unsafe - It's easy to lose tokens depositing with the current method because no validation is happening to validate the token is bridgable. At a minimum we should documenting this. Note this is kinda tricky. Validating a mintable token withdrawal is simple since it's all done on l2. Validating an l1 deposit matches l2 is less simple as it requires an l2 public client. The correct solution for now is to document it until higher level multiclient aware abstractions are made
• No legacy withdrawal support - Prebedrock withdrawals on OP mainnet do not have any support. Pre bedrock withdrawals are not 1559 therefore require extra work to get working encoding and decoding.

Minor missing functionality

• Add documentation about how to reliably get the bridge and token info from a token address - To use the erc20 bridge well one should be getting the l1 and l2 token info and the bridge info from the l2 token or from the tokenlist

// example
const l2BridgeAddress = l2MintableToken.l2Bridge()
const l1TokenAddress = l2MintableToken.l1Token()

client.withdrawERC20({
  ...sameOptionsAsBefore,
  address: l2BridgeAddress,

• Add action for getting token info - It would be nice if viem had a native way of getting stuff like the bridge address and matching token too

• No preregensis support - preregenisis are before the version of optimism that was before bedrock. My suggestion is to not support this completely but simply add a single sentence to the docs about this not being supported.

Consider wallet decorators unique to L1 and. L2

The actions users take on L1 -> L2 and entirely different than L2 -> L1.

E.g. Going L1 -> L2 is a deposit and takes minutes, but going L2 -> L1 is a withdraw and takes days. Replaying messages happens on L2. etc.

For each type of action, we want to have good types on client chain, the toChain in the transaction, and their relation. E.g. we only want someone to call deposit from an L1 to a valid L2.

If every function has a generic Chain and TTochain which enforce these rules, these type enforcements bubble up to the decorator. There are really two enforcements: actions for the L2 and actions for the L1.

It may make sense to just have entirely different decorators for these wallet actions. Users have to do a little more work, but it's a more clear and safe experience walletClient(...).extend(OPStackL2Actions) or walletClient(...).extend(OPStackL1Actions)

Read functions

Some functions for making call requests to specific OP Contract methods. Still thinking if worth it, but time of mind

• minimumGasLimit
• isOutputFinalized
• finalizedWithdrawals
• provenWithdrawals

Alias functions

We should have utils for computing the L2 alias of an L1 contract callers to the portal https://github.com/ethereum-optimism/optimism/blob/d8501a7fc58ce8887e22f83abcf7f0ebecfb1a89/packages/core-utils/src/optimism/alias.ts#L21-L39

https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal.sol#L407

writeInitiateWithdrawal

https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL1MessagePasser.sol#L74

Rename writeactionBase to be l1 specific and make L2 version

publicClient: getSecondsToFinalizable

Thinking it might be nice to have a function that tells you how long until a withdraw can be finalized. Can use L2_ORACLE.getL2Output(_l2OutputIndex).timestamp and L2_ORACLE.FINALIZATION_PERIOD_SECONDS()

walletL2OpStackActions decorator

Need a decorator for the L2 actions

High Level Tracking

Wallet Client

Deposit Flows

• depositERC20
• depositETH
• ? bulkDeposit

Withdrawal Flows

• initiateWithdrawal
• finalizeWithdrawal

Portal

• [] unsafeDepositTx

Replay

• [] replayTx(originalTxReciept)

Public Client

• [] getL2HashForDepositTx

write + simulate proveWithdrawalTransaction

API cleanup

• consider changing writeFinalize... to have args and withdrawal within to match the API of the other functions https://github.com/base-org/op-viem/blob/main/src/actions/wallet/L1/writeFinalizeWithdrawalTransaction.ts#L19
• depositETH args doesn't include amount or value, you just pass value. But withdraw does take an amount arg. This matches the smart contracts, but is kind of weird. We should consider picking one. Passing amount is probably more clear.

Document code coverage

We should have a github workflow that checks this

Migrate to viem 2 (alpha)

• for compatibility with wagmi v2 / op-wagmi

Add documentation for remaining utils

src/utils/getArgsFromTransactionDepositedOpaqueData.ts
src/utils/transactionSerializer.ts
src/actions/public/getProof.ts

simulateDepositERC20

Typo GetL2HashesForDepositTxParamters

Noticed a typo GetL2HashesForDepositTxParamters is missing an e

Add error types

Viem recently added error types. The op-viem error types should be the op-viem errors for a given action combined with the error type of any viem method it's using under the hood.

See: https://viem.sh/docs/error-handling.html

Update writeDepositETH to use writeDepositTransaction

We realized transferring ETH through the portal is safe and is by far the most efficient path. Need to update

• writeDepositETH
• simulateDepositETH
• docs

Add documentation for gas estimation actions

Deposit transactions need padding

We need to estimate gas and add additional padding because without it the algorithm wallets use to estimate gas will often result in a failed tx.

The optimism sdk does this here: https://github.com/ethereum-optimism/optimism/blob/develop/packages/sdk/src/cross-chain-messenger.ts#L2028

Add a stackblitz using op-viem

Add a sharable example of using op-viem to mint an nft on l2 from l1

writeContractDepositUnsafe

Use the portal to allow for msg.sender = msg.sender on L2, with exception of sending from contracts.

Set up Releases

Releases

Validate indexer is updated

Before releasing to GA make sure @roninjin10 has updated the indexer API to work correctly with portal eth deposits

Consider removing `value` from args for writeDepositTransaction and add `args.mint`

Consider adding mint here https://github.com/base-org/op-viem/blob/b9f1b8ba7c969ad281ec9952a4940aa161125f38/src/actions/wallet/L1/writeDepositTransaction.ts#L11C5-L17

as what is paid to this transaction will be minted to the user on L2. This would replace viem's normal value args, and we would set value = args.mint

L2 Public Client: estimateRelayMessageGas

OK so actually there's probably a subtask here that is estimateRelayMessageGas which would proxy to estimate gas from viem but set the caller to 0x0000000000000000000000000000000000000001, which is an address that will cause the function to revert if it is not relayed correctly.

from #55

Add typed return to getDepositEventsInfoFromTxReceipt

simulateDepositTransaction

Useful links and discussion about l2 configs

Just putting useful links here so they can easily be found later:
Here is what arbitrums config looks like: https://github.com/OffchainLabs/arbitrum-sdk/blob/29290590d5955d8bffa2d2bb80a64e98601077e8/src/lib/dataEntities/networks.ts#L156
Here is what the old OP sdk config looks like: contracts and rest of the config
Here is what a more complete superchain config looks like in the official repo: https://github.com/ethereum-optimism/superchain-registry/tree/main/superchain/configs/goerli

Op is working on having this l2 chain config be retrievable via an RPC call and a contract call

Missing non happy path message statuses

Op viem has ways of determining if a cross chain message is ready to prove, finalized etc. It does not have a way of determining if a message has not succeeded

Below is a list of the message statuses available. Note: failed l2 to l1 is missing from this list because the op sdk currently treats that as a ready to prove status since if using the sdk you can always try again.

Site

Let's get vitepress working so that we can have a site for docs.

simulateDepositETH

docs for getSecondsToFinalizable

DepositTransaction is not relaying correctly

Repro steps

1. Clone https://github.com/roninjin10/minimal-repo
2. Add private key to .env
3. run bun run index.ts to run the script

You will see the eth deposit work as expected but the l2 tx for the depositTx never get relayed

Additional steps
4. Try to direcly do a depositTransaction

Same you will see the eth deposit work as expected but the l2 tx for depositTx never get relayed

simulateOpStackL2

Use superchain registry as source of truth for superchain compatible op chains

Now that @Sabnock01 has unblocked publishing superchain registry to npm we should use this repo as the source of truth for things such as contract addresses and other chain config information. We can add a light build step to the superchain registry if it would help make this easier

writeReplayMesssage

This would be an L2 action. I think that this should take a transaction hash and a gas limit, we would

1. (optionally) verify that the transaction had a FailedRelayedMessage event emitted
2. fetch the calldata of the transaction
3. call relayMessage on the L2 cross domain messenger with the calldata from the first, (maybe new min gas limit?

See notes on this and gas limit here https://community.optimism.io/docs/protocol/deposit-flow/#replays-in-action

write + simulate finalizeWithdrawalTransaction

throw error in seconds to next l2 output if passed l2 block is < latestBlock according to L1 oracle

readFinalizedWithdrawals

like readProvenWithdrawals

Format hook

we should have pnpm format as a commit hook or github workflow