From bf7f6990965ac6c49d9c548824f4988bab0b00e8 Mon Sep 17 00:00:00 2001 From: Josh Crites Date: Wed, 10 Apr 2024 09:00:41 -0400 Subject: [PATCH 01/18] move files --- .../0-keys-latex-preamble.md | 0 .../addresses-and-keys/address.md | 0 .../diversified-and-stealth.md | 0 .../diversified-and-stealth-keys.mdx | 0 .../example-usage/encrypt-and-tag.mdx | 0 .../example-usage/nullifier.mdx | 2 +- .../example-usage/tag-sequence-derivation.mdx | 0 .../addresses-and-keys/index.md | 0 .../addresses-and-keys/keys-requirements.md | 0 .../addresses-and-keys/keys.mdx | 4 +- .../addresses-and-keys/precompiles.md | 0 .../docs/protocol-specs}/bytecode/index.md | 0 .../protocol-specs}/calls/batched-calls.md | 0 .../protocol-specs}/calls/delegate-calls.md | 0 .../protocol-specs}/calls/enqueued-calls.md | 0 .../docs/protocol-specs}/calls/index.md | 0 .../calls/public-private-messaging.md | 2 +- .../protocol-specs}/calls/static-calls.md | 0 .../docs/protocol-specs}/calls/sync-calls.md | 0 .../calls/unconstrained-calls.md | 0 .../circuits/high-level-topology.md | 0 .../circuits/private-function.md | 0 .../circuits/private-kernel-initial.mdx | 0 .../circuits/private-kernel-inner.mdx | 0 .../circuits/private-kernel-reset.md | 0 .../circuits/private-kernel-tail.md | 0 .../circuits/public-kernel-initial.md | 0 .../circuits/public-kernel-inner.md | 0 .../circuits/public-kernel-tail.md | 0 .../docs/protocol-specs}/constants.md | 0 .../contract-deployment/classes.md | 0 .../contract-deployment/index.md | 0 .../contract-deployment/instances.md | 0 .../cryptography/hashing/hashing.md | 0 .../cryptography/hashing/pedersen.md | 0 .../cryptography/hashing/poseidon2.md | 0 .../protocol-specs}/cryptography/index.md | 0 .../cryptography/merkle-trees.md | 0 .../cryptography/proving-system/data-bus.md | 0 .../cryptography/proving-system/overview.md | 2 +- .../proving-system/performance-targets.md | 0 .../index.md | 0 .../overview.md | 0 .../published-data.md | 0 .../decentralization/actors.md | 0 .../decentralization/block-production.md | 4 +- .../decentralization/governance.md | 10 +- .../decentralization/p2p-network.md | 53 +- .../gas-and-fees/fee-payments-and-metering.md | 41 +- .../gas-and-fees/fee-schedule.md | 0 .../protocol-specs}/gas-and-fees/index.md | 0 .../docs/protocol-specs}/intro.md | 0 .../l1-smart-contracts/frontier.md | 38 +- .../l1-smart-contracts/index.md | 0 .../docs/protocol-specs}/logs/index.md | 0 .../pre-compiled-contracts/index.md | 0 .../pre-compiled-contracts/registry.md | 0 .../private-message-delivery/index.md | 0 .../private-msg-delivery.md | 0 .../send-note-guidelines.md | 0 .../public-vm/_nested-context.md | 0 .../docs/protocol-specs}/public-vm/alu.md | 2 +- .../protocol-specs}/public-vm/avm-circuit.md | 0 .../public-vm/bytecode-validation-circuit.md | 0 .../public-vm/circuit-index.md | 0 .../protocol-specs}/public-vm/context.mdx | 0 .../protocol-specs}/public-vm/control-flow.md | 0 .../protocol-specs}/public-vm/execution.md | 0 .../public-vm/gen/_instruction-set.mdx | 0 .../public-vm/gen/images/bit-formats/ADD.png | Bin .../gen/images/bit-formats/ADDRESS.png | Bin .../public-vm/gen/images/bit-formats/AND.png | Bin .../images/bit-formats/BLOCKDAGASLIMIT.png | Bin .../images/bit-formats/BLOCKHEADERBYNUM.png | Bin .../images/bit-formats/BLOCKL1GASLIMIT.png | Bin .../images/bit-formats/BLOCKL2GASLIMIT.png | Bin .../gen/images/bit-formats/BLOCKNUMBER.png | Bin .../public-vm/gen/images/bit-formats/CALL.png | Bin .../gen/images/bit-formats/CALLDATACOPY.png | Bin .../public-vm/gen/images/bit-formats/CAST.png | Bin .../gen/images/bit-formats/CHAINID.png | Bin .../public-vm/gen/images/bit-formats/CMOV.png | Bin .../gen/images/bit-formats/COINBASE.png | Bin .../images/bit-formats/CONTRACTCALLDEPTH.png | Bin .../gen/images/bit-formats/DAGASLEFT.png | Bin .../public-vm/gen/images/bit-formats/DIV.png | Bin .../gen/images/bit-formats/EMITNOTEHASH.png | Bin .../gen/images/bit-formats/EMITNULLIFIER.png | Bin .../images/bit-formats/EMITUNENCRYPTEDLOG.png | Bin .../public-vm/gen/images/bit-formats/EQ.png | Bin .../gen/images/bit-formats/FEEPERDAGAS.png | Bin .../gen/images/bit-formats/FEEPERL1GAS.png | Bin .../gen/images/bit-formats/FEEPERL2GAS.png | Bin .../images/bit-formats/INTERNALCALLDEPTH.png | Bin .../gen/images/bit-formats/INTERNALRETURN.png | Bin .../public-vm/gen/images/bit-formats/JUMP.png | Bin .../gen/images/bit-formats/JUMPI.png | Bin .../gen/images/bit-formats/L1GASLEFT.png | Bin .../gen/images/bit-formats/L2GASLEFT.png | Bin .../public-vm/gen/images/bit-formats/LT.png | Bin .../public-vm/gen/images/bit-formats/LTE.png | Bin .../public-vm/gen/images/bit-formats/MOV.png | Bin .../public-vm/gen/images/bit-formats/MUL.png | Bin .../public-vm/gen/images/bit-formats/NOT.png | Bin .../public-vm/gen/images/bit-formats/OR.png | Bin .../gen/images/bit-formats/ORIGIN.png | Bin .../gen/images/bit-formats/PORTAL.png | Bin .../gen/images/bit-formats/READL1TOL2MSG.png | Bin .../gen/images/bit-formats/RETURN.png | Bin .../gen/images/bit-formats/REVERT.png | Bin .../gen/images/bit-formats/SENDER.png | Bin .../gen/images/bit-formats/SENDL2TOL1MSG.png | Bin .../public-vm/gen/images/bit-formats/SET.png | Bin .../public-vm/gen/images/bit-formats/SHL.png | Bin .../public-vm/gen/images/bit-formats/SHR.png | Bin .../gen/images/bit-formats/SLOAD.png | Bin .../gen/images/bit-formats/SSTORE.png | Bin .../gen/images/bit-formats/STATICCALL.png | Bin .../gen/images/bit-formats/STORAGEADDRESS.png | Bin .../public-vm/gen/images/bit-formats/SUB.png | Bin .../gen/images/bit-formats/TIMESTAMP.png | Bin .../gen/images/bit-formats/VERSION.png | Bin .../public-vm/gen/images/bit-formats/XOR.png | Bin .../gen/images/bit-formats/internalcall.png | Bin .../docs/protocol-specs}/public-vm/index.md | 0 .../public-vm/instruction-set.mdx | 0 .../docs/protocol-specs}/public-vm/intro.md | 0 .../protocol-specs}/public-vm/memory-model.md | 2 +- .../public-vm/nested-calls.mdx | 0 .../protocol-specs}/public-vm/security.md | 0 .../docs/protocol-specs}/public-vm/state.md | 0 .../protocol-specs}/public-vm/type-structs.md | 0 .../rollup-circuits/base-rollup.md | 0 .../protocol-specs}/rollup-circuits/index.md | 0 .../rollup-circuits/merge-rollup.md | 0 .../rollup-circuits/root-rollup.md | 0 .../rollup-circuits/tree-parity.md | 0 .../docs/protocol-specs}/state/archive.md | 0 .../docs/protocol-specs}/state/index.md | 0 .../protocol-specs}/state/note-hash-tree.md | 0 .../protocol-specs}/state/nullifier-tree.md | 0 .../protocol-specs}/state/public-data-tree.md | 0 .../state/tree-implementations.md | 0 .../docs => docs/docs/protocol-specs}/todo.md | 0 .../protocol-specs}/transactions/index.md | 0 .../transactions/local-execution.md | 0 .../transactions/public-execution.md | 0 .../protocol-specs}/transactions/tx-object.md | 0 .../protocol-specs}/transactions/validity.md | 0 docs/docusaurus.config.js | 6 + docs/sidebars.js | 226 +++ .../InstructionSet/InstructionSet.js | 1254 +++++++++++++++++ .../InstructionSet/InstructionSize.js | 90 ++ .../InstructionSet/genBitFormats.js | 16 + .../preprocess/InstructionSet/genMarkdown.js | 153 ++ docs/src/preprocess/index.js | 3 + .../addresses-and-keys/image-1.png | Bin .../addresses-and-keys/image-3.png | Bin .../addresses-and-keys/image-4.png | Bin .../addresses-and-keys/image-5.png | Bin .../addresses-and-keys/image.png | Bin .../calls/pub_pvt_messaging.png | Bin .../calls/pvt_pub_ordering.png | Bin .../cryptography}/proof-system-components.png | Bin .../Aztec-Block-Production-1.png | Bin .../Aztec-Block-Production-2.png | Bin .../Aztec-Block-Production-3.png | Bin .../Aztec-Governance-Summary-1.png | Bin .../Aztec-Governance-Summary-2.png | Bin .../Aztec-Governance-Summary-3.png | Bin .../Aztec-Governance-Summary-4.png | Bin .../Aztec-Governance-Summary-5.png | Bin .../decentralization}/network.png | Bin .../gas-and-fees/Transaction.png | Bin .../l1-smart-contracts}/com-abs-6.png | Bin .../l1-smart-contracts}/frontier/image-1.png | Bin .../l1-smart-contracts}/frontier/image-2.png | Bin .../l1-smart-contracts}/frontier/image-3.png | Bin .../l1-smart-contracts}/frontier/image-4.png | Bin .../l1-smart-contracts}/frontier/image-5.png | Bin .../l1-smart-contracts}/frontier/image-6.png | Bin .../l1-smart-contracts}/frontier/image-7.png | Bin .../l1-smart-contracts}/tree-order.png | Bin .../img/protocol-specs/public-vm}/alu.png | Bin .../public-vm}/avm-control-flow.png | Bin .../img/protocol-specs/public-vm}/memory.png | Bin 186 files changed, 1827 insertions(+), 81 deletions(-) rename {yellow-paper/docs => docs/docs/protocol-specs}/addresses-and-keys/0-keys-latex-preamble.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/addresses-and-keys/address.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/addresses-and-keys/diversified-and-stealth.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/addresses-and-keys/example-usage/diversified-and-stealth-keys.mdx (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/addresses-and-keys/example-usage/encrypt-and-tag.mdx (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/addresses-and-keys/example-usage/nullifier.mdx (98%) rename {yellow-paper/docs => docs/docs/protocol-specs}/addresses-and-keys/example-usage/tag-sequence-derivation.mdx (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/addresses-and-keys/index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/addresses-and-keys/keys-requirements.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/addresses-and-keys/keys.mdx (99%) rename {yellow-paper/docs => docs/docs/protocol-specs}/addresses-and-keys/precompiles.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/bytecode/index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/calls/batched-calls.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/calls/delegate-calls.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/calls/enqueued-calls.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/calls/index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/calls/public-private-messaging.md (98%) rename {yellow-paper/docs => docs/docs/protocol-specs}/calls/static-calls.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/calls/sync-calls.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/calls/unconstrained-calls.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/circuits/high-level-topology.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/circuits/private-function.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/circuits/private-kernel-initial.mdx (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/circuits/private-kernel-inner.mdx (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/circuits/private-kernel-reset.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/circuits/private-kernel-tail.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/circuits/public-kernel-initial.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/circuits/public-kernel-inner.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/circuits/public-kernel-tail.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/constants.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/contract-deployment/classes.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/contract-deployment/index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/contract-deployment/instances.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/cryptography/hashing/hashing.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/cryptography/hashing/pedersen.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/cryptography/hashing/poseidon2.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/cryptography/index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/cryptography/merkle-trees.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/cryptography/proving-system/data-bus.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/cryptography/proving-system/overview.md (98%) rename {yellow-paper/docs => docs/docs/protocol-specs}/cryptography/proving-system/performance-targets.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/data-publication-and-availability/index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/data-publication-and-availability/overview.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/data-publication-and-availability/published-data.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/decentralization/actors.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/decentralization/block-production.md (99%) rename {yellow-paper/docs => docs/docs/protocol-specs}/decentralization/governance.md (97%) rename {yellow-paper/docs => docs/docs/protocol-specs}/decentralization/p2p-network.md (91%) rename {yellow-paper/docs => docs/docs/protocol-specs}/gas-and-fees/fee-payments-and-metering.md (97%) rename {yellow-paper/docs => docs/docs/protocol-specs}/gas-and-fees/fee-schedule.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/gas-and-fees/index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/intro.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/l1-smart-contracts/frontier.md (87%) rename {yellow-paper/docs => docs/docs/protocol-specs}/l1-smart-contracts/index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/logs/index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/pre-compiled-contracts/index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/pre-compiled-contracts/registry.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/private-message-delivery/index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/private-message-delivery/private-msg-delivery.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/private-message-delivery/send-note-guidelines.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/_nested-context.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/alu.md (97%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/avm-circuit.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/bytecode-validation-circuit.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/circuit-index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/context.mdx (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/control-flow.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/execution.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/_instruction-set.mdx (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/ADD.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/ADDRESS.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/AND.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/BLOCKDAGASLIMIT.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/BLOCKHEADERBYNUM.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/BLOCKL1GASLIMIT.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/BLOCKL2GASLIMIT.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/BLOCKNUMBER.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/CALL.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/CALLDATACOPY.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/CAST.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/CHAINID.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/CMOV.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/COINBASE.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/CONTRACTCALLDEPTH.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/DAGASLEFT.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/DIV.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/EMITNOTEHASH.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/EMITNULLIFIER.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/EMITUNENCRYPTEDLOG.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/EQ.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/FEEPERDAGAS.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/FEEPERL1GAS.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/FEEPERL2GAS.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/INTERNALCALLDEPTH.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/INTERNALRETURN.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/JUMP.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/JUMPI.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/L1GASLEFT.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/L2GASLEFT.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/LT.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/LTE.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/MOV.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/MUL.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/NOT.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/OR.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/ORIGIN.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/PORTAL.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/READL1TOL2MSG.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/RETURN.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/REVERT.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/SENDER.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/SENDL2TOL1MSG.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/SET.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/SHL.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/SHR.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/SLOAD.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/SSTORE.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/STATICCALL.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/STORAGEADDRESS.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/SUB.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/TIMESTAMP.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/VERSION.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/XOR.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/gen/images/bit-formats/internalcall.png (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/instruction-set.mdx (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/intro.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/memory-model.md (99%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/nested-calls.mdx (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/security.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/state.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/public-vm/type-structs.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/rollup-circuits/base-rollup.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/rollup-circuits/index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/rollup-circuits/merge-rollup.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/rollup-circuits/root-rollup.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/rollup-circuits/tree-parity.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/state/archive.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/state/index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/state/note-hash-tree.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/state/nullifier-tree.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/state/public-data-tree.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/state/tree-implementations.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/todo.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/transactions/index.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/transactions/local-execution.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/transactions/public-execution.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/transactions/tx-object.md (100%) rename {yellow-paper/docs => docs/docs/protocol-specs}/transactions/validity.md (100%) create mode 100644 docs/src/preprocess/InstructionSet/InstructionSet.js create mode 100644 docs/src/preprocess/InstructionSet/InstructionSize.js create mode 100644 docs/src/preprocess/InstructionSet/genBitFormats.js create mode 100644 docs/src/preprocess/InstructionSet/genMarkdown.js rename {yellow-paper/docs/addresses-and-keys/images => docs/static/img/protocol-specs}/addresses-and-keys/image-1.png (100%) rename {yellow-paper/docs/addresses-and-keys/images => docs/static/img/protocol-specs}/addresses-and-keys/image-3.png (100%) rename {yellow-paper/docs/addresses-and-keys/images => docs/static/img/protocol-specs}/addresses-and-keys/image-4.png (100%) rename {yellow-paper/docs/addresses-and-keys/images => docs/static/img/protocol-specs}/addresses-and-keys/image-5.png (100%) rename {yellow-paper/docs/addresses-and-keys/images => docs/static/img/protocol-specs}/addresses-and-keys/image.png (100%) rename {yellow-paper/docs/calls/images => docs/static/img/protocol-specs}/calls/pub_pvt_messaging.png (100%) rename {yellow-paper/docs/calls/images => docs/static/img/protocol-specs}/calls/pvt_pub_ordering.png (100%) rename {yellow-paper/docs/cryptography/images => docs/static/img/protocol-specs/cryptography}/proof-system-components.png (100%) rename {yellow-paper/docs/decentralization/images => docs/static/img/protocol-specs/decentralization}/Aztec-Block-Production-1.png (100%) rename {yellow-paper/docs/decentralization/images => docs/static/img/protocol-specs/decentralization}/Aztec-Block-Production-2.png (100%) rename {yellow-paper/docs/decentralization/images => docs/static/img/protocol-specs/decentralization}/Aztec-Block-Production-3.png (100%) rename {yellow-paper/docs/decentralization/images => docs/static/img/protocol-specs/decentralization}/Aztec-Governance-Summary-1.png (100%) rename {yellow-paper/docs/decentralization/images => docs/static/img/protocol-specs/decentralization}/Aztec-Governance-Summary-2.png (100%) rename {yellow-paper/docs/decentralization/images => docs/static/img/protocol-specs/decentralization}/Aztec-Governance-Summary-3.png (100%) rename {yellow-paper/docs/decentralization/images => docs/static/img/protocol-specs/decentralization}/Aztec-Governance-Summary-4.png (100%) rename {yellow-paper/docs/decentralization/images => docs/static/img/protocol-specs/decentralization}/Aztec-Governance-Summary-5.png (100%) rename {yellow-paper/docs/decentralization/images => docs/static/img/protocol-specs/decentralization}/network.png (100%) rename {yellow-paper/docs/gas-and-fees/images => docs/static/img/protocol-specs}/gas-and-fees/Transaction.png (100%) rename {yellow-paper/docs/l1-smart-contracts/images => docs/static/img/protocol-specs/l1-smart-contracts}/com-abs-6.png (100%) rename {yellow-paper/docs/l1-smart-contracts/images => docs/static/img/protocol-specs/l1-smart-contracts}/frontier/image-1.png (100%) rename {yellow-paper/docs/l1-smart-contracts/images => docs/static/img/protocol-specs/l1-smart-contracts}/frontier/image-2.png (100%) rename {yellow-paper/docs/l1-smart-contracts/images => docs/static/img/protocol-specs/l1-smart-contracts}/frontier/image-3.png (100%) rename {yellow-paper/docs/l1-smart-contracts/images => docs/static/img/protocol-specs/l1-smart-contracts}/frontier/image-4.png (100%) rename {yellow-paper/docs/l1-smart-contracts/images => docs/static/img/protocol-specs/l1-smart-contracts}/frontier/image-5.png (100%) rename {yellow-paper/docs/l1-smart-contracts/images => docs/static/img/protocol-specs/l1-smart-contracts}/frontier/image-6.png (100%) rename {yellow-paper/docs/l1-smart-contracts/images => docs/static/img/protocol-specs/l1-smart-contracts}/frontier/image-7.png (100%) rename {yellow-paper/docs/l1-smart-contracts/images => docs/static/img/protocol-specs/l1-smart-contracts}/tree-order.png (100%) rename {yellow-paper/docs/public-vm/images => docs/static/img/protocol-specs/public-vm}/alu.png (100%) rename {yellow-paper/docs/public-vm/images => docs/static/img/protocol-specs/public-vm}/avm-control-flow.png (100%) rename {yellow-paper/docs/public-vm/images => docs/static/img/protocol-specs/public-vm}/memory.png (100%) diff --git a/yellow-paper/docs/addresses-and-keys/0-keys-latex-preamble.md b/docs/docs/protocol-specs/addresses-and-keys/0-keys-latex-preamble.md similarity index 100% rename from yellow-paper/docs/addresses-and-keys/0-keys-latex-preamble.md rename to docs/docs/protocol-specs/addresses-and-keys/0-keys-latex-preamble.md diff --git a/yellow-paper/docs/addresses-and-keys/address.md b/docs/docs/protocol-specs/addresses-and-keys/address.md similarity index 100% rename from yellow-paper/docs/addresses-and-keys/address.md rename to docs/docs/protocol-specs/addresses-and-keys/address.md diff --git a/yellow-paper/docs/addresses-and-keys/diversified-and-stealth.md b/docs/docs/protocol-specs/addresses-and-keys/diversified-and-stealth.md similarity index 100% rename from yellow-paper/docs/addresses-and-keys/diversified-and-stealth.md rename to docs/docs/protocol-specs/addresses-and-keys/diversified-and-stealth.md diff --git a/yellow-paper/docs/addresses-and-keys/example-usage/diversified-and-stealth-keys.mdx b/docs/docs/protocol-specs/addresses-and-keys/example-usage/diversified-and-stealth-keys.mdx similarity index 100% rename from yellow-paper/docs/addresses-and-keys/example-usage/diversified-and-stealth-keys.mdx rename to docs/docs/protocol-specs/addresses-and-keys/example-usage/diversified-and-stealth-keys.mdx diff --git a/yellow-paper/docs/addresses-and-keys/example-usage/encrypt-and-tag.mdx b/docs/docs/protocol-specs/addresses-and-keys/example-usage/encrypt-and-tag.mdx similarity index 100% rename from yellow-paper/docs/addresses-and-keys/example-usage/encrypt-and-tag.mdx rename to docs/docs/protocol-specs/addresses-and-keys/example-usage/encrypt-and-tag.mdx diff --git a/yellow-paper/docs/addresses-and-keys/example-usage/nullifier.mdx b/docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.mdx similarity index 98% rename from yellow-paper/docs/addresses-and-keys/example-usage/nullifier.mdx rename to docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.mdx index 6504066b7ce..f2e17a7a5b1 100644 --- a/yellow-paper/docs/addresses-and-keys/example-usage/nullifier.mdx +++ b/docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.mdx @@ -17,7 +17,7 @@ Here's example for how an app circuit _could_ constrain the nullifier key to be It's easiest to take a look at this first: -![Alt text](../images/addresses-and-keys/image.png) +![Alt text](/img/protocol-specs/addresses-and-keys/image.png) ### Within the app circuit diff --git a/yellow-paper/docs/addresses-and-keys/example-usage/tag-sequence-derivation.mdx b/docs/docs/protocol-specs/addresses-and-keys/example-usage/tag-sequence-derivation.mdx similarity index 100% rename from yellow-paper/docs/addresses-and-keys/example-usage/tag-sequence-derivation.mdx rename to docs/docs/protocol-specs/addresses-and-keys/example-usage/tag-sequence-derivation.mdx diff --git a/yellow-paper/docs/addresses-and-keys/index.md b/docs/docs/protocol-specs/addresses-and-keys/index.md similarity index 100% rename from yellow-paper/docs/addresses-and-keys/index.md rename to docs/docs/protocol-specs/addresses-and-keys/index.md diff --git a/yellow-paper/docs/addresses-and-keys/keys-requirements.md b/docs/docs/protocol-specs/addresses-and-keys/keys-requirements.md similarity index 100% rename from yellow-paper/docs/addresses-and-keys/keys-requirements.md rename to docs/docs/protocol-specs/addresses-and-keys/keys-requirements.md diff --git a/yellow-paper/docs/addresses-and-keys/keys.mdx b/docs/docs/protocol-specs/addresses-and-keys/keys.mdx similarity index 99% rename from yellow-paper/docs/addresses-and-keys/keys.mdx rename to docs/docs/protocol-specs/addresses-and-keys/keys.mdx index 03eb55d1544..2542c31710c 100644 --- a/yellow-paper/docs/addresses-and-keys/keys.mdx +++ b/docs/docs/protocol-specs/addresses-and-keys/keys.mdx @@ -3,6 +3,8 @@ title: Default Keys Specification description: Specification for default privacy keys format and derivation, and nullifier derivation. --- +import Image from "@theme/IdealImage"; + @@ -51,7 +53,7 @@ The protocol does not enforce the usage of any of the following keys, and does n Diagram is out of date vs the content on this page ::: -![Alt text](images/addresses-and-keys/image-5.png) + The red boxes are uncertainties, which are explained later in this doc. diff --git a/yellow-paper/docs/addresses-and-keys/precompiles.md b/docs/docs/protocol-specs/addresses-and-keys/precompiles.md similarity index 100% rename from yellow-paper/docs/addresses-and-keys/precompiles.md rename to docs/docs/protocol-specs/addresses-and-keys/precompiles.md diff --git a/yellow-paper/docs/bytecode/index.md b/docs/docs/protocol-specs/bytecode/index.md similarity index 100% rename from yellow-paper/docs/bytecode/index.md rename to docs/docs/protocol-specs/bytecode/index.md diff --git a/yellow-paper/docs/calls/batched-calls.md b/docs/docs/protocol-specs/calls/batched-calls.md similarity index 100% rename from yellow-paper/docs/calls/batched-calls.md rename to docs/docs/protocol-specs/calls/batched-calls.md diff --git a/yellow-paper/docs/calls/delegate-calls.md b/docs/docs/protocol-specs/calls/delegate-calls.md similarity index 100% rename from yellow-paper/docs/calls/delegate-calls.md rename to docs/docs/protocol-specs/calls/delegate-calls.md diff --git a/yellow-paper/docs/calls/enqueued-calls.md b/docs/docs/protocol-specs/calls/enqueued-calls.md similarity index 100% rename from yellow-paper/docs/calls/enqueued-calls.md rename to docs/docs/protocol-specs/calls/enqueued-calls.md diff --git a/yellow-paper/docs/calls/index.md b/docs/docs/protocol-specs/calls/index.md similarity index 100% rename from yellow-paper/docs/calls/index.md rename to docs/docs/protocol-specs/calls/index.md diff --git a/yellow-paper/docs/calls/public-private-messaging.md b/docs/docs/protocol-specs/calls/public-private-messaging.md similarity index 98% rename from yellow-paper/docs/calls/public-private-messaging.md rename to docs/docs/protocol-specs/calls/public-private-messaging.md index 9d8e164625c..edbe6720dce 100644 --- a/yellow-paper/docs/calls/public-private-messaging.md +++ b/docs/docs/protocol-specs/calls/public-private-messaging.md @@ -81,4 +81,4 @@ To elaborate, a public function may not have read access to encrypted private st In the picture below, it is worth noting that all data reads performed by private functions are historical in nature, and that private functions are not capable of modifying public storage. Conversely, public functions have the capacity to manipulate private storage (e.g., inserting new note hashes, potentially as part of transferring funds from the public domain to the private domain). -![Public - Private Messaging](./images/calls/pub_pvt_messaging.png) +![Public - Private Messaging](/img/protocol-specs/calls/pub_pvt_messaging.png) diff --git a/yellow-paper/docs/calls/static-calls.md b/docs/docs/protocol-specs/calls/static-calls.md similarity index 100% rename from yellow-paper/docs/calls/static-calls.md rename to docs/docs/protocol-specs/calls/static-calls.md diff --git a/yellow-paper/docs/calls/sync-calls.md b/docs/docs/protocol-specs/calls/sync-calls.md similarity index 100% rename from yellow-paper/docs/calls/sync-calls.md rename to docs/docs/protocol-specs/calls/sync-calls.md diff --git a/yellow-paper/docs/calls/unconstrained-calls.md b/docs/docs/protocol-specs/calls/unconstrained-calls.md similarity index 100% rename from yellow-paper/docs/calls/unconstrained-calls.md rename to docs/docs/protocol-specs/calls/unconstrained-calls.md diff --git a/yellow-paper/docs/circuits/high-level-topology.md b/docs/docs/protocol-specs/circuits/high-level-topology.md similarity index 100% rename from yellow-paper/docs/circuits/high-level-topology.md rename to docs/docs/protocol-specs/circuits/high-level-topology.md diff --git a/yellow-paper/docs/circuits/private-function.md b/docs/docs/protocol-specs/circuits/private-function.md similarity index 100% rename from yellow-paper/docs/circuits/private-function.md rename to docs/docs/protocol-specs/circuits/private-function.md diff --git a/yellow-paper/docs/circuits/private-kernel-initial.mdx b/docs/docs/protocol-specs/circuits/private-kernel-initial.mdx similarity index 100% rename from yellow-paper/docs/circuits/private-kernel-initial.mdx rename to docs/docs/protocol-specs/circuits/private-kernel-initial.mdx diff --git a/yellow-paper/docs/circuits/private-kernel-inner.mdx b/docs/docs/protocol-specs/circuits/private-kernel-inner.mdx similarity index 100% rename from yellow-paper/docs/circuits/private-kernel-inner.mdx rename to docs/docs/protocol-specs/circuits/private-kernel-inner.mdx diff --git a/yellow-paper/docs/circuits/private-kernel-reset.md b/docs/docs/protocol-specs/circuits/private-kernel-reset.md similarity index 100% rename from yellow-paper/docs/circuits/private-kernel-reset.md rename to docs/docs/protocol-specs/circuits/private-kernel-reset.md diff --git a/yellow-paper/docs/circuits/private-kernel-tail.md b/docs/docs/protocol-specs/circuits/private-kernel-tail.md similarity index 100% rename from yellow-paper/docs/circuits/private-kernel-tail.md rename to docs/docs/protocol-specs/circuits/private-kernel-tail.md diff --git a/yellow-paper/docs/circuits/public-kernel-initial.md b/docs/docs/protocol-specs/circuits/public-kernel-initial.md similarity index 100% rename from yellow-paper/docs/circuits/public-kernel-initial.md rename to docs/docs/protocol-specs/circuits/public-kernel-initial.md diff --git a/yellow-paper/docs/circuits/public-kernel-inner.md b/docs/docs/protocol-specs/circuits/public-kernel-inner.md similarity index 100% rename from yellow-paper/docs/circuits/public-kernel-inner.md rename to docs/docs/protocol-specs/circuits/public-kernel-inner.md diff --git a/yellow-paper/docs/circuits/public-kernel-tail.md b/docs/docs/protocol-specs/circuits/public-kernel-tail.md similarity index 100% rename from yellow-paper/docs/circuits/public-kernel-tail.md rename to docs/docs/protocol-specs/circuits/public-kernel-tail.md diff --git a/yellow-paper/docs/constants.md b/docs/docs/protocol-specs/constants.md similarity index 100% rename from yellow-paper/docs/constants.md rename to docs/docs/protocol-specs/constants.md diff --git a/yellow-paper/docs/contract-deployment/classes.md b/docs/docs/protocol-specs/contract-deployment/classes.md similarity index 100% rename from yellow-paper/docs/contract-deployment/classes.md rename to docs/docs/protocol-specs/contract-deployment/classes.md diff --git a/yellow-paper/docs/contract-deployment/index.md b/docs/docs/protocol-specs/contract-deployment/index.md similarity index 100% rename from yellow-paper/docs/contract-deployment/index.md rename to docs/docs/protocol-specs/contract-deployment/index.md diff --git a/yellow-paper/docs/contract-deployment/instances.md b/docs/docs/protocol-specs/contract-deployment/instances.md similarity index 100% rename from yellow-paper/docs/contract-deployment/instances.md rename to docs/docs/protocol-specs/contract-deployment/instances.md diff --git a/yellow-paper/docs/cryptography/hashing/hashing.md b/docs/docs/protocol-specs/cryptography/hashing/hashing.md similarity index 100% rename from yellow-paper/docs/cryptography/hashing/hashing.md rename to docs/docs/protocol-specs/cryptography/hashing/hashing.md diff --git a/yellow-paper/docs/cryptography/hashing/pedersen.md b/docs/docs/protocol-specs/cryptography/hashing/pedersen.md similarity index 100% rename from yellow-paper/docs/cryptography/hashing/pedersen.md rename to docs/docs/protocol-specs/cryptography/hashing/pedersen.md diff --git a/yellow-paper/docs/cryptography/hashing/poseidon2.md b/docs/docs/protocol-specs/cryptography/hashing/poseidon2.md similarity index 100% rename from yellow-paper/docs/cryptography/hashing/poseidon2.md rename to docs/docs/protocol-specs/cryptography/hashing/poseidon2.md diff --git a/yellow-paper/docs/cryptography/index.md b/docs/docs/protocol-specs/cryptography/index.md similarity index 100% rename from yellow-paper/docs/cryptography/index.md rename to docs/docs/protocol-specs/cryptography/index.md diff --git a/yellow-paper/docs/cryptography/merkle-trees.md b/docs/docs/protocol-specs/cryptography/merkle-trees.md similarity index 100% rename from yellow-paper/docs/cryptography/merkle-trees.md rename to docs/docs/protocol-specs/cryptography/merkle-trees.md diff --git a/yellow-paper/docs/cryptography/proving-system/data-bus.md b/docs/docs/protocol-specs/cryptography/proving-system/data-bus.md similarity index 100% rename from yellow-paper/docs/cryptography/proving-system/data-bus.md rename to docs/docs/protocol-specs/cryptography/proving-system/data-bus.md diff --git a/yellow-paper/docs/cryptography/proving-system/overview.md b/docs/docs/protocol-specs/cryptography/proving-system/overview.md similarity index 98% rename from yellow-paper/docs/cryptography/proving-system/overview.md rename to docs/docs/protocol-specs/cryptography/proving-system/overview.md index f7f786a257e..354702a5d9d 100644 --- a/yellow-paper/docs/cryptography/proving-system/overview.md +++ b/docs/docs/protocol-specs/cryptography/proving-system/overview.md @@ -122,4 +122,4 @@ To batch-verify multiple opening proofs, we use the technique articulated in the The following block diagrams describe the components used by the client-side and server-side Provers when computing client proofs and rollup proofs respectively. -![proof-system-components](../images/proof-system-components.png) +![proof-system-components](/img/protocol-specs/cryptography/proof-system-components.png) diff --git a/yellow-paper/docs/cryptography/proving-system/performance-targets.md b/docs/docs/protocol-specs/cryptography/proving-system/performance-targets.md similarity index 100% rename from yellow-paper/docs/cryptography/proving-system/performance-targets.md rename to docs/docs/protocol-specs/cryptography/proving-system/performance-targets.md diff --git a/yellow-paper/docs/data-publication-and-availability/index.md b/docs/docs/protocol-specs/data-publication-and-availability/index.md similarity index 100% rename from yellow-paper/docs/data-publication-and-availability/index.md rename to docs/docs/protocol-specs/data-publication-and-availability/index.md diff --git a/yellow-paper/docs/data-publication-and-availability/overview.md b/docs/docs/protocol-specs/data-publication-and-availability/overview.md similarity index 100% rename from yellow-paper/docs/data-publication-and-availability/overview.md rename to docs/docs/protocol-specs/data-publication-and-availability/overview.md diff --git a/yellow-paper/docs/data-publication-and-availability/published-data.md b/docs/docs/protocol-specs/data-publication-and-availability/published-data.md similarity index 100% rename from yellow-paper/docs/data-publication-and-availability/published-data.md rename to docs/docs/protocol-specs/data-publication-and-availability/published-data.md diff --git a/yellow-paper/docs/decentralization/actors.md b/docs/docs/protocol-specs/decentralization/actors.md similarity index 100% rename from yellow-paper/docs/decentralization/actors.md rename to docs/docs/protocol-specs/decentralization/actors.md diff --git a/yellow-paper/docs/decentralization/block-production.md b/docs/docs/protocol-specs/decentralization/block-production.md similarity index 99% rename from yellow-paper/docs/decentralization/block-production.md rename to docs/docs/protocol-specs/decentralization/block-production.md index f554c304865..43731b8d14f 100644 --- a/yellow-paper/docs/decentralization/block-production.md +++ b/docs/docs/protocol-specs/decentralization/block-production.md @@ -115,7 +115,7 @@ Anyone ->> Network: eligible as a sequencer - get rid of "pre-confirmed" ::: -![Governance Summary Image](./images/Aztec-Block-Production-1.png) +![Governance Summary Image](/img/protocol-specs/decentralization/Aztec-Block-Production-1.png) Every staked sequencers participate in the following phases, comprising an Aztec slot: @@ -275,7 +275,7 @@ It is likely that this proving ecosystem will emerge around a [flashbots mev-boo Specifically, Proof boost is expected to be open source software sequencers can optionally run alongside their clients that will facilitate a negotiation for the rights to prove this block, therefore earning block rewards in the form of the native protocol token. After the negotiation, the sequencer will commit to an address, and that address will need to put up an economic commitment (deposit) that will be slashed in the event that the block's proofs are not produced within the alloted timeframe. -![image](./images/Aztec-Block-Production-3.png) +![image](/img/protocol-specs/decentralization/Aztec-Block-Production-3.png) Initially it's expected that the negotiations and commitment could be facilitated by a trusted relay, similar to L1 block building, but options such as onchain proving pools are under consideration. Due to the out of protocol nature of [Sidecar](https://forum.aztec.network/t/proposal-prover-coordination-sidecar/2428), these designs can be iterated and improved upon outside the scope of other Aztec related governance or upgrades - as long as they maintain compatibility with the currently utilized proving system(s). Eventually, any upgrade or governance mechanism may choose to enshrine a specific well adopted proving protocol, if it makes sense to do so. diff --git a/yellow-paper/docs/decentralization/governance.md b/docs/docs/protocol-specs/decentralization/governance.md similarity index 97% rename from yellow-paper/docs/decentralization/governance.md rename to docs/docs/protocol-specs/decentralization/governance.md index 249b3149edf..ee7208b76f9 100644 --- a/yellow-paper/docs/decentralization/governance.md +++ b/docs/docs/protocol-specs/decentralization/governance.md @@ -12,13 +12,13 @@ These instances may choose to be immutable themselves, or have governance that e The version registry will keep track of all historical versions of Aztec & provide them with incentives proportionate to their current stake. Additionally the governance contract will point to what the _current canonical_ version of Aztec is, particularly relevant for 3rd parties to follow, such as centralized exchanges, or portals that wish to follow Aztec governance. -![Governance Summary Image](./images/Aztec-Governance-Summary-1.png) +![Governance Summary Image](/img/protocol-specs/decentralization/Aztec-Governance-Summary-1.png) ## Rewards We propose introducing a governance "version registry" which keeps track of a) which deployments of Aztec have been canonical, and b) which instances currently have tokens staked to them, specifically in order to issue a consistent, single new token in the form of _incentives_ or "rollup/block rewards". -![Rewards Summary Image](./images/Aztec-Governance-Summary-2.png) +![Rewards Summary Image](/img/protocol-specs/decentralization/Aztec-Governance-Summary-2.png) Given that deployments may be immutable, it is necessary to ensure that there are operators, i.e., sequencers & provers, running the infrastructure for a given deployment as long as users are interested in it. Therefore we suggest a model where all previous canonical instances of Aztec are rewarded pro-rata to their current proportion of stake. @@ -35,11 +35,11 @@ Upon initial deployment, there will be an immutable set of governance contracts The initial instance will be called "Aztec v0" and (the current thinking is that v0) will not include the ability to process user transactions. Sequencers can register for Fernet's sequencer selection algorithm by staking tokens to that particular instance, and practice proposing blocks on mainnet prior to deciding to "go live" with v1, which _does_ enable the processing of user transactions. This instance would then _"restake"_ these tokens within the governance contract, to have a voting weight equal to the amount of tokens staked by its sequencer set. This is in order to ensure that the sequencer selection algorithm is working properly and the community of operators themselves can decide what happens to the network next, i.e., if it's ready to actually "go live" with transactions. It will also serve as a production readiness test of the upgradeability. In the event that these v0 tests are unable to be successfully completed as expected, the community (with potential foundation approval) may need to redeploy and try again. -![Initial Deployment Image](./images/Aztec-Governance-Summary-3.png) +![Initial Deployment Image](/img/protocol-specs/decentralization/Aztec-Governance-Summary-3.png) The ability to upgrade to v1 is articulated below, and should follow a "happy path" upgrade where a majority of the v0 sequencer set must agree to upgrade by voting during their block proposals, similar to what was articulated in [the empire stakes back](https://forum.aztec.network/t/upgrade-proposal-the-empire-stakes-back/626). Additionally, token holders can directly participate in the vote, or choose to delegate a vote with the weight of their tokens to another address, including the v0 rollup. -![Version 1 Deployment Image](./images/Aztec-Governance-Summary-4.png) +![Version 1 Deployment Image](/img/protocol-specs/decentralization/Aztec-Governance-Summary-4.png) ## Proposing a new version @@ -224,7 +224,7 @@ Sequencers ->> Next Rollup: Proposing new blocks here! Emergency mode is proposed to be introduced to the initial instance "v0" or "v1" of Aztec, whatever the first instance or deployment is. Emergency mode **will not be included as part of the canonical governance contracts or registry**. If future deployments wish to have a similar security council, they can choose to do so. In this design, the current rollup can determine the timelock period as articulated above, within some predefined constraints, e.g., 3-30 days. Explicitly, the current rollup can give a security council the ability to define what this timelock period may be, and in the case of a potential vulnerability or otherwise, may be well within it's rights to choose the smallest value defined by the immutable governance contract to ensure that the network is able to recover and come back online as quickly as possible. -![Emergency Mode Image](./images/Aztec-Governance-Summary-4.png) +![Emergency Mode Image](/img/protocol-specs/decentralization/Aztec-Governance-Summary-4.png) ### Unpausing by default diff --git a/yellow-paper/docs/decentralization/p2p-network.md b/docs/docs/protocol-specs/decentralization/p2p-network.md similarity index 91% rename from yellow-paper/docs/decentralization/p2p-network.md rename to docs/docs/protocol-specs/decentralization/p2p-network.md index 69e2206e7eb..62c1bbe4c7f 100644 --- a/yellow-paper/docs/decentralization/p2p-network.md +++ b/docs/docs/protocol-specs/decentralization/p2p-network.md @@ -29,7 +29,7 @@ Anyone can operate an instance of the Aztec Node configured to serve their needs Client PXEs will interact with instances of the Aztec Node via it's JSON RPC interface. -![P2P Network](./images/network.png) +![P2P Network](/img/protocol-specs/decentralization/network.png) ### Transaction Size @@ -40,7 +40,6 @@ Client PXEs will interact with instances of the Aztec Node via it's JSON RPC int | Public Inputs, Public Calls and Emitted Logs | ~8KB | | Private Kernel Proof | ~32KB | - ### Sequencer-to-Prover Communication Proving is an out-of-protocol activity. The nature of the communication between sequencers and provers will depend entirely on the prover/s selected by the sequencer. Provers may choose to run their own Transaction Pool Node infrastructure so that they are prepared for generating proofs and don't need to receive this data out-of-band. @@ -82,11 +81,11 @@ The underlying transport for DiscV5 communication is UDP. Whilst UDP is not reli ##### Bootstrapping -When a node wishes to join the network for the first time. It needs to locate at least 1 initial peer in order to 'discover' other nodes. This role is performed by known public 'bootnodes'. Bootnodes may not be full network participants, they may simply be entrypoints containing well populated routing tables for nodes to query. +When a node wishes to join the network for the first time. It needs to locate at least 1 initial peer in order to 'discover' other nodes. This role is performed by known public 'bootnodes'. Bootnodes may not be full network participants, they may simply be entrypoints containing well populated routing tables for nodes to query. ##### Topics -Topics are part of the DiscV5 specification, though the spec is as yet unfinished and implementations do not yet exist. The intention of topics is for the Ethereum P2P network to efficiently support any number of applications under the same discovery scheme. To date, many other applications use Ethereum's discovery network but the only way to 'discover' other nodes for the same application is to query nodes at random and interrogate them. Topics will allow this to be done more efficiently with nodes being able to 'advertise' themselves as supporting specific applications across the network. +Topics are part of the DiscV5 specification, though the spec is as yet unfinished and implementations do not yet exist. The intention of topics is for the Ethereum P2P network to efficiently support any number of applications under the same discovery scheme. To date, many other applications use Ethereum's discovery network but the only way to 'discover' other nodes for the same application is to query nodes at random and interrogate them. Topics will allow this to be done more efficiently with nodes being able to 'advertise' themselves as supporting specific applications across the network. ##### DiscV5 on Aztec @@ -100,17 +99,16 @@ Using Ethereum's DiscV5 network will have significant benefits for Aztec. Networ The node record for an Aztec node will contain the following key/value pairs. The network endpoints don't all need to be specified but nodes will require at least one ip address and port. The public key is required to verify the signature included with the node record. The id is the identity scheme with "v4" being that currently used by Ethereum. - -| key | value | -| -------- | -------- | -| id | "v4" | -| secp256k1 | The node's public key | -| ip | ipv4 address | -| tcp | tcp port | -| ip6 | ipv6 address | -| tcp6 | tcp port for v6 address | -| aztec | The aztec chain id | -| eth | The ethereum chain id | +| key | value | +| --------- | ----------------------- | +| id | "v4" | +| secp256k1 | The node's public key | +| ip | ipv4 address | +| tcp | tcp port | +| ip6 | ipv6 address | +| tcp6 | tcp port for v6 address | +| aztec | The aztec chain id | +| eth | The ethereum chain id | ### Transaction Gossip @@ -128,7 +126,7 @@ LibP2P supports the multiplexing of stream based transports such as TCP. There a #### Encryption handshake -Communication between nodes within LibP2P is encrypted. This is important to protect individual nodes and the network at large from malicious actors. Establishing keys requires a secure handshake protocol. Client's must specify LibP2P's [noise](https://docs.libp2p.io/concepts/secure-comm/noise/) protocol for this purpose. +Communication between nodes within LibP2P is encrypted. This is important to protect individual nodes and the network at large from malicious actors. Establishing keys requires a secure handshake protocol. Client's must specify LibP2P's [noise](https://docs.libp2p.io/concepts/secure-comm/noise/) protocol for this purpose. #### GossipSub @@ -161,17 +159,16 @@ Aztec will use LibP2P's GossipSub protocol for transaction propagation. Nodes mu The table below contains some of the relevant configuration properties and their default values. These parameters can be validated on testnet but it is expected that for the Aztec network, clients would use similar values, perhaps reducing peering degree slightly to favour reduced bandwidth over message propagation latency. +| Parameter | Description | Value | +| ------------------ | -------------------------------------------------------------------- | -------- | +| D | The desired peering degree | 6 | +| D_low | The peering degree low watermark | 4 | +| D_high | The peering degree high watermark | 12 | +| heartbeat_interval | The time between heartbeats\* | 1 second | +| mcache_len | The number of history windows before messages are ejected from cache | 5 | +| mcache_gossip | The number of history windows for messages to be gossiped | 3 | -| Parameter | Description | Value | -| -------- | -------- | -------- | -| D | The desired peering degree | 6 | -| D_low | The peering degree low watermark | 4 | -| D_high | The peering degree high watermark | 12 | -| heartbeat_interval | The time between heartbeats* | 1 second | -| mcache_len | The number of history windows before messages are ejected from cache | 5 | -| mcache_gossip | The number of history windows for messages to be gossiped | 3 | - -(*)Several things happen at the heartbeat interval: +(\*)Several things happen at the heartbeat interval: 1. The nature of peerings are evaluated and changed if necessary 2. Message IDs are gossiped to a randomly selected set of metadata only peers @@ -197,6 +194,6 @@ GossipSub does not include a mechanism for synchronising the global set of messa 1. Aztec transactions are large, approximately 40Kb. Downloading the entire pool would require transferring in the order of 100s of MB of data. At best this is undesirable and at worst it represents a DoS vector. -2. It is largely redundant. At the point at which a node joins the network, it is likely that production of a block is already underway and many of the transactions that would be downloaded will be removed as soon as that block is published. +2. It is largely redundant. At the point at which a node joins the network, it is likely that production of a block is already underway and many of the transactions that would be downloaded will be removed as soon as that block is published. -3. Clients will naturally synchronise the transaction pool by joining the gossiping network and waiting for 1 or 2 blocks. New transactions will be received into the client's local pool and old transactions unknown to the client will be removed as blocks are published. \ No newline at end of file +3. Clients will naturally synchronise the transaction pool by joining the gossiping network and waiting for 1 or 2 blocks. New transactions will be received into the client's local pool and old transactions unknown to the client will be removed as blocks are published. diff --git a/yellow-paper/docs/gas-and-fees/fee-payments-and-metering.md b/docs/docs/protocol-specs/gas-and-fees/fee-payments-and-metering.md similarity index 97% rename from yellow-paper/docs/gas-and-fees/fee-payments-and-metering.md rename to docs/docs/protocol-specs/gas-and-fees/fee-payments-and-metering.md index 22042f28de9..39b97c0abb8 100644 --- a/yellow-paper/docs/gas-and-fees/fee-payments-and-metering.md +++ b/docs/docs/protocol-specs/gas-and-fees/fee-payments-and-metering.md @@ -55,7 +55,7 @@ Transactions will be divided into 3 phases: All of these phases occur **within the same transaction**, ultimately resulting in 2 sets of public inputs being emitted from the private kernel circuits. Those related to the fee payment and those related to the application logic. State changes requested by the application logic are reverted if any component fails. State changes in the fee preparation and distribution components are only reverted if either of those components fail. -![Transaction Components](../gas-and-fees/images/gas-and-fees/Transaction.png) +![Transaction Components](/img/protocol-specs/gas-and-fees/gas-and-fees/Transaction.png) The fee preparation and fee distribution phases respectively are responsible for ensuring that sufficient quantity of the fee payment asset is made available for the transaction and that it is correctly distributed to the sequencer with any refund being returned to the transaction sender. The sequencer will have have agency over which contract methods they are willing to accept for execution in these phases and will have visibility over the arguments passed to them. This is important as these functions must be successfully executed in order for the sequencer to be paid. It is assumed that the network will settle on a number of universally recognised fee payment contracts implementing fee preparation and distribution. @@ -90,12 +90,12 @@ An example of L2 gas amortization could be the transaction sender specifying a m TotalGasToBeAmortised = (1024 - 2) * GMerge + GRoot L2AmortizedGasLimit = TotalGasToBeAmortised / 1024 -Where +Where GMerge = The gas cost of proving the merge rollup circuit. GRoot = The gas cost of proving the root rollup circuit. ``` -In this example, were the transaction to be included within a rollup larger than 1024 transactions, the transaction sender would be refunded this amortization difference. +In this example, were the transaction to be included within a rollup larger than 1024 transactions, the transaction sender would be refunded this amortization difference. The private kernel circuits will output 8 `Gas` values. The 6 `GasLimit`'s represent maximum quantities of gas that the transaction sender permits to be consumed. Insufficient limits will cause the transaction to revert with an `OutOfGas` condition. Fees will be refunded to the transaction sender for unused quantities of gas, The `FeeDistributionGas` values are fixed amounts of gas effectively representing fixed fees that the transaction sender is willing to pay for their chosen fee distribution. @@ -129,7 +129,7 @@ L1Fee = (L1AmortizedGasLimit + L1TxGasLimit) * feePerL1Gas L2Fee = (L2AmortizedGasLimit + L2TxGasLimit + L2FeeDistributionGas) * feePerL2Gas DAFee = (DAAmortizedGasLimit + DATxGasLimit + DAFeeDistributionGas) * feePerDAGas -TotalFee = L1Fee + L2Fee + DAFee +TotalFee = L1Fee + L2Fee + DAFee ``` ## Executing Transactions and Collecting Fees @@ -150,12 +150,11 @@ The transaction's fee preparation and fee distribution functions must be called | `DAGasUsed` | The accumulated quantity of DA gas used, both amortized and per-transaction | | `feeRecipient` | The aztec address designated as the recipient of fees for the current block | - The values of gas used must be calculated and applied appropriately by the sequencer, a variety of constraints are in place for this. 1. The sequencer specifies the size of rollup being produced to the base rollup circuit and uses this value when calculating amortized gas consumption. This value is a public input of the base rollup circuit. 2. The sequencer specifies the fee recipient to the base rollup circuit and uses this value in fee distribution calls. This value is a public input of the base rollup circuit. -3. The sequencer calculates an initial set of values for consumed transaction specific and amortized gas. +3. The sequencer calculates an initial set of values for consumed transaction specific and amortized gas. 4. All forms of gas usage are accumulated by the public VM circuit and form part of the public inputs for the public kernel circuit. 5. The public kernel circuit public inputs also include the gas and fee related inputs provided to the public VM circuit. 6. The base rollup circuit computes the total amount of L1, L2 and DA gas consumed by the transaction, considering both private and public execution and transaction specific and amortized gas. It also considers reverted public execution. These values are public inputs to the circuit. @@ -198,7 +197,7 @@ sequenceDiagram Alice->>AccountContract: run entrypoint AccountContract->>FPA: enqueue FPA.pay_fee(max_fee) msg_sender == Alice as fee distribution function AccountContract->>App: app logic - App->>AccountContract: + App->>AccountContract: AccountContract->>Alice: finished private execution Alice->>Sequencer: tx object @@ -208,7 +207,7 @@ sequenceDiagram FPA->>Sequencer: Alice has >= funds required from tx object Sequencer->>App: app logic - App->>Sequencer: + App->>Sequencer: Sequencer->>FPA: FPA.pay_fee(max_fee) FPA->>FPA: calculate fee based on inputs to VM circuit @@ -238,13 +237,13 @@ sequenceDiagram Alice->>Alice: transient auth witness for AST private transfer Alice->>AccountContract: run entrypoint AccountContract->>FPC: private_fee_entrypoint(AST, max_fee, nonce) - + FPC->>AST: AST.transfer(FPC, max_fee + commission, nonce) AST->>AccountContract: check auth witness FPC->>FPC: enqueue FPA.private_fee_payment(max_fee) msg_sender == FPC as fee distribution function - FPC->>AccountContract: + FPC->>AccountContract: AccountContract->>App: app logic - App->>AccountContract: + App->>AccountContract: AccountContract->>Alice: finished private execution Alice->>Sequencer: tx object @@ -254,7 +253,7 @@ sequenceDiagram FPA->>Sequencer: FPC has >= funds required from tx object Sequencer->>App: app logic - App->>Sequencer: + App->>Sequencer: Sequencer->>FPA: FPA.private_fee_payment(max_fee) FPA->>FPA: calculate fee based on inputs to VM circuit @@ -288,10 +287,10 @@ sequenceDiagram activate FPC FPC->>FPC: enqueue FPC.public_fee_preparation(Alice, AST, max_fee, nonce) as fee preparation with msg_sender == FPC FPC->>FPC: enqueue FPC.public_fee_payment(Alice, AST, max_fee) as fee distribution with msg_sender == FPC - FPC->>AccountContract: + FPC->>AccountContract: deactivate FPC AccountContract->>App: app logic - App->>AccountContract: + App->>AccountContract: AccountContract->>Alice: finished private execution Alice->>Sequencer: tx object @@ -301,15 +300,15 @@ sequenceDiagram activate FPC FPC->>AST: AST.transfer_public(Alice, FPC, max_fee + commission, nonce) AST->>AccountContract: check auth witness - AccountContract->>AST: - AST->>FPC: + AccountContract->>AST: + AST->>FPC: FPC->>FPA: FPA.check_balance(max_fee) - FPA->>FPC: + FPA->>FPC: FPC->>Sequencer: FPC has the funds deactivate FPC Sequencer->>App: app logic - App->>Sequencer: + App->>Sequencer: Sequencer->>Sequencer: Recognise whitelisted function FPC.public_fee_payment(Alice, AST, max_fee) and msg.sender == FPC Sequencer->>FPC: FPC.public_fee_payment(Alice, AST, max_fee) @@ -319,7 +318,7 @@ sequenceDiagram FPA->>Sequencer: Sequencer's balance is increased by fee amount FPA->>FPC: rebate value FPC->>AST: AST.transfer_public(FPC, Alice, rebate, 0) - AST->>FPC: + AST->>FPC: FPC->>Alice: Alice's balance is increased by rebate value deactivate FPC ``` @@ -343,7 +342,7 @@ sequenceDiagram Alice->>DApp: run entrypoint DApp->>AccountContract: check auth witness - AccountContract->>DApp: + AccountContract->>DApp: DApp->>DApp: check if will sponsor action DApp->>FPA: enqueue FPA.pay_fee(max_fee) and msg_sender == DApp as fee distribution DApp->>DApp: app logic @@ -356,7 +355,7 @@ sequenceDiagram FPA->>Sequencer: DApp has >= funds required from tx object Sequencer->>DApp: app logic - DApp->>Sequencer: + DApp->>Sequencer: Sequencer->>FPA: FPA.pay_fee(max_fee) FPA->>FPA: calculate fee based on inputs to VM circuit diff --git a/yellow-paper/docs/gas-and-fees/fee-schedule.md b/docs/docs/protocol-specs/gas-and-fees/fee-schedule.md similarity index 100% rename from yellow-paper/docs/gas-and-fees/fee-schedule.md rename to docs/docs/protocol-specs/gas-and-fees/fee-schedule.md diff --git a/yellow-paper/docs/gas-and-fees/index.md b/docs/docs/protocol-specs/gas-and-fees/index.md similarity index 100% rename from yellow-paper/docs/gas-and-fees/index.md rename to docs/docs/protocol-specs/gas-and-fees/index.md diff --git a/yellow-paper/docs/intro.md b/docs/docs/protocol-specs/intro.md similarity index 100% rename from yellow-paper/docs/intro.md rename to docs/docs/protocol-specs/intro.md diff --git a/yellow-paper/docs/l1-smart-contracts/frontier.md b/docs/docs/protocol-specs/l1-smart-contracts/frontier.md similarity index 87% rename from yellow-paper/docs/l1-smart-contracts/frontier.md rename to docs/docs/protocol-specs/l1-smart-contracts/frontier.md index 682c4b0e0a2..885ae870e0c 100644 --- a/yellow-paper/docs/l1-smart-contracts/frontier.md +++ b/docs/docs/protocol-specs/l1-smart-contracts/frontier.md @@ -5,21 +5,21 @@ title: Frontier Merkle Tree The Frontier Merkle Tree is an append only Merkle tree that is optimized for minimal storage on chain. By storing only the right-most non-empty node at each level of the tree we can always extend the tree with a new leaf or compute the root without needing to store the entire tree. We call these values the frontier of the tree. -If we have the next index to insert at and the current frontier, we have everything needed to extend the tree or compute the root, with much less storage than a full merkle tree. +If we have the next index to insert at and the current frontier, we have everything needed to extend the tree or compute the root, with much less storage than a full merkle tree. Note that we're not actually keeping track of the data in the tree: we only store what's minimally required in order to be able to compute the root after inserting a new element. We will go through a few diagrams and explanations to understand how this works. And then a pseudo implementation is provided. - ## Insertion + Whenever we are inserting, we need to update the "root" of the largest subtree possible. This is done by updating the node at the level of the tree, where we have just inserted its right-most descendant. -This can sound a bit confusing, so we will go through a few examples. +This can sound a bit confusing, so we will go through a few examples. At first, say that we have the following tree, and that it is currently entirely empty. -![alt text](images/frontier/image-1.png) +![alt text](/img/protocol-specs/l1-smart-contracts/frontier/image-1.png) ### The first leaf @@ -27,7 +27,7 @@ When we are inserting the first leaf (lets call it A), the largest subtree is th In this case, we simply need to store the leaf value in `frontier[0]` and then we are done. For the sake of visualization, we will be drawing the elements in the `frontier` in blue. -![alt text](images/frontier/image-2.png) +![alt text](/img/protocol-specs/l1-smart-contracts/frontier/image-2.png) Notice that this will be the case whenever we are inserting a leaf at an even index. @@ -40,13 +40,14 @@ Therefore, we will compute the root of this subtree, `H(frontier[0],B)` and stor Notice, that we don't need to store the leaf B itself, since we won't be needing it for any future computations. This is what makes the frontier tree efficient - we get away with storing very little data. -![alt text](images/frontier/image-3.png) +![alt text](/img/protocol-specs/l1-smart-contracts/frontier/image-3.png) ### Third leaf + When inserting the third leaf, we are again back to the largest subtree being filled by the insertion being itself at level 0. The update will look similar to the first, where we only update `frontier[0]` with the new leaf. -![alt text](images/frontier/image-4.png) +![alt text](/img/protocol-specs/l1-smart-contracts/frontier/image-4.png) ### Fourth leaf @@ -56,39 +57,39 @@ Now the largest subtree getting filled by the insertion is at level 2. To compute the new subtree root, we have to compute `F = H(frontier[0], E)` and then `G = H(frontier[1], F)`. G is then stored in `frontier[2]`. - -As before, notice that we are only updating one value in the frontier. -![alt text](images/frontier/image-5.png) +As before, notice that we are only updating one value in the frontier. +![alt text](/img/protocol-specs/l1-smart-contracts/frontier/image-5.png) ## Figuring out what to update To figure out which level to update in the frontier, we simply need to figure out what the height is of the largest subtree that is filled by the insertion. -While this might sound complex, it is actually quite simple. +While this might sound complex, it is actually quite simple. Consider the following extension of the diagram. We have added the level to update, along with the index of the leaf in binary. Seeing any pattern? -![alt text](images/frontier/image-6.png) +![alt text](/img/protocol-specs/l1-smart-contracts/frontier/image-6.png) The level to update is simply the number of trailing ones in the binary representation of the index. -For a binary tree, we have that every `1` in the binary index represents a "right turn" down the tree. +For a binary tree, we have that every `1` in the binary index represents a "right turn" down the tree. Walking up the tree from the leaf, we can simply count the number of right turns until we hit a left-turn. ## How to compute the root -Computing the root based on the frontier is also quite simple. +Computing the root based on the frontier is also quite simple. We can use the last index inserted a leaf at to figure out how high up the frontier we should start. -Then we know that anything that is at the right of the frontier has not yet been inserted, so all of these values are simply "zeros" values. +Then we know that anything that is at the right of the frontier has not yet been inserted, so all of these values are simply "zeros" values. Zeros here are understood as the root for a subtree only containing zeros. For example, if we take the tree from above and compute the root for it, we would see that level 2 was updated last. Meaning that we can simply compute the root as `H(frontier[2], zeros[2])`. -![alt text](images/frontier/image-7.png) +![alt text](/img/protocol-specs/l1-smart-contracts/frontier/image-7.png) For cases where we have built further, we simply "walk" up the tree and use either the frontier value or the zero value for the level. ## Pseudo implementation + ```python class FrontierTree: HEIGHT: immutable(uint256) @@ -107,7 +108,7 @@ class FrontierTree: def compute_level(_index: uint256) -> uint256: ''' - We can get the right of the most filled subtree by + We can get the right of the most filled subtree by counting the number of trailing ones in the index ''' count = 0 @@ -154,6 +155,5 @@ class FrontierTree: ``` ## Optimizations -- The `zeros` can be pre-computed and stored in the `Inbox` directly, this way they can be shared across all of the trees. - +- The `zeros` can be pre-computed and stored in the `Inbox` directly, this way they can be shared across all of the trees. diff --git a/yellow-paper/docs/l1-smart-contracts/index.md b/docs/docs/protocol-specs/l1-smart-contracts/index.md similarity index 100% rename from yellow-paper/docs/l1-smart-contracts/index.md rename to docs/docs/protocol-specs/l1-smart-contracts/index.md diff --git a/yellow-paper/docs/logs/index.md b/docs/docs/protocol-specs/logs/index.md similarity index 100% rename from yellow-paper/docs/logs/index.md rename to docs/docs/protocol-specs/logs/index.md diff --git a/yellow-paper/docs/pre-compiled-contracts/index.md b/docs/docs/protocol-specs/pre-compiled-contracts/index.md similarity index 100% rename from yellow-paper/docs/pre-compiled-contracts/index.md rename to docs/docs/protocol-specs/pre-compiled-contracts/index.md diff --git a/yellow-paper/docs/pre-compiled-contracts/registry.md b/docs/docs/protocol-specs/pre-compiled-contracts/registry.md similarity index 100% rename from yellow-paper/docs/pre-compiled-contracts/registry.md rename to docs/docs/protocol-specs/pre-compiled-contracts/registry.md diff --git a/yellow-paper/docs/private-message-delivery/index.md b/docs/docs/protocol-specs/private-message-delivery/index.md similarity index 100% rename from yellow-paper/docs/private-message-delivery/index.md rename to docs/docs/protocol-specs/private-message-delivery/index.md diff --git a/yellow-paper/docs/private-message-delivery/private-msg-delivery.md b/docs/docs/protocol-specs/private-message-delivery/private-msg-delivery.md similarity index 100% rename from yellow-paper/docs/private-message-delivery/private-msg-delivery.md rename to docs/docs/protocol-specs/private-message-delivery/private-msg-delivery.md diff --git a/yellow-paper/docs/private-message-delivery/send-note-guidelines.md b/docs/docs/protocol-specs/private-message-delivery/send-note-guidelines.md similarity index 100% rename from yellow-paper/docs/private-message-delivery/send-note-guidelines.md rename to docs/docs/protocol-specs/private-message-delivery/send-note-guidelines.md diff --git a/yellow-paper/docs/public-vm/_nested-context.md b/docs/docs/protocol-specs/public-vm/_nested-context.md similarity index 100% rename from yellow-paper/docs/public-vm/_nested-context.md rename to docs/docs/protocol-specs/public-vm/_nested-context.md diff --git a/yellow-paper/docs/public-vm/alu.md b/docs/docs/protocol-specs/public-vm/alu.md similarity index 97% rename from yellow-paper/docs/public-vm/alu.md rename to docs/docs/protocol-specs/public-vm/alu.md index d4c0066d936..bf30043974c 100644 --- a/yellow-paper/docs/public-vm/alu.md +++ b/docs/docs/protocol-specs/public-vm/alu.md @@ -6,7 +6,7 @@ This component of the VM circuit evaluates both base-2 arithmetic operations and The following block diagram maps out an draft of the internal components of the "ALU" -![](./images/alu.png) +![](/img/protocol-specs/public-vm/alu.png) Notes: diff --git a/yellow-paper/docs/public-vm/avm-circuit.md b/docs/docs/protocol-specs/public-vm/avm-circuit.md similarity index 100% rename from yellow-paper/docs/public-vm/avm-circuit.md rename to docs/docs/protocol-specs/public-vm/avm-circuit.md diff --git a/yellow-paper/docs/public-vm/bytecode-validation-circuit.md b/docs/docs/protocol-specs/public-vm/bytecode-validation-circuit.md similarity index 100% rename from yellow-paper/docs/public-vm/bytecode-validation-circuit.md rename to docs/docs/protocol-specs/public-vm/bytecode-validation-circuit.md diff --git a/yellow-paper/docs/public-vm/circuit-index.md b/docs/docs/protocol-specs/public-vm/circuit-index.md similarity index 100% rename from yellow-paper/docs/public-vm/circuit-index.md rename to docs/docs/protocol-specs/public-vm/circuit-index.md diff --git a/yellow-paper/docs/public-vm/context.mdx b/docs/docs/protocol-specs/public-vm/context.mdx similarity index 100% rename from yellow-paper/docs/public-vm/context.mdx rename to docs/docs/protocol-specs/public-vm/context.mdx diff --git a/yellow-paper/docs/public-vm/control-flow.md b/docs/docs/protocol-specs/public-vm/control-flow.md similarity index 100% rename from yellow-paper/docs/public-vm/control-flow.md rename to docs/docs/protocol-specs/public-vm/control-flow.md diff --git a/yellow-paper/docs/public-vm/execution.md b/docs/docs/protocol-specs/public-vm/execution.md similarity index 100% rename from yellow-paper/docs/public-vm/execution.md rename to docs/docs/protocol-specs/public-vm/execution.md diff --git a/yellow-paper/docs/public-vm/gen/_instruction-set.mdx b/docs/docs/protocol-specs/public-vm/gen/_instruction-set.mdx similarity index 100% rename from yellow-paper/docs/public-vm/gen/_instruction-set.mdx rename to docs/docs/protocol-specs/public-vm/gen/_instruction-set.mdx diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/ADD.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/ADD.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/ADD.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/ADD.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/ADDRESS.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/ADDRESS.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/ADDRESS.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/ADDRESS.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/AND.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/AND.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/AND.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/AND.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKDAGASLIMIT.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/BLOCKDAGASLIMIT.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKDAGASLIMIT.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/BLOCKDAGASLIMIT.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKHEADERBYNUM.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/BLOCKHEADERBYNUM.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKHEADERBYNUM.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/BLOCKHEADERBYNUM.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKL1GASLIMIT.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/BLOCKL1GASLIMIT.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKL1GASLIMIT.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/BLOCKL1GASLIMIT.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKL2GASLIMIT.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/BLOCKL2GASLIMIT.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKL2GASLIMIT.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/BLOCKL2GASLIMIT.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKNUMBER.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/BLOCKNUMBER.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKNUMBER.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/BLOCKNUMBER.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/CALL.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/CALL.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/CALL.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/CALL.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/CALLDATACOPY.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/CALLDATACOPY.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/CALLDATACOPY.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/CALLDATACOPY.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/CAST.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/CAST.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/CAST.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/CAST.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/CHAINID.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/CHAINID.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/CHAINID.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/CHAINID.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/CMOV.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/CMOV.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/CMOV.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/CMOV.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/COINBASE.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/COINBASE.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/COINBASE.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/COINBASE.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/CONTRACTCALLDEPTH.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/CONTRACTCALLDEPTH.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/CONTRACTCALLDEPTH.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/CONTRACTCALLDEPTH.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/DAGASLEFT.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/DAGASLEFT.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/DAGASLEFT.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/DAGASLEFT.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/DIV.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/DIV.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/DIV.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/DIV.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/EMITNOTEHASH.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/EMITNOTEHASH.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/EMITNOTEHASH.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/EMITNOTEHASH.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/EMITNULLIFIER.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/EMITNULLIFIER.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/EMITNULLIFIER.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/EMITNULLIFIER.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/EMITUNENCRYPTEDLOG.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/EMITUNENCRYPTEDLOG.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/EMITUNENCRYPTEDLOG.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/EMITUNENCRYPTEDLOG.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/EQ.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/EQ.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/EQ.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/EQ.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/FEEPERDAGAS.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/FEEPERDAGAS.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/FEEPERDAGAS.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/FEEPERDAGAS.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/FEEPERL1GAS.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/FEEPERL1GAS.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/FEEPERL1GAS.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/FEEPERL1GAS.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/FEEPERL2GAS.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/FEEPERL2GAS.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/FEEPERL2GAS.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/FEEPERL2GAS.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/INTERNALCALLDEPTH.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/INTERNALCALLDEPTH.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/INTERNALCALLDEPTH.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/INTERNALCALLDEPTH.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/INTERNALRETURN.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/INTERNALRETURN.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/INTERNALRETURN.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/INTERNALRETURN.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/JUMP.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/JUMP.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/JUMP.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/JUMP.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/JUMPI.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/JUMPI.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/JUMPI.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/JUMPI.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/L1GASLEFT.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/L1GASLEFT.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/L1GASLEFT.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/L1GASLEFT.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/L2GASLEFT.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/L2GASLEFT.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/L2GASLEFT.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/L2GASLEFT.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/LT.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/LT.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/LT.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/LT.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/LTE.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/LTE.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/LTE.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/LTE.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/MOV.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/MOV.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/MOV.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/MOV.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/MUL.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/MUL.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/MUL.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/MUL.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/NOT.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/NOT.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/NOT.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/NOT.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/OR.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/OR.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/OR.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/OR.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/ORIGIN.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/ORIGIN.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/ORIGIN.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/ORIGIN.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/PORTAL.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/PORTAL.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/PORTAL.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/PORTAL.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/READL1TOL2MSG.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/READL1TOL2MSG.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/READL1TOL2MSG.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/READL1TOL2MSG.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/RETURN.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/RETURN.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/RETURN.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/RETURN.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/REVERT.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/REVERT.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/REVERT.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/REVERT.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/SENDER.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SENDER.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/SENDER.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SENDER.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/SENDL2TOL1MSG.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SENDL2TOL1MSG.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/SENDL2TOL1MSG.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SENDL2TOL1MSG.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/SET.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SET.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/SET.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SET.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/SHL.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SHL.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/SHL.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SHL.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/SHR.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SHR.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/SHR.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SHR.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/SLOAD.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SLOAD.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/SLOAD.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SLOAD.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/SSTORE.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SSTORE.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/SSTORE.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SSTORE.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/STATICCALL.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/STATICCALL.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/STATICCALL.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/STATICCALL.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/STORAGEADDRESS.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/STORAGEADDRESS.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/STORAGEADDRESS.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/STORAGEADDRESS.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/SUB.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SUB.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/SUB.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/SUB.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/TIMESTAMP.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/TIMESTAMP.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/TIMESTAMP.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/TIMESTAMP.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/VERSION.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/VERSION.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/VERSION.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/VERSION.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/XOR.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/XOR.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/XOR.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/XOR.png diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/internalcall.png b/docs/docs/protocol-specs/public-vm/gen/images/bit-formats/internalcall.png similarity index 100% rename from yellow-paper/docs/public-vm/gen/images/bit-formats/internalcall.png rename to docs/docs/protocol-specs/public-vm/gen/images/bit-formats/internalcall.png diff --git a/yellow-paper/docs/public-vm/index.md b/docs/docs/protocol-specs/public-vm/index.md similarity index 100% rename from yellow-paper/docs/public-vm/index.md rename to docs/docs/protocol-specs/public-vm/index.md diff --git a/yellow-paper/docs/public-vm/instruction-set.mdx b/docs/docs/protocol-specs/public-vm/instruction-set.mdx similarity index 100% rename from yellow-paper/docs/public-vm/instruction-set.mdx rename to docs/docs/protocol-specs/public-vm/instruction-set.mdx diff --git a/yellow-paper/docs/public-vm/intro.md b/docs/docs/protocol-specs/public-vm/intro.md similarity index 100% rename from yellow-paper/docs/public-vm/intro.md rename to docs/docs/protocol-specs/public-vm/intro.md diff --git a/yellow-paper/docs/public-vm/memory-model.md b/docs/docs/protocol-specs/public-vm/memory-model.md similarity index 99% rename from yellow-paper/docs/public-vm/memory-model.md rename to docs/docs/protocol-specs/public-vm/memory-model.md index 62c6912a13e..1fea8c66985 100644 --- a/yellow-paper/docs/public-vm/memory-model.md +++ b/docs/docs/protocol-specs/public-vm/memory-model.md @@ -6,7 +6,7 @@ This section describes the AVM memory model, and in particular specifies "intern The AVM possesses three distinct data regions, accessed via distinct VM instructions: memory, calldata and returndata -![](./images/memory.png) +![](/img/protocol-specs/public-vm/memory.png) All data regions are linear blocks of memory where each memory cell stores a finite field element. diff --git a/yellow-paper/docs/public-vm/nested-calls.mdx b/docs/docs/protocol-specs/public-vm/nested-calls.mdx similarity index 100% rename from yellow-paper/docs/public-vm/nested-calls.mdx rename to docs/docs/protocol-specs/public-vm/nested-calls.mdx diff --git a/yellow-paper/docs/public-vm/security.md b/docs/docs/protocol-specs/public-vm/security.md similarity index 100% rename from yellow-paper/docs/public-vm/security.md rename to docs/docs/protocol-specs/public-vm/security.md diff --git a/yellow-paper/docs/public-vm/state.md b/docs/docs/protocol-specs/public-vm/state.md similarity index 100% rename from yellow-paper/docs/public-vm/state.md rename to docs/docs/protocol-specs/public-vm/state.md diff --git a/yellow-paper/docs/public-vm/type-structs.md b/docs/docs/protocol-specs/public-vm/type-structs.md similarity index 100% rename from yellow-paper/docs/public-vm/type-structs.md rename to docs/docs/protocol-specs/public-vm/type-structs.md diff --git a/yellow-paper/docs/rollup-circuits/base-rollup.md b/docs/docs/protocol-specs/rollup-circuits/base-rollup.md similarity index 100% rename from yellow-paper/docs/rollup-circuits/base-rollup.md rename to docs/docs/protocol-specs/rollup-circuits/base-rollup.md diff --git a/yellow-paper/docs/rollup-circuits/index.md b/docs/docs/protocol-specs/rollup-circuits/index.md similarity index 100% rename from yellow-paper/docs/rollup-circuits/index.md rename to docs/docs/protocol-specs/rollup-circuits/index.md diff --git a/yellow-paper/docs/rollup-circuits/merge-rollup.md b/docs/docs/protocol-specs/rollup-circuits/merge-rollup.md similarity index 100% rename from yellow-paper/docs/rollup-circuits/merge-rollup.md rename to docs/docs/protocol-specs/rollup-circuits/merge-rollup.md diff --git a/yellow-paper/docs/rollup-circuits/root-rollup.md b/docs/docs/protocol-specs/rollup-circuits/root-rollup.md similarity index 100% rename from yellow-paper/docs/rollup-circuits/root-rollup.md rename to docs/docs/protocol-specs/rollup-circuits/root-rollup.md diff --git a/yellow-paper/docs/rollup-circuits/tree-parity.md b/docs/docs/protocol-specs/rollup-circuits/tree-parity.md similarity index 100% rename from yellow-paper/docs/rollup-circuits/tree-parity.md rename to docs/docs/protocol-specs/rollup-circuits/tree-parity.md diff --git a/yellow-paper/docs/state/archive.md b/docs/docs/protocol-specs/state/archive.md similarity index 100% rename from yellow-paper/docs/state/archive.md rename to docs/docs/protocol-specs/state/archive.md diff --git a/yellow-paper/docs/state/index.md b/docs/docs/protocol-specs/state/index.md similarity index 100% rename from yellow-paper/docs/state/index.md rename to docs/docs/protocol-specs/state/index.md diff --git a/yellow-paper/docs/state/note-hash-tree.md b/docs/docs/protocol-specs/state/note-hash-tree.md similarity index 100% rename from yellow-paper/docs/state/note-hash-tree.md rename to docs/docs/protocol-specs/state/note-hash-tree.md diff --git a/yellow-paper/docs/state/nullifier-tree.md b/docs/docs/protocol-specs/state/nullifier-tree.md similarity index 100% rename from yellow-paper/docs/state/nullifier-tree.md rename to docs/docs/protocol-specs/state/nullifier-tree.md diff --git a/yellow-paper/docs/state/public-data-tree.md b/docs/docs/protocol-specs/state/public-data-tree.md similarity index 100% rename from yellow-paper/docs/state/public-data-tree.md rename to docs/docs/protocol-specs/state/public-data-tree.md diff --git a/yellow-paper/docs/state/tree-implementations.md b/docs/docs/protocol-specs/state/tree-implementations.md similarity index 100% rename from yellow-paper/docs/state/tree-implementations.md rename to docs/docs/protocol-specs/state/tree-implementations.md diff --git a/yellow-paper/docs/todo.md b/docs/docs/protocol-specs/todo.md similarity index 100% rename from yellow-paper/docs/todo.md rename to docs/docs/protocol-specs/todo.md diff --git a/yellow-paper/docs/transactions/index.md b/docs/docs/protocol-specs/transactions/index.md similarity index 100% rename from yellow-paper/docs/transactions/index.md rename to docs/docs/protocol-specs/transactions/index.md diff --git a/yellow-paper/docs/transactions/local-execution.md b/docs/docs/protocol-specs/transactions/local-execution.md similarity index 100% rename from yellow-paper/docs/transactions/local-execution.md rename to docs/docs/protocol-specs/transactions/local-execution.md diff --git a/yellow-paper/docs/transactions/public-execution.md b/docs/docs/protocol-specs/transactions/public-execution.md similarity index 100% rename from yellow-paper/docs/transactions/public-execution.md rename to docs/docs/protocol-specs/transactions/public-execution.md diff --git a/yellow-paper/docs/transactions/tx-object.md b/docs/docs/protocol-specs/transactions/tx-object.md similarity index 100% rename from yellow-paper/docs/transactions/tx-object.md rename to docs/docs/protocol-specs/transactions/tx-object.md diff --git a/yellow-paper/docs/transactions/validity.md b/docs/docs/protocol-specs/transactions/validity.md similarity index 100% rename from yellow-paper/docs/transactions/validity.md rename to docs/docs/protocol-specs/transactions/validity.md diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index d2ffd760db2..7fbff54c608 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -199,6 +199,12 @@ const config = { position: "left", label: "Aztec Protocol", }, + { + type: "docSidebar", + sidebarId: "protocolSpecSidebar", + position: "left", + label: "Protocol Specification", + }, ], }, footer: { diff --git a/docs/sidebars.js b/docs/sidebars.js index f9b18d8372e..749b3d7b60a 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -635,6 +635,232 @@ const sidebars = { "misc/aztec_connect_sunset", ], + + protocolSpecSidebar: [ + "protocol-specs/intro", + { + label: "Cryptography", + type: "category", + link: { type: "doc", id: "protocol-specs/cryptography/index" }, + items: [ + { + label: "Proving System", + type: "category", + link: { + type: "doc", + id: "protocol-specs/cryptography/proving-system/performance-targets", + }, + items: [ + "protocol-specs/cryptography/proving-system/performance-targets", + "protocol-specs/cryptography/proving-system/overview", + "protocol-specs/cryptography/proving-system/data-bus", + ], + }, + { + label: "Hashing", + type: "category", + link: { + type: "doc", + id: "protocol-specs/cryptography/hashing/hashing", + }, + items: [ + "protocol-specs/cryptography/hashing/hashing", + "protocol-specs/cryptography/hashing/poseidon2", + "protocol-specs/cryptography/hashing/pedersen", + ], + }, + "protocol-specs/cryptography/merkle-trees", + ], + }, + { + label: "Addresses & Keys", + type: "category", + link: { type: "doc", id: "protocol-specs/addresses-and-keys/index" }, + items: [ + "protocol-specs/addresses-and-keys/address", + "protocol-specs/addresses-and-keys/keys-requirements", + "protocol-specs/addresses-and-keys/keys", + { + label: "Example Usage of Keys", + type: "category", + items: [ + "protocol-specs/addresses-and-keys/example-usage/nullifier", + "protocol-specs/addresses-and-keys/example-usage/diversified-and-stealth-keys", + "protocol-specs/addresses-and-keys/example-usage/tag-sequence-derivation", + "protocol-specs/addresses-and-keys/example-usage/encrypt-and-tag", + ], + }, + "protocol-specs/addresses-and-keys/precompiles", + "protocol-specs/addresses-and-keys/diversified-and-stealth", + ], + }, + { + label: "State", + type: "category", + link: { type: "doc", id: "protocol-specs/state/index" }, + items: [ + "protocol-specs/state/tree-implementations", + "protocol-specs/state/archive", + "protocol-specs/state/note-hash-tree", + "protocol-specs/state/nullifier-tree", + "protocol-specs/state/public-data-tree", + ], + }, + { + label: "Transactions", + type: "category", + link: { type: "doc", id: "protocol-specs/transactions/index" }, + items: [ + "protocol-specs/transactions/local-execution", + "protocol-specs/transactions/public-execution", + "protocol-specs/transactions/tx-object", + "protocol-specs/transactions/validity", + ], + }, + { + label: "Bytecode", + type: "category", + link: { type: "doc", id: "protocol-specs/bytecode/index" }, + items: [], + }, + { + label: "Contract Deployment", + type: "category", + link: { type: "doc", id: "protocol-specs/contract-deployment/index" }, + items: [ + "protocol-specs/contract-deployment/classes", + "protocol-specs/contract-deployment/instances", + ], + }, + { + label: "Calls", + type: "category", + link: { type: "doc", id: "protocol-specs/calls/index" }, + items: [ + "protocol-specs/calls/sync-calls", + "protocol-specs/calls/enqueued-calls", + "protocol-specs/calls/batched-calls", + "protocol-specs/calls/static-calls", + "protocol-specs/calls/delegate-calls", + "protocol-specs/calls/unconstrained-calls", + "protocol-specs/calls/public-private-messaging", + ], + }, + { + label: "L1 smart contracts", + type: "category", + link: { type: "doc", id: "protocol-specs/l1-smart-contracts/index" }, + items: ["protocol-specs/l1-smart-contracts/frontier"], + }, + { + label: "Data availability", + type: "category", + link: { + type: "doc", + id: "protocol-specs/data-publication-and-availability/index", + }, + items: [ + "protocol-specs/data-publication-and-availability/overview", + "protocol-specs/data-publication-and-availability/published-data", + ], + }, + { + label: "Logs", + type: "category", + link: { type: "doc", id: "protocol-specs/logs/index" }, + items: [], + }, + { + label: "Pre-compiled Contracts", + type: "category", + link: { type: "doc", id: "protocol-specs/pre-compiled-contracts/index" }, + items: ["protocol-specs/pre-compiled-contracts/registry"], + }, + { + label: "Private Message Delivery", + type: "category", + link: { + type: "doc", + id: "protocol-specs/private-message-delivery/index", + }, + items: [ + "protocol-specs/private-message-delivery/private-msg-delivery", // renamed to avoid routing problems + "protocol-specs/private-message-delivery/send-note-guidelines", + ], + }, + { + label: "Gas & Fees", + type: "category", + link: { type: "doc", id: "protocol-specs/gas-and-fees/index" }, + items: [ + "protocol-specs/gas-and-fees/fee-payments-and-metering", + "protocol-specs/gas-and-fees/fee-schedule", + ], + }, + { + label: "Decentralization", + type: "category", + link: { type: "doc", id: "protocol-specs/decentralization/governance" }, + items: [ + "protocol-specs/decentralization/actors", + "protocol-specs/decentralization/governance", + "protocol-specs/decentralization/block-production", + "protocol-specs/decentralization/p2p-network", + ], + }, + { + label: "Circuits", + type: "category", + link: { type: "doc", id: "protocol-specs/circuits/high-level-topology" }, + items: [ + "protocol-specs/circuits/private-function", + "protocol-specs/circuits/private-kernel-initial", + "protocol-specs/circuits/private-kernel-inner", + "protocol-specs/circuits/private-kernel-reset", + "protocol-specs/circuits/private-kernel-tail", + "protocol-specs/circuits/public-kernel-initial", + "protocol-specs/circuits/public-kernel-inner", + "protocol-specs/circuits/public-kernel-tail", + ], + }, + { + label: "Rollup Circuits", + type: "category", + link: { type: "doc", id: "protocol-specs/rollup-circuits/index" }, + items: [ + "protocol-specs/rollup-circuits/base-rollup", + "protocol-specs/rollup-circuits/merge-rollup", + "protocol-specs/rollup-circuits/tree-parity", + "protocol-specs/rollup-circuits/root-rollup", + ], + }, + { + label: "Aztec (Public) VM", + type: "category", + link: { type: "doc", id: "protocol-specs/public-vm/index" }, + items: [ + "protocol-specs/public-vm/intro", + "protocol-specs/public-vm/state", + "protocol-specs/public-vm/memory-model", + "protocol-specs/public-vm/context", + "protocol-specs/public-vm/execution", + "protocol-specs/public-vm/nested-calls", + "protocol-specs/public-vm/instruction-set", + { + label: "AVM Circuit", + type: "category", + link: { type: "doc", id: "protocol-specs/public-vm/circuit-index" }, + items: [ + "protocol-specs/public-vm/avm-circuit", + "protocol-specs/public-vm/control-flow", + "protocol-specs/public-vm/alu", + "protocol-specs/public-vm/bytecode-validation-circuit", + ], + }, + "protocol-specs/public-vm/type-structs", + ], + }, + ], }; module.exports = sidebars; diff --git a/docs/src/preprocess/InstructionSet/InstructionSet.js b/docs/src/preprocess/InstructionSet/InstructionSet.js new file mode 100644 index 00000000000..5f1202d7079 --- /dev/null +++ b/docs/src/preprocess/InstructionSet/InstructionSet.js @@ -0,0 +1,1254 @@ +const {instructionSize} = require('./InstructionSize'); + +const TOPICS_IN_TABLE = [ + "Name", "Summary", "Expression", +]; +const TOPICS_IN_SECTIONS = [ + "Name", "Summary", "Category", "Flags", "Args", "Expression", "Details", "World State access tracing", "Additional AVM circuit checks", "Triggers downstream circuit operations", "Tag checks", "Tag updates", "Bit-size", +]; + +const IN_TAG_DESCRIPTION = "The [tag/size](./memory-model#tags-and-tagged-memory) to check inputs against and tag the destination with."; +const IN_TAG_DESCRIPTION_NO_FIELD = IN_TAG_DESCRIPTION + " `field` type is NOT supported for this instruction."; +const DST_TAG_DESCRIPTION = "The [tag/size](./memory-model#tags-and-tagged-memory) to tag the destination with but not to check inputs against."; +const INDIRECT_FLAG_DESCRIPTION = "Toggles whether each memory-offset argument is an indirect offset. Rightmost bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`."; + +const CALL_INSTRUCTION_ARGS = [ + {"name": "gasOffset", "description": "offset to three words containing `{l1GasLeft, l2GasLeft, daGasLeft}`: amount of gas to provide to the callee"}, + {"name": "addrOffset", "description": "address of the contract to call"}, + {"name": "argsOffset", "description": "memory offset to args (will become the callee's calldata)"}, + {"name": "argsSize", "description": "number of words to pass via callee's calldata", "mode": "immediate", "type": "u32"}, + {"name": "retOffset", "description": "destination memory offset specifying where to store the data returned from the callee"}, + {"name": "retSize", "description": "number of words to copy from data returned by callee", "mode": "immediate", "type": "u32"}, + {"name": "successOffset", "description": "destination memory offset specifying where to store the call's success (0: failure, 1: success)", "type": "u8"}, +]; +const CALL_INSTRUCTION_DETAILS = ` + ["Nested contract calls"](./nested-calls) provides a full explanation of this + instruction along with the shorthand used in the expression above. + The explanation includes details on charging gas for nested calls, + nested context derivation, world state tracing, and updating the parent context + after the nested call halts.`; + +const INSTRUCTION_SET_RAW = [ + { + "id": "add", + "Name": "`ADD`", + "Category": "Compute - Arithmetic", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + {"name": "inTag", "description": IN_TAG_DESCRIPTION}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of the operation's left input"}, + {"name": "bOffset", "description": "memory offset of the operation's right input"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = M[aOffset] + M[bOffset] mod 2^k`", + "Summary": "Addition (a + b)", + "Details": "Wraps on overflow", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + "id": "sub", + "Name": "`SUB`", + "Category": "Compute - Arithmetic", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + {"name": "inTag", "description": IN_TAG_DESCRIPTION}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of the operation's left input"}, + {"name": "bOffset", "description": "memory offset of the operation's right input"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = M[aOffset] - M[bOffset] mod 2^k`", + "Summary": "Subtraction (a - b)", + "Details": "Wraps on undeflow", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + "id": "mul", + "Name": "`MUL`", + "Category": "Compute - Arithmetic", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + {"name": "inTag", "description": IN_TAG_DESCRIPTION}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of the operation's left input"}, + {"name": "bOffset", "description": "memory offset of the operation's right input"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = M[aOffset] * M[bOffset] mod 2^k`", + "Summary": "Multiplication (a * b)", + "Details": "Wraps on overflow", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + "id": "div", + "Name": "`DIV`", + "Category": "Compute - Arithmetic", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + {"name": "inTag", "description": IN_TAG_DESCRIPTION}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of the operation's left input"}, + {"name": "bOffset", "description": "memory offset of the operation's right input"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = M[aOffset] / M[bOffset]`", + "Summary": "Unsigned integer division (a / b)", + "Details": "If the input is a field, it will be interpreted as an integer", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + "id": "fdiv", + "Name": "`FDIV`", + "Category": "Compute - Arithmetic", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of the operation's left input"}, + {"name": "bOffset", "description": "memory offset of the operation's right input"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = M[aOffset] / M[bOffset]`", + "Summary": "Field division (a / b)", + "Details": "", + "Tag checks": "`T[aOffset] == T[bOffset] == field`", + "Tag updates": "`T[dstOffset] = field`", + }, + { + "id": "eq", + "Name": "`EQ`", + "Category": "Compute - Comparators", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + {"name": "inTag", "description": IN_TAG_DESCRIPTION}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of the operation's left input"}, + {"name": "bOffset", "description": "memory offset of the operation's right input"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result", "type": "u8"}, + ], + "Expression": "`M[dstOffset] = M[aOffset] == M[bOffset] ? 1 : 0`", + "Summary": "Equality check (a == b)", + "Details": "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = u8`", + }, + { + "id": "lt", + "Name": "`LT`", + "Category": "Compute - Comparators", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + {"name": "inTag", "description": IN_TAG_DESCRIPTION}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of the operation's left input"}, + {"name": "bOffset", "description": "memory offset of the operation's right input"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result", "type": "u8"}, + ], + "Expression": "`M[dstOffset] = M[aOffset] < M[bOffset] ? 1 : 0`", + "Summary": "Less-than check (a < b)", + "Details": "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = u8`", + }, + { + "id": "lte", + "Name": "`LTE`", + "Category": "Compute - Comparators", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + {"name": "inTag", "description": IN_TAG_DESCRIPTION}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of the operation's left input"}, + {"name": "bOffset", "description": "memory offset of the operation's right input"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result", "type": "u8"}, + ], + "Expression": "`M[dstOffset] = M[aOffset] <= M[bOffset] ? 1 : 0`", + "Summary": "Less-than-or-equals check (a <= b)", + "Details": "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = u8`", + }, + { + "id": "and", + "Name": "`AND`", + "Category": "Compute - Bitwise", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + {"name": "inTag", "description": IN_TAG_DESCRIPTION_NO_FIELD}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of the operation's left input"}, + {"name": "bOffset", "description": "memory offset of the operation's right input"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = M[aOffset] AND M[bOffset]`", + "Summary": "Bitwise AND (a & b)", + "Details": "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + "id": "or", + "Name": "`OR`", + "Category": "Compute - Bitwise", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + {"name": "inTag", "description": IN_TAG_DESCRIPTION_NO_FIELD}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of the operation's left input"}, + {"name": "bOffset", "description": "memory offset of the operation's right input"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = M[aOffset] OR M[bOffset]`", + "Summary": "Bitwise OR (a | b)", + "Details": "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + "id": "xor", + "Name": "`XOR`", + "Category": "Compute - Bitwise", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + {"name": "inTag", "description": IN_TAG_DESCRIPTION_NO_FIELD}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of the operation's left input"}, + {"name": "bOffset", "description": "memory offset of the operation's right input"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = M[aOffset] XOR M[bOffset]`", + "Summary": "Bitwise XOR (a ^ b)", + "Details": "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + "id": "not", + "Name": "`NOT`", + "Category": "Compute - Bitwise", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + {"name": "inTag", "description": IN_TAG_DESCRIPTION_NO_FIELD}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of the operation's input"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = NOT M[aOffset]`", + "Summary": "Bitwise NOT (inversion)", + "Details": "", + "Tag checks": "`T[aOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + "id": "shl", + "Name": "`SHL`", + "Category": "Compute - Bitwise", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + {"name": "inTag", "description": IN_TAG_DESCRIPTION_NO_FIELD}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of the operation's left input"}, + {"name": "bOffset", "description": "memory offset of the operation's right input"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = M[aOffset] << M[bOffset]`", + "Summary": "Bitwise leftward shift (a << b)", + "Details": "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + "id": "shr", + "Name": "`SHR`", + "Category": "Compute - Bitwise", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + {"name": "inTag", "description": IN_TAG_DESCRIPTION_NO_FIELD}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of the operation's left input"}, + {"name": "bOffset", "description": "memory offset of the operation's right input"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = M[aOffset] >> M[bOffset]`", + "Summary": "Bitwise rightward shift (a >> b)", + "Details": "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + "id": "cast", + "Name": "`CAST`", + "Category": "Type Conversions", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + {"name": "dstTag", "description": DST_TAG_DESCRIPTION}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of word to cast"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = cast(M[aOffset])`", + "Summary": "Type cast", + "Details": "Cast a word in memory based on the `dstTag` specified in the bytecode. Truncates (`M[dstOffset] = M[aOffset] mod 2^dstsize`) when casting to a smaller type, left-zero-pads when casting to a larger type. See [here](./memory-model#cast-and-tag-conversions) for more details.", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = dstTag`", + }, + { + "id": "address", + "Name": "`ADDRESS`", + "Category": "Execution Environment", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.address`", + "Summary": "Get the address of the currently executing l2 contract", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "storageaddress", + "Name": "`STORAGEADDRESS`", + "Category": "Execution Environment", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.storageAddress`", + "Summary": "Get the _storage_ address of the currently executing context", + "Details": "The storage address is used for public storage accesses.", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "origin", + "Name": "`ORIGIN`", + "Category": "Execution Environment", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.origin`", + "Summary": "Get the transaction's origination address", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "sender", + "Name": "`SENDER`", + "Category": "Execution Environment", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.sender`", + "Summary": "Get the address of the sender (caller of the current context)", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "portal", + "Name": "`PORTAL`", + "Category": "Execution Environment", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.portal`", + "Summary": "Get the address of the l1 portal contract", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "feeperl1gas", + "Name": "`FEEPERL1GAS`", + "Category": "Execution Environment", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.feePerL1Gas`", + "Summary": "Get the fee to be paid per \"L1 gas\" - constant for entire transaction", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "feeperl2gas", + "Name": "`FEEPERL2GAS`", + "Category": "Execution Environment", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.feePerL2Gas`", + "Summary": "Get the fee to be paid per \"L2 gas\" - constant for entire transaction", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "feeperdagas", + "Name": "`FEEPERDAGAS`", + "Category": "Execution Environment", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.feePerDaGas`", + "Summary": "Get the fee to be paid per \"DA gas\" - constant for entire transaction", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "contractcalldepth", + "Name": "`CONTRACTCALLDEPTH`", + "Category": "Execution Environment", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.contractCallDepth`", + "Summary": "Get how many contract calls deep the current call context is", + "Details": "Note: security issues with EVM's tx.origin can be resolved by asserting `calldepth == 0`.", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u8`", + }, + { + "id": "chainid", + "Name": "`CHAINID`", + "Category": "Execution Environment - Globals", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.globals.chainId`", + "Summary": "Get this rollup's L1 chain ID", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "version", + "Name": "`VERSION`", + "Category": "Execution Environment - Globals", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.globals.version`", + "Summary": "Get this rollup's L2 version ID", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "blocknumber", + "Name": "`BLOCKNUMBER`", + "Category": "Execution Environment - Globals", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.globals.blocknumber`", + "Summary": "Get this L2 block's number", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "timestamp", + "Name": "`TIMESTAMP`", + "Category": "Execution Environment - Globals", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.globals.timestamp`", + "Summary": "Get this L2 block's timestamp", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u64`", + }, + { + "id": "coinbase", + "Name": "`COINBASE`", + "Category": "Execution Environment - Globals", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.globals.coinbase`", + "Summary": "Get the block's beneficiary address", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "blockl1gaslimit", + "Name": "`BLOCKL1GASLIMIT`", + "Category": "Execution Environment - Globals", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.globals.l1GasLimit`", + "Summary": "Total amount of \"L1 gas\" that a block can consume", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "blockl2gaslimit", + "Name": "`BLOCKL2GASLIMIT`", + "Category": "Execution Environment - Globals", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.globals.l2GasLimit`", + "Summary": "Total amount of \"L2 gas\" that a block can consume", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "blockdagaslimit", + "Name": "`BLOCKDAGASLIMIT`", + "Category": "Execution Environment - Globals", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.environment.globals.daGasLimit`", + "Summary": "Total amount of \"DA gas\" that a block can consume", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "calldatacopy", + "Name": "`CALLDATACOPY`", + "Category": "Execution Environment - Calldata", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "cdOffset", "description": "offset into calldata to copy from"}, + {"name": "copySize", "description": "number of words to copy", "mode": "immediate", "type": "u32"}, + {"name": "dstOffset", "description": "memory offset specifying where to copy the first word to"}, + ], + "Expression": "`M[dstOffset:dstOffset+copySize] = context.environment.calldata[cdOffset:cdOffset+copySize]`", + "Summary": "Copy calldata into memory", + "Details": "Calldata is read-only and cannot be directly operated on by other instructions. This instruction moves words from calldata into memory so they can be operated on normally.", + "Tag checks": "", + "Tag updates": "`T[dstOffset:dstOffset+copySize] = field`", + }, + { + "id": "l1gasleft", + "Name": "`L1GASLEFT`", + "Category": "Machine State - Gas", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.machineState.l1GasLeft`", + "Summary": "Remaining \"L1 gas\" for this call (after this instruction)", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "l2gasleft", + "Name": "`L2GASLEFT`", + "Category": "Machine State - Gas", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.MachineState.l2GasLeft`", + "Summary": "Remaining \"L2 gas\" for this call (after this instruction)", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "dagasleft", + "Name": "`DAGASLEFT`", + "Category": "Machine State - Gas", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = context.machineState.daGasLeft`", + "Summary": "Remaining \"DA gas\" for this call (after this instruction)", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + "id": "jump", + "Name": "`JUMP`", + "Category": "Machine State - Control Flow", + "Flags": [], + "Args": [ + {"name": "loc", "description": "target location to jump to", "mode": "immediate", "type": "u32"}, + ], + "Expression": "`context.machineState.pc = loc`", + "Summary": "Jump to a location in the bytecode", + "Details": "Target location is an immediate value (a constant in the bytecode).", + "Tag checks": "", + "Tag updates": "", + }, + { + "id": "jumpi", + "Name": "`JUMPI`", + "Category": "Machine State - Control Flow", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "loc", "description": "target location conditionally jump to", "mode": "immediate", "type": "u32"}, + {"name": "condOffset", "description": "memory offset of the operations 'conditional' input"}, + ], + "Expression": "`context.machineState.pc = M[condOffset] > 0 ? loc : context.machineState.pc`", + "Summary": "Conditionally jump to a location in the bytecode", + "Details": "Target location is an immediate value (a constant in the bytecode). `T[condOffset]` is not checked because the greater-than-zero suboperation is the same regardless of type.", + "Tag checks": "", + "Tag updates": "", + }, + { + "id": "internalcall", + "Name": "`INTERNALCALL`", + "Category": "Machine State - Control Flow", + "Flags": [], + "Args": [ + {"name": "loc", "description": "target location to jump/call to", "mode": "immediate", "type": "u32"}, + ], + "Expression": ` +context.machineState.internalCallStack.push(context.machineState.pc) +context.machineState.pc = loc +`, + "Summary": "Make an internal call. Push the current PC to the internal call stack and jump to the target location.", + "Details": "Target location is an immediate value (a constant in the bytecode).", + "Tag checks": "", + "Tag updates": "", + }, + { + "id": "internalreturn", + "Name": "`INTERNALRETURN`", + "Category": "Machine State - Control Flow", + "Flags": [], + "Args": [], + "Expression": "`context.machineState.pc = context.machineState.internalCallStack.pop()`", + "Summary": "Return from an internal call. Pop from the internal call stack and jump to the popped location.", + "Details": "", + "Tag checks": "", + "Tag updates": "", + }, + { + "id": "set", + "Name": "`SET`", + "Category": "Machine State - Memory", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + {"name": "inTag", "description": "The [type/size](./memory-model#tags-and-tagged-memory) to check inputs against and tag the destination with. `field` type is NOT supported for SET."}, + ], + "Args": [ + {"name": "const", "description": "an N-bit constant value from the bytecode to store in memory (any type except `field`)", "mode": "immediate"}, + {"name": "dstOffset", "description": "memory offset specifying where to store the constant"}, + ], + "Expression": "`M[dstOffset] = const`", + "Summary": "Set a memory word from a constant in the bytecode", + "Details": "Set memory word at `dstOffset` to `const`'s immediate value. `const`'s bit-size (N) can be 8, 16, 32, 64, or 128 based on `inTag`. It _cannot be 254 (`field` type)_!", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + "id": "mov", + "Name": "`MOV`", + "Category": "Machine State - Memory", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "srcOffset", "description": "memory offset of word to move"}, + {"name": "dstOffset", "description": "memory offset specifying where to store that word"}, + ], + "Expression": "`M[dstOffset] = M[srcOffset]`", + "Summary": "Move a word from source memory location to destination", + "Details": "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = T[srcOffset]`", + }, + { + "id": "cmov", + "Name": "`CMOV`", + "Category": "Machine State - Memory", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "aOffset", "description": "memory offset of word 'a' to conditionally move"}, + {"name": "bOffset", "description": "memory offset of word 'b' to conditionally move"}, + {"name": "condOffset", "description": "memory offset of the operations 'conditional' input"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": "`M[dstOffset] = M[condOffset] > 0 ? M[aOffset] : M[bOffset]`", + "Summary": "Move a word (conditionally chosen) from one memory location to another (`d = cond > 0 ? a : b`)", + "Details": "One of two source memory locations is chosen based on the condition. `T[condOffset]` is not checked because the greater-than-zero suboperation is the same regardless of type.", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = M[condOffset] > 0 ? T[aOffset] : T[bOffset]`", + }, + { + "id": "sload", + "Name": "`SLOAD`", + "Category": "World State - Public Storage", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "slotOffset", "description": "memory offset of the storage slot to load from"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, + ], + "Expression": ` +M[dstOffset] = S[M[slotOffset]] +`, + "Summary": "Load a word from this contract's persistent public storage. Zero is loaded for unwritten slots.", + "Details": ` +// Expression is shorthand for +leafIndex = hash(context.environment.storageAddress, M[slotOffset]) +exists = context.worldState.publicStorage.has(leafIndex) // exists == previously-written +if exists: + value = context.worldState.publicStorage.get(leafIndex: leafIndex) +else: + value = 0 +M[dstOffset] = value +`, + "World State access tracing": ` +context.worldStateAccessTrace.publicStorageReads.append( + TracedStorageRead { + callPointer: context.environment.callPointer, + slot: M[slotOffset], + exists: exists, // defined above + value: value, // defined above + counter: ++context.worldStateAccessTrace.accessCounter, + } +) +`, + "Triggers downstream circuit operations": "Storage slot siloing (hash with contract address), public data tree membership check", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = field`", + }, + { + "id": "sstore", + "Name": "`SSTORE`", + "Category": "World State - Public Storage", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "srcOffset", "description": "memory offset of the word to store"}, + {"name": "slotOffset", "description": "memory offset containing the storage slot to store to"}, + ], + "Expression": ` +S[M[slotOffset]] = M[srcOffset] +`, + "Summary": "Write a word to this contract's persistent public storage", + "Details": ` +// Expression is shorthand for +context.worldState.publicStorage.set({ + leafIndex: hash(context.environment.storageAddress, M[slotOffset]), + leaf: M[srcOffset], +}) +`, + "World State access tracing": ` +context.worldStateAccessTrace.publicStorageWrites.append( + TracedStorageWrite { + callPointer: context.environment.callPointer, + slot: M[slotOffset], + value: M[srcOffset], + counter: ++context.worldStateAccessTrace.accessCounter, + } +) +`, + "Triggers downstream circuit operations": "Storage slot siloing (hash with contract address), public data tree update", + "Tag checks": "", + "Tag updates": "", + }, + { + "id": "notehashexists", + "Name": "`NOTEHASHEXISTS`", + "Category": "World State - Notes & Nullifiers", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "noteHashOffset", "description": "memory offset of the note hash"}, + {"name": "leafIndexOffset", "description": "memory offset of the leaf index"}, + {"name": "existsOffset", "description": "memory offset specifying where to store operation's result (whether the note hash leaf exists)"}, + ], + "Expression": ` +exists = context.worldState.noteHashes.has({ + leafIndex: M[leafIndexOffset] + leaf: hash(context.environment.storageAddress, M[noteHashOffset]), +}) +M[existsOffset] = exists +`, + "Summary": "Check whether a note hash exists in the note hash tree (as of the start of the current block)", + "World State access tracing": ` +context.worldStateAccessTrace.noteHashChecks.append( + TracedNoteHashCheck { + callPointer: context.environment.callPointer, + leafIndex: M[leafIndexOffset] + noteHash: M[noteHashOffset], + exists: exists, // defined above + counter: ++context.worldStateAccessTrace.accessCounter, + } +) +`, + "Triggers downstream circuit operations": "Note hash siloing (hash with storage contract address), note hash tree membership check", + "Tag checks": "", + "Tag updates": "`T[existsOffset] = u8`", + }, + { + "id": "emitnotehash", + "Name": "`EMITNOTEHASH`", + "Category": "World State - Notes & Nullifiers", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "noteHashOffset", "description": "memory offset of the note hash"}, + ], + "Expression": ` +context.worldState.noteHashes.append( + hash(context.environment.storageAddress, M[noteHashOffset]) +) +`, + "Summary": "Emit a new note hash to be inserted into the note hash tree", + "World State access tracing": ` +context.worldStateAccessTrace.newNoteHashes.append( + TracedNoteHash { + callPointer: context.environment.callPointer, + noteHash: M[noteHashOffset], // unsiloed note hash + counter: ++context.worldStateAccessTrace.accessCounter, + } +) +`, + "Triggers downstream circuit operations": "Note hash siloing (hash with contract address), note hash tree insertion.", + "Tag checks": "", + "Tag updates": "", + }, + { + "id": "nullifierexists", + "Name": "`NULLIFIEREXISTS`", + "Category": "World State - Notes & Nullifiers", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "nullifierOffset", "description": "memory offset of the unsiloed nullifier"}, + {"name": "existsOffset", "description": "memory offset specifying where to store operation's result (whether the nullifier exists)"}, + ], + "Expression": ` +exists = context.worldState.nullifiers.has( + hash(context.environment.storageAddress, M[nullifierOffset]) +) +M[existsOffset] = exists +`, + "Summary": "Check whether a nullifier exists in the nullifier tree (including nullifiers from earlier in the current transaction or from earlier in the current block)", + "World State access tracing": ` +context.worldStateAccessTrace.nullifierChecks.append( + TracedNullifierCheck { + callPointer: context.environment.callPointer, + nullifier: M[nullifierOffset], + exists: exists, // defined above + counter: ++context.worldStateAccessTrace.accessCounter, + } +) +`, + "Triggers downstream circuit operations": "Nullifier siloing (hash with storage contract address), nullifier tree membership check", + "Tag checks": "", + "Tag updates": "`T[existsOffset] = u8`", + }, + { + "id": "emitnullifier", + "Name": "`EMITNULLIFIER`", + "Category": "World State - Notes & Nullifiers", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "nullifierOffset", "description": "memory offset of nullifier"}, + ], + "Expression": ` +context.worldState.nullifiers.append( + hash(context.environment.storageAddress, M[nullifierOffset]) +) +`, + "Summary": "Emit a new nullifier to be inserted into the nullifier tree", + "World State access tracing": ` +context.worldStateAccessTrace.newNullifiers.append( + TracedNullifier { + callPointer: context.environment.callPointer, + nullifier: M[nullifierOffset], // unsiloed nullifier + counter: ++context.worldStateAccessTrace.accessCounter, + } +) +`, + "Triggers downstream circuit operations": "Nullifier siloing (hash with contract address), nullifier tree non-membership-check and insertion.", + "Tag checks": "", + "Tag updates": "", + }, + { + "id": "l1tol2msgexists", + "Name": "`L1TOL2MSGEXISTS`", + "Category": "World State - Messaging", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "msgHashOffset", "description": "memory offset of the message hash"}, + {"name": "msgLeafIndexOffset", "description": "memory offset of the message's leaf index in the L1-to-L2 message tree"}, + {"name": "existsOffset", "description": "memory offset specifying where to store operation's result (whether the message exists in the L1-to-L2 message tree)"}, + ], + "Expression": ` +exists = context.worldState.l1ToL2Messages.has({ + leafIndex: M[msgLeafIndexOffset], leaf: M[msgHashOffset] +}) +M[existsOffset] = exists +`, + "Summary": "Check if a message exists in the L1-to-L2 message tree", + "World State access tracing": ` +context.worldStateAccessTrace.l1ToL2MessagesChecks.append( + L1ToL2Message { + callPointer: context.environment.callPointer, + leafIndex: M[msgLeafIndexOffset], + msgHash: M[msgHashOffset], + exists: exists, // defined above + } +) +`, + "Triggers downstream circuit operations": "L1-to-L2 message tree membership check", + "Tag checks": "", + "Tag updates": ` +T[existsOffset] = u8, +`, + }, + { + "id": "headermember", + "Name": "`HEADERMEMBER`", + "Category": "World State - Archive Tree & Headers", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "blockIndexOffset", "description": "memory offset of the block index (same as archive tree leaf index) of the header to access"}, + {"name": "memberIndexOffset", "description": "memory offset of the index of the member to retrieve from the header of the specified block"}, + {"name": "existsOffset", "description": "memory offset specifying where to store operation's result (whether the leaf exists in the archive tree)"}, + {"name": "dstOffset", "description": "memory offset specifying where to store operation's result (the retrieved header member)"}, + ], + "Expression": ` +exists = context.worldState.header.has({ + leafIndex: M[blockIndexOffset], leaf: M[msgKeyOffset] +}) +M[existsOffset] = exists +if exists: + header = context.worldState.headers.get(M[blockIndexOffset]) + M[dstOffset] = header[M[memberIndexOffset]] // member +`, + "Summary": "Check if a header exists in the [archive tree](../state/archive) and retrieve the specified member if so", + "World State access tracing": ` +context.worldStateAccessTrace.archiveChecks.append( + TracedArchiveLeafCheck { + leafIndex: M[blockIndexOffset], // leafIndex == blockIndex + leaf: exists ? hash(header) : 0, // "exists" defined above + } +) +`, + "Additional AVM circuit checks": "Hashes entire header to archive leaf for tracing. Aggregates header accesses and so that a header need only be hashed once.", + "Triggers downstream circuit operations": "Archive tree membership check", + "Tag checks": "", + "Tag updates": ` +T[existsOffset] = u8 +T[dstOffset] = field +`, + }, + { + "id": "getcontractinstance", + "Name": "`GETCONTRACTINSTANCE`", + "Category": "Other", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "addressOffset", "description": "memory offset of the contract instance address"}, + {"name": "dstOffset", "description": "location to write the contract instance information to"}, + ], + "Expression": ` +M[dstOffset:dstOffset+CONTRACT_INSTANCE_SIZE+1] = [ + instance_found_in_address, + instance.salt ?? 0, + instance.deployer ?? 0, + instance.contractClassId ?? 0, + instance.initializationHash ?? 0, + instance.portalContractAddress ?? 0, + instance.publicKeysHash ?? 0, +] +`, + "Summary": "Copies contract instance data to memory", + "Tag checks": "", + "Tag updates": "T[dstOffset:dstOffset+CONTRACT_INSTANCE_SIZE+1] = field", + "Additional AVM circuit checks": "TO-DO", + "Triggers downstream circuit operations": "TO-DO", + }, + { + "id": "emitunencryptedlog", + "Name": "`EMITUNENCRYPTEDLOG`", + "Category": "Accrued Substate - Logging", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "eventSelectorOffset", "description": "memory offset of the event selector"}, + {"name": "logOffset", "description": "memory offset of the data to log"}, + {"name": "logSize", "description": "number of words to log", "mode": "immediate", "type": "u32"}, + ], + "Expression": ` +context.accruedSubstate.unencryptedLogs.append( + UnencryptedLog { + address: context.environment.address, + eventSelector: M[eventSelectorOffset], + log: M[logOffset:logOffset+logSize], + } +) +`, + "Summary": "Emit an unencrypted log", + "Tag checks": "", + "Tag updates": "", + }, + { + "id": "sendl2tol1msg", + "Name": "`SENDL2TOL1MSG`", + "Category": "Accrued Substate - Messaging", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "recipientOffset", "description": "memory offset of the message recipient"}, + {"name": "contentOffset", "description": "memory offset of the message content"}, + ], + "Expression": ` +context.accruedSubstate.sentL2ToL1Messages.append( + SentL2ToL1Message { + address: context.environment.address, + recipient: M[recipientOffset], + message: M[contentOffset] + } +) +`, + "Summary": "Send an L2-to-L1 message", + "Tag checks": "", + "Tag updates": "", + }, + { + "id": "call", + "Name": "`CALL`", + "Category": "Control Flow - Contract Calls", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": CALL_INSTRUCTION_ARGS, + "Expression":` +// instr.args are { gasOffset, addrOffset, argsOffset, retOffset, retSize } +chargeGas(context, + l1GasCost=M[instr.args.gasOffset], + l2GasCost=M[instr.args.gasOffset+1], + daGasCost=M[instr.args.gasOffset+2]) +traceNestedCall(context, instr.args.addrOffset) +nestedContext = deriveContext(context, instr.args, isStaticCall=false, isDelegateCall=false) +execute(nestedContext) +updateContextAfterNestedCall(context, instr.args, nestedContext) +`, + "Summary": "Call into another contract", + "Details": `Creates a new (nested) execution context and triggers execution within that context. + Execution proceeds in the nested context until it reaches a halt at which point + execution resumes in the current/calling context. + A non-existent contract or one with no code will return success. ` + + CALL_INSTRUCTION_DETAILS, + "Tag checks": "`T[gasOffset] == T[gasOffset+1] == T[gasOffset+2] == u32`", + "Tag updates": ` +T[successOffset] = u8 +T[retOffset:retOffset+retSize] = field +`, + }, + { + "id": "staticcall", + "Name": "`STATICCALL`", + "Category": "Control Flow - Contract Calls", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": CALL_INSTRUCTION_ARGS, + "Expression": ` +// instr.args are { gasOffset, addrOffset, argsOffset, retOffset, retSize } +chargeGas(context, + l1GasCost=M[instr.args.gasOffset], + l2GasCost=M[instr.args.gasOffset+1], + daGasCost=M[instr.args.gasOffset+2]) +traceNestedCall(context, instr.args.addrOffset) +nestedContext = deriveContext(context, instr.args, isStaticCall=true, isDelegateCall=false) +execute(nestedContext) +updateContextAfterNestedCall(context, instr.args, nestedContext) +`, + "Summary": "Call into another contract, disallowing World State and Accrued Substate modifications", + "Details": `Same as \`CALL\`, but disallows World State and Accrued Substate modifications. ` + + CALL_INSTRUCTION_DETAILS, + "Tag checks": "`T[gasOffset] == T[gasOffset+1] == T[gasOffset+2] == u32`", + "Tag updates": ` +T[successOffset] = u8 +T[retOffset:retOffset+retSize] = field +`, + }, + { + "id": "delegatecall", + "Name": "`DELEGATECALL`", + "Category": "Control Flow - Contract Calls", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": CALL_INSTRUCTION_ARGS, + "Expression": ` +// instr.args are { gasOffset, addrOffset, argsOffset, retOffset, retSize } +chargeGas(context, + l1GasCost=M[instr.args.gasOffset], + l2GasCost=M[instr.args.gasOffset+1], + daGasCost=M[instr.args.gasOffset+2]) +traceNestedCall(context, instr.args.addrOffset) +nestedContext = deriveContext(context, instr.args, isStaticCall=false, isDelegateCall=true) +execute(nestedContext) +updateContextAfterNestedCall(context, instr.args, nestedContext) +`, + "Summary": "Call into another contract, but keep the caller's `sender` and `storageAddress`", + "Details": `Same as \`CALL\`, but \`sender\` and \`storageAddress\` remains + the same in the nested call as they were in the caller. ` + + CALL_INSTRUCTION_DETAILS, + "Tag checks": "`T[gasOffset] == T[gasOffset+1] == T[gasOffset+2] == u32`", + "Tag updates": ` +T[successOffset] = u8 +T[retOffset:retOffset+retSize] = field +`, + }, + { + "id": "return", + "Name": "`RETURN`", + "Category": "Control Flow - Contract Calls", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "retOffset", "description": "memory offset of first word to return"}, + {"name": "retSize", "description": "number of words to return", "mode": "immediate", "type": "u32"}, + ], + "Expression": ` +context.contractCallResults.output = M[retOffset:retOffset+retSize] +halt +`, + "Summary": "Halt execution within this context (without revert), optionally returning some data", + "Details": "Return control flow to the calling context/contract. Caller will accept World State and Accrued Substate modifications. See [\"Halting\"](./execution#halting) to learn more. See [\"Nested contract calls\"](./nested-calls) to see how the caller updates its context after the nested call halts.", + "Tag checks": "", + "Tag updates": "", + }, + { + "id": "revert", + "Name": "`REVERT`", + "Category": "Control Flow - Contract Calls", + "Flags": [ + {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, + ], + "Args": [ + {"name": "retOffset", "description": "memory offset of first word to return"}, + {"name": "retSize", "description": "number of words to return", "mode": "immediate", "type": "u32"}, + ], + "Expression": ` +context.contractCallResults.output = M[retOffset:retOffset+retSize] +context.contractCallResults.reverted = true +halt +`, + "Summary": "Halt execution within this context as `reverted`, optionally returning some data", + "Details": "Return control flow to the calling context/contract. Caller will reject World State and Accrued Substate modifications. See [\"Halting\"](./execution#halting) to learn more. See [\"Nested contract calls\"](./nested-calls) to see how the caller updates its context after the nested call halts.", + "Tag checks": "", + "Tag updates": "", + }, +]; +const INSTRUCTION_SET = INSTRUCTION_SET_RAW.map((instr) => {instr['Bit-size'] = instructionSize(instr); return instr;}); + +module.exports = { + TOPICS_IN_TABLE, + TOPICS_IN_SECTIONS, + INSTRUCTION_SET, +}; diff --git a/docs/src/preprocess/InstructionSet/InstructionSize.js b/docs/src/preprocess/InstructionSet/InstructionSize.js new file mode 100644 index 00000000000..f6cac342791 --- /dev/null +++ b/docs/src/preprocess/InstructionSet/InstructionSize.js @@ -0,0 +1,90 @@ +const OPCODE_SIZE = 8; +const FLAG_SIZE = 8; +const RESERVED_SIZE = 8; + +const DEFAULT_OPERAND_SIZE = 32; // for direct/indirect memory offsets + +function argSize(arg) { + if (arg['mode'] && arg['mode'] == 'immediate') { + if (arg['type']) { + return Number(arg['type'].replace(/u/, '')); + } else { + return undefined; // none specified! + } + } else { + return DEFAULT_OPERAND_SIZE; + } +} + +function toOpcode(index) { + return '0x' + index.toString(16).padStart(2, '0'); +} + +/* Compute bit-size of instruction based on flags and number of operands, + * whether they are immediate (and op-type if so) + * + * All instructions have: + * - 1 byte for opcode + * - 1 byte to toggle indirect mode for up to 8 non-immediate args + * 24 bits per-arg (for non-immediates) + * N bits per immediate arg, where N is 8, 16, 32, 64, or 128 based on type + * 1 byte for op-type + * 1 byte for dest-type + */ +function instructionSize(instr) { + let size = OPCODE_SIZE + RESERVED_SIZE; + let numUntypedImmediates = 0; + for (let arg of instr['Args']) { + const aSize = argSize(arg); + if (aSize === undefined) { + numUntypedImmediates++; + } else { + size += aSize; + } + } + if (instr['Flags']) { + // assigns each flag a byte (indirect, op-type, dest-type) + size += instr['Flags'].length * FLAG_SIZE; + } + let sizeStr = size.toString(); + if (numUntypedImmediates > 0) { + sizeStr += '+N'; + } + return sizeStr; +} + +function instructionBitFormat(instr, index) { + let bitFormat = { + 'Name': instr['Name'], + 'Opcode': { + 'code': toOpcode(index), + 'size': OPCODE_SIZE, + }, + 'Reserved': { + 'size': RESERVED_SIZE, + }, + 'Args': [], + 'Flags': [], + }; + + //for (let arg of instr['Args']) { + for (let a = 0; a < instr['Args'].length; a++) { + const arg = instr['Args'][a]; + const aSize = argSize(arg); + if (aSize === undefined) { + bitFormat['Args'][a] = {"name": arg['name'], "size": 'N'}; + } else { + bitFormat['Args'][a] = {"name": arg['name'], "size": aSize}; + } + } + for (let f = 0; f < instr['Flags'].length; f++) { + const flag = instr['Flags'][f]; + bitFormat['Flags'][f] = {"name": flag['name'], "size": FLAG_SIZE}; + } + return bitFormat; +} + +module.exports = { + instructionSize, + instructionBitFormat, +}; \ No newline at end of file diff --git a/docs/src/preprocess/InstructionSet/genBitFormats.js b/docs/src/preprocess/InstructionSet/genBitFormats.js new file mode 100644 index 00000000000..c406f70a85e --- /dev/null +++ b/docs/src/preprocess/InstructionSet/genBitFormats.js @@ -0,0 +1,16 @@ +const fs = require("fs"); + +const {instructionBitFormat} = require('./InstructionSize'); +const {INSTRUCTION_SET} = require('./InstructionSet'); + +function run() { + const formats = []; + for (let i = 0; i < INSTRUCTION_SET.length; i++) { + const instr = INSTRUCTION_SET[i]; + const bitFormat = instructionBitFormat(instr, i); + formats.push(bitFormat); + } + console.log(`Writing ${formats.length} bit formats to InstructionBitFormats.json`); + fs.writeFileSync('./InstructionBitFormats.json', JSON.stringify(formats)); +} +run(); \ No newline at end of file diff --git a/docs/src/preprocess/InstructionSet/genMarkdown.js b/docs/src/preprocess/InstructionSet/genMarkdown.js new file mode 100644 index 00000000000..7c68f0d98bb --- /dev/null +++ b/docs/src/preprocess/InstructionSet/genMarkdown.js @@ -0,0 +1,153 @@ +const fs = require("fs"); +const path = require("path"); + +const { + TOPICS_IN_TABLE, + TOPICS_IN_SECTIONS, + INSTRUCTION_SET, + instructionSize, +} = require("./InstructionSet"); + +function escapeBraces(str) { + return str.replace(//g, ">"); +} + +function stripBraces(str) { + return str.replace(/[<>]/g, ""); +} + +function instructionSetPreface() { + let preface = "[comment]: # (THIS IS A GENERATED FILE! DO NOT EDIT!)\n"; + preface += "[comment]: # (Generated via `yarn preprocess`)\n\n"; + preface += + "[comment]: # (Generated by genMarkdown.js, InstructionSet.js, InstructionSize.js)\n\n"; + preface += "import Markdown from 'react-markdown'\n"; + preface += "import CodeBlock from '@theme/CodeBlock'\n\n"; + return preface; +} + +function toOpcode(index) { + return "0x" + index.toString(16).padStart(2, "0"); +} + +function htmlInstructionSetTable() { + let table = "## Instructions Table\n"; + table += "\nClick on an instruction name to jump to its section.\n"; + table += "\n\n"; + let header = ""; + for (let t = 0; t < TOPICS_IN_TABLE.length; t++) { + header += ``; + } + table += `${header}\n`; + + for (let i = 0; i < INSTRUCTION_SET.length; i++) { + const instr = INSTRUCTION_SET[i]; + const name = instr["Name"]; + let row = `\n`; + row += `\t`; + row += `\t`; + + for (let t = 0; t < TOPICS_IN_TABLE.length; t++) { + const topic = TOPICS_IN_TABLE[t]; + + if (topic == "Name") continue; // skip + let cell = instr[topic]; + if (cell[0] == "\n") { + // if string starts with newline, assume it's a multi-line code block + cell = `\n{\`${cell.trim()}\`}\n\t`; + } else if (cell[0] == "`" && topic != "Name") { + cell = `{\n\t\t\`${cell.replace( + /`/g, + "" + )}\`\n\t}`; + } else { + cell = escapeBraces(cell); // escape html + cell = `${cell}`; + } + row += `\n\t`; + } + row += "\n"; + table += `${row}\n`; + } + table += "
Opcode${TOPICS_IN_TABLE[t]}
${toOpcode(i)}[${stripBraces(name)}](#isa-section-${ + instr["id"] + })${cell}
\n"; + return table; +} + +function markdownSublist(items) { + let markdown = ""; + for (let i = 0; i < items.length; i++) { + let item = items[i]; + if (typeof item === "string") { + markdown += `\n\t- ${item}`; + } else { + markdown += `\n\t- **${item["name"]}**: ${item["description"]}`; + } + } + return markdown; +} + +function markdownInstructionSetSection(pathToGenDir) { + let markdown = "## Instructions\n"; + for (let i = 0; i < INSTRUCTION_SET.length; i++) { + const instr = INSTRUCTION_SET[i]; + const name = instr["Name"]; + let subsection = `### ${name}\n`; + subsection += `${instr["Summary"]}\n\n`; + subsection += `[See in table.](#isa-table-${instr["id"]})\n\n`; + subsection += `- **Opcode**: ${toOpcode(i)}\n`; + for (let t = 0; t < TOPICS_IN_SECTIONS.length; t++) { + const topic = TOPICS_IN_SECTIONS[t]; + let field = instr[topic]; + if (topic == "Name" || topic == "Summary" || !field || field.length == 0) + continue; // skip + + let item = `- **${topic}**: `; + if (Array.isArray(field)) { + item += markdownSublist(field); + } else if (field[0] == "\n") { + // if string starts with newline, assume it's a multi-line code block + item += `\n\n{\`${field.trim()}\`}\n`; + } else { + item += field; + } + subsection += `${item}\n`; + } + const bitFormatPath = `./images/bit-formats/${name.replace(/`/g, "")}.png`; + if (fs.existsSync(`${pathToGenDir}/${bitFormatPath}`)) { + subsection += `\n[![](${bitFormatPath})](${bitFormatPath})`; + } + markdown += `\n${subsection}\n`; + } + return markdown; +} + +async function generateInstructionSet() { + const rootDir = path.join(__dirname, "../../../"); + const docsDir = path.join(rootDir, "docs", "docs"); + + const relPath = path.relative( + docsDir, + "docs/protocol-specs/public-vm/gen/_instruction-set.mdx" + ); + const docsFilePath = path.resolve(docsDir, relPath); + const docsDirName = path.dirname(docsFilePath); + if (!fs.existsSync(docsDirName)) { + fs.mkdirSync(docsDirName, { recursive: true }); + } + + const preface = instructionSetPreface(); + const table = htmlInstructionSetTable(); + const section = markdownInstructionSetSection(docsDirName); + const doc = `${preface}\n${table}\n\n${section}`; + fs.writeFileSync(docsFilePath, doc); + + console.log("Preprocessing complete."); +} + +module.exports = { + generateInstructionSet, +}; diff --git a/docs/src/preprocess/index.js b/docs/src/preprocess/index.js index 129321d4ecd..e188bc21490 100644 --- a/docs/src/preprocess/index.js +++ b/docs/src/preprocess/index.js @@ -5,6 +5,8 @@ const childProcess = require("child_process"); const { preprocessIncludeCode } = require("./include_code"); const { preprocessIncludeVersion } = require("./include_version"); +const { generateInstructionSet } = require("./InstructionSet/genMarkdown"); + async function processMarkdownFilesInDir(rootDir, docsDir, regex) { const files = fs.readdirSync(docsDir); const contentUpdates = []; @@ -125,6 +127,7 @@ async function run() { const content = await processMarkdownFilesInDir(rootDir, docsDir); await writeProcessedFiles(docsDir, destDir, cachedDestDir, content); + await generateInstructionSet(); console.log("Preprocessing complete."); } diff --git a/yellow-paper/docs/addresses-and-keys/images/addresses-and-keys/image-1.png b/docs/static/img/protocol-specs/addresses-and-keys/image-1.png similarity index 100% rename from yellow-paper/docs/addresses-and-keys/images/addresses-and-keys/image-1.png rename to docs/static/img/protocol-specs/addresses-and-keys/image-1.png diff --git a/yellow-paper/docs/addresses-and-keys/images/addresses-and-keys/image-3.png b/docs/static/img/protocol-specs/addresses-and-keys/image-3.png similarity index 100% rename from yellow-paper/docs/addresses-and-keys/images/addresses-and-keys/image-3.png rename to docs/static/img/protocol-specs/addresses-and-keys/image-3.png diff --git a/yellow-paper/docs/addresses-and-keys/images/addresses-and-keys/image-4.png b/docs/static/img/protocol-specs/addresses-and-keys/image-4.png similarity index 100% rename from yellow-paper/docs/addresses-and-keys/images/addresses-and-keys/image-4.png rename to docs/static/img/protocol-specs/addresses-and-keys/image-4.png diff --git a/yellow-paper/docs/addresses-and-keys/images/addresses-and-keys/image-5.png b/docs/static/img/protocol-specs/addresses-and-keys/image-5.png similarity index 100% rename from yellow-paper/docs/addresses-and-keys/images/addresses-and-keys/image-5.png rename to docs/static/img/protocol-specs/addresses-and-keys/image-5.png diff --git a/yellow-paper/docs/addresses-and-keys/images/addresses-and-keys/image.png b/docs/static/img/protocol-specs/addresses-and-keys/image.png similarity index 100% rename from yellow-paper/docs/addresses-and-keys/images/addresses-and-keys/image.png rename to docs/static/img/protocol-specs/addresses-and-keys/image.png diff --git a/yellow-paper/docs/calls/images/calls/pub_pvt_messaging.png b/docs/static/img/protocol-specs/calls/pub_pvt_messaging.png similarity index 100% rename from yellow-paper/docs/calls/images/calls/pub_pvt_messaging.png rename to docs/static/img/protocol-specs/calls/pub_pvt_messaging.png diff --git a/yellow-paper/docs/calls/images/calls/pvt_pub_ordering.png b/docs/static/img/protocol-specs/calls/pvt_pub_ordering.png similarity index 100% rename from yellow-paper/docs/calls/images/calls/pvt_pub_ordering.png rename to docs/static/img/protocol-specs/calls/pvt_pub_ordering.png diff --git a/yellow-paper/docs/cryptography/images/proof-system-components.png b/docs/static/img/protocol-specs/cryptography/proof-system-components.png similarity index 100% rename from yellow-paper/docs/cryptography/images/proof-system-components.png rename to docs/static/img/protocol-specs/cryptography/proof-system-components.png diff --git a/yellow-paper/docs/decentralization/images/Aztec-Block-Production-1.png b/docs/static/img/protocol-specs/decentralization/Aztec-Block-Production-1.png similarity index 100% rename from yellow-paper/docs/decentralization/images/Aztec-Block-Production-1.png rename to docs/static/img/protocol-specs/decentralization/Aztec-Block-Production-1.png diff --git a/yellow-paper/docs/decentralization/images/Aztec-Block-Production-2.png b/docs/static/img/protocol-specs/decentralization/Aztec-Block-Production-2.png similarity index 100% rename from yellow-paper/docs/decentralization/images/Aztec-Block-Production-2.png rename to docs/static/img/protocol-specs/decentralization/Aztec-Block-Production-2.png diff --git a/yellow-paper/docs/decentralization/images/Aztec-Block-Production-3.png b/docs/static/img/protocol-specs/decentralization/Aztec-Block-Production-3.png similarity index 100% rename from yellow-paper/docs/decentralization/images/Aztec-Block-Production-3.png rename to docs/static/img/protocol-specs/decentralization/Aztec-Block-Production-3.png diff --git a/yellow-paper/docs/decentralization/images/Aztec-Governance-Summary-1.png b/docs/static/img/protocol-specs/decentralization/Aztec-Governance-Summary-1.png similarity index 100% rename from yellow-paper/docs/decentralization/images/Aztec-Governance-Summary-1.png rename to docs/static/img/protocol-specs/decentralization/Aztec-Governance-Summary-1.png diff --git a/yellow-paper/docs/decentralization/images/Aztec-Governance-Summary-2.png b/docs/static/img/protocol-specs/decentralization/Aztec-Governance-Summary-2.png similarity index 100% rename from yellow-paper/docs/decentralization/images/Aztec-Governance-Summary-2.png rename to docs/static/img/protocol-specs/decentralization/Aztec-Governance-Summary-2.png diff --git a/yellow-paper/docs/decentralization/images/Aztec-Governance-Summary-3.png b/docs/static/img/protocol-specs/decentralization/Aztec-Governance-Summary-3.png similarity index 100% rename from yellow-paper/docs/decentralization/images/Aztec-Governance-Summary-3.png rename to docs/static/img/protocol-specs/decentralization/Aztec-Governance-Summary-3.png diff --git a/yellow-paper/docs/decentralization/images/Aztec-Governance-Summary-4.png b/docs/static/img/protocol-specs/decentralization/Aztec-Governance-Summary-4.png similarity index 100% rename from yellow-paper/docs/decentralization/images/Aztec-Governance-Summary-4.png rename to docs/static/img/protocol-specs/decentralization/Aztec-Governance-Summary-4.png diff --git a/yellow-paper/docs/decentralization/images/Aztec-Governance-Summary-5.png b/docs/static/img/protocol-specs/decentralization/Aztec-Governance-Summary-5.png similarity index 100% rename from yellow-paper/docs/decentralization/images/Aztec-Governance-Summary-5.png rename to docs/static/img/protocol-specs/decentralization/Aztec-Governance-Summary-5.png diff --git a/yellow-paper/docs/decentralization/images/network.png b/docs/static/img/protocol-specs/decentralization/network.png similarity index 100% rename from yellow-paper/docs/decentralization/images/network.png rename to docs/static/img/protocol-specs/decentralization/network.png diff --git a/yellow-paper/docs/gas-and-fees/images/gas-and-fees/Transaction.png b/docs/static/img/protocol-specs/gas-and-fees/Transaction.png similarity index 100% rename from yellow-paper/docs/gas-and-fees/images/gas-and-fees/Transaction.png rename to docs/static/img/protocol-specs/gas-and-fees/Transaction.png diff --git a/yellow-paper/docs/l1-smart-contracts/images/com-abs-6.png b/docs/static/img/protocol-specs/l1-smart-contracts/com-abs-6.png similarity index 100% rename from yellow-paper/docs/l1-smart-contracts/images/com-abs-6.png rename to docs/static/img/protocol-specs/l1-smart-contracts/com-abs-6.png diff --git a/yellow-paper/docs/l1-smart-contracts/images/frontier/image-1.png b/docs/static/img/protocol-specs/l1-smart-contracts/frontier/image-1.png similarity index 100% rename from yellow-paper/docs/l1-smart-contracts/images/frontier/image-1.png rename to docs/static/img/protocol-specs/l1-smart-contracts/frontier/image-1.png diff --git a/yellow-paper/docs/l1-smart-contracts/images/frontier/image-2.png b/docs/static/img/protocol-specs/l1-smart-contracts/frontier/image-2.png similarity index 100% rename from yellow-paper/docs/l1-smart-contracts/images/frontier/image-2.png rename to docs/static/img/protocol-specs/l1-smart-contracts/frontier/image-2.png diff --git a/yellow-paper/docs/l1-smart-contracts/images/frontier/image-3.png b/docs/static/img/protocol-specs/l1-smart-contracts/frontier/image-3.png similarity index 100% rename from yellow-paper/docs/l1-smart-contracts/images/frontier/image-3.png rename to docs/static/img/protocol-specs/l1-smart-contracts/frontier/image-3.png diff --git a/yellow-paper/docs/l1-smart-contracts/images/frontier/image-4.png b/docs/static/img/protocol-specs/l1-smart-contracts/frontier/image-4.png similarity index 100% rename from yellow-paper/docs/l1-smart-contracts/images/frontier/image-4.png rename to docs/static/img/protocol-specs/l1-smart-contracts/frontier/image-4.png diff --git a/yellow-paper/docs/l1-smart-contracts/images/frontier/image-5.png b/docs/static/img/protocol-specs/l1-smart-contracts/frontier/image-5.png similarity index 100% rename from yellow-paper/docs/l1-smart-contracts/images/frontier/image-5.png rename to docs/static/img/protocol-specs/l1-smart-contracts/frontier/image-5.png diff --git a/yellow-paper/docs/l1-smart-contracts/images/frontier/image-6.png b/docs/static/img/protocol-specs/l1-smart-contracts/frontier/image-6.png similarity index 100% rename from yellow-paper/docs/l1-smart-contracts/images/frontier/image-6.png rename to docs/static/img/protocol-specs/l1-smart-contracts/frontier/image-6.png diff --git a/yellow-paper/docs/l1-smart-contracts/images/frontier/image-7.png b/docs/static/img/protocol-specs/l1-smart-contracts/frontier/image-7.png similarity index 100% rename from yellow-paper/docs/l1-smart-contracts/images/frontier/image-7.png rename to docs/static/img/protocol-specs/l1-smart-contracts/frontier/image-7.png diff --git a/yellow-paper/docs/l1-smart-contracts/images/tree-order.png b/docs/static/img/protocol-specs/l1-smart-contracts/tree-order.png similarity index 100% rename from yellow-paper/docs/l1-smart-contracts/images/tree-order.png rename to docs/static/img/protocol-specs/l1-smart-contracts/tree-order.png diff --git a/yellow-paper/docs/public-vm/images/alu.png b/docs/static/img/protocol-specs/public-vm/alu.png similarity index 100% rename from yellow-paper/docs/public-vm/images/alu.png rename to docs/static/img/protocol-specs/public-vm/alu.png diff --git a/yellow-paper/docs/public-vm/images/avm-control-flow.png b/docs/static/img/protocol-specs/public-vm/avm-control-flow.png similarity index 100% rename from yellow-paper/docs/public-vm/images/avm-control-flow.png rename to docs/static/img/protocol-specs/public-vm/avm-control-flow.png diff --git a/yellow-paper/docs/public-vm/images/memory.png b/docs/static/img/protocol-specs/public-vm/memory.png similarity index 100% rename from yellow-paper/docs/public-vm/images/memory.png rename to docs/static/img/protocol-specs/public-vm/memory.png From 689012c0d62fd56c3c1fa12ccf018d841167792c Mon Sep 17 00:00:00 2001 From: Josh Crites Date: Wed, 10 Apr 2024 11:38:05 -0400 Subject: [PATCH 02/18] move images, update paths --- .../gas-and-fees/fee-payments-and-metering.md | 2 +- .../l1-smart-contracts/index.md | 138 +++++++++--------- .../protocol-specs/public-vm/control-flow.md | 2 +- .../public-vm/gen/_instruction-set.mdx | 102 ++++++------- docs/package.json | 1 + .../preprocess/InstructionSet/genMarkdown.js | 21 ++- docs/src/preprocess/index.js | 3 +- .../public-vm}/bit-formats/ADD.png | Bin .../public-vm}/bit-formats/ADDRESS.png | Bin .../public-vm}/bit-formats/AND.png | Bin .../bit-formats/BLOCKDAGASLIMIT.png | Bin .../bit-formats/BLOCKHEADERBYNUM.png | Bin .../bit-formats/BLOCKL1GASLIMIT.png | Bin .../bit-formats/BLOCKL2GASLIMIT.png | Bin .../public-vm}/bit-formats/BLOCKNUMBER.png | Bin .../public-vm}/bit-formats/CALL.png | Bin .../public-vm}/bit-formats/CALLDATACOPY.png | Bin .../public-vm}/bit-formats/CAST.png | Bin .../public-vm}/bit-formats/CHAINID.png | Bin .../public-vm}/bit-formats/CMOV.png | Bin .../public-vm}/bit-formats/COINBASE.png | Bin .../bit-formats/CONTRACTCALLDEPTH.png | Bin .../public-vm}/bit-formats/DAGASLEFT.png | Bin .../public-vm}/bit-formats/DIV.png | Bin .../public-vm}/bit-formats/EMITNOTEHASH.png | Bin .../public-vm}/bit-formats/EMITNULLIFIER.png | Bin .../bit-formats/EMITUNENCRYPTEDLOG.png | Bin .../public-vm}/bit-formats/EQ.png | Bin .../public-vm}/bit-formats/FEEPERDAGAS.png | Bin .../public-vm}/bit-formats/FEEPERL1GAS.png | Bin .../public-vm}/bit-formats/FEEPERL2GAS.png | Bin .../bit-formats/INTERNALCALLDEPTH.png | Bin .../public-vm}/bit-formats/INTERNALRETURN.png | Bin .../public-vm}/bit-formats/JUMP.png | Bin .../public-vm}/bit-formats/JUMPI.png | Bin .../public-vm}/bit-formats/L1GASLEFT.png | Bin .../public-vm}/bit-formats/L2GASLEFT.png | Bin .../public-vm}/bit-formats/LT.png | Bin .../public-vm}/bit-formats/LTE.png | Bin .../public-vm}/bit-formats/MOV.png | Bin .../public-vm}/bit-formats/MUL.png | Bin .../public-vm}/bit-formats/NOT.png | Bin .../public-vm}/bit-formats/OR.png | Bin .../public-vm}/bit-formats/ORIGIN.png | Bin .../public-vm}/bit-formats/PORTAL.png | Bin .../public-vm}/bit-formats/READL1TOL2MSG.png | Bin .../public-vm}/bit-formats/RETURN.png | Bin .../public-vm}/bit-formats/REVERT.png | Bin .../public-vm}/bit-formats/SENDER.png | Bin .../public-vm}/bit-formats/SENDL2TOL1MSG.png | Bin .../public-vm}/bit-formats/SET.png | Bin .../public-vm}/bit-formats/SHL.png | Bin .../public-vm}/bit-formats/SHR.png | Bin .../public-vm}/bit-formats/SLOAD.png | Bin .../public-vm}/bit-formats/SSTORE.png | Bin .../public-vm}/bit-formats/STATICCALL.png | Bin .../public-vm}/bit-formats/STORAGEADDRESS.png | Bin .../public-vm}/bit-formats/SUB.png | Bin .../public-vm}/bit-formats/TIMESTAMP.png | Bin .../public-vm}/bit-formats/VERSION.png | Bin .../public-vm}/bit-formats/XOR.png | Bin .../public-vm}/bit-formats/internalcall.png | Bin docs/yarn.lock | 74 +++++++++- 63 files changed, 211 insertions(+), 132 deletions(-) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/ADD.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/ADDRESS.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/AND.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/BLOCKDAGASLIMIT.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/BLOCKHEADERBYNUM.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/BLOCKL1GASLIMIT.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/BLOCKL2GASLIMIT.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/BLOCKNUMBER.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/CALL.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/CALLDATACOPY.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/CAST.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/CHAINID.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/CMOV.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/COINBASE.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/CONTRACTCALLDEPTH.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/DAGASLEFT.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/DIV.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/EMITNOTEHASH.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/EMITNULLIFIER.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/EMITUNENCRYPTEDLOG.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/EQ.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/FEEPERDAGAS.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/FEEPERL1GAS.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/FEEPERL2GAS.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/INTERNALCALLDEPTH.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/INTERNALRETURN.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/JUMP.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/JUMPI.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/L1GASLEFT.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/L2GASLEFT.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/LT.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/LTE.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/MOV.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/MUL.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/NOT.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/OR.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/ORIGIN.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/PORTAL.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/READL1TOL2MSG.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/RETURN.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/REVERT.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/SENDER.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/SENDL2TOL1MSG.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/SET.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/SHL.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/SHR.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/SLOAD.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/SSTORE.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/STATICCALL.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/STORAGEADDRESS.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/SUB.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/TIMESTAMP.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/VERSION.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/XOR.png (100%) rename docs/{docs/protocol-specs/public-vm/gen/images => static/img/protocol-specs/public-vm}/bit-formats/internalcall.png (100%) diff --git a/docs/docs/protocol-specs/gas-and-fees/fee-payments-and-metering.md b/docs/docs/protocol-specs/gas-and-fees/fee-payments-and-metering.md index 39b97c0abb8..b8a7c1db90e 100644 --- a/docs/docs/protocol-specs/gas-and-fees/fee-payments-and-metering.md +++ b/docs/docs/protocol-specs/gas-and-fees/fee-payments-and-metering.md @@ -55,7 +55,7 @@ Transactions will be divided into 3 phases: All of these phases occur **within the same transaction**, ultimately resulting in 2 sets of public inputs being emitted from the private kernel circuits. Those related to the fee payment and those related to the application logic. State changes requested by the application logic are reverted if any component fails. State changes in the fee preparation and distribution components are only reverted if either of those components fail. -![Transaction Components](/img/protocol-specs/gas-and-fees/gas-and-fees/Transaction.png) +![Transaction Components](/img/protocol-specs/gas-and-fees/Transaction.png) The fee preparation and fee distribution phases respectively are responsible for ensuring that sufficient quantity of the fee payment asset is made available for the transaction and that it is correctly distributed to the sequencer with any refund being returned to the transaction sender. The sequencer will have have agency over which contract methods they are willing to accept for execution in these phases and will have visibility over the arguments passed to them. This is important as these functions must be successfully executed in order for the sequencer to be paid. It is assumed that the network will settle on a number of universally recognised fee payment contracts implementing fee preparation and distribution. diff --git a/docs/docs/protocol-specs/l1-smart-contracts/index.md b/docs/docs/protocol-specs/l1-smart-contracts/index.md index ad676a95d75..0a2f7a924d8 100644 --- a/docs/docs/protocol-specs/l1-smart-contracts/index.md +++ b/docs/docs/protocol-specs/l1-smart-contracts/index.md @@ -4,7 +4,7 @@ title: Cross-chain communication This section describes what our L1 contracts do, what they are responsible for and how they interact with the circuits. -Note that the only reason that we even have any contracts is to facilitate cross-chain communication. +Note that the only reason that we even have any contracts is to facilitate cross-chain communication. The contracts are not required for the rollup to function, but required to bridge assets and to reduce the cost of light nodes. :::info Purpose of contracts @@ -12,11 +12,11 @@ The purpose of the L1 contracts are simple: - Facilitate cross-chain communication such that L1 liquidity can be used on L2 - Act as a validating light node for L2 that every L1 node implicitly run -::: + ::: ## Overview -When presented with a new [`ProvenBlock`](../rollup-circuits/root-rollup.md) and its proof, an Aztec node can be convinced of its validity if the proof passes and the `Header.last_archive` matches the `archive` of the node (archive here represents a root of [archive tree](../state/archive.md)). +When presented with a new [`ProvenBlock`](../rollup-circuits/root-rollup.md) and its proof, an Aztec node can be convinced of its validity if the proof passes and the `Header.last_archive` matches the `archive` of the node (archive here represents a root of [archive tree](../state/archive.md)). The `archive` used as public input is the archive after the new header is inserted (see [root rollup](./../rollup-circuits/root-rollup.md)). ```python @@ -31,8 +31,8 @@ def process(block: ProvenBlock, proof: Proof): assert proof.verify(header, block.archive) assert self.inbox.consume() == header.in_hash assert self.outbox.insert( - block_number, - header.content_commitment.out_hash, + block_number, + header.content_commitment.out_hash, header.content_commitment.tx_tree_height + math.ceil(log2(MAX_NEW_L2_TO_L1_MSGS_PER_TX)) ) self.archive = block.archive @@ -44,15 +44,15 @@ def process(block: ProvenBlock, proof: Proof): The argument to the `insert` function is the `outbox` is the heigh of the message tree. Since every transaction can hold more than 1 message, it might add multiple layers to the tree. For a binary tree, the number of extra layers to add is computed as `math.ceil(log2(MAX_NEW_L2_TO_L1_MSGS_PER_TX))`. -Currently, `MAX_NEW_L2_TO_L1_MSGS_PER_TX = 2` which means that we are simply adding 1 extra layer. +Currently, `MAX_NEW_L2_TO_L1_MSGS_PER_TX = 2` which means that we are simply adding 1 extra layer. ::: -While the `ProvenBlock` must be published and available for nodes to build the state of the rollup, we can build the validating light node (the contract) such that as long as the node can be _convinced_ that the data is available we can progress the state. +While the `ProvenBlock` must be published and available for nodes to build the state of the rollup, we can build the validating light node (the contract) such that as long as the node can be _convinced_ that the data is available we can progress the state. This means our light node can be built to only require a subset of the `ProvenBlock` to be published to Ethereum L1 as calldata and use a different data availability layer for most of the block body. Namely, we need the cross-chain messages to be published to L1, but the rest of the block body can be published to a different data availability layer. :::info Validium or Rollup -If a different data availability layer than Ethereum is used for the block body, we are effectively building a Validium. +If a different data availability layer than Ethereum is used for the block body, we are effectively building a Validium. If we use Ethereum for the block body, we are building a Rollup. ::: @@ -91,8 +91,8 @@ StateTransitioner --> Verifier: verify() ### State transitioner -The state transitioner is the heart of the validating light node for the L2. -The contract keeps track of the current state of the L2 and progresses this state when a valid L2 block is received. +The state transitioner is the heart of the validating light node for the L2. +The contract keeps track of the current state of the L2 and progresses this state when a valid L2 block is received. It also facilitates cross-chain communication (communication between the L1 inbox and outbox contracts). ```python @@ -124,8 +124,8 @@ class StateTransitioner: assert VERIFIER.verify(header, archive, proof) assert self.INBOX.consume() == header.content_commitment.in_hash assert self.OUTBOX.insert( - block_number, - header.content_commitment.out_hash, + block_number, + header.content_commitment.out_hash, header.content_commitment.tx_tree_height + math.ceil(log2(MAX_NEW_L2_TO_L1_MSGS_PER_TX)) ) self.archive = archive @@ -148,7 +148,7 @@ class StateTransitioner: The state transitioner should be connected to an oracle which addresses the availability condition. -For the case of a rollup, this "oracle" will be deriving the `TxsHash` from calldata and blobs. +For the case of a rollup, this "oracle" will be deriving the `TxsHash` from calldata and blobs. For a validium it should be connected to a bridge that it can use to verify that the data is available on the other chain. For a generic DA that publishes data commitments to Ethereum, the oracle could be a snark proof that opens the data commitment from the bridge and computes the `TxsHash` from it. @@ -157,7 +157,7 @@ By having the availability oracle be independent from state progression we can e For more information around the requirements we have for the availability oracle, see [Data Availability](../data-publication-and-availability/index.md). -An interesting observation around the availability oracle is that the `OutHash` and `InHash` don't need to be explicitly proven available through it. +An interesting observation around the availability oracle is that the `OutHash` and `InHash` don't need to be explicitly proven available through it. The `InHash` is already proven as part of the L1 inbox, as we will see in a second. And the `OutHash` consists entirely of a subset of the contents of the `TxsHash`, which is already proven available. @@ -165,30 +165,30 @@ And the `OutHash` consists entirely of a subset of the contents of the `TxsHash` ### Registry -To keep one location where all the core rollup contracts can be found, we have a registry contract. -The registry is a contract that holds the current and historical addresses of the core rollup contracts. -The addresses of a rollup deployment are contained in a snapshot, and the registry is tracking version-snapshot pairs. -Depending on the upgrade scheme, it might be used to handle upgrades, or it could entirely be removed. -It is generally the one address that a node MUST know about, as it can then tell the node where to find the remainder of the contracts. +To keep one location where all the core rollup contracts can be found, we have a registry contract. +The registry is a contract that holds the current and historical addresses of the core rollup contracts. +The addresses of a rollup deployment are contained in a snapshot, and the registry is tracking version-snapshot pairs. +Depending on the upgrade scheme, it might be used to handle upgrades, or it could entirely be removed. +It is generally the one address that a node MUST know about, as it can then tell the node where to find the remainder of the contracts. This is for example used when looking for the address new L2 blocks should be published to. ## Message Bridges To let users communicate between L1 and the L2, we are using message bridges, namely an L1 inbox that is paired to an L2 outbox, and an L2 inbox that is paired to an L1 outbox. -![Alt text](images/com-abs-6.png) +![Alt text](/img/protocol-specs/l1-smart-contracts/com-abs-6.png) :::info Naming is based from the PoV of the state transitioner. ::: -While we logically have 4 boxes, we practically only require 3 of those. -The L2 inbox is not real - but only logical. -This is due to the fact that they are always inserted and then consumed in the same block! +While we logically have 4 boxes, we practically only require 3 of those. +The L2 inbox is not real - but only logical. +This is due to the fact that they are always inserted and then consumed in the same block! Insertions require a L2 transaction, and it is then to be consumed and moved to the L1 outbox by the state transitioner in the same block. ### Portals -When deploying a contract on L2, it is possible to specify its "portal" address. +When deploying a contract on L2, it is possible to specify its "portal" address. This is an immutable variable, that can be used to constrain who the L2 contract expects messages from, and who it sends messages to. ### Messages @@ -220,32 +220,32 @@ struct L2ToL1Msg { } ``` -Beware, that while we speak of messages, we are practically passing around only their **hashes** to reduce cost. -The `version` value of the `L2Actor` is the version of the rollup, which is intended to be used to specify which version of the rollup the message is intended for or sent from. +Beware, that while we speak of messages, we are practically passing around only their **hashes** to reduce cost. +The `version` value of the `L2Actor` is the version of the rollup, which is intended to be used to specify which version of the rollup the message is intended for or sent from. This way, multiple rollup instances can use the same inbox/outbox contracts. :::info Why a single hash? -Compute on L1 is expensive, but storage is extremely expensive! -To reduce overhead, we trade storage for computation and only commit to the messages and then "open" these for consumption later. -However, since computation also bears significant we need to use a hash function that is relatively cheap on L1, while still being doable inside a snark. +Compute on L1 is expensive, but storage is extremely expensive! +To reduce overhead, we trade storage for computation and only commit to the messages and then "open" these for consumption later. +However, since computation also bears significant we need to use a hash function that is relatively cheap on L1, while still being doable inside a snark. For this purpose a modded SHA256 was chosen, modded here meaning that it fits the output value into a single field element using the modulo operator. ::: Some additional discussion/comments on the message structure can be found in [The Republic](https://forum.aztec.network/t/the-republic-a-flexible-optional-governance-proposal-with-self-governed-portals/609/2#supporting-pending-messages-5). -Since any data that is moving from one chain to the other at some point will live on L1, it will be PUBLIC. +Since any data that is moving from one chain to the other at some point will live on L1, it will be PUBLIC. While this is fine for L1 consumption (which is public in itself), we want to ensure that the L2 consumption can be private. -To support this, we use a nullifier scheme similar to what we are doing for the other [notes](./../state/note-hash-tree.md). +To support this, we use a nullifier scheme similar to what we are doing for the other [notes](./../state/note-hash-tree.md). As part of the nullifier computation we then use the `secret` which hashes to the `secretHash`, this ensures that only actors with knowledge of `secret` will be able to see when it is spent on L2. -Any message that is consumed on one side MUST be moved to the other side. -This is to ensure that the messages exist AND are only consumed once. +Any message that is consumed on one side MUST be moved to the other side. +This is to ensure that the messages exist AND are only consumed once. The L1 contracts can handle one side, but the circuits must handle the other. :::info Is `secretHash` required? We are using the `secretHash` to ensure that the user can spend the message privately with a generic nullifier computation. -However, as the nullifier computation is almost entirely controlled by the app circuit (except the siloing, see [Nullifier Tree](./../state/nullifier-tree.md) ) applications could be made to simply use a different nullifier computation and have it become part of the content. -However, this reduces the developer burden and is quite easy to mess up. +However, as the nullifier computation is almost entirely controlled by the app circuit (except the siloing, see [Nullifier Tree](./../state/nullifier-tree.md) ) applications could be made to simply use a different nullifier computation and have it become part of the content. +However, this reduces the developer burden and is quite easy to mess up. For those reasons we have decided to use the `secretHash` as part of the message. ::: @@ -256,21 +256,20 @@ For those reasons we have decided to use the `secretHash` as part of the message When we say inbox, we are generally referring to the L1 contract that handles the L1 to L2 messages. The inbox takes messages from L1 contracts and inserts them into a series of message trees. -We build multiple "trees" instead of a single tree, since we are building one tree for every block and not one large with all the messages. +We build multiple "trees" instead of a single tree, since we are building one tree for every block and not one large with all the messages. The reasoning is fairly straight-forward; we need to split it into epochs such that a sequencer can build a proof based on a tree that is not going to update in the middle of the proof building. Such updates would allow DOS attacks on the sequencer, which is undesirable. To support this, we can simply introduce a "lag" between when trees are built and when they must be included. We can actually do this quite easily. -Say that whenever a new block is published, we start building a new tree. +Say that whenever a new block is published, we start building a new tree. Essentially meaning that at block $n$ we include tree $n$ which was created earlier (during block $n-1$). - Example visualized below. Here we have that tree $n$ is "fixed" when block $n$ needs to be published. And that tree $n+1$ is being built upon until block $n$ is being published. -![Feeding trees into the blocks](images/tree-order.png) +![Feeding trees into the blocks](/img/protocol-specs/l1-smart-contracts/tree-order.png) When the state transitioner is consuming a tree, it MUST insert the subtree into the "L2 outbox" ([message tree](./../state/index.md)). @@ -279,27 +278,27 @@ When a message is inserted into the inbox, the inbox **MUST** fill in the `sende - `L1Actor.actor`: The sender of the message (the caller), `msg.sender` - `L1Actor.chainId`: The chainId of the L1 chain sending the message, `block.chainId` -We MUST populate these values in the inbox, since we cannot rely on the user providing anything meaningful. -From the `L1ToL2Msg` we compute a hash of the message. +We MUST populate these values in the inbox, since we cannot rely on the user providing anything meaningful. +From the `L1ToL2Msg` we compute a hash of the message. This hash is what is moved by the state transitioner to the L2 outbox. -Since message from L1 to L2 can be inserted independently of the L2 block, the message transfer (moving from inbox into outbox) is not synchronous as it is for L2 to L1 messages. -This means that the message can be inserted into the inbox, but not yet moved to the outbox. -The message will then be moved to the outbox when the state transitioner is consuming the message as part of a block. +Since message from L1 to L2 can be inserted independently of the L2 block, the message transfer (moving from inbox into outbox) is not synchronous as it is for L2 to L1 messages. +This means that the message can be inserted into the inbox, but not yet moved to the outbox. +The message will then be moved to the outbox when the state transitioner is consuming the message as part of a block. Since the sequencers are required to move the entire subtree at once, you can be sure that the message will be moved to the outbox at some point. As mentioned earlier, this is done to ensure that the messages are not used to DOS the state transitioner. -Since we will be building the tree on L1, we need to use a gas-friendly hash-function such as SHA256. -However, as we need to allow users to prove inclusion in this tree, we cannot just insert the SHA256 tree into the rollup state, it requires too many constraints to be used by most small users. +Since we will be building the tree on L1, we need to use a gas-friendly hash-function such as SHA256. +However, as we need to allow users to prove inclusion in this tree, we cannot just insert the SHA256 tree into the rollup state, it requires too many constraints to be used by most small users. Therefore, we need to "convert" the tree into a tree using a more snark-friendly hash. This part is done in the [tree parity circuits](./../rollup-circuits/tree-parity.md). -Furthermore, to build the tree on L1, we need to put some storage on L1 such that the insertions don't need to provide a lot of merkle-related data which could be cumbersome to do and prone to race-conditions. -For example two insertions based on inclusion paths that are created at the same time will invalidate each other. -As storage costs an arm and a leg on L1, we need to be careful with how we store this. +Furthermore, to build the tree on L1, we need to put some storage on L1 such that the insertions don't need to provide a lot of merkle-related data which could be cumbersome to do and prone to race-conditions. +For example two insertions based on inclusion paths that are created at the same time will invalidate each other. +As storage costs an arm and a leg on L1, we need to be careful with how we store this. -Luckily for us, we can use a "frontier" merkle tree to store the messages. +Luckily for us, we can use a "frontier" merkle tree to store the messages. This is a special kind of append-only merkle tree that allows us to store very few elements in storage, but just enough for us to be able to extend it, and compute the root of the tree. Consult [Frontier Merkle Tree](#frontier-merkle-tree]) for more information on this. @@ -307,7 +306,6 @@ Assuming that we have these trees, we can build an `inbox` utilizing them as fol When a new block is published, we start building a new tree. Notice however, that if we have entirely filled the current tree, we can start building a new one immediately, and the blocks can then "catch up". - ```python class Inbox: STATE_TRANSITIONER: immutable(address) @@ -328,7 +326,7 @@ class Inbox: self.STATE_TRANSITIONER = _state_transitioner self.trees[1] = FrontierTree(self.HEIGHT) - + def insert(self, message: L1ToL2Message) -> bytes32: ''' Insert into the next FrontierTree. If the tree is full, creates a new one @@ -366,7 +364,7 @@ class Inbox: #### L2 Inbox -While the L2 inbox is not a real contract, it is a logical contract that apply mutations to the data similar to the L1 inbox to ensure that the sender cannot fake his position. +While the L2 inbox is not a real contract, it is a logical contract that apply mutations to the data similar to the L1 inbox to ensure that the sender cannot fake his position. This logic is handled by the kernel and rollup circuits. Just like the L1 variant, we must populate the `sender`: @@ -378,7 +376,7 @@ In practice, this is done in the kernel circuit of the L2, and the message hashe ### Outbox -The outboxes are the location where a user can consume messages from. +The outboxes are the location where a user can consume messages from. An outbox can only contain elements that have previously been removed from the paired inbox. + diff --git a/docs/docs/protocol-specs/circuits/private-kernel-inner.mdx b/docs/docs/protocol-specs/circuits/private-kernel-inner.mdx index 1f13b5f3b5c..ca4e5af9cce 100644 --- a/docs/docs/protocol-specs/circuits/private-kernel-inner.mdx +++ b/docs/docs/protocol-specs/circuits/private-kernel-inner.mdx @@ -1,6 +1,6 @@ # Private Kernel Circuit - Inner - + ## Requirements diff --git a/docs/docs/protocol-specs/cryptography/proving-system/overview.md b/docs/docs/protocol-specs/cryptography/proving-system/overview.md index 354702a5d9d..c76a01969d0 100644 --- a/docs/docs/protocol-specs/cryptography/proving-system/overview.md +++ b/docs/docs/protocol-specs/cryptography/proving-system/overview.md @@ -62,7 +62,7 @@ The "Fold" Prover/Verifier validates that `k` instances of a defined relation (i #### Protogalaxy Decider -The "Decider" Prover/Verifier validate whether an accumulator instance correctly satisfies the accumulator relation. The accumulator being satisfiable inductively shows that all instances that have been folded were satisfied as well. (additional protocol checks are required to reason about _which_ instances have been folded into the accumulator. See the [IVC specification](https://hackmd.io/h0yTcOHiQWeeTXnxTQhTNQ?view) for more information. (note to zac: put this in the yellow paper!) +The "Decider" Prover/Verifier validate whether an accumulator instance correctly satisfies the accumulator relation. The accumulator being satisfiable inductively shows that all instances that have been folded were satisfied as well. (additional protocol checks are required to reason about _which_ instances have been folded into the accumulator. See the [IVC specification](https://hackmd.io/h0yTcOHiQWeeTXnxTQhTNQ?view) for more information. (note to zac: put this in the protocol specs!) ## Goblin Plonk diff --git a/docs/docs/protocol-specs/state/nullifier-tree.md b/docs/docs/protocol-specs/state/nullifier-tree.md index 036b69cff01..e33c294643d 100644 --- a/docs/docs/protocol-specs/state/nullifier-tree.md +++ b/docs/docs/protocol-specs/state/nullifier-tree.md @@ -40,7 +40,7 @@ Missing info: - Details of the hash to use, and a domain separator for the hash. We might not know the final hash that we'll use, but we should propose one, and we should probably also give each hash a name. - E.g. `compute_parent_node("nullifier parent node".to_field(), left_child, right_child)` where `compute_siloed_nullifier = pedersen_hash` (for now). -Pseudocode/algorithms for insertion, batch insertion, membership proofs, non-membership proofs, so that the security of our approach can be validated. We should discuss the best way to consistently present such information, for all sections of the yellow paper. +Pseudocode/algorithms for insertion, batch insertion, membership proofs, non-membership proofs, so that the security of our approach can be validated. We should discuss the best way to consistently present such information, for all sections of the protocol specs. EDIT: maybe all these comments should actually go in cryptography/merkle-tree.md --> diff --git a/docs/docs/protocol-specs/state/public-data-tree.md b/docs/docs/protocol-specs/state/public-data-tree.md index 1c48c23a4d5..9489cfc40aa 100644 --- a/docs/docs/protocol-specs/state/public-data-tree.md +++ b/docs/docs/protocol-specs/state/public-data-tree.md @@ -39,5 +39,5 @@ Missing info: - Details of the hash to use, and a domain separator for the hash. We might not know the final hash that we'll use, but we should propose one, and we should probably also give each hash a name. - E.g. `compute_parent_node("nullifier parent node".to_field(), left_child, right_child)` where `compute_siloed_nullifier = pedersen_hash` (for now. Poseidon eventually, iiuc. Perhaps we should write this spec to state Poseidon). -Pseudocode/algorithms for insertion, batch insertion, membership proofs, non-membership proofs, so that the security of our approach can be validated. We should discuss the best way to consistently present such information, for all sections of the yellow paper. (EDIT: put this in cryptography/merkle-trees) +Pseudocode/algorithms for insertion, batch insertion, membership proofs, non-membership proofs, so that the security of our approach can be validated. We should discuss the best way to consistently present such information, for all sections of the protocol specs. (EDIT: put this in cryptography/merkle-trees) --> diff --git a/docs/docs/protocol-specs/transactions/local-execution.md b/docs/docs/protocol-specs/transactions/local-execution.md index 77f7a02ec7e..9beb8624db5 100644 --- a/docs/docs/protocol-specs/transactions/local-execution.md +++ b/docs/docs/protocol-specs/transactions/local-execution.md @@ -5,8 +5,8 @@ Transactions are initiated via a _transaction execution request_ sent from the u - `origin` diff --git a/l1-contracts/src/core/libraries/HeaderLib.sol b/l1-contracts/src/core/libraries/HeaderLib.sol index 9123f0e262b..b9688e4778b 100644 --- a/l1-contracts/src/core/libraries/HeaderLib.sol +++ b/l1-contracts/src/core/libraries/HeaderLib.sol @@ -67,7 +67,7 @@ library HeaderLib { struct StateReference { AppendOnlyTreeSnapshot l1ToL2MessageTree; - // Note: Can't use "partial" name here as in yellow paper because it is a reserved solidity keyword + // Note: Can't use "partial" name here as in protocol specs because it is a reserved solidity keyword PartialStateReference partialStateReference; } diff --git a/yarn-project/circuits.js/src/contract/contract_address.ts b/yarn-project/circuits.js/src/contract/contract_address.ts index 96196f01971..695ef983a54 100644 --- a/yarn-project/circuits.js/src/contract/contract_address.ts +++ b/yarn-project/circuits.js/src/contract/contract_address.ts @@ -11,7 +11,7 @@ import { type PublicKey } from '../types/public_key.js'; // TODO(@spalladino): Review all generator indices in this file /** - * Returns the deployment address for a given contract instance as defined on the [Yellow Paper](../../../../yellow-paper/docs/addresses-and-keys/specification.md). + * Returns the deployment address for a given contract instance as defined on the [Protocol Specs](../../../../docs/docs/protocol-specs/addresses-and-keys/specification.md). * ``` * salted_initialization_hash = pedersen([salt, initialization_hash, deployer, portal_contract_address as Field], GENERATOR__SALTED_INITIALIZATION_HASH) * partial_address = pedersen([contract_class_id, salted_initialization_hash], GENERATOR__CONTRACT_PARTIAL_ADDRESS_V1) diff --git a/yarn-project/circuits.js/src/contract/private_function_membership_proof.ts b/yarn-project/circuits.js/src/contract/private_function_membership_proof.ts index cbd39f5f253..2857b463c24 100644 --- a/yarn-project/circuits.js/src/contract/private_function_membership_proof.ts +++ b/yarn-project/circuits.js/src/contract/private_function_membership_proof.ts @@ -82,7 +82,7 @@ export function createPrivateFunctionMembershipProof( /** * Verifies that a private function with a membership proof as emitted by the ClassRegisterer contract is valid, - * as defined in the yellow paper at contract-deployment/classes: + * as defined in the protocol specs at contract-deployment/classes: * * ``` * // Load contract class from local db diff --git a/yarn-project/circuits.js/src/contract/unconstrained_function_membership_proof.ts b/yarn-project/circuits.js/src/contract/unconstrained_function_membership_proof.ts index 6df7afdb72e..a6b368c6d5e 100644 --- a/yarn-project/circuits.js/src/contract/unconstrained_function_membership_proof.ts +++ b/yarn-project/circuits.js/src/contract/unconstrained_function_membership_proof.ts @@ -66,7 +66,7 @@ export function createUnconstrainedFunctionMembershipProof( /** * Verifies that an unconstrained function with a membership proof as emitted by the ClassRegisterer contract is valid, - * as defined in the yellow paper at contract-deployment/classes: + * as defined in the protocol specs at contract-deployment/classes: * * ``` * // Load contract class from local db diff --git a/yarn-project/foundation/src/fields/fields.ts b/yarn-project/foundation/src/fields/fields.ts index bc180fa9ecb..c9b3c88fe96 100644 --- a/yarn-project/foundation/src/fields/fields.ts +++ b/yarn-project/foundation/src/fields/fields.ts @@ -372,7 +372,7 @@ function extendedEuclidean(a: bigint, modulus: bigint): [bigint, bigint, bigint] /** * GrumpkinScalar is an Fq. * @remarks Called GrumpkinScalar because it is used to represent elements in Grumpkin's scalar field as defined in - * the Aztec Yellow Paper. + * the Aztec Protocol Specs. */ export type GrumpkinScalar = Fq; export const GrumpkinScalar = Fq; diff --git a/yarn-project/simulator/src/avm/opcodes/context_getters.ts b/yarn-project/simulator/src/avm/opcodes/context_getters.ts index e07948e4657..d1fbc639771 100644 --- a/yarn-project/simulator/src/avm/opcodes/context_getters.ts +++ b/yarn-project/simulator/src/avm/opcodes/context_getters.ts @@ -7,7 +7,7 @@ export class L2GasLeft extends GetterInstruction { static type: string = 'L2GASLEFT'; static readonly opcode: Opcode = Opcode.L2GASLEFT; - // TODO(@spalladino) Yellow paper specifies that the value should be an Uint32, not a Field. + // TODO(@spalladino) Protocol specs specifies that the value should be an Uint32, not a Field. protected getValue(context: AvmContext): MemoryValue { return new Field(context.machineState.l2GasLeft); } From fafee8abbf922ded012a7b76faa48c445a3b60b5 Mon Sep 17 00:00:00 2001 From: Josh Crites Date: Wed, 10 Apr 2024 13:46:16 -0400 Subject: [PATCH 05/18] fix broken links --- docs/docs/protocol-specs/bytecode/index.md | 16 ++++++++-------- docs/docs/protocol-specs/logs/index.md | 2 +- docs/docs/protocol-specs/state/index.md | 4 ++-- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/docs/protocol-specs/bytecode/index.md b/docs/docs/protocol-specs/bytecode/index.md index a7484820b14..4f54d240c5f 100644 --- a/docs/docs/protocol-specs/bytecode/index.md +++ b/docs/docs/protocol-specs/bytecode/index.md @@ -42,7 +42,7 @@ There are three different (but related) bytecode standards that are used in Azte # AVM Bytecode -The AVM bytecode is the compilation target of the public functions of a contract. It's specified in the [AVM section](../public-vm/instruction-set). It allows control flow and uses a flat memory model which tracks bit sizes of values stored in memory via tagging of memory indexes. Sequencers run the AVM bytecode of the public functions of a contract using the AVM and prove the correct execution of it. +The AVM bytecode is the compilation target of the public functions of a contract. It's specified in the [AVM section](../public-vm/instruction-set.mdx). It allows control flow and uses a flat memory model which tracks bit sizes of values stored in memory via tagging of memory indexes. Sequencers run the AVM bytecode of the public functions of a contract using the AVM and prove the correct execution of it. # Brillig Bytecode @@ -52,7 +52,7 @@ Brillig bytecode will be very similar to AVM bytecode. While AVM bytecode is spe Oracles allow nondeterminism during the execution of a given function, allowing the simulator entity to choose the value that an oracle will return during the simulation process. Oracles are heavily used by aztec.nr to fetch data during simulation of private and unconstrained functions, such as fetching notes. They are also used to notify the simulator about events arising during execution, such as a nullified note so that it's not offered again during the simulation. -However, AVM bytecode doesn't allow arbitrary oracles, any nondeterminism introduced is done in a way that the protocol can ensure that the simulator entity (the sequencer) cannot manipulate the result of an oracle. As such, when transforming brillig bytecode to AVM bytecode, all the oracles are replaced by the specific opcodes that the AVM supports for nondeterminism, like [TIMESTAMP](../public-vm/instruction-set#isa-section-timestamp), [ADDRESS](../public-vm/instruction-set#isa-section-address), etc. Any opcode that requires the simulator entity to provide data external to the AVM memory is non-deterministic. +However, AVM bytecode doesn't allow arbitrary oracles, any nondeterminism introduced is done in a way that the protocol can ensure that the simulator entity (the sequencer) cannot manipulate the result of an oracle. As such, when transforming brillig bytecode to AVM bytecode, all the oracles are replaced by the specific opcodes that the AVM supports for nondeterminism, like [TIMESTAMP](../public-vm/instruction-set.mdx#isa-section-timestamp), [ADDRESS](../public-vm/instruction-set.mdx#isa-section-address), etc. Any opcode that requires the simulator entity to provide data external to the AVM memory is non-deterministic. The current implementation of Brillig can be found [in the noir repository](https://github.com/noir-lang/noir/blob/master/acvm-repo/brillig/src/opcodes.rs#L60). It's actively being changed to become "AVM bytecode without arbitrary oracles" and right now the differences are handled by a transpiler. @@ -73,7 +73,7 @@ This implies that a block of ACIR bytecode can represent more than one program, ## Compiling a contract -When a contract is compiled, an artifact will be generated. This artifact needs to be hashed in a specific manner [detailed in the deployment section](../contract-deployment/classes#artifact-hash) for publishing. +When a contract is compiled, an artifact will be generated. This artifact needs to be hashed in a specific manner [detailed in the deployment section](../contract-deployment/classes.md#artifact-hash) for publishing. The exact form of the artifact is not specified by the protocol, but it needs at least the following information: @@ -148,19 +148,19 @@ If the function is public, the entry will be its ABI. If the function is private ### Bytecode in the artifact -The protocol mandates that public bytecode needs to be published to a data availability solution, since the sequencers need to have the data available to run the public functions. Also, it needs to use an encoding that is friendly to the public VM, such as the one specified in the [AVM section](../public-vm/bytecode-validation-circuit). +The protocol mandates that public bytecode needs to be published to a data availability solution, since the sequencers need to have the data available to run the public functions. Also, it needs to use an encoding that is friendly to the public VM, such as the one specified in the [AVM section](../public-vm/bytecode-validation-circuit.md). -The bytecode of private and unconstrained functions doesn't need to be published, instead, users that desire to use a given contract can add the artifact to their PXE before interacting with it. Publishing it is [supported but not required](../contract-deployment/classes/#broadcast) by the protocol. However, the verification key of a private function is hashed into the function's leaf of the contract's function tree, so the user can prove to the protocol that he executed the function correctly. Also, contract classes contain an [artifact hash](../contract-deployment/classes#artifact-hash) so the PXE can verify that the artifact corresponds with the contract class. +The bytecode of private and unconstrained functions doesn't need to be published, instead, users that desire to use a given contract can add the artifact to their PXE before interacting with it. Publishing it is [supported but not required](../contract-deployment/classes.md#broadcast) by the protocol. However, the verification key of a private function is hashed into the function's leaf of the contract's function tree, so the user can prove to the protocol that he executed the function correctly. Also, contract classes contain an [artifact hash](../contract-deployment/classes.md#artifact-hash) so the PXE can verify that the artifact corresponds with the contract class. The encoding of private and unconstrained functions is not specified by the protocol, but it's recommended to follow [the encoding](https://github.com/noir-lang/noir/blob/master/acvm-repo/acir/src/circuit/mod.rs#L157) that Barretenberg and the ACVM share that is serialization using bincode and gzip for compression. -This implies that the encoding of private and unconstrained functions does not need to be friendly to circuits, since when publishing it the protocol only sees a [generic array of field elements](../contract-deployment/classes#broadcast). +This implies that the encoding of private and unconstrained functions does not need to be friendly to circuits, since when publishing it the protocol only sees a [generic array of field elements](../contract-deployment/classes.md#broadcast). ## Executing a private function When executing a private function, its ACIR bytecode will be executed by the PXE using the ACVM. The ACVM will generate the witness of the execution. The proving system can be used to generate a proof of the correctness of the witness. -The fact that the correct function was executed is checked by the protocol by verifying that the [contract class ID](../contract-deployment/classes#class-identifier) contains one leaf in the function tree with this selector and the verification key of the function. +The fact that the correct function was executed is checked by the protocol by verifying that the [contract class ID](../contract-deployment/classes.md#class-identifier) contains one leaf in the function tree with this selector and the verification key of the function. ## Executing an unconstrained function @@ -170,4 +170,4 @@ When executing an unconstrained function, its Brillig bytecode will be executed When executing a public function, its AVM bytecode will be executed by the sequencer with the specified selector and arguments. The sequencer will generate a public VM proof of the correct execution of the AVM bytecode. -The fact that the correct bytecode was executed is checked by the protocol by verifying that the [contract class ID](../contract-deployment/classes#class-identifier) contains the [commitment](../public-vm/bytecode-validation-circuit#committed-representation) to the bytecode used. +The fact that the correct bytecode was executed is checked by the protocol by verifying that the [contract class ID](../contract-deployment/classes.md#class-identifier) contains the [commitment](../public-vm/bytecode-validation-circuit.md#committed-representation) to the bytecode used. diff --git a/docs/docs/protocol-specs/logs/index.md b/docs/docs/protocol-specs/logs/index.md index 343b4d980fe..ab805085834 100644 --- a/docs/docs/protocol-specs/logs/index.md +++ b/docs/docs/protocol-specs/logs/index.md @@ -333,4 +333,4 @@ function hash_log_data(logs_data) { ## Log Encryption -Refer to [Private Message Delivery](../private-message-delivery/) for detailed information on generating encrypted data. +Refer to [Private Message Delivery](../private-message-delivery/index.md) for detailed information on generating encrypted data. diff --git a/docs/docs/protocol-specs/state/index.md b/docs/docs/protocol-specs/state/index.md index c927444bd88..bd0a53485b7 100644 --- a/docs/docs/protocol-specs/state/index.md +++ b/docs/docs/protocol-specs/state/index.md @@ -76,10 +76,10 @@ Below is a short description of the state catagories (trees) and why they have t - [**Note Hashes**](./note-hash-tree.md): A set of hashes (commitments) of the individual blobs of contract data (we call these blobs of data notes). New notes can be created and their hashes inserted through contract execution. We need to support efficient membership proofs as any read will require one to prove validity. The set is represented as an [Append-only Merkle tree](./tree-implementations.md#append-only-merkle-trees), storing the note hashes as leaves. - [**Nullifiers**](./nullifier-tree.md): A set of nullifiers for notes that have been spent. We need to support efficient non-membership proofs since we need to check that a note has not been spent before it can be used. The set is represented as an [Indexed Merkle tree](./tree-implementations.md#indexed-merkle-trees). - [**Public Data**](./public-data-tree.md): The key-value store for public contract state. We need to support both efficient membership and non-membership proofs! We require both, since the tree is "empty" from the start. Meaning that if the key is not already stored (non-membership), we need to insert it, and if it is already stored (membership) we need to just update the value. -- **L1 to L2 Messages**: The set of messages sent from L1 to L2. The set itself only needs to support efficient membership proofs, so we can ensure that the message was correctly sent from L1. However, it utilizes the Nullifier tree from above to ensure that the message cannot be processed twice. The set is represented as an [Append-only Merkle tree](./tree-implementations.md#append-only-merkle-trees). For more information on how the L1 to L2 messages are used, see the [L1 Smart Contracts](../l1-smart-contracts) page. +- **L1 to L2 Messages**: The set of messages sent from L1 to L2. The set itself only needs to support efficient membership proofs, so we can ensure that the message was correctly sent from L1. However, it utilizes the Nullifier tree from above to ensure that the message cannot be processed twice. The set is represented as an [Append-only Merkle tree](./tree-implementations.md#append-only-merkle-trees). For more information on how the L1 to L2 messages are used, see the [L1 Smart Contracts](../l1-smart-contracts/index.md) page. - [**Archive Tree**](./archive.md): The set of block headers that have been processed. We need to support efficient membership proofs as this is used in private execution to get the roots of the other trees. The set is represented as an [Append-only Merkle tree](./tree-implementations.md#append-only-merkle-trees). -To recall, the global state in Aztec is represented by a set of Merkle trees: the [Note Hash tree](./note-hash-tree.md), [Nullifier tree](./nullifier-tree.md), and [Public Data tree](./public-data-tree.md) reflect the latest state of the chain, while the L1 to L2 message tree allows for [cross-chain communication](../l1-smart-contracts/#l2-outbox) and the [Archive Tree](./archive.md) allows for historical state access. +To recall, the global state in Aztec is represented by a set of Merkle trees: the [Note Hash tree](./note-hash-tree.md), [Nullifier tree](./nullifier-tree.md), and [Public Data tree](./public-data-tree.md) reflect the latest state of the chain, while the L1 to L2 message tree allows for [cross-chain communication](../l1-smart-contracts/index.md#l2-outbox) and the [Archive Tree](./archive.md) allows for historical state access. From 672df73978d5b90af069e495810224840fddd474 Mon Sep 17 00:00:00 2001 From: Josh Crites Date: Wed, 10 Apr 2024 13:51:50 -0400 Subject: [PATCH 06/18] changes from 986e7f924e9af6461e3e88de29f22cf2a8f45c4e --- .../InstructionSet/InstructionSet.js | 2428 ++++++++++------- 1 file changed, 1398 insertions(+), 1030 deletions(-) diff --git a/docs/src/preprocess/InstructionSet/InstructionSet.js b/docs/src/preprocess/InstructionSet/InstructionSet.js index ac5def0355e..936a15b0c23 100644 --- a/docs/src/preprocess/InstructionSet/InstructionSet.js +++ b/docs/src/preprocess/InstructionSet/InstructionSet.js @@ -1,25 +1,65 @@ -const {instructionSize} = require('./InstructionSize'); +const { instructionSize } = require("./InstructionSize"); -const TOPICS_IN_TABLE = [ - "Name", "Summary", "Expression", -]; +const TOPICS_IN_TABLE = ["Name", "Summary", "Expression"]; const TOPICS_IN_SECTIONS = [ - "Name", "Summary", "Category", "Flags", "Args", "Expression", "Details", "World State access tracing", "Additional AVM circuit checks", "Triggers downstream circuit operations", "Tag checks", "Tag updates", "Bit-size", + "Name", + "Summary", + "Category", + "Flags", + "Args", + "Expression", + "Details", + "World State access tracing", + "Additional AVM circuit checks", + "Triggers downstream circuit operations", + "Tag checks", + "Tag updates", + "Bit-size", ]; -const IN_TAG_DESCRIPTION = "The [tag/size](./memory-model#tags-and-tagged-memory) to check inputs against and tag the destination with."; -const IN_TAG_DESCRIPTION_NO_FIELD = IN_TAG_DESCRIPTION + " `field` type is NOT supported for this instruction."; -const DST_TAG_DESCRIPTION = "The [tag/size](./memory-model#tags-and-tagged-memory) to tag the destination with but not to check inputs against."; -const INDIRECT_FLAG_DESCRIPTION = "Toggles whether each memory-offset argument is an indirect offset. Rightmost bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`."; +const IN_TAG_DESCRIPTION = + "The [tag/size](./memory-model#tags-and-tagged-memory) to check inputs against and tag the destination with."; +const IN_TAG_DESCRIPTION_NO_FIELD = + IN_TAG_DESCRIPTION + " `field` type is NOT supported for this instruction."; +const DST_TAG_DESCRIPTION = + "The [tag/size](./memory-model#tags-and-tagged-memory) to tag the destination with but not to check inputs against."; +const INDIRECT_FLAG_DESCRIPTION = + "Toggles whether each memory-offset argument is an indirect offset. Rightmost bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`."; const CALL_INSTRUCTION_ARGS = [ - {"name": "gasOffset", "description": "offset to three words containing `{l1GasLeft, l2GasLeft, daGasLeft}`: amount of gas to provide to the callee"}, - {"name": "addrOffset", "description": "address of the contract to call"}, - {"name": "argsOffset", "description": "memory offset to args (will become the callee's calldata)"}, - {"name": "argsSize", "description": "number of words to pass via callee's calldata", "mode": "immediate", "type": "u32"}, - {"name": "retOffset", "description": "destination memory offset specifying where to store the data returned from the callee"}, - {"name": "retSize", "description": "number of words to copy from data returned by callee", "mode": "immediate", "type": "u32"}, - {"name": "successOffset", "description": "destination memory offset specifying where to store the call's success (0: failure, 1: success)", "type": "u8"}, + { + name: "gasOffset", + description: + "offset to three words containing `{l1GasLeft, l2GasLeft, daGasLeft}`: amount of gas to provide to the callee", + }, + { name: "addrOffset", description: "address of the contract to call" }, + { + name: "argsOffset", + description: "memory offset to args (will become the callee's calldata)", + }, + { + name: "argsSize", + description: "number of words to pass via callee's calldata", + mode: "immediate", + type: "u32", + }, + { + name: "retOffset", + description: + "destination memory offset specifying where to store the data returned from the callee", + }, + { + name: "retSize", + description: "number of words to copy from data returned by callee", + mode: "immediate", + type: "u32", + }, + { + name: "successOffset", + description: + "destination memory offset specifying where to store the call's success (0: failure, 1: success)", + type: "u8", + }, ]; const CALL_INSTRUCTION_DETAILS = ` ["Nested contract calls"](./nested-calls) provides a full explanation of this @@ -29,756 +69,1008 @@ const CALL_INSTRUCTION_DETAILS = ` after the nested call halts.`; const INSTRUCTION_SET_RAW = [ - { - "id": "add", - "Name": "`ADD`", - "Category": "Compute - Arithmetic", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - {"name": "inTag", "description": IN_TAG_DESCRIPTION}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of the operation's left input"}, - {"name": "bOffset", "description": "memory offset of the operation's right input"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = M[aOffset] + M[bOffset] mod 2^k`", - "Summary": "Addition (a + b)", - "Details": "Wraps on overflow", - "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", - "Tag updates": "`T[dstOffset] = inTag`", - }, - { - "id": "sub", - "Name": "`SUB`", - "Category": "Compute - Arithmetic", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - {"name": "inTag", "description": IN_TAG_DESCRIPTION}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of the operation's left input"}, - {"name": "bOffset", "description": "memory offset of the operation's right input"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = M[aOffset] - M[bOffset] mod 2^k`", - "Summary": "Subtraction (a - b)", - "Details": "Wraps on undeflow", - "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", - "Tag updates": "`T[dstOffset] = inTag`", - }, - { - "id": "mul", - "Name": "`MUL`", - "Category": "Compute - Arithmetic", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - {"name": "inTag", "description": IN_TAG_DESCRIPTION}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of the operation's left input"}, - {"name": "bOffset", "description": "memory offset of the operation's right input"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = M[aOffset] * M[bOffset] mod 2^k`", - "Summary": "Multiplication (a * b)", - "Details": "Wraps on overflow", - "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", - "Tag updates": "`T[dstOffset] = inTag`", - }, - { - "id": "div", - "Name": "`DIV`", - "Category": "Compute - Arithmetic", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - {"name": "inTag", "description": IN_TAG_DESCRIPTION}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of the operation's left input"}, - {"name": "bOffset", "description": "memory offset of the operation's right input"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = M[aOffset] / M[bOffset]`", - "Summary": "Unsigned integer division (a / b)", - "Details": "If the input is a field, it will be interpreted as an integer", - "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", - "Tag updates": "`T[dstOffset] = inTag`", - }, - { - "id": "fdiv", - "Name": "`FDIV`", - "Category": "Compute - Arithmetic", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of the operation's left input"}, - {"name": "bOffset", "description": "memory offset of the operation's right input"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = M[aOffset] / M[bOffset]`", - "Summary": "Field division (a / b)", - "Details": "", - "Tag checks": "`T[aOffset] == T[bOffset] == field`", - "Tag updates": "`T[dstOffset] = field`", - }, - { - "id": "eq", - "Name": "`EQ`", - "Category": "Compute - Comparators", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - {"name": "inTag", "description": IN_TAG_DESCRIPTION}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of the operation's left input"}, - {"name": "bOffset", "description": "memory offset of the operation's right input"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result", "type": "u8"}, - ], - "Expression": "`M[dstOffset] = M[aOffset] == M[bOffset] ? 1 : 0`", - "Summary": "Equality check (a == b)", - "Details": "", - "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", - "Tag updates": "`T[dstOffset] = u8`", - }, - { - "id": "lt", - "Name": "`LT`", - "Category": "Compute - Comparators", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - {"name": "inTag", "description": IN_TAG_DESCRIPTION}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of the operation's left input"}, - {"name": "bOffset", "description": "memory offset of the operation's right input"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result", "type": "u8"}, - ], - "Expression": "`M[dstOffset] = M[aOffset] < M[bOffset] ? 1 : 0`", - "Summary": "Less-than check (a < b)", - "Details": "", - "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", - "Tag updates": "`T[dstOffset] = u8`", - }, - { - "id": "lte", - "Name": "`LTE`", - "Category": "Compute - Comparators", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - {"name": "inTag", "description": IN_TAG_DESCRIPTION}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of the operation's left input"}, - {"name": "bOffset", "description": "memory offset of the operation's right input"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result", "type": "u8"}, - ], - "Expression": "`M[dstOffset] = M[aOffset] <= M[bOffset] ? 1 : 0`", - "Summary": "Less-than-or-equals check (a <= b)", - "Details": "", - "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", - "Tag updates": "`T[dstOffset] = u8`", - }, - { - "id": "and", - "Name": "`AND`", - "Category": "Compute - Bitwise", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - {"name": "inTag", "description": IN_TAG_DESCRIPTION_NO_FIELD}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of the operation's left input"}, - {"name": "bOffset", "description": "memory offset of the operation's right input"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = M[aOffset] AND M[bOffset]`", - "Summary": "Bitwise AND (a & b)", - "Details": "", - "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", - "Tag updates": "`T[dstOffset] = inTag`", - }, - { - "id": "or", - "Name": "`OR`", - "Category": "Compute - Bitwise", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - {"name": "inTag", "description": IN_TAG_DESCRIPTION_NO_FIELD}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of the operation's left input"}, - {"name": "bOffset", "description": "memory offset of the operation's right input"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = M[aOffset] OR M[bOffset]`", - "Summary": "Bitwise OR (a | b)", - "Details": "", - "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", - "Tag updates": "`T[dstOffset] = inTag`", - }, - { - "id": "xor", - "Name": "`XOR`", - "Category": "Compute - Bitwise", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - {"name": "inTag", "description": IN_TAG_DESCRIPTION_NO_FIELD}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of the operation's left input"}, - {"name": "bOffset", "description": "memory offset of the operation's right input"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = M[aOffset] XOR M[bOffset]`", - "Summary": "Bitwise XOR (a ^ b)", - "Details": "", - "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", - "Tag updates": "`T[dstOffset] = inTag`", - }, - { - "id": "not", - "Name": "`NOT`", - "Category": "Compute - Bitwise", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - {"name": "inTag", "description": IN_TAG_DESCRIPTION_NO_FIELD}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of the operation's input"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = NOT M[aOffset]`", - "Summary": "Bitwise NOT (inversion)", - "Details": "", - "Tag checks": "`T[aOffset] == inTag`", - "Tag updates": "`T[dstOffset] = inTag`", - }, - { - "id": "shl", - "Name": "`SHL`", - "Category": "Compute - Bitwise", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - {"name": "inTag", "description": IN_TAG_DESCRIPTION_NO_FIELD}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of the operation's left input"}, - {"name": "bOffset", "description": "memory offset of the operation's right input"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = M[aOffset] << M[bOffset]`", - "Summary": "Bitwise leftward shift (a << b)", - "Details": "", - "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", - "Tag updates": "`T[dstOffset] = inTag`", - }, - { - "id": "shr", - "Name": "`SHR`", - "Category": "Compute - Bitwise", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - {"name": "inTag", "description": IN_TAG_DESCRIPTION_NO_FIELD}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of the operation's left input"}, - {"name": "bOffset", "description": "memory offset of the operation's right input"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = M[aOffset] >> M[bOffset]`", - "Summary": "Bitwise rightward shift (a >> b)", - "Details": "", - "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", - "Tag updates": "`T[dstOffset] = inTag`", - }, - { - "id": "cast", - "Name": "`CAST`", - "Category": "Type Conversions", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - {"name": "dstTag", "description": DST_TAG_DESCRIPTION}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of word to cast"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = cast(M[aOffset])`", - "Summary": "Type cast", - "Details": "Cast a word in memory based on the `dstTag` specified in the bytecode. Truncates (`M[dstOffset] = M[aOffset] mod 2^dstsize`) when casting to a smaller type, left-zero-pads when casting to a larger type. See [here](./memory-model#cast-and-tag-conversions) for more details.", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = dstTag`", - }, - { - "id": "address", - "Name": "`ADDRESS`", - "Category": "Execution Environment", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.address`", - "Summary": "Get the address of the currently executing l2 contract", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "storageaddress", - "Name": "`STORAGEADDRESS`", - "Category": "Execution Environment", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.storageAddress`", - "Summary": "Get the _storage_ address of the currently executing context", - "Details": "The storage address is used for public storage accesses.", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "origin", - "Name": "`ORIGIN`", - "Category": "Execution Environment", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.origin`", - "Summary": "Get the transaction's origination address", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "sender", - "Name": "`SENDER`", - "Category": "Execution Environment", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.sender`", - "Summary": "Get the address of the sender (caller of the current context)", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "portal", - "Name": "`PORTAL`", - "Category": "Execution Environment", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.portal`", - "Summary": "Get the address of the l1 portal contract", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "feeperl1gas", - "Name": "`FEEPERL1GAS`", - "Category": "Execution Environment", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.feePerL1Gas`", - "Summary": "Get the fee to be paid per \"L1 gas\" - constant for entire transaction", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "feeperl2gas", - "Name": "`FEEPERL2GAS`", - "Category": "Execution Environment", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.feePerL2Gas`", - "Summary": "Get the fee to be paid per \"L2 gas\" - constant for entire transaction", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "feeperdagas", - "Name": "`FEEPERDAGAS`", - "Category": "Execution Environment", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.feePerDaGas`", - "Summary": "Get the fee to be paid per \"DA gas\" - constant for entire transaction", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "contractcalldepth", - "Name": "`CONTRACTCALLDEPTH`", - "Category": "Execution Environment", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.contractCallDepth`", - "Summary": "Get how many contract calls deep the current call context is", - "Details": "Note: security issues with EVM's tx.origin can be resolved by asserting `calldepth == 0`.", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u8`", - }, - { - "id": "chainid", - "Name": "`CHAINID`", - "Category": "Execution Environment - Globals", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.globals.chainId`", - "Summary": "Get this rollup's L1 chain ID", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "version", - "Name": "`VERSION`", - "Category": "Execution Environment - Globals", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.globals.version`", - "Summary": "Get this rollup's L2 version ID", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "blocknumber", - "Name": "`BLOCKNUMBER`", - "Category": "Execution Environment - Globals", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.globals.blocknumber`", - "Summary": "Get this L2 block's number", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "timestamp", - "Name": "`TIMESTAMP`", - "Category": "Execution Environment - Globals", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.globals.timestamp`", - "Summary": "Get this L2 block's timestamp", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u64`", - }, - { - "id": "coinbase", - "Name": "`COINBASE`", - "Category": "Execution Environment - Globals", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.globals.coinbase`", - "Summary": "Get the block's beneficiary address", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "blockl1gaslimit", - "Name": "`BLOCKL1GASLIMIT`", - "Category": "Execution Environment - Globals", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.globals.l1GasLimit`", - "Summary": "Total amount of \"L1 gas\" that a block can consume", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "blockl2gaslimit", - "Name": "`BLOCKL2GASLIMIT`", - "Category": "Execution Environment - Globals", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.globals.l2GasLimit`", - "Summary": "Total amount of \"L2 gas\" that a block can consume", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "blockdagaslimit", - "Name": "`BLOCKDAGASLIMIT`", - "Category": "Execution Environment - Globals", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.environment.globals.daGasLimit`", - "Summary": "Total amount of \"DA gas\" that a block can consume", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "calldatacopy", - "Name": "`CALLDATACOPY`", - "Category": "Execution Environment - Calldata", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "cdOffset", "description": "offset into calldata to copy from"}, - {"name": "copySize", "description": "number of words to copy", "mode": "immediate", "type": "u32"}, - {"name": "dstOffset", "description": "memory offset specifying where to copy the first word to"}, - ], - "Expression": "`M[dstOffset:dstOffset+copySize] = context.environment.calldata[cdOffset:cdOffset+copySize]`", - "Summary": "Copy calldata into memory", - "Details": "Calldata is read-only and cannot be directly operated on by other instructions. This instruction moves words from calldata into memory so they can be operated on normally.", - "Tag checks": "", - "Tag updates": "`T[dstOffset:dstOffset+copySize] = field`", - }, - { - "id": "l1gasleft", - "Name": "`L1GASLEFT`", - "Category": "Machine State - Gas", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.machineState.l1GasLeft`", - "Summary": "Remaining \"L1 gas\" for this call (after this instruction)", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "l2gasleft", - "Name": "`L2GASLEFT`", - "Category": "Machine State - Gas", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.MachineState.l2GasLeft`", - "Summary": "Remaining \"L2 gas\" for this call (after this instruction)", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "dagasleft", - "Name": "`DAGASLEFT`", - "Category": "Machine State - Gas", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = context.machineState.daGasLeft`", - "Summary": "Remaining \"DA gas\" for this call (after this instruction)", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = u32`", - }, - { - "id": "jump", - "Name": "`JUMP`", - "Category": "Machine State - Control Flow", - "Flags": [], - "Args": [ - {"name": "loc", "description": "target location to jump to", "mode": "immediate", "type": "u32"}, - ], - "Expression": "`context.machineState.pc = loc`", - "Summary": "Jump to a location in the bytecode", - "Details": "Target location is an immediate value (a constant in the bytecode).", - "Tag checks": "", - "Tag updates": "", - }, - { - "id": "jumpi", - "Name": "`JUMPI`", - "Category": "Machine State - Control Flow", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "loc", "description": "target location conditionally jump to", "mode": "immediate", "type": "u32"}, - {"name": "condOffset", "description": "memory offset of the operations 'conditional' input"}, - ], - "Expression": "`context.machineState.pc = M[condOffset] > 0 ? loc : context.machineState.pc`", - "Summary": "Conditionally jump to a location in the bytecode", - "Details": "Target location is an immediate value (a constant in the bytecode). `T[condOffset]` is not checked because the greater-than-zero suboperation is the same regardless of type.", - "Tag checks": "", - "Tag updates": "", - }, - { - "id": "internalcall", - "Name": "`INTERNALCALL`", - "Category": "Machine State - Control Flow", - "Flags": [], - "Args": [ - {"name": "loc", "description": "target location to jump/call to", "mode": "immediate", "type": "u32"}, - ], - "Expression": ` + { + id: "add", + Name: "`ADD`", + Category: "Compute - Arithmetic", + Flags: [ + { name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }, + { name: "inTag", description: IN_TAG_DESCRIPTION }, + ], + Args: [ + { + name: "aOffset", + description: "memory offset of the operation's left input", + }, + { + name: "bOffset", + description: "memory offset of the operation's right input", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = M[aOffset] + M[bOffset] mod 2^k`", + Summary: "Addition (a + b)", + Details: "Wraps on overflow", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + id: "sub", + Name: "`SUB`", + Category: "Compute - Arithmetic", + Flags: [ + { name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }, + { name: "inTag", description: IN_TAG_DESCRIPTION }, + ], + Args: [ + { + name: "aOffset", + description: "memory offset of the operation's left input", + }, + { + name: "bOffset", + description: "memory offset of the operation's right input", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = M[aOffset] - M[bOffset] mod 2^k`", + Summary: "Subtraction (a - b)", + Details: "Wraps on undeflow", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + id: "mul", + Name: "`MUL`", + Category: "Compute - Arithmetic", + Flags: [ + { name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }, + { name: "inTag", description: IN_TAG_DESCRIPTION }, + ], + Args: [ + { + name: "aOffset", + description: "memory offset of the operation's left input", + }, + { + name: "bOffset", + description: "memory offset of the operation's right input", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = M[aOffset] * M[bOffset] mod 2^k`", + Summary: "Multiplication (a * b)", + Details: "Wraps on overflow", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + id: "div", + Name: "`DIV`", + Category: "Compute - Arithmetic", + Flags: [ + { name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }, + { name: "inTag", description: IN_TAG_DESCRIPTION }, + ], + Args: [ + { + name: "aOffset", + description: "memory offset of the operation's left input", + }, + { + name: "bOffset", + description: "memory offset of the operation's right input", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = M[aOffset] / M[bOffset]`", + Summary: "Unsigned integer division (a / b)", + Details: "If the input is a field, it will be interpreted as an integer", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + id: "fdiv", + Name: "`FDIV`", + Category: "Compute - Arithmetic", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "aOffset", + description: "memory offset of the operation's left input", + }, + { + name: "bOffset", + description: "memory offset of the operation's right input", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = M[aOffset] / M[bOffset]`", + Summary: "Field division (a / b)", + Details: "", + "Tag checks": "`T[aOffset] == T[bOffset] == field`", + "Tag updates": "`T[dstOffset] = field`", + }, + { + id: "eq", + Name: "`EQ`", + Category: "Compute - Comparators", + Flags: [ + { name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }, + { name: "inTag", description: IN_TAG_DESCRIPTION }, + ], + Args: [ + { + name: "aOffset", + description: "memory offset of the operation's left input", + }, + { + name: "bOffset", + description: "memory offset of the operation's right input", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + type: "u8", + }, + ], + Expression: "`M[dstOffset] = M[aOffset] == M[bOffset] ? 1 : 0`", + Summary: "Equality check (a == b)", + Details: "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = u8`", + }, + { + id: "lt", + Name: "`LT`", + Category: "Compute - Comparators", + Flags: [ + { name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }, + { name: "inTag", description: IN_TAG_DESCRIPTION }, + ], + Args: [ + { + name: "aOffset", + description: "memory offset of the operation's left input", + }, + { + name: "bOffset", + description: "memory offset of the operation's right input", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + type: "u8", + }, + ], + Expression: "`M[dstOffset] = M[aOffset] < M[bOffset] ? 1 : 0`", + Summary: "Less-than check (a < b)", + Details: "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = u8`", + }, + { + id: "lte", + Name: "`LTE`", + Category: "Compute - Comparators", + Flags: [ + { name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }, + { name: "inTag", description: IN_TAG_DESCRIPTION }, + ], + Args: [ + { + name: "aOffset", + description: "memory offset of the operation's left input", + }, + { + name: "bOffset", + description: "memory offset of the operation's right input", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + type: "u8", + }, + ], + Expression: "`M[dstOffset] = M[aOffset] <= M[bOffset] ? 1 : 0`", + Summary: "Less-than-or-equals check (a <= b)", + Details: "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = u8`", + }, + { + id: "and", + Name: "`AND`", + Category: "Compute - Bitwise", + Flags: [ + { name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }, + { name: "inTag", description: IN_TAG_DESCRIPTION_NO_FIELD }, + ], + Args: [ + { + name: "aOffset", + description: "memory offset of the operation's left input", + }, + { + name: "bOffset", + description: "memory offset of the operation's right input", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = M[aOffset] AND M[bOffset]`", + Summary: "Bitwise AND (a & b)", + Details: "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + id: "or", + Name: "`OR`", + Category: "Compute - Bitwise", + Flags: [ + { name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }, + { name: "inTag", description: IN_TAG_DESCRIPTION_NO_FIELD }, + ], + Args: [ + { + name: "aOffset", + description: "memory offset of the operation's left input", + }, + { + name: "bOffset", + description: "memory offset of the operation's right input", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = M[aOffset] OR M[bOffset]`", + Summary: "Bitwise OR (a | b)", + Details: "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + id: "xor", + Name: "`XOR`", + Category: "Compute - Bitwise", + Flags: [ + { name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }, + { name: "inTag", description: IN_TAG_DESCRIPTION_NO_FIELD }, + ], + Args: [ + { + name: "aOffset", + description: "memory offset of the operation's left input", + }, + { + name: "bOffset", + description: "memory offset of the operation's right input", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = M[aOffset] XOR M[bOffset]`", + Summary: "Bitwise XOR (a ^ b)", + Details: "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + id: "not", + Name: "`NOT`", + Category: "Compute - Bitwise", + Flags: [ + { name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }, + { name: "inTag", description: IN_TAG_DESCRIPTION_NO_FIELD }, + ], + Args: [ + { + name: "aOffset", + description: "memory offset of the operation's input", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = NOT M[aOffset]`", + Summary: "Bitwise NOT (inversion)", + Details: "", + "Tag checks": "`T[aOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + id: "shl", + Name: "`SHL`", + Category: "Compute - Bitwise", + Flags: [ + { name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }, + { name: "inTag", description: IN_TAG_DESCRIPTION_NO_FIELD }, + ], + Args: [ + { + name: "aOffset", + description: "memory offset of the operation's left input", + }, + { + name: "bOffset", + description: "memory offset of the operation's right input", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = M[aOffset] << M[bOffset]`", + Summary: "Bitwise leftward shift (a << b)", + Details: "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + id: "shr", + Name: "`SHR`", + Category: "Compute - Bitwise", + Flags: [ + { name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }, + { name: "inTag", description: IN_TAG_DESCRIPTION_NO_FIELD }, + ], + Args: [ + { + name: "aOffset", + description: "memory offset of the operation's left input", + }, + { + name: "bOffset", + description: "memory offset of the operation's right input", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = M[aOffset] >> M[bOffset]`", + Summary: "Bitwise rightward shift (a >> b)", + Details: "", + "Tag checks": "`T[aOffset] == T[bOffset] == inTag`", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + id: "cast", + Name: "`CAST`", + Category: "Type Conversions", + Flags: [ + { name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }, + { name: "dstTag", description: DST_TAG_DESCRIPTION }, + ], + Args: [ + { name: "aOffset", description: "memory offset of word to cast" }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = cast(M[aOffset])`", + Summary: "Type cast", + Details: + "Cast a word in memory based on the `dstTag` specified in the bytecode. Truncates (`M[dstOffset] = M[aOffset] mod 2^dstsize`) when casting to a smaller type, left-zero-pads when casting to a larger type. See [here](./memory-model#cast-and-tag-conversions) for more details.", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = dstTag`", + }, + { + id: "address", + Name: "`ADDRESS`", + Category: "Execution Environment", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.address`", + Summary: "Get the address of the currently executing l2 contract", + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "storageaddress", + Name: "`STORAGEADDRESS`", + Category: "Execution Environment", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.storageAddress`", + Summary: "Get the _storage_ address of the currently executing context", + Details: "The storage address is used for public storage accesses.", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "origin", + Name: "`ORIGIN`", + Category: "Execution Environment", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.origin`", + Summary: "Get the transaction's origination address", + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "sender", + Name: "`SENDER`", + Category: "Execution Environment", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.sender`", + Summary: "Get the address of the sender (caller of the current context)", + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "portal", + Name: "`PORTAL`", + Category: "Execution Environment", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.portal`", + Summary: "Get the address of the l1 portal contract", + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "feeperl1gas", + Name: "`FEEPERL1GAS`", + Category: "Execution Environment", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.feePerL1Gas`", + Summary: + 'Get the fee to be paid per "L1 gas" - constant for entire transaction', + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "feeperl2gas", + Name: "`FEEPERL2GAS`", + Category: "Execution Environment", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.feePerL2Gas`", + Summary: + 'Get the fee to be paid per "L2 gas" - constant for entire transaction', + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "feeperdagas", + Name: "`FEEPERDAGAS`", + Category: "Execution Environment", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.feePerDaGas`", + Summary: + 'Get the fee to be paid per "DA gas" - constant for entire transaction', + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "contractcalldepth", + Name: "`CONTRACTCALLDEPTH`", + Category: "Execution Environment", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.contractCallDepth`", + Summary: "Get how many contract calls deep the current call context is", + Details: + "Note: security issues with EVM's tx.origin can be resolved by asserting `calldepth == 0`.", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u8`", + }, + { + id: "chainid", + Name: "`CHAINID`", + Category: "Execution Environment - Globals", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.globals.chainId`", + Summary: "Get this rollup's L1 chain ID", + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "version", + Name: "`VERSION`", + Category: "Execution Environment - Globals", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.globals.version`", + Summary: "Get this rollup's L2 version ID", + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "blocknumber", + Name: "`BLOCKNUMBER`", + Category: "Execution Environment - Globals", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.globals.blocknumber`", + Summary: "Get this L2 block's number", + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "timestamp", + Name: "`TIMESTAMP`", + Category: "Execution Environment - Globals", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.globals.timestamp`", + Summary: "Get this L2 block's timestamp", + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u64`", + }, + { + id: "coinbase", + Name: "`COINBASE`", + Category: "Execution Environment - Globals", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.globals.coinbase`", + Summary: "Get the block's beneficiary address", + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "blockl1gaslimit", + Name: "`BLOCKL1GASLIMIT`", + Category: "Execution Environment - Globals", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.globals.l1GasLimit`", + Summary: 'Total amount of "L1 gas" that a block can consume', + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "blockl2gaslimit", + Name: "`BLOCKL2GASLIMIT`", + Category: "Execution Environment - Globals", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.globals.l2GasLimit`", + Summary: 'Total amount of "L2 gas" that a block can consume', + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "blockdagaslimit", + Name: "`BLOCKDAGASLIMIT`", + Category: "Execution Environment - Globals", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.environment.globals.daGasLimit`", + Summary: 'Total amount of "DA gas" that a block can consume', + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "calldatacopy", + Name: "`CALLDATACOPY`", + Category: "Execution Environment - Calldata", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { name: "cdOffset", description: "offset into calldata to copy from" }, + { + name: "copySize", + description: "number of words to copy", + mode: "immediate", + type: "u32", + }, + { + name: "dstOffset", + description: "memory offset specifying where to copy the first word to", + }, + ], + Expression: + "`M[dstOffset:dstOffset+copySize] = context.environment.calldata[cdOffset:cdOffset+copySize]`", + Summary: "Copy calldata into memory", + Details: + "Calldata is read-only and cannot be directly operated on by other instructions. This instruction moves words from calldata into memory so they can be operated on normally.", + "Tag checks": "", + "Tag updates": "`T[dstOffset:dstOffset+copySize] = field`", + }, + { + id: "l1gasleft", + Name: "`L1GASLEFT`", + Category: "Machine State - Gas", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.machineState.l1GasLeft`", + Summary: 'Remaining "L1 gas" for this call (after this instruction)', + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "l2gasleft", + Name: "`L2GASLEFT`", + Category: "Machine State - Gas", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.MachineState.l2GasLeft`", + Summary: 'Remaining "L2 gas" for this call (after this instruction)', + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "dagasleft", + Name: "`DAGASLEFT`", + Category: "Machine State - Gas", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = context.machineState.daGasLeft`", + Summary: 'Remaining "DA gas" for this call (after this instruction)', + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = u32`", + }, + { + id: "jump", + Name: "`JUMP`", + Category: "Machine State - Control Flow", + Flags: [], + Args: [ + { + name: "loc", + description: "target location to jump to", + mode: "immediate", + type: "u32", + }, + ], + Expression: "`context.machineState.pc = loc`", + Summary: "Jump to a location in the bytecode", + Details: + "Target location is an immediate value (a constant in the bytecode).", + "Tag checks": "", + "Tag updates": "", + }, + { + id: "jumpi", + Name: "`JUMPI`", + Category: "Machine State - Control Flow", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "loc", + description: "target location conditionally jump to", + mode: "immediate", + type: "u32", + }, + { + name: "condOffset", + description: "memory offset of the operations 'conditional' input", + }, + ], + Expression: + "`context.machineState.pc = M[condOffset] > 0 ? loc : context.machineState.pc`", + Summary: "Conditionally jump to a location in the bytecode", + Details: + "Target location is an immediate value (a constant in the bytecode). `T[condOffset]` is not checked because the greater-than-zero suboperation is the same regardless of type.", + "Tag checks": "", + "Tag updates": "", + }, + { + id: "internalcall", + Name: "`INTERNALCALL`", + Category: "Machine State - Control Flow", + Flags: [], + Args: [ + { + name: "loc", + description: "target location to jump/call to", + mode: "immediate", + type: "u32", + }, + ], + Expression: ` context.machineState.internalCallStack.push(context.machineState.pc) context.machineState.pc = loc `, - "Summary": "Make an internal call. Push the current PC to the internal call stack and jump to the target location.", - "Details": "Target location is an immediate value (a constant in the bytecode).", - "Tag checks": "", - "Tag updates": "", - }, - { - "id": "internalreturn", - "Name": "`INTERNALRETURN`", - "Category": "Machine State - Control Flow", - "Flags": [], - "Args": [], - "Expression": "`context.machineState.pc = context.machineState.internalCallStack.pop()`", - "Summary": "Return from an internal call. Pop from the internal call stack and jump to the popped location.", - "Details": "", - "Tag checks": "", - "Tag updates": "", - }, - { - "id": "set", - "Name": "`SET`", - "Category": "Machine State - Memory", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - {"name": "inTag", "description": "The [type/size](./memory-model#tags-and-tagged-memory) to check inputs against and tag the destination with. `field` type is NOT supported for SET."}, - ], - "Args": [ - {"name": "const", "description": "an N-bit constant value from the bytecode to store in memory (any type except `field`)", "mode": "immediate"}, - {"name": "dstOffset", "description": "memory offset specifying where to store the constant"}, - ], - "Expression": "`M[dstOffset] = const`", - "Summary": "Set a memory word from a constant in the bytecode", - "Details": "Set memory word at `dstOffset` to `const`'s immediate value. `const`'s bit-size (N) can be 8, 16, 32, 64, or 128 based on `inTag`. It _cannot be 254 (`field` type)_!", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = inTag`", - }, - { - "id": "mov", - "Name": "`MOV`", - "Category": "Machine State - Memory", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "srcOffset", "description": "memory offset of word to move"}, - {"name": "dstOffset", "description": "memory offset specifying where to store that word"}, - ], - "Expression": "`M[dstOffset] = M[srcOffset]`", - "Summary": "Move a word from source memory location to destination", - "Details": "", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = T[srcOffset]`", - }, - { - "id": "cmov", - "Name": "`CMOV`", - "Category": "Machine State - Memory", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "aOffset", "description": "memory offset of word 'a' to conditionally move"}, - {"name": "bOffset", "description": "memory offset of word 'b' to conditionally move"}, - {"name": "condOffset", "description": "memory offset of the operations 'conditional' input"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": "`M[dstOffset] = M[condOffset] > 0 ? M[aOffset] : M[bOffset]`", - "Summary": "Move a word (conditionally chosen) from one memory location to another (`d = cond > 0 ? a : b`)", - "Details": "One of two source memory locations is chosen based on the condition. `T[condOffset]` is not checked because the greater-than-zero suboperation is the same regardless of type.", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = M[condOffset] > 0 ? T[aOffset] : T[bOffset]`", - }, - { - "id": "sload", - "Name": "`SLOAD`", - "Category": "World State - Public Storage", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "slotOffset", "description": "memory offset of the storage slot to load from"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result"}, - ], - "Expression": ` + Summary: + "Make an internal call. Push the current PC to the internal call stack and jump to the target location.", + Details: + "Target location is an immediate value (a constant in the bytecode).", + "Tag checks": "", + "Tag updates": "", + }, + { + id: "internalreturn", + Name: "`INTERNALRETURN`", + Category: "Machine State - Control Flow", + Flags: [], + Args: [], + Expression: + "`context.machineState.pc = context.machineState.internalCallStack.pop()`", + Summary: + "Return from an internal call. Pop from the internal call stack and jump to the popped location.", + Details: "", + "Tag checks": "", + "Tag updates": "", + }, + { + id: "set", + Name: "`SET`", + Category: "Machine State - Memory", + Flags: [ + { name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }, + { + name: "inTag", + description: + "The [type/size](./memory-model#tags-and-tagged-memory) to check inputs against and tag the destination with. `field` type is NOT supported for SET.", + }, + ], + Args: [ + { + name: "const", + description: + "an N-bit constant value from the bytecode to store in memory (any type except `field`)", + mode: "immediate", + }, + { + name: "dstOffset", + description: "memory offset specifying where to store the constant", + }, + ], + Expression: "`M[dstOffset] = const`", + Summary: "Set a memory word from a constant in the bytecode", + Details: + "Set memory word at `dstOffset` to `const`'s immediate value. `const`'s bit-size (N) can be 8, 16, 32, 64, or 128 based on `inTag`. It _cannot be 254 (`field` type)_!", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = inTag`", + }, + { + id: "mov", + Name: "`MOV`", + Category: "Machine State - Memory", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { name: "srcOffset", description: "memory offset of word to move" }, + { + name: "dstOffset", + description: "memory offset specifying where to store that word", + }, + ], + Expression: "`M[dstOffset] = M[srcOffset]`", + Summary: "Move a word from source memory location to destination", + Details: "", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = T[srcOffset]`", + }, + { + id: "cmov", + Name: "`CMOV`", + Category: "Machine State - Memory", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "aOffset", + description: "memory offset of word 'a' to conditionally move", + }, + { + name: "bOffset", + description: "memory offset of word 'b' to conditionally move", + }, + { + name: "condOffset", + description: "memory offset of the operations 'conditional' input", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: "`M[dstOffset] = M[condOffset] > 0 ? M[aOffset] : M[bOffset]`", + Summary: + "Move a word (conditionally chosen) from one memory location to another (`d = cond > 0 ? a : b`)", + Details: + "One of two source memory locations is chosen based on the condition. `T[condOffset]` is not checked because the greater-than-zero suboperation is the same regardless of type.", + "Tag checks": "", + "Tag updates": + "`T[dstOffset] = M[condOffset] > 0 ? T[aOffset] : T[bOffset]`", + }, + { + id: "sload", + Name: "`SLOAD`", + Category: "World State - Public Storage", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "slotOffset", + description: "memory offset of the storage slot to load from", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result", + }, + ], + Expression: ` M[dstOffset] = S[M[slotOffset]] `, - "Summary": "Load a word from this contract's persistent public storage. Zero is loaded for unwritten slots.", - "Details": ` + Summary: + "Load a word from this contract's persistent public storage. Zero is loaded for unwritten slots.", + Details: ` // Expression is shorthand for leafIndex = hash(context.environment.storageAddress, M[slotOffset]) exists = context.worldState.publicStorage.has(leafIndex) // exists == previously-written @@ -788,7 +1080,7 @@ else: value = 0 M[dstOffset] = value `, - "World State access tracing": ` + "World State access tracing": ` context.worldStateAccessTrace.publicStorageReads.append( TracedStorageRead { callPointer: context.environment.callPointer, @@ -799,33 +1091,35 @@ context.worldStateAccessTrace.publicStorageReads.append( } ) `, - "Triggers downstream circuit operations": "Storage slot siloing (hash with contract address), public data tree membership check", - "Tag checks": "", - "Tag updates": "`T[dstOffset] = field`", - }, - { - "id": "sstore", - "Name": "`SSTORE`", - "Category": "World State - Public Storage", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "srcOffset", "description": "memory offset of the word to store"}, - {"name": "slotOffset", "description": "memory offset containing the storage slot to store to"}, - ], - "Expression": ` + "Triggers downstream circuit operations": + "Storage slot siloing (hash with contract address), public data tree membership check", + "Tag checks": "", + "Tag updates": "`T[dstOffset] = field`", + }, + { + id: "sstore", + Name: "`SSTORE`", + Category: "World State - Public Storage", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { name: "srcOffset", description: "memory offset of the word to store" }, + { + name: "slotOffset", + description: "memory offset containing the storage slot to store to", + }, + ], + Expression: ` S[M[slotOffset]] = M[srcOffset] `, - "Summary": "Write a word to this contract's persistent public storage", - "Details": ` + Summary: "Write a word to this contract's persistent public storage", + Details: ` // Expression is shorthand for context.worldState.publicStorage.set({ leafIndex: hash(context.environment.storageAddress, M[slotOffset]), leaf: M[srcOffset], }) `, - "World State access tracing": ` + "World State access tracing": ` context.worldStateAccessTrace.publicStorageWrites.append( TracedStorageWrite { callPointer: context.environment.callPointer, @@ -835,31 +1129,38 @@ context.worldStateAccessTrace.publicStorageWrites.append( } ) `, - "Triggers downstream circuit operations": "Storage slot siloing (hash with contract address), public data tree update", - "Tag checks": "", - "Tag updates": "", - }, - { - "id": "notehashexists", - "Name": "`NOTEHASHEXISTS`", - "Category": "World State - Notes & Nullifiers", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "noteHashOffset", "description": "memory offset of the note hash"}, - {"name": "leafIndexOffset", "description": "memory offset of the leaf index"}, - {"name": "existsOffset", "description": "memory offset specifying where to store operation's result (whether the note hash leaf exists)"}, - ], - "Expression": ` + "Triggers downstream circuit operations": + "Storage slot siloing (hash with contract address), public data tree update", + "Tag checks": "", + "Tag updates": "", + }, + { + id: "notehashexists", + Name: "`NOTEHASHEXISTS`", + Category: "World State - Notes & Nullifiers", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { name: "noteHashOffset", description: "memory offset of the note hash" }, + { + name: "leafIndexOffset", + description: "memory offset of the leaf index", + }, + { + name: "existsOffset", + description: + "memory offset specifying where to store operation's result (whether the note hash leaf exists)", + }, + ], + Expression: ` exists = context.worldState.noteHashes.has({ leafIndex: M[leafIndexOffset] leaf: hash(context.environment.storageAddress, M[noteHashOffset]), }) M[existsOffset] = exists `, - "Summary": "Check whether a note hash exists in the note hash tree (as of the start of the current block)", - "World State access tracing": ` + Summary: + "Check whether a note hash exists in the note hash tree (as of the start of the current block)", + "World State access tracing": ` context.worldStateAccessTrace.noteHashChecks.append( TracedNoteHashCheck { callPointer: context.environment.callPointer, @@ -870,27 +1171,26 @@ context.worldStateAccessTrace.noteHashChecks.append( } ) `, - "Triggers downstream circuit operations": "Note hash siloing (hash with storage contract address), note hash tree membership check", - "Tag checks": "", - "Tag updates": "`T[existsOffset] = u8`", - }, - { - "id": "emitnotehash", - "Name": "`EMITNOTEHASH`", - "Category": "World State - Notes & Nullifiers", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "noteHashOffset", "description": "memory offset of the note hash"}, - ], - "Expression": ` + "Triggers downstream circuit operations": + "Note hash siloing (hash with storage contract address), note hash tree membership check", + "Tag checks": "", + "Tag updates": "`T[existsOffset] = u8`", + }, + { + id: "emitnotehash", + Name: "`EMITNOTEHASH`", + Category: "World State - Notes & Nullifiers", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { name: "noteHashOffset", description: "memory offset of the note hash" }, + ], + Expression: ` context.worldState.noteHashes.append( hash(context.environment.storageAddress, M[noteHashOffset]) ) `, - "Summary": "Emit a new note hash to be inserted into the note hash tree", - "World State access tracing": ` + Summary: "Emit a new note hash to be inserted into the note hash tree", + "World State access tracing": ` context.worldStateAccessTrace.newNoteHashes.append( TracedNoteHash { callPointer: context.environment.callPointer, @@ -899,30 +1199,40 @@ context.worldStateAccessTrace.newNoteHashes.append( } ) `, - "Triggers downstream circuit operations": "Note hash siloing (hash with contract address), note hash tree insertion.", - "Tag checks": "", - "Tag updates": "", - }, - { - "id": "nullifierexists", - "Name": "`NULLIFIEREXISTS`", - "Category": "World State - Notes & Nullifiers", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "nullifierOffset", "description": "memory offset of the unsiloed nullifier"}, - {"name": "addressOffset", "description": "memory offset of the storage address"}, - {"name": "existsOffset", "description": "memory offset specifying where to store operation's result (whether the nullifier exists)"}, - ], - "Expression": ` + "Triggers downstream circuit operations": + "Note hash siloing (hash with contract address), note hash tree insertion.", + "Tag checks": "", + "Tag updates": "", + }, + { + id: "nullifierexists", + Name: "`NULLIFIEREXISTS`", + Category: "World State - Notes & Nullifiers", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "nullifierOffset", + description: "memory offset of the unsiloed nullifier", + }, + { + name: "addressOffset", + description: "memory offset of the storage address", + }, + { + name: "existsOffset", + description: + "memory offset specifying where to store operation's result (whether the nullifier exists)", + }, + ], + Expression: ` exists = pendingNullifiers.has(M[addressOffset], M[nullifierOffset]) || context.worldState.nullifiers.has( hash(M[addressOffset], M[nullifierOffset]) ) M[existsOffset] = exists `, - "Summary": "Check whether a nullifier exists in the nullifier tree (including nullifiers from earlier in the current transaction or from earlier in the current block)", - "World State access tracing": ` + Summary: + "Check whether a nullifier exists in the nullifier tree (including nullifiers from earlier in the current transaction or from earlier in the current block)", + "World State access tracing": ` context.worldStateAccessTrace.nullifierChecks.append( TracedNullifierCheck { callPointer: context.environment.callPointer, @@ -933,27 +1243,26 @@ context.worldStateAccessTrace.nullifierChecks.append( } ) `, - "Triggers downstream circuit operations": "Nullifier siloing (hash with storage contract address), nullifier tree membership check", - "Tag checks": "", - "Tag updates": "`T[existsOffset] = u8`", - }, - { - "id": "emitnullifier", - "Name": "`EMITNULLIFIER`", - "Category": "World State - Notes & Nullifiers", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "nullifierOffset", "description": "memory offset of nullifier"}, - ], - "Expression": ` + "Triggers downstream circuit operations": + "Nullifier siloing (hash with storage contract address), nullifier tree membership check", + "Tag checks": "", + "Tag updates": "`T[existsOffset] = u8`", + }, + { + id: "emitnullifier", + Name: "`EMITNULLIFIER`", + Category: "World State - Notes & Nullifiers", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { name: "nullifierOffset", description: "memory offset of nullifier" }, + ], + Expression: ` context.worldState.nullifiers.append( hash(context.environment.storageAddress, M[nullifierOffset]) ) `, - "Summary": "Emit a new nullifier to be inserted into the nullifier tree", - "World State access tracing": ` + Summary: "Emit a new nullifier to be inserted into the nullifier tree", + "World State access tracing": ` context.worldStateAccessTrace.newNullifiers.append( TracedNullifier { callPointer: context.environment.callPointer, @@ -962,30 +1271,40 @@ context.worldStateAccessTrace.newNullifiers.append( } ) `, - "Triggers downstream circuit operations": "Nullifier siloing (hash with contract address), nullifier tree non-membership-check and insertion.", - "Tag checks": "", - "Tag updates": "", - }, - { - "id": "l1tol2msgexists", - "Name": "`L1TOL2MSGEXISTS`", - "Category": "World State - Messaging", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "msgHashOffset", "description": "memory offset of the message hash"}, - {"name": "msgLeafIndexOffset", "description": "memory offset of the message's leaf index in the L1-to-L2 message tree"}, - {"name": "existsOffset", "description": "memory offset specifying where to store operation's result (whether the message exists in the L1-to-L2 message tree)"}, - ], - "Expression": ` + "Triggers downstream circuit operations": + "Nullifier siloing (hash with contract address), nullifier tree non-membership-check and insertion.", + "Tag checks": "", + "Tag updates": "", + }, + { + id: "l1tol2msgexists", + Name: "`L1TOL2MSGEXISTS`", + Category: "World State - Messaging", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "msgHashOffset", + description: "memory offset of the message hash", + }, + { + name: "msgLeafIndexOffset", + description: + "memory offset of the message's leaf index in the L1-to-L2 message tree", + }, + { + name: "existsOffset", + description: + "memory offset specifying where to store operation's result (whether the message exists in the L1-to-L2 message tree)", + }, + ], + Expression: ` exists = context.worldState.l1ToL2Messages.has({ leafIndex: M[msgLeafIndexOffset], leaf: M[msgHashOffset] }) M[existsOffset] = exists `, - "Summary": "Check if a message exists in the L1-to-L2 message tree", - "World State access tracing": ` + Summary: "Check if a message exists in the L1-to-L2 message tree", + "World State access tracing": ` context.worldStateAccessTrace.l1ToL2MessagesChecks.append( L1ToL2Message { callPointer: context.environment.callPointer, @@ -995,26 +1314,41 @@ context.worldStateAccessTrace.l1ToL2MessagesChecks.append( } ) `, - "Triggers downstream circuit operations": "L1-to-L2 message tree membership check", - "Tag checks": "", - "Tag updates": ` + "Triggers downstream circuit operations": + "L1-to-L2 message tree membership check", + "Tag checks": "", + "Tag updates": ` T[existsOffset] = u8, `, - }, - { - "id": "headermember", - "Name": "`HEADERMEMBER`", - "Category": "World State - Archive Tree & Headers", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "blockIndexOffset", "description": "memory offset of the block index (same as archive tree leaf index) of the header to access"}, - {"name": "memberIndexOffset", "description": "memory offset of the index of the member to retrieve from the header of the specified block"}, - {"name": "existsOffset", "description": "memory offset specifying where to store operation's result (whether the leaf exists in the archive tree)"}, - {"name": "dstOffset", "description": "memory offset specifying where to store operation's result (the retrieved header member)"}, - ], - "Expression": ` + }, + { + id: "headermember", + Name: "`HEADERMEMBER`", + Category: "World State - Archive Tree & Headers", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "blockIndexOffset", + description: + "memory offset of the block index (same as archive tree leaf index) of the header to access", + }, + { + name: "memberIndexOffset", + description: + "memory offset of the index of the member to retrieve from the header of the specified block", + }, + { + name: "existsOffset", + description: + "memory offset specifying where to store operation's result (whether the leaf exists in the archive tree)", + }, + { + name: "dstOffset", + description: + "memory offset specifying where to store operation's result (the retrieved header member)", + }, + ], + Expression: ` exists = context.worldState.header.has({ leafIndex: M[blockIndexOffset], leaf: M[msgKeyOffset] }) @@ -1023,8 +1357,9 @@ if exists: header = context.worldState.headers.get(M[blockIndexOffset]) M[dstOffset] = header[M[memberIndexOffset]] // member `, - "Summary": "Check if a header exists in the [archive tree](../state/archive) and retrieve the specified member if so", - "World State access tracing": ` + Summary: + "Check if a header exists in the [archive tree](../state/archive) and retrieve the specified member if so", + "World State access tracing": ` context.worldStateAccessTrace.archiveChecks.append( TracedArchiveLeafCheck { leafIndex: M[blockIndexOffset], // leafIndex == blockIndex @@ -1032,26 +1367,31 @@ context.worldStateAccessTrace.archiveChecks.append( } ) `, - "Additional AVM circuit checks": "Hashes entire header to archive leaf for tracing. Aggregates header accesses and so that a header need only be hashed once.", - "Triggers downstream circuit operations": "Archive tree membership check", - "Tag checks": "", - "Tag updates": ` + "Additional AVM circuit checks": + "Hashes entire header to archive leaf for tracing. Aggregates header accesses and so that a header need only be hashed once.", + "Triggers downstream circuit operations": "Archive tree membership check", + "Tag checks": "", + "Tag updates": ` T[existsOffset] = u8 T[dstOffset] = field `, - }, - { - "id": "getcontractinstance", - "Name": "`GETCONTRACTINSTANCE`", - "Category": "Other", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "addressOffset", "description": "memory offset of the contract instance address"}, - {"name": "dstOffset", "description": "location to write the contract instance information to"}, - ], - "Expression": ` + }, + { + id: "getcontractinstance", + Name: "`GETCONTRACTINSTANCE`", + Category: "Other", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "addressOffset", + description: "memory offset of the contract instance address", + }, + { + name: "dstOffset", + description: "location to write the contract instance information to", + }, + ], + Expression: ` M[dstOffset:dstOffset+CONTRACT_INSTANCE_SIZE+1] = [ instance_found_in_address, instance.salt ?? 0, @@ -1062,25 +1402,31 @@ M[dstOffset:dstOffset+CONTRACT_INSTANCE_SIZE+1] = [ instance.publicKeysHash ?? 0, ] `, - "Summary": "Copies contract instance data to memory", - "Tag checks": "", - "Tag updates": "T[dstOffset:dstOffset+CONTRACT_INSTANCE_SIZE+1] = field", - "Additional AVM circuit checks": "TO-DO", - "Triggers downstream circuit operations": "TO-DO", - }, - { - "id": "emitunencryptedlog", - "Name": "`EMITUNENCRYPTEDLOG`", - "Category": "Accrued Substate - Logging", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "eventSelectorOffset", "description": "memory offset of the event selector"}, - {"name": "logOffset", "description": "memory offset of the data to log"}, - {"name": "logSize", "description": "number of words to log", "mode": "immediate", "type": "u32"}, - ], - "Expression": ` + Summary: "Copies contract instance data to memory", + "Tag checks": "", + "Tag updates": "T[dstOffset:dstOffset+CONTRACT_INSTANCE_SIZE+1] = field", + "Additional AVM circuit checks": "TO-DO", + "Triggers downstream circuit operations": "TO-DO", + }, + { + id: "emitunencryptedlog", + Name: "`EMITUNENCRYPTEDLOG`", + Category: "Accrued Substate - Logging", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "eventSelectorOffset", + description: "memory offset of the event selector", + }, + { name: "logOffset", description: "memory offset of the data to log" }, + { + name: "logSize", + description: "number of words to log", + mode: "immediate", + type: "u32", + }, + ], + Expression: ` context.accruedSubstate.unencryptedLogs.append( UnencryptedLog { address: context.environment.address, @@ -1089,22 +1435,26 @@ context.accruedSubstate.unencryptedLogs.append( } ) `, - "Summary": "Emit an unencrypted log", - "Tag checks": "", - "Tag updates": "", - }, - { - "id": "sendl2tol1msg", - "Name": "`SENDL2TOL1MSG`", - "Category": "Accrued Substate - Messaging", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "recipientOffset", "description": "memory offset of the message recipient"}, - {"name": "contentOffset", "description": "memory offset of the message content"}, - ], - "Expression": ` + Summary: "Emit an unencrypted log", + "Tag checks": "", + "Tag updates": "", + }, + { + id: "sendl2tol1msg", + Name: "`SENDL2TOL1MSG`", + Category: "Accrued Substate - Messaging", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "recipientOffset", + description: "memory offset of the message recipient", + }, + { + name: "contentOffset", + description: "memory offset of the message content", + }, + ], + Expression: ` context.accruedSubstate.sentL2ToL1Messages.append( SentL2ToL1Message { address: context.environment.address, @@ -1113,19 +1463,17 @@ context.accruedSubstate.sentL2ToL1Messages.append( } ) `, - "Summary": "Send an L2-to-L1 message", - "Tag checks": "", - "Tag updates": "", - }, - { - "id": "call", - "Name": "`CALL`", - "Category": "Control Flow - Contract Calls", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": CALL_INSTRUCTION_ARGS, - "Expression":` + Summary: "Send an L2-to-L1 message", + "Tag checks": "", + "Tag updates": "", + }, + { + id: "call", + Name: "`CALL`", + Category: "Control Flow - Contract Calls", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: CALL_INSTRUCTION_ARGS, + Expression: ` // instr.args are { gasOffset, addrOffset, argsOffset, retOffset, retSize } chargeGas(context, l1GasCost=M[instr.args.gasOffset], @@ -1136,27 +1484,26 @@ nestedContext = deriveContext(context, instr.args, isStaticCall=false, isDelegat execute(nestedContext) updateContextAfterNestedCall(context, instr.args, nestedContext) `, - "Summary": "Call into another contract", - "Details": `Creates a new (nested) execution context and triggers execution within that context. + Summary: "Call into another contract", + Details: + `Creates a new (nested) execution context and triggers execution within that context. Execution proceeds in the nested context until it reaches a halt at which point execution resumes in the current/calling context. - A non-existent contract or one with no code will return success. ` - + CALL_INSTRUCTION_DETAILS, - "Tag checks": "`T[gasOffset] == T[gasOffset+1] == T[gasOffset+2] == u32`", - "Tag updates": ` + A non-existent contract or one with no code will return success. ` + + CALL_INSTRUCTION_DETAILS, + "Tag checks": "`T[gasOffset] == T[gasOffset+1] == T[gasOffset+2] == u32`", + "Tag updates": ` T[successOffset] = u8 T[retOffset:retOffset+retSize] = field `, - }, - { - "id": "staticcall", - "Name": "`STATICCALL`", - "Category": "Control Flow - Contract Calls", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": CALL_INSTRUCTION_ARGS, - "Expression": ` + }, + { + id: "staticcall", + Name: "`STATICCALL`", + Category: "Control Flow - Contract Calls", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: CALL_INSTRUCTION_ARGS, + Expression: ` // instr.args are { gasOffset, addrOffset, argsOffset, retOffset, retSize } chargeGas(context, l1GasCost=M[instr.args.gasOffset], @@ -1167,24 +1514,24 @@ nestedContext = deriveContext(context, instr.args, isStaticCall=true, isDelegate execute(nestedContext) updateContextAfterNestedCall(context, instr.args, nestedContext) `, - "Summary": "Call into another contract, disallowing World State and Accrued Substate modifications", - "Details": `Same as \`CALL\`, but disallows World State and Accrued Substate modifications. ` - + CALL_INSTRUCTION_DETAILS, - "Tag checks": "`T[gasOffset] == T[gasOffset+1] == T[gasOffset+2] == u32`", - "Tag updates": ` + Summary: + "Call into another contract, disallowing World State and Accrued Substate modifications", + Details: + `Same as \`CALL\`, but disallows World State and Accrued Substate modifications. ` + + CALL_INSTRUCTION_DETAILS, + "Tag checks": "`T[gasOffset] == T[gasOffset+1] == T[gasOffset+2] == u32`", + "Tag updates": ` T[successOffset] = u8 T[retOffset:retOffset+retSize] = field `, - }, - { - "id": "delegatecall", - "Name": "`DELEGATECALL`", - "Category": "Control Flow - Contract Calls", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": CALL_INSTRUCTION_ARGS, - "Expression": ` + }, + { + id: "delegatecall", + Name: "`DELEGATECALL`", + Category: "Control Flow - Contract Calls", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: CALL_INSTRUCTION_ARGS, + Expression: ` // instr.args are { gasOffset, addrOffset, argsOffset, retOffset, retSize } chargeGas(context, l1GasCost=M[instr.args.gasOffset], @@ -1195,59 +1542,80 @@ nestedContext = deriveContext(context, instr.args, isStaticCall=false, isDelegat execute(nestedContext) updateContextAfterNestedCall(context, instr.args, nestedContext) `, - "Summary": "Call into another contract, but keep the caller's `sender` and `storageAddress`", - "Details": `Same as \`CALL\`, but \`sender\` and \`storageAddress\` remains - the same in the nested call as they were in the caller. ` - + CALL_INSTRUCTION_DETAILS, - "Tag checks": "`T[gasOffset] == T[gasOffset+1] == T[gasOffset+2] == u32`", - "Tag updates": ` + Summary: + "Call into another contract, but keep the caller's `sender` and `storageAddress`", + Details: + `Same as \`CALL\`, but \`sender\` and \`storageAddress\` remains + the same in the nested call as they were in the caller. ` + + CALL_INSTRUCTION_DETAILS, + "Tag checks": "`T[gasOffset] == T[gasOffset+1] == T[gasOffset+2] == u32`", + "Tag updates": ` T[successOffset] = u8 T[retOffset:retOffset+retSize] = field `, - }, - { - "id": "return", - "Name": "`RETURN`", - "Category": "Control Flow - Contract Calls", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "retOffset", "description": "memory offset of first word to return"}, - {"name": "retSize", "description": "number of words to return", "mode": "immediate", "type": "u32"}, - ], - "Expression": ` + }, + { + id: "return", + Name: "`RETURN`", + Category: "Control Flow - Contract Calls", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "retOffset", + description: "memory offset of first word to return", + }, + { + name: "retSize", + description: "number of words to return", + mode: "immediate", + type: "u32", + }, + ], + Expression: ` context.contractCallResults.output = M[retOffset:retOffset+retSize] halt `, - "Summary": "Halt execution within this context (without revert), optionally returning some data", - "Details": "Return control flow to the calling context/contract. Caller will accept World State and Accrued Substate modifications. See [\"Halting\"](./execution#halting) to learn more. See [\"Nested contract calls\"](./nested-calls) to see how the caller updates its context after the nested call halts.", - "Tag checks": "", - "Tag updates": "", - }, - { - "id": "revert", - "Name": "`REVERT`", - "Category": "Control Flow - Contract Calls", - "Flags": [ - {"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION}, - ], - "Args": [ - {"name": "retOffset", "description": "memory offset of first word to return"}, - {"name": "retSize", "description": "number of words to return", "mode": "immediate", "type": "u32"}, - ], - "Expression": ` + Summary: + "Halt execution within this context (without revert), optionally returning some data", + Details: + 'Return control flow to the calling context/contract. Caller will accept World State and Accrued Substate modifications. See ["Halting"](./execution#halting) to learn more. See ["Nested contract calls"](./nested-calls) to see how the caller updates its context after the nested call halts.', + "Tag checks": "", + "Tag updates": "", + }, + { + id: "revert", + Name: "`REVERT`", + Category: "Control Flow - Contract Calls", + Flags: [{ name: "indirect", description: INDIRECT_FLAG_DESCRIPTION }], + Args: [ + { + name: "retOffset", + description: "memory offset of first word to return", + }, + { + name: "retSize", + description: "number of words to return", + mode: "immediate", + type: "u32", + }, + ], + Expression: ` context.contractCallResults.output = M[retOffset:retOffset+retSize] context.contractCallResults.reverted = true halt `, - "Summary": "Halt execution within this context as `reverted`, optionally returning some data", - "Details": "Return control flow to the calling context/contract. Caller will reject World State and Accrued Substate modifications. See [\"Halting\"](./execution#halting) to learn more. See [\"Nested contract calls\"](./nested-calls) to see how the caller updates its context after the nested call halts.", - "Tag checks": "", - "Tag updates": "", - }, + Summary: + "Halt execution within this context as `reverted`, optionally returning some data", + Details: + 'Return control flow to the calling context/contract. Caller will reject World State and Accrued Substate modifications. See ["Halting"](./execution#halting) to learn more. See ["Nested contract calls"](./nested-calls) to see how the caller updates its context after the nested call halts.', + "Tag checks": "", + "Tag updates": "", + }, ]; -const INSTRUCTION_SET = INSTRUCTION_SET_RAW.map((instr) => {instr['Bit-size'] = instructionSize(instr); return instr;}); +const INSTRUCTION_SET = INSTRUCTION_SET_RAW.map((instr) => { + instr["Bit-size"] = instructionSize(instr); + return instr; +}); module.exports = { TOPICS_IN_TABLE, From 2867cb084549eb5970c711269f2bffdd72bf08a3 Mon Sep 17 00:00:00 2001 From: Josh Crites Date: Wed, 10 Apr 2024 14:19:27 -0400 Subject: [PATCH 07/18] rm old console log --- docs/sidebars.js | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/sidebars.js b/docs/sidebars.js index 749b3d7b60a..5a5e9b00006 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -51,7 +51,6 @@ const aztecNRSidebar = buildSidebarItemsFromStructure( "developers/contracts/references/aztec-nr" ); -console.log(aztecNRSidebar); /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { docsSidebar: [ From 7d6a5bb2536aedeb7bd65311ddca4c035c75e7b9 Mon Sep 17 00:00:00 2001 From: josh crites Date: Wed, 10 Apr 2024 16:06:04 -0400 Subject: [PATCH 08/18] add katex options --- docs/docusaurus.config.js | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 7fbff54c608..99560ff91b1 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -52,7 +52,13 @@ const config = { }, routeBasePath: "/", remarkPlugins: [math], - rehypePlugins: [katex], + rehypePlugins: [ + katex, + { + throwOnError: true, + globalGroup: true, + }, + ], }, blog: false, theme: { From 5576d2c36560c89fc258c3313ffb5371cf751630 Mon Sep 17 00:00:00 2001 From: josh crites Date: Wed, 10 Apr 2024 16:21:58 -0400 Subject: [PATCH 09/18] changes from b4a6f174e2b88f5e4fed128752fc0c30d919084d --- docs/docs/protocol-specs/transactions/local-execution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/protocol-specs/transactions/local-execution.md b/docs/docs/protocol-specs/transactions/local-execution.md index 9beb8624db5..f9f7e5c57c7 100644 --- a/docs/docs/protocol-specs/transactions/local-execution.md +++ b/docs/docs/protocol-specs/transactions/local-execution.md @@ -25,7 +25,7 @@ A transaction execution request has the following structure. Note that, since Az | `functionSelector` | u32 | Selector (identifier) of the function to be called as entrypoint in the origin contract. | | `argsHash` | `Field` | Hash of the arguments to be used for calling the entrypoint function. | | `txContext` | `TxContext` | Includes chain id, and protocol version. | -| `packedArguments` | `PackedArguments[]` | Preimages for argument hashes. When executing a function call with the hash of the arguments, the PXE will look for the preimage of that hash in this list, and expand the arguments to execute the call. | +| `packedArguments` | `PackedValues[]` | Preimages for argument hashes. When executing a function call with the hash of the arguments, the PXE will look for the preimage of that hash in this list, and expand the arguments to execute the call. | | `authWitnesses` | `AuthWitness[]` | Authorization witnesses. When authorizing an action identified by a hash, the PXE will look for the authorization witness identified by that hash and provide that value to the account contract. | ## Simulation step From 841f152ce27ff1d07de1ce6faeec6a2984f9ae08 Mon Sep 17 00:00:00 2001 From: josh crites Date: Wed, 10 Apr 2024 16:41:56 -0400 Subject: [PATCH 10/18] add macros --- docs/docusaurus.config.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 99560ff91b1..2ca96fe4c9a 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -8,6 +8,9 @@ const katex = require("rehype-katex"); const path = require("path"); const fs = require("fs"); +// required for katex +let macros = {}; + /** @type {import('@docusaurus/types').Config} */ const config = { title: "Privacy-first zkRollup | Aztec Documentation", @@ -57,6 +60,7 @@ const config = { { throwOnError: true, globalGroup: true, + macros, }, ], }, From 49a3631cea6ff9457774ffca094aa7d341ded940 Mon Sep 17 00:00:00 2001 From: josh crites Date: Thu, 11 Apr 2024 17:30:34 -0400 Subject: [PATCH 11/18] its working --- .../0-keys-latex-preamble.md => katex-macros.md} | 1 - .../example-usage/diversified-and-stealth-keys.mdx | 2 +- .../example-usage/encrypt-and-tag.mdx | 2 +- .../addresses-and-keys/example-usage/nullifier.mdx | 2 +- .../example-usage/tag-sequence-derivation.mdx | 2 +- .../protocol-specs/addresses-and-keys/keys.mdx | 5 ++--- docs/docusaurus.config.js | 14 ++++++++------ 7 files changed, 14 insertions(+), 14 deletions(-) rename docs/docs/{protocol-specs/addresses-and-keys/0-keys-latex-preamble.md => katex-macros.md} (99%) diff --git a/docs/docs/protocol-specs/addresses-and-keys/0-keys-latex-preamble.md b/docs/docs/katex-macros.md similarity index 99% rename from docs/docs/protocol-specs/addresses-and-keys/0-keys-latex-preamble.md rename to docs/docs/katex-macros.md index c0a5816a572..bbdac2f64d6 100644 --- a/docs/docs/protocol-specs/addresses-and-keys/0-keys-latex-preamble.md +++ b/docs/docs/katex-macros.md @@ -14,7 +14,6 @@ $$ \gdef\Ivpkm{\color{green}{Ivpk_m}\color{black}{}} \gdef\Ovpkm{\color{green}{Ovpk_m}\color{black}{}} - \gdef\address{\color{green}{address}\color{black}{}} \gdef\codehash{\color{green}{code\_hash}\color{black}{}} \gdef\constructorhash{\color{green}{constructor\_hash}\color{black}{}} diff --git a/docs/docs/protocol-specs/addresses-and-keys/example-usage/diversified-and-stealth-keys.mdx b/docs/docs/protocol-specs/addresses-and-keys/example-usage/diversified-and-stealth-keys.mdx index b973e567ff5..2279fcd63c8 100644 --- a/docs/docs/protocol-specs/addresses-and-keys/example-usage/diversified-and-stealth-keys.mdx +++ b/docs/docs/protocol-specs/addresses-and-keys/example-usage/diversified-and-stealth-keys.mdx @@ -1,6 +1,6 @@ -import LatexPreamble from "../0-keys-latex-preamble.md"; +import LatexPreamble from "../../../katex-macros.md"; ; ## Deriving diversified public keys diff --git a/docs/docs/protocol-specs/addresses-and-keys/example-usage/encrypt-and-tag.mdx b/docs/docs/protocol-specs/addresses-and-keys/example-usage/encrypt-and-tag.mdx index 92835a848e9..65519d2fe7b 100644 --- a/docs/docs/protocol-specs/addresses-and-keys/example-usage/encrypt-and-tag.mdx +++ b/docs/docs/protocol-specs/addresses-and-keys/example-usage/encrypt-and-tag.mdx @@ -1,6 +1,6 @@ -import LatexPreamble from "../0-keys-latex-preamble.md"; +import LatexPreamble from "../../../katex-macros.md"; ; ## Encrypt and tag an incoming message diff --git a/docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.mdx b/docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.mdx index f2e17a7a5b1..05cbdaa53e3 100644 --- a/docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.mdx +++ b/docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.mdx @@ -1,6 +1,6 @@ -import LatexPreamble from "../0-keys-latex-preamble.md"; +import LatexPreamble from "../../../katex-macros.md"; ; ## Deriving a nullifier within an app contract diff --git a/docs/docs/protocol-specs/addresses-and-keys/example-usage/tag-sequence-derivation.mdx b/docs/docs/protocol-specs/addresses-and-keys/example-usage/tag-sequence-derivation.mdx index 4919c665fce..6d23e862724 100644 --- a/docs/docs/protocol-specs/addresses-and-keys/example-usage/tag-sequence-derivation.mdx +++ b/docs/docs/protocol-specs/addresses-and-keys/example-usage/tag-sequence-derivation.mdx @@ -1,6 +1,6 @@ -import LatexPreamble from "../0-keys-latex-preamble.md"; +import LatexPreamble from "../../../katex-macros.md"; ; # Handshaking for tag-hopping diff --git a/docs/docs/protocol-specs/addresses-and-keys/keys.mdx b/docs/docs/protocol-specs/addresses-and-keys/keys.mdx index 2542c31710c..ccf69787a03 100644 --- a/docs/docs/protocol-specs/addresses-and-keys/keys.mdx +++ b/docs/docs/protocol-specs/addresses-and-keys/keys.mdx @@ -3,13 +3,12 @@ title: Default Keys Specification description: Specification for default privacy keys format and derivation, and nullifier derivation. --- -import Image from "@theme/IdealImage"; - -import LatexPreamble from "./0-keys-latex-preamble.md"; +import LatexPreamble from "../../katex-macros.md"; + ; ## Cheat Sheet diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 2ca96fe4c9a..9afc6108bba 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -56,12 +56,14 @@ const config = { routeBasePath: "/", remarkPlugins: [math], rehypePlugins: [ - katex, - { - throwOnError: true, - globalGroup: true, - macros, - }, + [ + katex, + { + throwOnError: true, + globalGroup: true, + macros, + }, + ], ], }, blog: false, From bd8a736edacbaed19247254dd8bc2175afc34029 Mon Sep 17 00:00:00 2001 From: josh crites Date: Thu, 11 Apr 2024 17:35:43 -0400 Subject: [PATCH 12/18] updates from master --- .../circuits/private-function.md | 31 ++++++++++++++----- .../rollup-circuits/base-rollup.md | 22 +++++++++++++ .../protocol-specs/rollup-circuits/index.md | 22 +++++++++++++ .../rollup-circuits/merge-rollup.md | 3 ++ .../rollup-circuits/root-rollup.md | 3 ++ docs/docs/protocol-specs/state/archive.md | 3 ++ docs/docs/protocol-specs/state/index.md | 7 +++-- 7 files changed, 82 insertions(+), 9 deletions(-) diff --git a/docs/docs/protocol-specs/circuits/private-function.md b/docs/docs/protocol-specs/circuits/private-function.md index 5e1de6d992b..fe8138e8134 100644 --- a/docs/docs/protocol-specs/circuits/private-function.md +++ b/docs/docs/protocol-specs/circuits/private-function.md @@ -67,13 +67,30 @@ After generating a proof for a private function circuit, that proof (and associa ### `CallContext` -| Field | Type | Description | -| -------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `msg_sender` | `AztecAddress` | Address of the caller contract. | -| `storage_contract_address` | `AztecAddress` | Address of the contract against which all state changes will be stored. (It is not called `contract_address`, because in the context of delegate calls, that would be an ambiguous name.) | -| `portal_contract_address` | `AztecAddress` | Address of the portal contract to the storage contract. | -| `is_delegate_call` | `bool` | A flag indicating whether the call is a [delegate call](../calls/delegate-calls.md). | -| `is_static_call` | `bool` | A flag indicating whether the call is a [static call](../calls/static-calls.md). | +| Field | Type | Description | +| -------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `msg_sender` | `AztecAddress` | Address of the caller contract. | +| `storage_contract_address` | `AztecAddress` | Address of the contract against which all state changes will be stored. (It is not called `contract_address`, because in the context of delegate calls, that would be an ambiguous name.) | +| `portal_contract_address` | `AztecAddress` | Address of the portal contract to the storage contract. | +| `is_delegate_call` | `bool` | A flag indicating whether the call is a [delegate call](../calls/delegate-calls.md). | +| `is_static_call` | `bool` | A flag indicating whether the call is a [static call](../calls/static-calls.md). | +| `gas_settings` | [`GasSettings`](#gassettings) | Limits and max fees per each gas dimension. | +| `transaction_fee` | `field` | Accumulated transaction fee, only set during teardown phase. | + +### `GasSettings` + +| Field | Type | Description | +| ----------------------- | ------- | -------------------------------------------------------------------- | +| `da.gas_limit` | `u32` | Total limit for DA gas for the transaction. | +| `da.teardown_gas_limit` | `u32` | Limit for DA gas specific to the teardown phase. | +| `da.max_fee_per_gas` | `field` | Maximum amount that the sender is willing to pay per unit of DA gas. | +| `l1.gas_limit` | `u32` | Total limit for L1 gas for the transaction. | +| `l1.teardown_gas_limit` | `u32` | Limit for L1 gas specific to the teardown phase. | +| `l1.max_fee_per_gas` | `field` | Maximum amount that the sender is willing to pay per unit of L1 gas. | +| `l2.gas_limit` | `u32` | Total limit for L2 gas for the transaction. | +| `l2.teardown_gas_limit` | `u32` | Limit for L2 gas specific to the teardown phase. | +| `l2.max_fee_per_gas` | `field` | Maximum amount that the sender is willing to pay per unit of L2 gas. | +| `inclusion_fee` | `field` | Flat fee the user pays for inclusion. | ### `NoteHash` diff --git a/docs/docs/protocol-specs/rollup-circuits/base-rollup.md b/docs/docs/protocol-specs/rollup-circuits/base-rollup.md index 1dbb48d1ddc..dc1e75f93df 100644 --- a/docs/docs/protocol-specs/rollup-circuits/base-rollup.md +++ b/docs/docs/protocol-specs/rollup-circuits/base-rollup.md @@ -40,6 +40,9 @@ class GlobalVariables { chain_id: Fr coinbase: EthAddress fee_recipient: Address + gas_fees.fees_per_da_gas: Fr + gas_fees.fees_per_l1_gas: Fr + gas_fees.fees_per_l2_gas: Fr } class ContentCommitment { @@ -145,6 +148,10 @@ class CombinedAccumulatedData { public_call_stack: List~CallRequest~ start_public_data_root: Fr end_public_data_root: Fr + + gas_used.da_gas: u32 + gas_used.l1_gas: u32 + gas_used.l2_gas: u32 } CombinedAccumulatedData *-- "m" NewContractData: contracts CombinedAccumulatedData *-- "m" PublicDataUpdateRequest: public_update_requests @@ -172,9 +179,24 @@ TxContext *-- ContractDeploymentData: contract_deployment_data class CombinedConstantData { historical_header: Header tx_context: TxContext + gas_settings: GasSettings } CombinedConstantData *-- Header : historical_header CombinedConstantData *-- TxContext : tx_context +CombinedConstantData *-- GasSettings : gas_settings + +class GasSettings { + da.gas_limit: u32 + da.teardown_gas_limit: u32 + da.max_fee_per_gas: Fr + l1.gas_limit: u32 + l1.teardown_gas_limit: u32 + l1.max_fee_per_gas: Fr + l2.gas_limit: u32 + l2.teardown_gas_limit: u32 + l2.max_fee_per_gas: Fr + inclusion_fee: Fr +} class KernelPublicInputs { is_private: bool diff --git a/docs/docs/protocol-specs/rollup-circuits/index.md b/docs/docs/protocol-specs/rollup-circuits/index.md index 36bb88132e5..21284ea1974 100644 --- a/docs/docs/protocol-specs/rollup-circuits/index.md +++ b/docs/docs/protocol-specs/rollup-circuits/index.md @@ -172,6 +172,9 @@ class GlobalVariables { chain_id: Fr coinbase: EthAddress fee_recipient: Address + gas_fees.fees_per_da_gas: Fr + gas_fees.fees_per_l1_gas: Fr + gas_fees.fees_per_l2_gas: Fr } class ContentCommitment { @@ -262,6 +265,10 @@ class CombinedAccumulatedData { public_call_stack: List~CallRequest~ start_public_data_root: Fr end_public_data_root: Fr + + gas_used.da_gas: u32 + gas_used.l1_gas: u32 + gas_used.l2_gas: u32 } CombinedAccumulatedData *-- "m" PublicDataUpdateRequest: public_update_requests CombinedAccumulatedData *-- "m" PublicDataRead: public_reads @@ -276,9 +283,24 @@ class TxContext { class CombinedConstantData { historical_header: Header tx_context: TxContext + gas_settings: GasSettings } CombinedConstantData *-- Header : historical_header CombinedConstantData *-- TxContext : tx_context +CombinedConstantData *-- GasSettings : gas_settings + +class GasSettings { + da.gas_limit: u32 + da.teardown_gas_limit: u32 + da.max_fee_per_gas: Fr + l1.gas_limit: u32 + l1.teardown_gas_limit: u32 + l1.max_fee_per_gas: Fr + l2.gas_limit: u32 + l2.teardown_gas_limit: u32 + l2.max_fee_per_gas: Fr + inclusion_fee: Fr +} class KernelPublicInputs { is_private: bool diff --git a/docs/docs/protocol-specs/rollup-circuits/merge-rollup.md b/docs/docs/protocol-specs/rollup-circuits/merge-rollup.md index ae5468ca5af..b9a34004683 100644 --- a/docs/docs/protocol-specs/rollup-circuits/merge-rollup.md +++ b/docs/docs/protocol-specs/rollup-circuits/merge-rollup.md @@ -31,6 +31,9 @@ class GlobalVariables { chain_id: Fr coinbase: EthAddress fee_recipient: Address + gas_fees.fees_per_da_gas: Fr + gas_fees.fees_per_l1_gas: Fr + gas_fees.fees_per_l2_gas: Fr } class ConstantRollupData { diff --git a/docs/docs/protocol-specs/rollup-circuits/root-rollup.md b/docs/docs/protocol-specs/rollup-circuits/root-rollup.md index e4cdf8804be..ad3fa6a32ff 100644 --- a/docs/docs/protocol-specs/rollup-circuits/root-rollup.md +++ b/docs/docs/protocol-specs/rollup-circuits/root-rollup.md @@ -40,6 +40,9 @@ class GlobalVariables { chain_id: Fr coinbase: EthAddress fee_recipient: Address + gas_fees.fees_per_da_gas: Fr + gas_fees.fees_per_l1_gas: Fr + gas_fees.fees_per_l2_gas: Fr } class ContentCommitment { diff --git a/docs/docs/protocol-specs/state/archive.md b/docs/docs/protocol-specs/state/archive.md index cd9e5feca77..4214cbc509c 100644 --- a/docs/docs/protocol-specs/state/archive.md +++ b/docs/docs/protocol-specs/state/archive.md @@ -68,6 +68,9 @@ class GlobalVariables { chain_id: Fr coinbase: EthAddress fee_recipient: Address + gas_fees.fees_per_da_gas: Fr + gas_fees.fees_per_l1_gas: Fr + gas_fees.fees_per_l2_gas: Fr } class Header { diff --git a/docs/docs/protocol-specs/state/index.md b/docs/docs/protocol-specs/state/index.md index bd0a53485b7..7ad7cd344c6 100644 --- a/docs/docs/protocol-specs/state/index.md +++ b/docs/docs/protocol-specs/state/index.md @@ -76,10 +76,10 @@ Below is a short description of the state catagories (trees) and why they have t - [**Note Hashes**](./note-hash-tree.md): A set of hashes (commitments) of the individual blobs of contract data (we call these blobs of data notes). New notes can be created and their hashes inserted through contract execution. We need to support efficient membership proofs as any read will require one to prove validity. The set is represented as an [Append-only Merkle tree](./tree-implementations.md#append-only-merkle-trees), storing the note hashes as leaves. - [**Nullifiers**](./nullifier-tree.md): A set of nullifiers for notes that have been spent. We need to support efficient non-membership proofs since we need to check that a note has not been spent before it can be used. The set is represented as an [Indexed Merkle tree](./tree-implementations.md#indexed-merkle-trees). - [**Public Data**](./public-data-tree.md): The key-value store for public contract state. We need to support both efficient membership and non-membership proofs! We require both, since the tree is "empty" from the start. Meaning that if the key is not already stored (non-membership), we need to insert it, and if it is already stored (membership) we need to just update the value. -- **L1 to L2 Messages**: The set of messages sent from L1 to L2. The set itself only needs to support efficient membership proofs, so we can ensure that the message was correctly sent from L1. However, it utilizes the Nullifier tree from above to ensure that the message cannot be processed twice. The set is represented as an [Append-only Merkle tree](./tree-implementations.md#append-only-merkle-trees). For more information on how the L1 to L2 messages are used, see the [L1 Smart Contracts](../l1-smart-contracts/index.md) page. +- **L1 to L2 Messages**: The set of messages sent from L1 to L2. The set itself only needs to support efficient membership proofs, so we can ensure that the message was correctly sent from L1. However, it utilizes the Nullifier tree from above to ensure that the message cannot be processed twice. The set is represented as an [Append-only Merkle tree](./tree-implementations.md#append-only-merkle-trees). For more information on how the L1 to L2 messages are used, see the [L1 Smart Contracts](../l1-smart-contracts) page. - [**Archive Tree**](./archive.md): The set of block headers that have been processed. We need to support efficient membership proofs as this is used in private execution to get the roots of the other trees. The set is represented as an [Append-only Merkle tree](./tree-implementations.md#append-only-merkle-trees). -To recall, the global state in Aztec is represented by a set of Merkle trees: the [Note Hash tree](./note-hash-tree.md), [Nullifier tree](./nullifier-tree.md), and [Public Data tree](./public-data-tree.md) reflect the latest state of the chain, while the L1 to L2 message tree allows for [cross-chain communication](../l1-smart-contracts/index.md#l2-outbox) and the [Archive Tree](./archive.md) allows for historical state access. +To recall, the global state in Aztec is represented by a set of Merkle trees: the [Note Hash tree](./note-hash-tree.md), [Nullifier tree](./nullifier-tree.md), and [Public Data tree](./public-data-tree.md) reflect the latest state of the chain, while the L1 to L2 message tree allows for [cross-chain communication](../l1-smart-contracts/#l2-outbox) and the [Archive Tree](./archive.md) allows for historical state access. @@ -106,6 +106,9 @@ class GlobalVariables { chain_id: Fr coinbase: EthAddress fee_recipient: Address + gas_fees.fees_per_da_gas: Fr + gas_fees.fees_per_l1_gas: Fr + gas_fees.fees_per_l2_gas: Fr } class ContentCommitment { From 63a5b54dd06e08aa884bccdb33ee2cba019a5440 Mon Sep 17 00:00:00 2001 From: josh crites Date: Fri, 12 Apr 2024 20:09:16 -0400 Subject: [PATCH 13/18] import katex macros as settings --- docs/docs/katex-macros.md | 89 ------------------- ...ys.mdx => diversified-and-stealth-keys.md} | 5 -- ...encrypt-and-tag.mdx => encrypt-and-tag.md} | 5 -- .../{nullifier.mdx => nullifier.md} | 5 -- ...ivation.mdx => tag-sequence-derivation.md} | 5 -- .../addresses-and-keys/{keys.mdx => keys.md} | 4 - docs/docusaurus.config.js | 4 +- docs/src/katex-macros.js | 80 +++++++++++++++++ 8 files changed, 81 insertions(+), 116 deletions(-) delete mode 100644 docs/docs/katex-macros.md rename docs/docs/protocol-specs/addresses-and-keys/example-usage/{diversified-and-stealth-keys.mdx => diversified-and-stealth-keys.md} (96%) rename docs/docs/protocol-specs/addresses-and-keys/example-usage/{encrypt-and-tag.mdx => encrypt-and-tag.md} (98%) rename docs/docs/protocol-specs/addresses-and-keys/example-usage/{nullifier.mdx => nullifier.md} (94%) rename docs/docs/protocol-specs/addresses-and-keys/example-usage/{tag-sequence-derivation.mdx => tag-sequence-derivation.md} (96%) rename docs/docs/protocol-specs/addresses-and-keys/{keys.mdx => keys.md} (99%) create mode 100644 docs/src/katex-macros.js diff --git a/docs/docs/katex-macros.md b/docs/docs/katex-macros.md deleted file mode 100644 index bbdac2f64d6..00000000000 --- a/docs/docs/katex-macros.md +++ /dev/null @@ -1,89 +0,0 @@ -$$ - - -\gdef\sk{\color{red}{sk}\color{black}{}} -\gdef\seed{\color{red}\text{{seed}}\color{black}{}} - -\gdef\nskm{\color{red}{nsk_m}\color{black}{}} -\gdef\tskm{\color{red}{tsk_m}\color{black}{}} -\gdef\ivskm{\color{red}{ivsk_m}\color{black}{}} -\gdef\ovskm{\color{red}{ovsk_m}\color{black}{}} - -\gdef\Npkm{\color{green}{Npk_m}\color{black}{}} -\gdef\Tpkm{\color{green}{Tpk_m}\color{black}{}} -\gdef\Ivpkm{\color{green}{Ivpk_m}\color{black}{}} -\gdef\Ovpkm{\color{green}{Ovpk_m}\color{black}{}} - -\gdef\address{\color{green}{address}\color{black}{}} -\gdef\codehash{\color{green}{code\_hash}\color{black}{}} -\gdef\constructorhash{\color{green}{constructor\_hash}\color{black}{}} -\gdef\classid{\color{green}{class\id}\color{black}{}} - - -\gdef\nskapp{\color{red}{nsk_{app}}\color{black}{}} -\gdef\tskapp{\color{red}{tsk_{app}}\color{black}{}} -\gdef\ivskapp{\color{red}{ivsk_{app}}\color{black}{}} -\gdef\ovskapp{\color{red}{ovsk_{app}}\color{black}{}} - -\gdef\Nkapp{\color{orange}{Nk_{app}}\color{black}{}} - -\gdef\Npkapp{\color{green}{Npk_{app}}\color{black}{}} - - -\gdef\Ivpkapp{\color{green}{Ivpk_{app}}\color{black}{}} - - -\gdef\happL{\color{green}{h_{app}^L}\color{black}{}} -\gdef\happn{\color{green}{h_{app}^n}\color{black}{}} -\gdef\happiv{\color{green}{h_{app}^{iv}}\color{black}{}} - - -\gdef\d{\color{green}{d}\color{black}{}} -\gdef\Gd{\color{green}{G_d}\color{black}{}} - -\gdef\Ivpkappd{\color{violet}{Ivpk_{app,d}}\color{black}{}} -\gdef\shareableIvpkappd{\color{violet}{\widetilde{Ivpk_{app,d}}}\color{black}{}} -\gdef\Ivpkmd{\color{violet}{Ivpk_{m,d}}\color{black}{}} -\gdef\shareableIvpkmd{\color{violet}{\widetilde{Ivpk_{m,d}}}\color{black}{}} - - -\gdef\ivskappstealth{\color{red}{ivsk_{app,stealth}}\color{black}{}} -\gdef\Ivpkappdstealth{\color{violet}{Ivpk_{app,d,stealth}}\color{black}{}} -\gdef\Pkappdstealth{\color{violet}{Pk_{app,d,stealth}}\color{black}{}} -\gdef\ivskmstealth{\color{red}{ivsk_{m,stealth}}\color{black}{}} -\gdef\Ivpkmdstealth{\color{violet}{Ivpk_{m,d,stealth}}\color{black}{}} -\gdef\Pkmdstealth{\color{violet}{Pk_{m,d,stealth}}\color{black}{}} - -\gdef\hstealth{\color{violet}{h_{stealth}}\color{black}{}} - - -\gdef\esk{\color{red}{esk}\color{black}{}} -\gdef\Epk{\color{green}{Epk}\color{black}{}} -\gdef\Epkd{\color{green}{Epk_d}\color{black}{}} -\gdef\eskheader{\color{red}{esk_{header}}\color{black}{}} -\gdef\Epkheader{\color{green}{Epk_{header}}\color{black}{}} -\gdef\Epkdheader{\color{green}{Epk_{d,header}}\color{black}{}} - -\gdef\sharedsecret{\color{violet}{\text{S}}\color{black}{}} -\gdef\sharedsecretmheader{\color{violet}{\text{S_{m,header}}}\color{black}{}} -\gdef\sharedsecretappheader{\color{violet}{\text{S_{app,header}}}\color{black}{}} - - -\gdef\hmencheader{\color{violet}{h_{m,enc,header}}\color{black}{}} -\gdef\happencheader{\color{violet}{h_{app,enc,header}}\color{black}{}} -\gdef\hmenc{\color{violet}{h_{m,enc}}\color{black}{}} -\gdef\happenc{\color{violet}{h_{app,enc}}\color{black}{}} -\gdef\incomingenckey{\color{violet}{h_{incoming\_enc\_key}}\color{black}{}} - - -\gdef\plaintext{\color{red}{\text{plaintext}}\color{black}{}} -\gdef\ciphertext{\color{green}{\text{ciphertext}}\color{black}{}} -\gdef\ciphertextheader{\color{green}{\text{ciphertext\_header}}\color{black}{}} -\gdef\payload{\color{green}{\text{payload}}\color{black}{}} - - -\gdef\tagg{\color{green}{\text{tag}}\color{black}{}} -\gdef\Taghs{\color{green}{\text{Tag}_{hs}}\color{black}{}} - - -$$ diff --git a/docs/docs/protocol-specs/addresses-and-keys/example-usage/diversified-and-stealth-keys.mdx b/docs/docs/protocol-specs/addresses-and-keys/example-usage/diversified-and-stealth-keys.md similarity index 96% rename from docs/docs/protocol-specs/addresses-and-keys/example-usage/diversified-and-stealth-keys.mdx rename to docs/docs/protocol-specs/addresses-and-keys/example-usage/diversified-and-stealth-keys.md index 2279fcd63c8..fed3329e895 100644 --- a/docs/docs/protocol-specs/addresses-and-keys/example-usage/diversified-and-stealth-keys.mdx +++ b/docs/docs/protocol-specs/addresses-and-keys/example-usage/diversified-and-stealth-keys.md @@ -1,8 +1,3 @@ - - -import LatexPreamble from "../../../katex-macros.md"; -; - ## Deriving diversified public keys A diversified public key can be derived from Alice's keys, to enhance Alice's transaction privacy. If Alice's counterparties' databases are compromised, it enables Alice to retain privacy from such leakages. Diversified public keys are used for generating diversified addresses. diff --git a/docs/docs/protocol-specs/addresses-and-keys/example-usage/encrypt-and-tag.mdx b/docs/docs/protocol-specs/addresses-and-keys/example-usage/encrypt-and-tag.md similarity index 98% rename from docs/docs/protocol-specs/addresses-and-keys/example-usage/encrypt-and-tag.mdx rename to docs/docs/protocol-specs/addresses-and-keys/example-usage/encrypt-and-tag.md index 65519d2fe7b..c25642d832f 100644 --- a/docs/docs/protocol-specs/addresses-and-keys/example-usage/encrypt-and-tag.mdx +++ b/docs/docs/protocol-specs/addresses-and-keys/example-usage/encrypt-and-tag.md @@ -1,8 +1,3 @@ - - -import LatexPreamble from "../../../katex-macros.md"; -; - ## Encrypt and tag an incoming message Bob wants to send Alice a private message, e.g. the contents of a note, which we'll refer to as the $\plaintext$. Bob and Alice are using a "tag hopping" scheme to help with note discovery. Let's assume they've already handshaked to establish a shared secret $\sharedsecret_{m,tagging}^{Bob \rightarrow Alice}$, from which a sequence of tags $\tagg_{m,i}^{Bob \rightarrow Alice}$ can be derived. diff --git a/docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.mdx b/docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.md similarity index 94% rename from docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.mdx rename to docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.md index 05cbdaa53e3..4c5242c18ca 100644 --- a/docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.mdx +++ b/docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.md @@ -1,8 +1,3 @@ - - -import LatexPreamble from "../../../katex-macros.md"; -; - ## Deriving a nullifier within an app contract Let's assume a developer wants a nullifier of a note to be derived as: diff --git a/docs/docs/protocol-specs/addresses-and-keys/example-usage/tag-sequence-derivation.mdx b/docs/docs/protocol-specs/addresses-and-keys/example-usage/tag-sequence-derivation.md similarity index 96% rename from docs/docs/protocol-specs/addresses-and-keys/example-usage/tag-sequence-derivation.mdx rename to docs/docs/protocol-specs/addresses-and-keys/example-usage/tag-sequence-derivation.md index 6d23e862724..3484ec38560 100644 --- a/docs/docs/protocol-specs/addresses-and-keys/example-usage/tag-sequence-derivation.mdx +++ b/docs/docs/protocol-specs/addresses-and-keys/example-usage/tag-sequence-derivation.md @@ -1,8 +1,3 @@ - - -import LatexPreamble from "../../../katex-macros.md"; -; - # Handshaking for tag-hopping Deriving a sequence of tags for tag-hopping. diff --git a/docs/docs/protocol-specs/addresses-and-keys/keys.mdx b/docs/docs/protocol-specs/addresses-and-keys/keys.md similarity index 99% rename from docs/docs/protocol-specs/addresses-and-keys/keys.mdx rename to docs/docs/protocol-specs/addresses-and-keys/keys.md index ccf69787a03..3e275e60dd7 100644 --- a/docs/docs/protocol-specs/addresses-and-keys/keys.mdx +++ b/docs/docs/protocol-specs/addresses-and-keys/keys.md @@ -7,10 +7,6 @@ description: Specification for default privacy keys format and derivation, and n -import LatexPreamble from "../../katex-macros.md"; - -; - ## Cheat Sheet The protocol does not enforce the usage of any of the following keys, and does not enforce the keys to conform to a particular length or algorithm. Users are expected to pick a set of keys valid for the encryption and tagging precompile they choose for their account. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 9afc6108bba..b0a158adaf4 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -7,9 +7,7 @@ const math = require("remark-math"); const katex = require("rehype-katex"); const path = require("path"); const fs = require("fs"); - -// required for katex -let macros = {}; +const macros = require("./src/katex-macros.js"); /** @type {import('@docusaurus/types').Config} */ const config = { diff --git a/docs/src/katex-macros.js b/docs/src/katex-macros.js new file mode 100644 index 00000000000..66a8bbd739b --- /dev/null +++ b/docs/src/katex-macros.js @@ -0,0 +1,80 @@ +module.exports = { + "\\sk": "\\color{red}{sk}\\color{black}{}", + "\\seed": "\\color{red}\\text{{seed}}\\color{black}{}", + "\\nskm": "\\color{red}{nsk_m}\\color{black}{}", + "\\tskm": "\\color{red}{tsk_m}\\color{black}{}", + "\\ivskm": "\\color{red}{ivsk_m}\\color{black}{}", + "\\ovskm": "\\color{red}{ovsk_m}\\color{black}{}", + + "\\Npkm": "\\color{green}{Npk_m}\\color{black}{}", + "\\Tpkm": "\\color{green}{Tpk_m}\\color{black}{}", + "\\Ivpkm": "\\color{green}{Ivpk_m}\\color{black}{}", + "\\Ovpkm": "\\color{green}{Ovpk_m}\\color{black}{}", + + "\\address": "\\color{green}{address}\\color{black}{}", + "\\codehash": "\\color{green}{code_hash}\\color{black}{}", + "\\constructorhash": "\\color{green}{constructor_hash}\\color{black}{}", + "\\classid": "\\color{green}{classid}\\color{black}{}", + + "\\nskapp": "\\color{red}{nsk_{app}}\\color{black}{}", + "\\tskapp": "\\color{red}{tsk_{app}}color{black}{}", + "\\ivskapp": "\\color{red}{ivsk_{app}}color{black}{}", + "\\ovskapp": "\\color{red}{ovsk_{app}}color{black}{}", + + "\\Nkapp": "\\color{orange}{Nk_{app}}\\color{black}{}", + + "\\Npkapp": "\\color{green}{Npk_{app}}\\color{black}{}", + + "\\Ivpkapp": "\\color{green}{Ivpk_{app}}\\color{black}{}", + + "\\happL": "\\color{green}{h_{app}^L}\\color{black}{}", + "\\happn": "\\color{green}{h_{app}^n}\\color{black}{}", + "\\happiv": "\\color{green}{h_{app}^{iv}}\\color{black}{}", + + "\\d": "\\color{green}{d}\\color{black}{}", + "\\Gd": "\\color{green}{G_d}\\color{black}{}", + + "\\Ivpkappd": "\\color{violet}{Ivpk_{app,d}}\\color{black}{}", + "\\shareableIvpkappd": + "\\color{violet}{\\widetilde{Ivpk_{app,d}}}\\color{black}{}", + "\\Ivpkmd": "\\color{violet}{Ivpk_{m,d}}\\color{black}{}", + "\\shareableIvpkmd": + "\\color{violet}{\\widetilde{Ivpk_{m,d}}}\\color{black}{}", + + "\\ivskappstealth": "\\color{red}{ivsk_{app,stealth}}\\color{black}{}", + "\\Ivpkappdstealth": "\\color{violet}{Ivpk_{app,d,stealth}}\\color{black}{}", + "\\Pkappdstealth": "\\color{violet}{Pk_{app,d,stealth}}\\color{black}{}", + "\\ivskmstealth": "\\color{red}{ivsk_{m,stealth}}\\color{black}{}", + "\\Ivpkmdstealth": "\\color{violet}{Ivpk_{m,d,stealth}}\\color{black}{}", + "\\Pkmdstealth": "\\color{violet}{Pk_{m,d,stealth}}\\color{black}{}", + + "\\hstealth": "\\color{violet}{h_{stealth}}\\color{black}{}", + + "\\esk": "\\color{red}{esk}\\color{black}{}", + "\\Epk": "\\color{green}{Epk}\\color{black}{}", + "\\Epkd": "\\color{green}{Epk_d}\\color{black}{}", + "\\eskheader": "\\color{red}{esk_{header}}\\color{black}{}", + "\\Epkheader": "\\color{green}{Epk_{header}}\\color{black}{}", + "\\Epkdheader": "\\color{green}{Epk_{d,header}}\\color{black}{}", + + "\\sharedsecret": "\\color{violet}{\\text{S}}\\color{black}{}", + "\\sharedsecretmheader": + "\\color{violet}{\\text{S_{m,header}}}\\color{black}{}", + "\\sharedsecretappheader": + "\\color{violet}{\\text{S_{app,header}}}\\color{black}{}", + + "\\hmencheader": "\\color{violet}{h_{m,enc,header}}\\color{black}{}", + "\\happencheader": "\\color{violet}{h_{app,enc,header}}\\color{black}{}", + "\\hmenc": "\\color{violet}{h_{m,enc}}\\color{black}{}", + "\\happenc": "\\color{violet}{h_{app,enc}}\\color{black}{}", + "\\incomingenckey": "\\color{violet}{h_{incoming_enc_key}}\\color{black}{}", + + "\\plaintext": "\\color{red}{\\text{plaintext}}\\color{black}{}", + "\\ciphertext": "\\color{green}{\\text{ciphertext}}\\color{black}{}", + "\\ciphertextheader": + "\\color{green}{\\text{ciphertext_header}}\\color{black}{}", + "\\payload": "\\color{green}{\\text{payload}}\\color{black}{}", + + "\\tagg": "\\color{green}{\\text{tag}}\\color{black}{}", + "\\Taghs": "\\color{green}{\\text{Tag}_{hs}}\\color{black}{}", +}; From 442f6c205dbe64b0f42fdd54bd47a351681a8e79 Mon Sep 17 00:00:00 2001 From: josh crites Date: Fri, 12 Apr 2024 20:09:29 -0400 Subject: [PATCH 14/18] fix unescaped _ --- docs/src/katex-macros.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/katex-macros.js b/docs/src/katex-macros.js index 66a8bbd739b..b6513451bb0 100644 --- a/docs/src/katex-macros.js +++ b/docs/src/katex-macros.js @@ -72,9 +72,9 @@ module.exports = { "\\plaintext": "\\color{red}{\\text{plaintext}}\\color{black}{}", "\\ciphertext": "\\color{green}{\\text{ciphertext}}\\color{black}{}", "\\ciphertextheader": - "\\color{green}{\\text{ciphertext_header}}\\color{black}{}", + "\\color{green}{\\text{ciphertext\\_header}}\\color{black}{}", "\\payload": "\\color{green}{\\text{payload}}\\color{black}{}", "\\tagg": "\\color{green}{\\text{tag}}\\color{black}{}", - "\\Taghs": "\\color{green}{\\text{Tag}_{hs}}\\color{black}{}", + "\\Taghs": "\\color{green}{\\text{Tag}\\_{hs}}\\color{black}{}", }; From c39208a7171fcf17cde0ccbb87439f830a60178f Mon Sep 17 00:00:00 2001 From: josh crites Date: Fri, 12 Apr 2024 20:09:43 -0400 Subject: [PATCH 15/18] fix links --- docs/docs/protocol-specs/state/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/protocol-specs/state/index.md b/docs/docs/protocol-specs/state/index.md index 7ad7cd344c6..f855fe792c6 100644 --- a/docs/docs/protocol-specs/state/index.md +++ b/docs/docs/protocol-specs/state/index.md @@ -76,10 +76,10 @@ Below is a short description of the state catagories (trees) and why they have t - [**Note Hashes**](./note-hash-tree.md): A set of hashes (commitments) of the individual blobs of contract data (we call these blobs of data notes). New notes can be created and their hashes inserted through contract execution. We need to support efficient membership proofs as any read will require one to prove validity. The set is represented as an [Append-only Merkle tree](./tree-implementations.md#append-only-merkle-trees), storing the note hashes as leaves. - [**Nullifiers**](./nullifier-tree.md): A set of nullifiers for notes that have been spent. We need to support efficient non-membership proofs since we need to check that a note has not been spent before it can be used. The set is represented as an [Indexed Merkle tree](./tree-implementations.md#indexed-merkle-trees). - [**Public Data**](./public-data-tree.md): The key-value store for public contract state. We need to support both efficient membership and non-membership proofs! We require both, since the tree is "empty" from the start. Meaning that if the key is not already stored (non-membership), we need to insert it, and if it is already stored (membership) we need to just update the value. -- **L1 to L2 Messages**: The set of messages sent from L1 to L2. The set itself only needs to support efficient membership proofs, so we can ensure that the message was correctly sent from L1. However, it utilizes the Nullifier tree from above to ensure that the message cannot be processed twice. The set is represented as an [Append-only Merkle tree](./tree-implementations.md#append-only-merkle-trees). For more information on how the L1 to L2 messages are used, see the [L1 Smart Contracts](../l1-smart-contracts) page. +- **L1 to L2 Messages**: The set of messages sent from L1 to L2. The set itself only needs to support efficient membership proofs, so we can ensure that the message was correctly sent from L1. However, it utilizes the Nullifier tree from above to ensure that the message cannot be processed twice. The set is represented as an [Append-only Merkle tree](./tree-implementations.md#append-only-merkle-trees). For more information on how the L1 to L2 messages are used, see the [L1 Smart Contracts](../l1-smart-contracts/index.md) page. - [**Archive Tree**](./archive.md): The set of block headers that have been processed. We need to support efficient membership proofs as this is used in private execution to get the roots of the other trees. The set is represented as an [Append-only Merkle tree](./tree-implementations.md#append-only-merkle-trees). -To recall, the global state in Aztec is represented by a set of Merkle trees: the [Note Hash tree](./note-hash-tree.md), [Nullifier tree](./nullifier-tree.md), and [Public Data tree](./public-data-tree.md) reflect the latest state of the chain, while the L1 to L2 message tree allows for [cross-chain communication](../l1-smart-contracts/#l2-outbox) and the [Archive Tree](./archive.md) allows for historical state access. +To recall, the global state in Aztec is represented by a set of Merkle trees: the [Note Hash tree](./note-hash-tree.md), [Nullifier tree](./nullifier-tree.md), and [Public Data tree](./public-data-tree.md) reflect the latest state of the chain, while the L1 to L2 message tree allows for [cross-chain communication](../l1-smart-contracts/index.md#l2-outbox) and the [Archive Tree](./archive.md) allows for historical state access. From 95b8e0b1b7220d069bbb90e390d0dcaa35a5d229 Mon Sep 17 00:00:00 2001 From: josh crites Date: Fri, 12 Apr 2024 22:23:08 -0400 Subject: [PATCH 16/18] fix links --- docs/docs/protocol-specs/addresses-and-keys/index.md | 2 +- docs/docs/protocol-specs/cryptography/hashing/hashing.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/protocol-specs/addresses-and-keys/index.md b/docs/docs/protocol-specs/addresses-and-keys/index.md index bc0f6f27ab5..d9c2730d8fd 100644 --- a/docs/docs/protocol-specs/addresses-and-keys/index.md +++ b/docs/docs/protocol-specs/addresses-and-keys/index.md @@ -14,7 +14,7 @@ Keys in Aztec are used both for authorization and privacy. Authorization keys ar Privacy keys are used for note encryption, tagging, and nullifying. These are also not enforced by the protocol. However, for facilitating composability, the protocol enshrines a set of enshrined encryption and tagging mechanisms, that can be leveraged by applications as they interact with accounts. -The [requirements](./keys-requirements.md) section outlines the features that were sought when designing Aztec's addresses and keys. We then specify how [addresses](./address.md) are derived, as well as the default way in which [keys](./keys.mdx) will be derived. The [precompiles](./precompiles.md) section describes enshrined contract addresses, with implementations defined by the protocol, used for note encryption and tagging. +The [requirements](./keys-requirements.md) section outlines the features that were sought when designing Aztec's addresses and keys. We then specify how [addresses](./address.md) are derived, as well as the default way in which [keys](./keys.md) will be derived. The [precompiles](./precompiles.md) section describes enshrined contract addresses, with implementations defined by the protocol, used for note encryption and tagging. Last, the [diversified and stealth accounts](./diversified-and-stealth.md) sections describe application-level recommendations for diversified and stealth accounts. diff --git a/docs/docs/protocol-specs/cryptography/hashing/hashing.md b/docs/docs/protocol-specs/cryptography/hashing/hashing.md index d720c250cc9..a3e4cb5f5e7 100644 --- a/docs/docs/protocol-specs/cryptography/hashing/hashing.md +++ b/docs/docs/protocol-specs/cryptography/hashing/hashing.md @@ -24,6 +24,6 @@ Pseudo-randomness is required in cases such as: - Fiat-Shamir challenge generation. - Expanding a random seed to generate additional randomness. - - See the derivation of [master secret keys](../../addresses-and-keys/keys.mdx#master-keys). + - See the derivation of [master secret keys](../../addresses-and-keys/keys.md#master-keys). - Deriving a nullifier, and siloing a nullifier. - - See [deriving a nullifier](../../addresses-and-keys/keys.mdx#deriving-a-nullifier-within-an-app-contract). + - See [deriving a nullifier](../../addresses-and-keys/keys.md#deriving-a-nullifier-within-an-app-contract). From e41f809958defcd363e8a6a147d32465a6c724ab Mon Sep 17 00:00:00 2001 From: josh crites Date: Sat, 13 Apr 2024 07:29:43 -0400 Subject: [PATCH 17/18] fix links --- docs/docs/protocol-specs/addresses-and-keys/address.md | 2 +- .../addresses-and-keys/diversified-and-stealth.md | 2 +- .../addresses-and-keys/example-usage/nullifier.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docs/protocol-specs/addresses-and-keys/address.md b/docs/docs/protocol-specs/addresses-and-keys/address.md index e2fc1a1acff..5cd2e3ac20d 100644 --- a/docs/docs/protocol-specs/addresses-and-keys/address.md +++ b/docs/docs/protocol-specs/addresses-and-keys/address.md @@ -73,7 +73,7 @@ address_crh( } ``` -The `public_keys` array can vary depending on the format of keys used by the address, but it is suggested it includes the master keys defined in the [keys section](./keys.mdx). For example: +The `public_keys` array can vary depending on the format of keys used by the address, but it is suggested it includes the master keys defined in the [keys section](./keys.md). For example: ```rust let public_keys_hash: Field = poseidon2( diff --git a/docs/docs/protocol-specs/addresses-and-keys/diversified-and-stealth.md b/docs/docs/protocol-specs/addresses-and-keys/diversified-and-stealth.md index f4fc8613f80..51a274e12b4 100644 --- a/docs/docs/protocol-specs/addresses-and-keys/diversified-and-stealth.md +++ b/docs/docs/protocol-specs/addresses-and-keys/diversified-and-stealth.md @@ -2,7 +2,7 @@ title: Diversified and Stealth Accounts --- -The [keys specification](./keys.mdx) describes derivation mechanisms for diversified and stealth public keys. However, the protocol requires users to interact with addresses. +The [keys specification](./keys.md) describes derivation mechanisms for diversified and stealth public keys. However, the protocol requires users to interact with addresses. ## Computing Addresses diff --git a/docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.md b/docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.md index 4c5242c18ca..5c3419d8fbe 100644 --- a/docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.md +++ b/docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.md @@ -18,8 +18,8 @@ It's easiest to take a look at this first: Within the app, we can prove links between: -- the user's [$\nskapp$](../keys.mdx#app-siloed-nullifier-secret-key) and their [$\Nkapp$](../keys.mdx#app-siloed-nullifier-key); and between -- the user's [$\Npkm$](../keys.mdx#master-nullifier-public-key) and their [$\address$](../address.md). +- the user's [$\nskapp$](../keys.md#app-siloed-nullifier-secret-key) and their [$\Nkapp$](../keys.md#app-siloed-nullifier-key); and between +- the user's [$\Npkm$](../keys.md#master-nullifier-public-key) and their [$\address$](../address.md). The link that's missing is to prove that $\Npkm$ relates to $\nskapp$. To compute this missing link requires the $\nskm$, which MUST NOT be passed into an app circuit, and may only be passed into a kernel circuit. See the next ['Within the kernel circuit'](#within-the-kernel-circuit) section for details of this logic. From dd2f3731d6ea062b6930a26084b03266d93ee556 Mon Sep 17 00:00:00 2001 From: josh crites Date: Mon, 15 Apr 2024 09:54:21 -0400 Subject: [PATCH 18/18] add missing \\ --- docs/src/katex-macros.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/katex-macros.js b/docs/src/katex-macros.js index b6513451bb0..f60a6f0b66b 100644 --- a/docs/src/katex-macros.js +++ b/docs/src/katex-macros.js @@ -17,9 +17,9 @@ module.exports = { "\\classid": "\\color{green}{classid}\\color{black}{}", "\\nskapp": "\\color{red}{nsk_{app}}\\color{black}{}", - "\\tskapp": "\\color{red}{tsk_{app}}color{black}{}", - "\\ivskapp": "\\color{red}{ivsk_{app}}color{black}{}", - "\\ovskapp": "\\color{red}{ovsk_{app}}color{black}{}", + "\\tskapp": "\\color{red}{tsk_{app}}\\color{black}{}", + "\\ivskapp": "\\color{red}{ivsk_{app}}\\color{black}{}", + "\\ovskapp": "\\color{red}{ovsk_{app}}\\color{black}{}", "\\Nkapp": "\\color{orange}{Nk_{app}}\\color{black}{}",