diff --git a/specs/interop/contracts.md b/specs/interop/contracts.md new file mode 100644 index 000000000..f65aa9b50 --- /dev/null +++ b/specs/interop/contracts.md @@ -0,0 +1,257 @@ +## Network Upgrade Transactions + +Could use some advice on how accurate this deployment plan is. I think it is *not* + +The interop network upgrade timestamp defines the timestamp at which all functionality in this document is considered +the consensus rules for an OP Stack based network. + +The upgrade transaction details below are based on a nightly release at commit +hash `71c460ec7c7c05791ddd841b97bcb664a1f0c753`, and will be updated once a +contracts release is made. + +On the [activation block](#activation-block), a set of deposit transaction +based upgrade transactions are deterministically generated by the derivation pipeline in the following order: + + + +### L2ToL2CrossDomainMessenger Deployment + + + +The `L2ToL2CrossDomainMessenger` contract is deployed. + +A deposit transaction is derived with the following attributes: + +- `from`: `0x4220000000000000000000000000000000000001` +- `to`: `null` +- `mint`: `0` +- `value`: `0` +- `nonce`: `0` +- `gasLimit`: `1100000` +- `data`: `0x6080604052348015600e575f80fd5b...` ([full bytecode](../static/bytecode/interop-l2-to-l2-cross-domain-messenger-deployment.txt)) +- `sourceHash`: `0xf5484697c7a9a791db32a3bf0763bf2ba686c77ae7d4c0a5ee8c222a92a8dcc2`, + computed with the "Upgrade-deposited" type, with `intent = "Interop: L2ToL2CrossDomainMessenger Deployment"` + +This results in the Interop L2ToL2CrossDomainMessenger contract being deployed to +`0x0D0eDd0ebd0e94d218670a8De867Eb5C4d37cadD`, to verify: + +```bash +cast compute-address --nonce=0 0x4220000000000000000000000000000000000001 +Computed Address: 0x0D0eDd0ebd0e94d218670a8De867Eb5C4d37cadD +``` + +Verify `sourceHash`: + +```bash +cast keccak $(cast concat-hex 0x0000000000000000000000000000000000000000000000000000000000000002 $(cast keccak "Interop: L2ToL2CrossDomainMessenger Deployment")) +# 0xf5484697c7a9a791db32a3bf0763bf2ba686c77ae7d4c0a5ee8c222a92a8dcc2 +``` + +Verify `data`: + +```bash +git checkout 71c460ec7c7c05791ddd841b97bcb664a1f0c753 +make build-contracts +jq -r ".bytecode.object" packages/contracts-bedrock/forge-artifacts/L2ToL2CrossDomainMessenger.sol/L2ToL2CrossDomainMessenger.json +``` + +This transaction MUST deploy a contract with the following code hash +`0x458925c90ec70736600bef3d6529643a0e7a0a848e62626d61314c057b4a71a9`. + +To verify the code hash: + +```bash +git checkout 71c460ec7c7c05791ddd841b97bcb664a1f0c753 +make build-contracts +cast k $(jq -r ".deployedBytecode.object" packages/contracts-bedrock/forge-artifacts/L2ToL2CrossDomainMessenger.sol/L2ToL2CrossDomainMessenger.json) +``` + +### L2ToL2CrossDomainMessenger Proxy Update + +This transaction updates the L2ToL2CrossDomainMessenger Proxy ERC-1967 +implementation slot to point to the new L2ToL2CrossDomainMessenger deployment. + +A deposit transaction is derived with the following attributes: + +- `from`: `0x0000000000000000000000000000000000000000` +- `to`: `0x4200000000000000000000000000000000000023` (L2ToL2CrossDomainMessenger Proxy) +- `mint`: `0` +- `value`: `0` +- `gasLimit`: `50,000` +- `data`: `0x3659cfe60000000000000000000000000d0edd0ebd0e94d218670a8de867eb5c4d37cadd` +- `sourceHash`: `0xe54b4d06bbcc857f41ae00e89d820339ac5ce0034aac722c817b2873e03a7e68` + computed with the "Upgrade-deposited" type, with `intent = "Interop: L2ToL2CrossDomainMessenger Proxy Update"` + +Verify data: + +```bash +cast concat-hex $(cast sig "upgradeTo(address)") $(cast abi-encode "upgradeTo(address)" 0x0D0eDd0ebd0e94d218670a8De867Eb5C4d37cadD) +# 0x3659cfe60000000000000000000000000d0edd0ebd0e94d218670a8de867eb5c4d37cadd +``` + +Verify `sourceHash`: + +```bash +cast keccak $(cast concat-hex 0x0000000000000000000000000000000000000000000000000000000000000002 $(cast keccak "Interop: L2ToL2CrossDomainMessenger Proxy Update")) +# 0xe54b4d06bbcc857f41ae00e89d820339ac5ce0034aac722c817b2873e03a7e68 +``` + +### L2 Gas Limit Requirements + +This upgrade requires `3_270_000` in gas, plus `50_000` gas if the CrossL2Inbox proxy is initialized in the same block. +In order to upgrade successfully the following invariant MUST be maintained: + +```plaintext +MaxResourceLimit + SystemTxMaxGas + UpgradeGasUsage ≤ L2GasLimit +``` + +With MaxResourceLimit set to `20_000_000` and SystemTxMaxGas set to `1_000_000`, +this mean every upgrading chain MUST have their L2GasLimit set to greater than +`24_320_000`. + +## CrossL2InboxProxy Initialization + +On the first block at or after the interop [activation block](#activation-block), where the current chain is in a +dependency set with two or more active chains, a deposit transaction based upgrade transaction is deterministically +generated by the derivation pipeline: + +### CrossL2Inbox Deployment + + + +The `CrossL2Inbox` contract is deployed. + +A deposit transaction is derived with the following attributes: + +- `from`: `0x4220000000000000000000000000000000000000` +- `to`: `null` +- `mint`: `0` +- `value`: `0` +- `nonce`: `0` +- `gasLimit`: `420000` +- `data`: `0x6080604052348015600e575f80fd5b...` ([full bytecode](../static/bytecode/interop-cross-l2-inbox-deployment.txt)) +- `sourceHash`: `0x6e5e214f73143df8fe6f6054a3ed7eb472d373376458a9c8aecdf23475beb616`, + computed with the "Upgrade-deposited" type, with `intent = "Interop: CrossL2Inbox Deployment"` + +This results in the Interop CrossL2Inbox contract being deployed to +`0x691300f512e48B463C2617b34Eef1A9f82EE7dBf`, to verify: + +```bash +cast compute-address --nonce=0 0x4220000000000000000000000000000000000000 +Computed Address: 0x691300f512e48B463C2617b34Eef1A9f82EE7dBf +``` + +Verify `sourceHash`: + +```bash +cast keccak $(cast concat-hex 0x0000000000000000000000000000000000000000000000000000000000000002 $(cast keccak "Interop: CrossL2Inbox Deployment")) +# 0x6e5e214f73143df8fe6f6054a3ed7eb472d373376458a9c8aecdf23475beb616 +``` + +Verify `data`: + +```bash +git checkout 71c460ec7c7c05791ddd841b97bcb664a1f0c753 +make build-contracts +jq -r ".bytecode.object" packages/contracts-bedrock/forge-artifacts/CrossL2Inbox.sol/CrossL2Inbox.json +``` + +This transaction MUST deploy a contract with the following code hash +`0x0e7d028dd71bac22d1fb28966043c8d35c3232c78b7fb99fd1db112b5b60d9dd`. + +To verify the code hash: + +```bash +git checkout 71c460ec7c7c05791ddd841b97bcb664a1f0c753 +make build-contracts +cast k $(jq -r ".deployedBytecode.object" packages/contracts-bedrock/forge-artifacts/CrossL2Inbox.sol/CrossL2Inbox.json) +``` + +### CrossL2Inbox Proxy Update + +This transaction updates the CrossL2Inbox Proxy ERC-1967 +implementation slot to point to the CrossL2Inbox deployment deployed at the interop activation block. + +A deposit transaction is derived with the following attributes: + +- `from`: `0x0000000000000000000000000000000000000000` +- `to`: `0x4200000000000000000000000000000000000022` (CrossL2Inbox Proxy) +- `mint`: `0` +- `value`: `0` +- `gasLimit`: `50,000` +- `data`: `0x3659cfe6000000000000000000000000691300f512e48b463c2617b34eef1a9f82ee7dbf` +- `sourceHash`: `0x88c6b48354c367125a59792a93a7b60ad7cd66e516157dbba16558c68a46d3cb` + computed with the "Upgrade-deposited" type, with `intent = "Interop: CrossL2Inbox Proxy Update"` + +Verify data: + +```bash +cast concat-hex $(cast sig "upgradeTo(address)") $(cast abi-encode "upgradeTo(address)" 0x691300f512e48B463C2617b34Eef1A9f82EE7dBf) +# 0x3659cfe6000000000000000000000000691300f512e48b463c2617b34eef1a9f82ee7dbf +``` + +Verify `sourceHash`: + +```bash +cast keccak $(cast concat-hex 0x0000000000000000000000000000000000000000000000000000000000000002 $(cast keccak "Interop: CrossL2Inbox Proxy Update")) +# 0x88c6b48354c367125a59792a93a7b60ad7cd66e516157dbba16558c68a46d3cb +``` + +### L2 Gas Limit Requirements + +Deploying and initializing the CrossL2InboxProxy requires `470_000` in gas. This fits within the standard SystemTxMaxGas +of `1_000_000` even allowing for the gas used by the +[L1 attributes deposited transaction](../glossary.md#l1-attributes-deposited-transaction). + +## Expiry Window + +The expiry window is the time period after which an initiating message is no longer considered valid. + +| Constant | Value | +| --------------- | ---------------------- | +| `EXPIRY_WINDOW` | `604800 secs` (7 days) | + +## Security Considerations + +### Depositing an Executing Message + +Deposit transactions (force inclusion transactions) give censorship resistance to layer two networks. +If it were possible to deposit an invalid executing message, this would force the sequencer to reorg. It would +be fairly cheap to continuously deposit invalid executing messages through L1 and cause L2 liveness +instability, therefore deposits are prevented from triggering executing messages. +A future upgrade may enable deposits to trigger executing messages. + +### Expiry Window + +The expiry window ensures that the proof can execute in a reasonable amount of time. [`EIP-2935`][eip-2935] introduced +the capability to traverse history with sub-linear complexity, however deep lookups remain expensive. App developers and +users, in the event that they encounter a message that has expired but has yet to be relayed, can +[resend the message][resend-msg] in order to complete the process. + +### Reliance on History + +When fully executing historical blocks, a dependency on historical receipts from remote chains is present. +[EIP-4444][eip-4444] will eventually provide a solution for making historical receipts available without +needing to execute increasingly long chain histories. + +[eip-2935]: https://eips.ethereum.org/EIPS/eip-2935 +[eip-4444]: https://eips.ethereum.org/EIPS/eip-4444 +[resend-msg]: https://github.com/ethereum-optimism/design-docs/blob/25ef5537e39b63cddf1c83479cee9f0e02431dce/protocol/resend-messages.md#L4 \ No newline at end of file diff --git a/specs/interop/dependency-set.md b/specs/interop/dependency-set.md index fb6396b66..f10fb8372 100644 --- a/specs/interop/dependency-set.md +++ b/specs/interop/dependency-set.md @@ -23,11 +23,10 @@ social consensus MUST be used to determine the chain that represents the canonic particularly impacts the block builder as they SHOULD use the chain id to assist in validation of executing messages. -The dependency set is configured on a per cluster basis. All chains that are in the dependency set -can accept initiating messages from any other chain in the dependency set, resulting in a mesh. +Chains implicitly belong to their own Dependency Set. -The chain id of the local chain MUST be considered as part of its own dependency set. This allows a chain -to consume logs that it has produced much more cheaply than providing a block hash proof. +Chains define their own dependency sets, but by convention chains are intended to +depend on one another in interop. ## Chain ID @@ -47,13 +46,6 @@ It is a known issue that not all software in the Ethereum ecosystem can handle 3 The dependency set is managed in the client software. Adding a chain to the dependency set is considered an upgrade to the network. It is not possible to remove chains from the dependency set. -## Future Considerations - -### Layer 1 as Part of the Dependency Set - -The layer one MAY be part of the dependency set in the future. This means that any event -created on layer one is consumable on layer two. - ## Security Considerations ### Dependency Set Size diff --git a/specs/interop/derivation.md b/specs/interop/derivation.md index 0c4204c73..53a8dbc42 100644 --- a/specs/interop/derivation.md +++ b/specs/interop/derivation.md @@ -49,324 +49,43 @@ because it includes invalid executing messages MUST be replaced by a deposits on block height. This guarantees progression of the chain, ensuring that an infinite loop of processing the same block in the proof system is not possible. -## Activation Block +## New Protocol Rules -The activation block is the first block that has a timestamp higher or equal to the -interop network upgrade timestamp. -The activation block timestamp may not exactly match the upgrade timestamp. +For Chains featuring interop, an L2 contract called the "<>" is available. +A transaction which invokes the contract emits an Executing Message, which make reference to Log Events which have +occured on any chain in the Dependency Set. -The genesis block is not technically considered an activation-block, as forks are already active. -However, the genesis block does not contain transactions, and thus also meets the activation criteria. +For any L2 block which contains these Executing Messages, the block's validity is conditional on the correctness of the Executing Messages it contains. -The activation block has several special properties and constraints: +Put another way: blocks which contain invalid Executing Messages are, by definition, invalid. -- It MUST NOT include any non-deposit-type transactions. - Sequencers, when building the fork activation block, MUST set `noTxPool` to `true` - in the execution payload attributes for this block, instructing the builder to exclude user transactions. -- Messages MUST NOT be executed in this block. This is implemented by only processing deposit-type transactions. -- Any contract log events MUST NOT count as valid initiating messages. - Verifiers may use the activation block as an anchor point, without indexing the block-contents. -- The derivation pipeline MUST enforce that the sequencer has not included any user transactions in - the batch covering the upgrade's activation block. If the sequencer includes any user transactions - within the activation block, this block and the remaining span batch it originated from - (if part of a span batch) MUST be dropped, - following the batch-dropping rules introduced in the - [Holocene upgrade span-batch rules](../protocol/holocene/derivation.md#span-batches). +### Safety Application -## Replacing Invalid Blocks - -When the [cross chain dependency resolution](./messaging.md#resolving-cross-chain-safety) determines -that a block contains an [invalid message](./messaging.md#invalid-messages), the block is replaced -by a block with the same inputs, except for the transactions included. The transactions from the -original block are trimmed to include only deposit transactions plus an -[optimistic block info deposit transaction](#optimistic-block-deposited-transaction), which is appended -to the trimmed transaction list. - -### Optimistic Block Deposited Transaction - -An Optimistic Block Deposited Transaction is a system deposited transaction, -inserted into the replacement block, -to signal when a previously derived local-safe block (the "optimistic" block) was invalidated. - -This transaction MUST have the following values: - -1. `from` is `0xdeaddeaddeaddeaddeaddeaddeaddeaddead0002`, like the address of the - [L1 Attributes depositor account](../protocol/deposits.md#l1-attributes-depositor-account), but incremented by 1 -2. `to` is `0x0000000000000000000000000000000000000000` (the zero address as no EVM code execution is expected). -3. `mint` is `0` -4. `value` is `0` -5. `gasLimit` is set `36000` gas, to cover intrinsic costs, processing costs, and margin for change. -6. `isSystemTx` is set to `false`. -7. `data` is the preimage of the [L2 output root] - of the replaced block. i.e. `version_byte || payload` without applying the `keccak256` hashing. -8. `sourceHash` is computed with a new deposit source-hash domain, see below. - -This system-initiated transaction for L1 attributes is not charged any ETH for its allocated -`gasLimit`, as it is considered part of state-transition processing. - -[L2 output root]: ../glossary.md#l2-output-root-proposals - -#### Optimistic Block Source-hash - -The source hash is [computed](../protocol/deposits.md#source-hash-computation) -with a source-hash domain: `4` (instead of `1`), -combined with the [L2 output root] of the optimistic block that was invalidated. - -The source-hash is thus computed as: -`keccak256(bytes32(uint256(4)), outputRoot))`. - -## Network Upgrade Transactions - -The interop network upgrade timestamp defines the timestamp at which all functionality in this document is considered -the consensus rules for an OP Stack based network. - -The upgrade transaction details below are based on a nightly release at commit -hash `71c460ec7c7c05791ddd841b97bcb664a1f0c753`, and will be updated once a -contracts release is made. - -On the [activation block](#activation-block), a set of deposit transaction -based upgrade transactions are deterministically generated by the derivation pipeline in the following order: - - - -### L2ToL2CrossDomainMessenger Deployment - - - -The `L2ToL2CrossDomainMessenger` contract is deployed. - -A deposit transaction is derived with the following attributes: - -- `from`: `0x4220000000000000000000000000000000000001` -- `to`: `null` -- `mint`: `0` -- `value`: `0` -- `nonce`: `0` -- `gasLimit`: `1100000` -- `data`: `0x6080604052348015600e575f80fd5b...` ([full bytecode](../static/bytecode/interop-l2-to-l2-cross-domain-messenger-deployment.txt)) -- `sourceHash`: `0xf5484697c7a9a791db32a3bf0763bf2ba686c77ae7d4c0a5ee8c222a92a8dcc2`, - computed with the "Upgrade-deposited" type, with `intent = "Interop: L2ToL2CrossDomainMessenger Deployment"` - -This results in the Interop L2ToL2CrossDomainMessenger contract being deployed to -`0x0D0eDd0ebd0e94d218670a8De867Eb5C4d37cadD`, to verify: - -```bash -cast compute-address --nonce=0 0x4220000000000000000000000000000000000001 -Computed Address: 0x0D0eDd0ebd0e94d218670a8De867Eb5C4d37cadD -``` - -Verify `sourceHash`: - -```bash -cast keccak $(cast concat-hex 0x0000000000000000000000000000000000000000000000000000000000000002 $(cast keccak "Interop: L2ToL2CrossDomainMessenger Deployment")) -# 0xf5484697c7a9a791db32a3bf0763bf2ba686c77ae7d4c0a5ee8c222a92a8dcc2 -``` - -Verify `data`: - -```bash -git checkout 71c460ec7c7c05791ddd841b97bcb664a1f0c753 -make build-contracts -jq -r ".bytecode.object" packages/contracts-bedrock/forge-artifacts/L2ToL2CrossDomainMessenger.sol/L2ToL2CrossDomainMessenger.json -``` - -This transaction MUST deploy a contract with the following code hash -`0x458925c90ec70736600bef3d6529643a0e7a0a848e62626d61314c057b4a71a9`. - -To verify the code hash: - -```bash -git checkout 71c460ec7c7c05791ddd841b97bcb664a1f0c753 -make build-contracts -cast k $(jq -r ".deployedBytecode.object" packages/contracts-bedrock/forge-artifacts/L2ToL2CrossDomainMessenger.sol/L2ToL2CrossDomainMessenger.json) -``` - -### L2ToL2CrossDomainMessenger Proxy Update - -This transaction updates the L2ToL2CrossDomainMessenger Proxy ERC-1967 -implementation slot to point to the new L2ToL2CrossDomainMessenger deployment. - -A deposit transaction is derived with the following attributes: - -- `from`: `0x0000000000000000000000000000000000000000` -- `to`: `0x4200000000000000000000000000000000000023` (L2ToL2CrossDomainMessenger Proxy) -- `mint`: `0` -- `value`: `0` -- `gasLimit`: `50,000` -- `data`: `0x3659cfe60000000000000000000000000d0edd0ebd0e94d218670a8de867eb5c4d37cadd` -- `sourceHash`: `0xe54b4d06bbcc857f41ae00e89d820339ac5ce0034aac722c817b2873e03a7e68` - computed with the "Upgrade-deposited" type, with `intent = "Interop: L2ToL2CrossDomainMessenger Proxy Update"` - -Verify data: - -```bash -cast concat-hex $(cast sig "upgradeTo(address)") $(cast abi-encode "upgradeTo(address)" 0x0D0eDd0ebd0e94d218670a8De867Eb5C4d37cadD) -# 0x3659cfe60000000000000000000000000d0edd0ebd0e94d218670a8de867eb5c4d37cadd -``` +While blocks are eventually determined to be valid or invalid by protocol rules, they may be optimistically applied as unsafe or "locally safe" blocks. -Verify `sourceHash`: +However, blocks are only considered Safe once they meet all additional rules of verification, +in this case "Cross Validation". -```bash -cast keccak $(cast concat-hex 0x0000000000000000000000000000000000000000000000000000000000000002 $(cast keccak "Interop: L2ToL2CrossDomainMessenger Proxy Update")) -# 0xe54b4d06bbcc857f41ae00e89d820339ac5ce0034aac722c817b2873e03a7e68 -``` +Likewise, blocks may not be Finalized until all L1 data used to verify it is included in Finalized L1 Blocks. -### L2 Gas Limit Requirements +## Activation Block and Timestamp -This upgrade requires `3_270_000` in gas, plus `50_000` gas if the CrossL2Inbox proxy is initialized in the same block. -In order to upgrade successfully the following invariant MUST be maintained: +Interop Activation is represented as a shared L2 timestamp, representing +the first timestamp to be scrutinized by Interop. -```plaintext -MaxResourceLimit + SystemTxMaxGas + UpgradeGasUsage ≤ L2GasLimit -``` +For chains which create a block with timestamp _equal_ to the Activation Time, that block is the first to be subject to Interop. -With MaxResourceLimit set to `20_000_000` and SystemTxMaxGas set to `1_000_000`, -this mean every upgrading chain MUST have their L2GasLimit set to greater than -`24_320_000`. +For chains which do not have a block _equal_ to the Activation Time, +their state _at_ the Activation Time is the prior block. Meaning that the +block imediately preceeding the timestamp is the first block subject to Interop. -## CrossL2InboxProxy Initialization +// I just deleted a bunch of constraints... I don't think we need them if +we have a superchain-timestamp to define the activation. +Need to know more about this. -On the first block at or after the interop [activation block](#activation-block), where the current chain is in a -dependency set with two or more active chains, a deposit transaction based upgrade transaction is deterministically -generated by the derivation pipeline: - -### CrossL2Inbox Deployment - - - -The `CrossL2Inbox` contract is deployed. - -A deposit transaction is derived with the following attributes: - -- `from`: `0x4220000000000000000000000000000000000000` -- `to`: `null` -- `mint`: `0` -- `value`: `0` -- `nonce`: `0` -- `gasLimit`: `420000` -- `data`: `0x6080604052348015600e575f80fd5b...` ([full bytecode](../static/bytecode/interop-cross-l2-inbox-deployment.txt)) -- `sourceHash`: `0x6e5e214f73143df8fe6f6054a3ed7eb472d373376458a9c8aecdf23475beb616`, - computed with the "Upgrade-deposited" type, with `intent = "Interop: CrossL2Inbox Deployment"` - -This results in the Interop CrossL2Inbox contract being deployed to -`0x691300f512e48B463C2617b34Eef1A9f82EE7dBf`, to verify: - -```bash -cast compute-address --nonce=0 0x4220000000000000000000000000000000000000 -Computed Address: 0x691300f512e48B463C2617b34Eef1A9f82EE7dBf -``` - -Verify `sourceHash`: - -```bash -cast keccak $(cast concat-hex 0x0000000000000000000000000000000000000000000000000000000000000002 $(cast keccak "Interop: CrossL2Inbox Deployment")) -# 0x6e5e214f73143df8fe6f6054a3ed7eb472d373376458a9c8aecdf23475beb616 -``` - -Verify `data`: - -```bash -git checkout 71c460ec7c7c05791ddd841b97bcb664a1f0c753 -make build-contracts -jq -r ".bytecode.object" packages/contracts-bedrock/forge-artifacts/CrossL2Inbox.sol/CrossL2Inbox.json -``` - -This transaction MUST deploy a contract with the following code hash -`0x0e7d028dd71bac22d1fb28966043c8d35c3232c78b7fb99fd1db112b5b60d9dd`. - -To verify the code hash: - -```bash -git checkout 71c460ec7c7c05791ddd841b97bcb664a1f0c753 -make build-contracts -cast k $(jq -r ".deployedBytecode.object" packages/contracts-bedrock/forge-artifacts/CrossL2Inbox.sol/CrossL2Inbox.json) -``` - -### CrossL2Inbox Proxy Update - -This transaction updates the CrossL2Inbox Proxy ERC-1967 -implementation slot to point to the CrossL2Inbox deployment deployed at the interop activation block. - -A deposit transaction is derived with the following attributes: - -- `from`: `0x0000000000000000000000000000000000000000` -- `to`: `0x4200000000000000000000000000000000000022` (CrossL2Inbox Proxy) -- `mint`: `0` -- `value`: `0` -- `gasLimit`: `50,000` -- `data`: `0x3659cfe6000000000000000000000000691300f512e48b463c2617b34eef1a9f82ee7dbf` -- `sourceHash`: `0x88c6b48354c367125a59792a93a7b60ad7cd66e516157dbba16558c68a46d3cb` - computed with the "Upgrade-deposited" type, with `intent = "Interop: CrossL2Inbox Proxy Update"` - -Verify data: - -```bash -cast concat-hex $(cast sig "upgradeTo(address)") $(cast abi-encode "upgradeTo(address)" 0x691300f512e48B463C2617b34Eef1A9f82EE7dBf) -# 0x3659cfe6000000000000000000000000691300f512e48b463c2617b34eef1a9f82ee7dbf -``` - -Verify `sourceHash`: - -```bash -cast keccak $(cast concat-hex 0x0000000000000000000000000000000000000000000000000000000000000002 $(cast keccak "Interop: CrossL2Inbox Proxy Update")) -# 0x88c6b48354c367125a59792a93a7b60ad7cd66e516157dbba16558c68a46d3cb -``` - -### L2 Gas Limit Requirements - -Deploying and initializing the CrossL2InboxProxy requires `470_000` in gas. This fits within the standard SystemTxMaxGas -of `1_000_000` even allowing for the gas used by the -[L1 attributes deposited transaction](../glossary.md#l1-attributes-deposited-transaction). - -## Expiry Window - -The expiry window is the time period after which an initiating message is no longer considered valid. - -| Constant | Value | -| --------------- | ---------------------- | -| `EXPIRY_WINDOW` | `604800 secs` (7 days) | - -## Security Considerations - -### Depositing an Executing Message - -Deposit transactions (force inclusion transactions) give censorship resistance to layer two networks. -If it were possible to deposit an invalid executing message, this would force the sequencer to reorg. It would -be fairly cheap to continuously deposit invalid executing messages through L1 and cause L2 liveness -instability, therefore deposits are prevented from triggering executing messages. -A future upgrade may enable deposits to trigger executing messages. - -### Expiry Window - -The expiry window ensures that the proof can execute in a reasonable amount of time. [`EIP-2935`][eip-2935] introduced -the capability to traverse history with sub-linear complexity, however deep lookups remain expensive. App developers and -users, in the event that they encounter a message that has expired but has yet to be relayed, can -[resend the message][resend-msg] in order to complete the process. - -### Reliance on History - -When fully executing historical blocks, a dependency on historical receipts from remote chains is present. -[EIP-4444][eip-4444] will eventually provide a solution for making historical receipts available without -needing to execute increasingly long chain histories. +## Replacing Invalid Blocks -[eip-2935]: https://eips.ethereum.org/EIPS/eip-2935 -[eip-4444]: https://eips.ethereum.org/EIPS/eip-4444 -[resend-msg]: https://github.com/ethereum-optimism/design-docs/blob/25ef5537e39b63cddf1c83479cee9f0e02431dce/protocol/resend-messages.md#L4 +When the [cross chain dependency resolution](./messaging.md#resolving-cross-chain-safety) determines +that a block contains an [invalid message](./messaging.md#invalid-messages), the block is replaced +using Holocene Replacement Rules, which is a block containing +only Deposit Transactions, replacing the original block. diff --git a/specs/interop/managed-node.md b/specs/interop/managed-node.md deleted file mode 100644 index 162fd1d54..000000000 --- a/specs/interop/managed-node.md +++ /dev/null @@ -1,323 +0,0 @@ -# Control flow between Supervisor and Managed node - - - -**Table of Contents** - -- [Authentication](#authentication) -- [Node `->` Supervisor](#node---supervisor) - - [Reset](#reset) - - [UnsafeBlock](#unsafeblock) - - [DerivationUpdate](#derivationupdate) - - [DerivationCurrentL1Update](#derivationcurrentl1update) - - [ExhaustL1](#exhaustl1) - - [ReplaceBlock](#replaceblock) -- [Supervisor `->` Node](#supervisor---node) - - [Control Signals](#control-signals) - - [interop_pullEvent](#interop_pullevent) - - [interop_anchorPoint (Soon to be deprecated)](#interop_anchorpoint-soon-to-be-deprecated) - - [interop_invalidateBlock](#interop_invalidateblock) - - [interop_provideL1](#interop_providel1) - - [interop_reset](#interop_reset) - - [DB](#db) - - [interop_updateCrossSafe](#interop_updatecrosssafe) - - [interop_updateCrossUnsafe](#interop_updatecrossunsafe) - - [interop_updateFinalized](#interop_updatefinalized) - - [Sync Methods](#sync-methods) - - [interop_fetchReceipts](#interop_fetchreceipts) - - [interop_l2BlockRefByTimestamp](#interop_l2blockrefbytimestamp) - - [interop_l2BlockRefByNumber](#interop_l2blockrefbynumber) - - [interop_chainID](#interop_chainid) - - [interop_outputV0AtTimestamp](#interop_outputv0attimestamp) - - [interop_pendingOutputV0AtTimestamp](#interop_pendingoutputv0attimestamp) -- [Types](#types) - - - -This section is based on the control flow between `managed` node and `supervisor`, described -[here](https://github.com/ethereum-optimism/optimism/blob/develop/op-supervisor/README.md). - -Whether the node and supervisor use a `pubsub` pattern or pulling events over HTTP is up to the implementation detail. -Both cases should be handled because `op-node` and `op-supervisor` can be using different client implementations. -In both the case, we use `event` based signaling of new information. Ideally, this should be done using bi-directional -RPC using web sockets. - -## Authentication - -Supervisor [initiates the connection](https://github.com/ethereum-optimism/optimism/issues/13182) to the node in order -to manage it. As supervisor does the dial in, for our context, it is the client and the node is the server. For the web -socket authentication, only the initial request is authenticated and a live socket is opened. -No re-authentication is needed during the lifetime of this socket. - -The authentication is performed using `JWT`. The construction of jwt is the same to the one -[used in Engine API](https://github.com/ethereum/execution-apis/blob/main/src/engine/authentication.md). The path of -the file containing the jwt secret should be provided to the supervisor instance. - -## Node `->` Supervisor - -Events that a supervisor should subscribe to, originating from the node, handled by the supervisor. For the used types, -refer [this](#Types) section. - -Every event sent from the node is of type `ManagedEvent` whose fields are populated with the events that occurred. All -non-null events are sent at once. The other fields are omitted. - -```javascript -ManagedEvent { - Reset, - UnsafeBlock, - DerivationUpdate, - DerivationCurrentL1Update, - ExhaustL1, - ReplaceBlock -} -``` - -Each field item is an event of the type as described below: - -### Reset - -```javascript -Reset: string -``` - -This is emitted when the node has determined that it needs a reset. It tells the supervisor to send the -[interop_reset](#interop_reset) event with the required parameters. - -### UnsafeBlock - -```javascript -UnsafeBlock: BlockRef //L2's BlockRef -``` - -New L2 unsafe block was processed, updating local-unsafe head. - -### DerivationUpdate - -```javascript -DerivationUpdate: DerivedBlockRefPair { - source: BlockRef //L1 - derived: BlockRef //Last L2 BlockRef -} -``` - -Signals that an L2 block is considered local-safe. - -### DerivationCurrentL1Update - -```javascript -DerivationCurrentL1Update: DerivedBlockRefPair { - source: BlockRef //Newly observed L1 - derived: BlockRef //L2's BlockRef -} -``` - -Signals that an L2 block is considered local-safe following the observation of a new L1 block. - -### ExhaustL1 - -```javascript -ExhaustL1: DerivedBlockRefPair { - source: BlockRef //Last L1 - derived: BlockRef //Last L2 BlockRef -} -``` - -Emitted when no more L1 Blocks are available. Ready to take new L1 blocks from supervisor. - -### ReplaceBlock - -```javascript -ReplaceBlock: BlockReplacement -``` - -Emitted when a block gets replaced for any reason. - -## Supervisor `->` Node - -Messages that a node should watch for, originating from supervisor, handled by node. This also includes control signals -that the supervisor can ask the node to perform. For the used types, refer [this](#types) section. - -*Note: Headings represent the actual name of the methods over RPC, payload is the serialized version of the given type.* - -`-> indicates return` - -### Control Signals - -RPC calls that are relevant to managing the node via supervisor. These are directly called by the supervisor. - -#### interop_pullEvent - -```javascript -payload() -> One of the event from node events (previous section). -``` - -When websocket is not available, supervisor can use this method to get the next event from node. - -#### interop_anchorPoint (Soon to be deprecated) - -```javascript -payload() -> DerivedBlockRefPair { - source: L1 BlockRef that rollup starts after (no derived transaction) - derived: L2 BlockRef that rollup starts from (no txn, pre-configuration state) -} -``` - -Returns the genesis block ref for L1 and L2 that the current node used as anchor point. -This method will soon be removed in favor of fetching the information from a supervisor specific rollup config. -(Once a spec is created about [this](https://github.com/ethereum-optimism/optimism/pull/16038) PR.) - -#### interop_invalidateBlock - -```javascript -payload (BlockSeal) //L2's Block -``` - -Based on some dependency or L1 changes, supervisor can instruct the L2 to invalidate a specific block. - -*(Suggestion: BlockSeal can be replaced with Hash, as only that is being used in op-node.)* - -#### interop_provideL1 - -```javascript -payload (BlockRef) //L1 Block -``` - -Supervisor sends the next L1 block to the node. Ideally sent after the node emits `exhausted-l1`. - -#### interop_reset - -```javascript -payload (lUnsafe, xUnsafe, lSafe, xSafe, finalized: BlockID) -``` - -Forces a reset to a specific local-unsafe/local-safe/finalized starting point only if the blocks did exist. Resets may -override local-unsafe, to reset the very end of the chain. Resets may override local-safe, since post-interop we need -the local-safe block derivation to continue. - -### DB - -RPC calls that a node should watch for, originating from supervisor that is called on DB updates for relevant block -safety info for a given chain and block. - -#### interop_updateCrossSafe - -```javascript -payload (derived: BlockID, source: BlockID) -``` - -Signal that a block can be promoted to cross-safe. - -#### interop_updateCrossUnsafe - -```javascript -payload (BlockID) -``` - -Signal that a block can be promoted to cross-unsafe. - -#### interop_updateFinalized - -```javascript -payload (BlockID) -``` - -Signal that a block can be marked as finalized. - -### Sync Methods - -RPC methods that are relevant for syncing the supervisor. These are directly called by the supervisor for fetching L2 -data. - -#### interop_fetchReceipts - -```javascript -payload (Hash) -> Receipts //L2 block hash -``` - -Fetches all transaction receipts in a given L2 block. - -#### interop_l2BlockRefByTimestamp - -```javascript -payload (uint64) -> BlockRef -``` - -Fetches L2 BlockRef of the block that occurred at given timestamp - -#### interop_l2BlockRefByNumber - -```javascript -payload (uint64) -> L2BlockRef -``` - -Fetches the L2 BlockRef from a given L2 block number - -#### interop_chainID - -```javascript -payload () -> string -``` - -Returns chainID of the L2 - -#### interop_outputV0AtTimestamp - -```javascript -payload (uint64) -> OutputV0 -``` - -Returns the state root, storage root and block hash for a given timestamp - -#### interop_pendingOutputV0AtTimestamp - -```javascript -payload (uint64) -> OutputV0 -``` - -Returns the optimistic output of the invalidated block from replacement - -**Note:** All events should return relevant error(s) in case of unsuccessful calls. - -## Types - -```javascript -Hash: 0x prefixed, hex encoded, fixed-length string representing 32 bytes - -BlockID { - hash: Hash - number: uint64 -} - -BlockSeal { - hash: Hash - number: uint64 - timestamp: uint64 -} - -BlockRef { - hash: Hash - number: uint64 - parentHash: Hash - timestamp: uint64 -} - -DerivedBlockRefPair { - source: BlockRef - derived: BlockRef -} - -BlockReplacement { - replacement: BlockRef - invalidated: Hash -} - -Receipts -> []Receipt - -Receipt -> op-geth/core/types/receipt - -OutputV0 { - stateRoot: Hash - messagePasserStorageRoot: Hash - blockHash: Hash -} -``` diff --git a/specs/interop/supernode.md b/specs/interop/supernode.md new file mode 100644 index 000000000..5545cd86f --- /dev/null +++ b/specs/interop/supernode.md @@ -0,0 +1,123 @@ +# Supernode + + + +**Table of Contents** + +- [Overview](#overview) +- [Architecture](#architecture) + - [Chain Containers](#chain-containers) + - [Chain Isolation](#chain-isolation) + - [Virtual Nodes](#virtual-nodes) + - [Engine Controller](#engine-controller) + - [Shared Resources](#shared-resources) + - [L1 Client](#l1-client) + - [Beacon Client](#beacon-client) + - [RPC Router](#rpc-router) + - [Metrics](#metrics) + - [Activities](#activities) + - [Heartbeat](#heartbeat) + - [Superroot](#superroot) + - [Interop](#interop) +- [RPC API](#rpc-api) + - [Common Types](#common-types) + - [`HexUint64`](#hexuint64) + - [`ChainID`](#chainid) + - [`Hash`](#hash) + - [`BlockID`](#blockid) + - [`OutputWithRequiredL1`](#outputwithrequiredl1) + - [`SuperRootResponseData`](#superrootrootresponsedata) + - [`SuperRootAtTimestampResponse`](#superrootattimestampresponse) + - [Root Namespace Methods](#root-namespace-methods) + - [`heartbeat_check`](#heartbeat_check) + - [`superroot_atTimestamp`](#superroot_attimestamp) + - [Per-Chain Namespace Methods](#per-chain-namespace-methods) +- [Configuration](#configuration) + - [Required Flags](#required-flags) + - [Optional Flags](#optional-flags) + - [Virtual Node Flags](#virtual-node-flags) + - [Global Virtual Node Flags](#global-virtual-node-flags) + - [Per-Chain Virtual Node Flags](#per-chain-virtual-node-flags) + - [Activity Flags](#activity-flags) +- [Example Usage](#example-usage) + + + +## Overview + +OP-Supernode is an implementation of an Optimism Consensus Client which +implements the Interop Protocol. + +The Interop Protocol is implemented fully outside of the existing +OP-Node Consensus Client, and instead runs as a corrective process +that enforces eventual-correctness of the Locally Safe Chain, +and promotion to Safe and ultimately Finalized. + +## Architecture + +### Chain Containers + +Chain Containers represent the concerns of one specific chain being managed by the Supernode. +It contains a client connection to the Execution Client, and a process +which runs `op-node` as an in-memory "Virtual Node". + +All interactions with a chain are abstracted through the Chain Container, +which routes and coordinates the response. + + +#### Virtual Nodes + +Each Chain Container manages a Virtual Node, which is an in-process `op-node` instance +configured for the specific chain. +Virtual Nodes are created with shared resources injected via initialization overrides, +allowing them to share L1 clients and beacon clients while maintaining isolation. + +Virtual Nodes are ephemeral: when a Virtual Node encounters an error or needs to restart, +the Chain Container automatically creates a new Virtual Node instance +and resumes derivation from the last known safe state. + +### Shared Resources + +Chain Containers benefit from running in a shared environment through the use of shared resources. +Shared resources are dependencies injected into Virtual Nodes such that the original behavior is intact, +but redundant access is eliminated. + + +### RPC Router + +The Supernode exposes a single HTTP endpoint that routes requests to the appropriate chain +based on the URL path prefix. + +- Root path (`/`) routes to the Supernode's root RPC handler for Activity RPCs +- Chain-prefixed paths (`//`) route to the corresponding chain's RPC handler + +For example: + +- `http://localhost:8545/` - Root namespace (heartbeat, superroot) +- `http://localhost:8545/11155420/` - OP Sepolia's RPC namespace +- `http://localhost:8545/84532/` - Base Sepolia's RPC namespace + + +### Verification Activities + +Activities represent the concerns of the Supernode which fall outside of any one chain. +They are modular plugins that extend the capabilities of the software. + +Verification Activities in particular help to inform Chain Containers +when Chain Content is Valid or Invalid. The Chain Container, in turn, +ensures the Chain State is correct, given what is known to be verified. + +### Interop + +Interop is implemented as a Verification Activity. +It is enabled when the `--interop.activation-timestamp` flag is set. + +The Interop activity: + +1. Maintains a tracking of the extent of the L1 that has been considered +by the activity. +2. Waits for all Chains to reach a target L2 Timestamp. Each chain must +have derived the timestamp (ie it must be Local Safe). +3. Performs Interop Executing Message Validation per this spec. +4. Record the Verified Result, or notify the Chain Container on Invalid +Blocks. \ No newline at end of file diff --git a/specs/interop/supervisor.md b/specs/interop/supervisor.md index 5ea586474..91913732e 100644 --- a/specs/interop/supervisor.md +++ b/specs/interop/supervisor.md @@ -1,449 +1 @@ -# Supervisor - - - -**Table of Contents** - -- [Overview](#overview) -- [RPC API](#rpc-api) - - [Common types](#common-types) - - [`Identifier`](#identifier) - - [`Message`](#message) - - [`ExecutingDescriptor`](#executingdescriptor) - - [`HexUint64`](#hexuint64) - - [`Int`](#int) - - [`ChainID`](#chainid) - - [`Hash`](#hash) - - [`Bytes`](#bytes) - - [`BlockID`](#blockid) - - [`BlockRef`](#blockref) - - [`DerivedIDPair`](#derivedidpair) - - [`ChainRootInfo`](#chainrootinfo) - - [`SupervisorSyncStatus`](#supervisorsyncstatus) - - [`SupervisorChainSyncStatus`](#supervisorchainsyncstatus) - - [`SuperRootResponse`](#superrootresponse) - - [`SafetyLevel`](#safetylevel) - - [Methods](#methods) - - [`supervisor_crossDerivedToSource`](#supervisor_crossderivedtosource) - - [`supervisor_localUnsafe`](#supervisor_localunsafe) - - [`supervisor_crossSafe`](#supervisor_crosssafe) - - [`supervisor_finalized`](#supervisor_finalized) - - [`supervisor_finalizedL1`](#supervisor_finalizedl1) - - [`supervisor_superRootAtTimestamp`](#supervisor_superrootattimestamp) - - [`supervisor_syncStatus`](#supervisor_syncstatus) - - [`supervisor_allSafeDerivedAt`](#supervisor_allsafederivedat) - - [`supervisor_checkAccessList`](#supervisor_checkaccesslist) - - [Access-list contents](#access-list-contents) - - [Access-list execution context](#access-list-execution-context) - - [Access-list checks](#access-list-checks) - - [`supervisor_checkAccessList` contents](#supervisor_checkaccesslist-contents) - - [Errors](#errors) - - [JSON-RPC Error Codes](#json-rpc-error-codes) - - [Error Code Structure](#error-code-structure) - - [Protocol Specific Error Codes](#protocol-specific-error-codes) - - [`-3204XX` `DEADLINE_EXCEEDED` errors](#-3204xx-deadline_exceeded-errors) - - [`-320400` `UNINITIALIZED_CHAIN_DATABASE`](#-320400-uninitialized_chain_database) - - [`-3205XX` `NOT_FOUND` errors](#-3205xx-not_found-errors) - - [`-320500` `SKIPPED_DATA`](#-320500-skipped_data) - - [`-320501` `UNKNOWN_CHAIN`](#-320501-unknown_chain) - - [`-3206XX` `ALREADY_EXISTS` errors](#-3206xx-already_exists-errors) - - [`-320600` `CONFLICTING_DATA`](#-320600-conflicting_data) - - [`-320601` `INEFFECTIVE_DATA`](#-320601-ineffective_data) - - [`-3209XX` `FAILED_PRECONDITION` errors](#-3209xx-failed_precondition-errors) - - [`-320900` `OUT_OF_ORDER`](#-320900-out_of_order) - - [`-320901` `AWAITING_REPLACEMENT_BLOCK`](#-320901-awaiting_replacement_block) - - [`-3210XX` `ABORTED` errors](#-3210xx-aborted-errors) - - [`-321000` `ITER_STOP`](#-321000-iter_stop) - - [`-3211XX` `OUT_OF_RANGE` errors](#-3211xx-out_of_range-errors) - - [`-321100` `OUT_OF_SCOPE`](#-321100-out_of_scope) - - [`-3212XX` `UNIMPLEMENTED` errors](#-3212xx-unimplemented-errors) - - [`-321200` `CANNOT_GET_PARENT_OF_FIRST_BLOCK_IN_DB`](#-321200-cannot_get_parent_of_first_block_in_db) - - [`-3214XX` `UNAVAILABLE` errors](#-3214xx-unavailable-errors) - - [`-321401` `FUTURE_DATA`](#-321401-future_data) - - [`-3215XX` `DATA_LOSS` errors](#-3215xx-data_loss-errors) - - [`-321500` `MISSED_DATA`](#-321500-missed_data) - - [`-321501` `DATA_CORRUPTION`](#-321501-data_corruption) - - - -## Overview - -The supervisor is an implementation detail of OP Stack native interop and is not the only -architecture that can be used to implement it. The supervisor is responsible for indexing -data from all of the chains in a cluster so that the [safety level](./verifier.md#safety) -of executing messages can quickly be determined. - -## RPC API - -### Common types - -#### `Identifier` - -The identifier of a message. -Corresponds to an [Identifier](./messaging.md#message-identifier). - -Object: -- `origin`: `Address` -- `blockNumber`: `HexUint64` -- `logIndex`: `HexUint64` -- `timestamp`: `HexUint64` -- `chainID`: `ChainID` - -#### `Message` - -Describes an initiating message. - -Object: -- `identifier`: `Identifier` - identifier of the message -- `payloadHash`: `Hash` - `keccak256` hash of the message-payload bytes - -#### `ExecutingDescriptor` - -Describes the context for message verification. -Specifically, this helps apply message-expiry rules on message checks. - -Object: -- `timestamp`: `HexUint64` - expected timestamp during message execution. -- `timeout`: `HexUint64` - optional, requests verification to still hold at `timestamp+timeout` (inclusive). - The message expiry-window may invalidate messages. - Default interpretation is a `0` timeout: what is valid at `timestamp` may not be valid at `timestamp+1`. - -#### `HexUint64` - -`STRING`: -Hex-encoded big-endian number, variable length up to 64 bits, prefixed with `0x`. - -#### `Int` - -`NUMBER`: -Regular JSON number, always integer. Assumed to always fit in 51 bits. - -#### `ChainID` - -`STRING`: -Hex-encoded big-endian number, variable length up to 256 bits, prefixed with `0x`. - -#### `Hash` - -`STRING`: -Hex-encoded, fixed-length, representing 32 bytes, prefixed with `0x`. - -#### `Bytes` - -`STRING`: -Hex-encoded, variable length (always full bytes, no odd number of nibbles), -representing a bytes list, prefixed with `0x`. - -#### `BlockID` - -Describes a block. - -`OBJECT`: -- `hash`: `Hash` - block hash -- `number`: `Int` - block number - -#### `BlockRef` - -Describes a block. - -`OBJECT`: -- `hash`: `Hash` - block hash -- `number`: `Int` - block number -- `parentHash`: `Hash` - block parent-hash -- `timestamp`: `Int` - block timestamp - -#### `DerivedIDPair` - -A pair of block identifiers, linking a `derived` block to the `source` block from which it was derived. - -`OBJECT`: - -- `source`: `BlockID` - The block ID of the `source` block. -- `derived`: `BlockID` - The block ID of the `derived` block. - -#### `ChainRootInfo` - -`OBJECT`: -- `chainId`: `HexUint64` - The chain ID (Note: this is changing to `ChainID` soon) -- `canonical`: `Hash` - output root at the latest canonical block -- `pending`: `Bytes` - output root preimage - -#### `SupervisorSyncStatus` - -Describes the sync status of the Supervisor component. Fields `minSyncedL1`, -`safeTimestamp` and `finalizedTimestamp` are set as the minimum value among -chains in `chains`. - -`OBJECT`: -- `minSyncedL1`: `BlockRef` - block ref to the synced L1 block -- `safeTimestamp`: `Int` - safe timestamp -- `finalizedTimestamp`: `Int` - finalized timestamp -- `chains`: `OBJECT` with `ChainID` keys and `SupervisorChainSyncStatus` values - -> **Note:** -> If `minSyncedL1` does not exist, it MUST be represented as a `BlockRef` with a `hash` and `parentHash` of -> `0x0000000000000000000000000000000000000000000000000000000000000000`, a `number` of `0`, -> and a `timestamp` of `0`. - -#### `SupervisorChainSyncStatus` - -Describes the sync status for a specific chain - -`OBJECT`: -- `localUnsafe`: `BlockRef` - local-unsafe ref for the given chain -- `localSafe`: `BlockID` - local-safe ref for the given chain -- `crossUnsafe`: `BlockID` - cross-unsafe ref for the given chain -- `safe`: `BlockID` - cross-safe ref for the given chain -- `finalized`: `BlockID` - finalized ref for the given chain - -> **Note:** -> For the fields `localSafe`, `crossUnsafe`, `safe`, and `finalized`, if the referenced block does not exist yet, -> the `BlockID` MUST be represented with a `hash` of -> `0x0000000000000000000000000000000000000000000000000000000000000000` and a `number` of `0`. - -#### `SuperRootResponse` - -`OBJECT`: -- `crossSafeDerivedFrom`: `BlockID` - common derived-from where all chains are cross-safe -- `timestamp`: `Int` - The timestamp of the super root -- `superRoot`: `Hash` - The root of the super root -- `version`: `Int` - The version of the response -- `chains`: `ARRAY` of `ChainRootInfo` - List of chains included in the super root - -#### `SafetyLevel` - -The safety level of the message. -Corresponds to a verifier [SafetyLevel](./verifier.md#safety). - -`STRING`, one of: -- `invalid` -- `unsafe`: matching local-unsafe, equivalent to safety of the `latest` RPC label. -- `cross-unsafe` -- `local-safe` -- `safe`: matching cross-safe, named `safe` to match the RPC label. -- `finalized` - -### Methods - -#### `supervisor_crossDerivedToSource` - -Parameters: -- `chainID`: `ChainID` -- `derived`: `BlockID` - -Returns: derivedFrom `BlockRef` - -#### `supervisor_localUnsafe` - -Parameters: -- `chainID`: `ChainID` - -Returns: `BlockID` - -#### `supervisor_crossSafe` - -Parameters: -- `chainID`: `ChainID` - -Returns: `DerivedIDPair` - -#### `supervisor_finalized` - -Parameters: -- `chainID`: `ChainID` - -Returns: `BlockID` - -#### `supervisor_finalizedL1` - -Parameters: (none) - -Returns: `BlockRef` - -#### `supervisor_superRootAtTimestamp` - -Retrieves the super root state at the specified timestamp, -which represents the global state across all monitored chains. - -Parameters: -- `timestamp`: `HexUint64` - -Returns: `SuperRootResponse` - -#### `supervisor_syncStatus` - -Parameters: (none) - -Returns: `SupervisorSyncStatus`. -Throws: Some error if set of supervised chains is empty. - -#### `supervisor_allSafeDerivedAt` - -Returns the last derived block for each chain, from the given L1 block. - -Parameters: -- `derivedFrom`: `BlockID` - -Returns: derived blocks, mapped in a `OBJECT`: -- key: `ChainID` -- value: `BlockID` - -#### `supervisor_checkAccessList` - -Verifies if an access-list, as defined in [EIP-2930], references only valid messages. -Message execution in the [`CrossL2Inbox`] that is statically declared in the access-list will not revert. - -[EIP-2930]: https://eips.ethereum.org/EIPS/eip-2930 - -##### Access-list contents - -Only the [`CrossL2Inbox`] subset of the access-list in the transaction is required, -storage-access by other addresses is not included. - -Note that an access-list can contain multiple different storage key lists for the `CrossL2Inbox` address. -All storage keys applicable to the `CrossL2Inbox` MUST be joined together (preserving ordering), -missing storage-keys breaks inbox safety. - -**ALL storage-keys in the access-list for the `CrossL2Inbox` MUST be checked.** -If there is any unrecognized or invalid key, the access-list check MUST fail. - -[`CrossL2Inbox`]: ./predeploys.md#crossl2inbox - -##### Access-list execution context - -The provided execution-context is used to determine validity relative to the provided time constraints, -see [timestamp invariants](./derivation.md#invariants). - -Since messages expire, validity is not definitive. -To reserve validity for a longer time range, a non-zero `timeout` value can be used. -See [`ExecutingDescriptor`](#executingdescriptor) documentation. - -As block-builder a `timeout` of `0` should be used. - -As transaction pre-verifier, a `timeout` of `86400` (1 day) should be used. -The transaction should be re-verified or dropped after this time duration, -as it can no longer be safely included in the block due to message-expiry. - -##### Access-list checks - -The access-list check errors are not definite state-transition blockers, the RPC based checks can be extra conservative. -I.e. a message that is uncertain to meet the requested safety level may be denied. -Specifically, no attempt may be made to verify messages that are initiated and executed within the same timestamp, -these are `invalid` by default. -Advanced block-builders may still choose to include these messages by verifying the intra-block constraints. - -##### `supervisor_checkAccessList` contents - -Parameters: -- `inboxEntries`: `ARRAY` of `Hash` - statically declared `CrossL2Inbox` access entries. -- `minSafety`: `SafetyLevel` - minimum required safety, one of: - - `unsafe`: the message exists. - - `cross-unsafe`: the message exists in a cross-unsafe block. - - `local-safe`: the message exists in a local-safe block, not yet cross-verified. - - `safe`: the message exists in a derived block that is cross-verified. - - `finalized`: the message exists in a finalized block. - - Other safety levels are invalid and result in an error. -- `executingDescriptor`: `ExecutingDescriptor` - applies as execution-context to all messages. - -Returns: RPC error if the `minSafety` is not met by one or more of the access entries. - -The access-list entries represent messages, and may be incomplete or malformed. -Malformed access-lists result in an RPC error. - -### Errors - -The Supervisor RPC API uses a 6-digit error code system that extends standard JSON-RPC error codes -while providing additional categorization based on gRPC status codes. - -For standard JSON-RPC error codes, refer to [Ethereum JSON-RPC Error Reference](https://ethereum-json-rpc.com/errors). - -#### JSON-RPC Error Codes - -#### Error Code Structure - -Supervisor error codes follow this structure: - -- First 2 digits: `32` (indicating server error, matching JSON-RPC conventions) -- Middle 2 digits: gRPC status code category (01-16, zero-padded) -- Last 2 digits: Specific error index within that category (00-99) - -For gRPC status codes reference, see [gRPC Status Codes](https://grpc.io/docs/guides/status-codes/). - -#### Protocol Specific Error Codes - -##### `-3204XX` `DEADLINE_EXCEEDED` errors - -###### `-320400` `UNINITIALIZED_CHAIN_DATABASE` - -Happens when a chain database is not initialized yet. - -##### `-3205XX` `NOT_FOUND` errors - -###### `-320500` `SKIPPED_DATA` - -Happens when we try to retrieve data that is not available (pruned). -It may also happen if we erroneously skip data, that was not considered a conflict, if the DB is corrupted. - -###### `-320501` `UNKNOWN_CHAIN` - -Happens when a chain is unknown, not in the dependency set. - -##### `-3206XX` `ALREADY_EXISTS` errors - -###### `-320600` `CONFLICTING_DATA` - -Happens when we know for sure that there is different canonical data. - -###### `-320601` `INEFFECTIVE_DATA` - -Happens when data is accepted as compatible, but did not change anything. -This happens when a node is deriving an L2 block we already know of being derived from the given source, -but without path to skip forward to newer source blocks without doing the known derivation work first. - -##### `-3209XX` `FAILED_PRECONDITION` errors - -###### `-320900` `OUT_OF_ORDER` - -Happens when you try to add data to the DB, but it does not actually fit onto the latest data -(by being too old or new). - -###### `-320901` `AWAITING_REPLACEMENT_BLOCK` - -Happens when we know for sure that a replacement block is needed before progress can be made. - -##### `-3210XX` `ABORTED` errors - -###### `-321000` `ITER_STOP` - -Happens in iterator to indicate iteration has to stop. -This error might only be used internally and not sent over the network. - -##### `-3211XX` `OUT_OF_RANGE` errors - -###### `-321100` `OUT_OF_SCOPE` - -Happens when data is accessed, but access is not allowed, because of a limited scope. -E.g. when limiting scope to L2 blocks derived from a specific subset of the L1 chain. - -##### `-3212XX` `UNIMPLEMENTED` errors - -###### `-321200` `CANNOT_GET_PARENT_OF_FIRST_BLOCK_IN_DB` - -Happens when you try to get the previous block of the first block. -E.g. when trying to determine the previous source block for the first L1 block in the database. - -##### `-3214XX` `UNAVAILABLE` errors - -###### `-321401` `FUTURE_DATA` - -Happens when data is just not yet available. - -##### `-3215XX` `DATA_LOSS` errors - -###### `-321500` `MISSED_DATA` - -Happens when we search the DB, know the data may be there, but is not (e.g. different revision). - -###### `-321501` `DATA_CORRUPTION` - -Happens when the underlying DB has some I/O issue. +*yoink* \ No newline at end of file