diff --git a/yellow-paper/docs/public-vm/Types.mdx b/yellow-paper/docs/public-vm/Types.mdx
deleted file mode 100644
index e69de29bb2d..00000000000
diff --git a/yellow-paper/docs/public-vm/alu.md b/yellow-paper/docs/public-vm/alu.md
index bd83dde6a23..d4c0066d936 100644
--- a/yellow-paper/docs/public-vm/alu.md
+++ b/yellow-paper/docs/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"
-![](./gen/images/alu/alu.png)
+![](./images/alu.png)
Notes:
diff --git a/yellow-paper/docs/public-vm/control-flow.md b/yellow-paper/docs/public-vm/control-flow.md
index 707e78ecf8b..836697fa346 100644
--- a/yellow-paper/docs/public-vm/control-flow.md
+++ b/yellow-paper/docs/public-vm/control-flow.md
@@ -14,7 +14,7 @@ The intention is for sub-operations to be implementable as independent VM circui
# Control flow
-![](./gen/images/control-flow/avm-control-flow.png)
+![](./images/avm-control-flow.png)
> Notation note: whenever the VM "sends a signal" to one or more VM components, this is analogous to defining a boolean column in the execution trace that toggles on/off specific functionality
diff --git a/yellow-paper/docs/public-vm/gen/_InstructionSet.mdx b/yellow-paper/docs/public-vm/gen/_InstructionSet.mdx
index ba11a18a0e9..4f13ec9bd98 100644
--- a/yellow-paper/docs/public-vm/gen/_InstructionSet.mdx
+++ b/yellow-paper/docs/public-vm/gen/_InstructionSet.mdx
@@ -1,7 +1,7 @@
[comment]: # (THIS IS A GENERATED FILE! DO NOT EDIT!)
[comment]: # (Generated via `yarn preprocess`)
-[comment]: # (Generated by InstructionSetMarkdownGen.tsx and InstructionSet.js)
+[comment]: # (Generated by genMarkdown.js, InstructionSet.js, InstructionSize.js)
import Markdown from 'react-markdown'
import CodeBlock from '@theme/CodeBlock'
@@ -16,7 +16,7 @@ Click on an instruction name to jump to its section.
0x00 | [`ADD`](#isa-section-add) |
Addition (a + b) |
- 96 |
+ 128 |
{
`M[dstOffset] = M[aOffset] + M[bOffset] mod 2^k`
} |
@@ -24,7 +24,7 @@ Click on an instruction name to jump to its section.
0x01 | [`SUB`](#isa-section-sub) |
Subtraction (a - b) |
- 96 |
+ 128 |
{
`M[dstOffset] = M[aOffset] - M[bOffset] mod 2^k`
} |
@@ -32,7 +32,7 @@ Click on an instruction name to jump to its section.
0x02 | [`DIV`](#isa-section-div) |
Unsigned division (a / b) |
- 96 |
+ 128 |
{
`M[dstOffset] = M[aOffset] / M[bOffset]`
} |
@@ -40,7 +40,7 @@ Click on an instruction name to jump to its section.
0x03 | [`EQ`](#isa-section-eq) |
Equality check (a == b) |
- 96 |
+ 128 |
{
`M[dstOffset] = M[aOffset] == M[bOffset] ? 1 : 0`
} |
@@ -48,7 +48,7 @@ Click on an instruction name to jump to its section.
0x04 | [`LT`](#isa-section-lt) |
Less-than check (a < b) |
- 96 |
+ 128 |
{
`M[dstOffset] = M[aOffset] < M[bOffset] ? 1 : 0`
} |
@@ -56,7 +56,7 @@ Click on an instruction name to jump to its section.
0x05 | [`LTE`](#isa-section-lte) |
Less-than-or-equals check (a <= b) |
- 96 |
+ 128 |
{
`M[dstOffset] = M[aOffset] <= M[bOffset] ? 1 : 0`
} |
@@ -64,7 +64,7 @@ Click on an instruction name to jump to its section.
0x06 | [`AND`](#isa-section-and) |
Bitwise AND (a & b) |
- 96 |
+ 128 |
{
`M[dstOffset] = M[aOffset] AND M[bOffset]`
} |
@@ -72,7 +72,7 @@ Click on an instruction name to jump to its section.
0x07 | [`OR`](#isa-section-or) |
Bitwise OR (a | b) |
- 96 |
+ 128 |
{
`M[dstOffset] = M[aOffset] OR M[bOffset]`
} |
@@ -80,7 +80,7 @@ Click on an instruction name to jump to its section.
0x08 | [`XOR`](#isa-section-xor) |
Bitwise XOR (a ^ b) |
- 96 |
+ 128 |
{
`M[dstOffset] = M[aOffset] XOR M[bOffset]`
} |
@@ -88,7 +88,7 @@ Click on an instruction name to jump to its section.
0x09 | [`NOT`](#isa-section-not) |
Bitwise NOT (inversion) |
- 72 |
+ 96 |
{
`M[dstOffset] = NOT M[aOffset]`
} |
@@ -96,7 +96,7 @@ Click on an instruction name to jump to its section.
0x0a | [`SHL`](#isa-section-shl) |
Bitwise leftward shift (a << b) |
- 96 |
+ 128 |
{
`M[dstOffset] = M[aOffset] << M[bOffset]`
} |
@@ -104,7 +104,7 @@ Click on an instruction name to jump to its section.
0x0b | [`SHR`](#isa-section-shr) |
Bitwise rightward shift (a >> b) |
- 96 |
+ 128 |
{
`M[dstOffset] = M[aOffset] >> M[bOffset]`
} |
@@ -112,15 +112,15 @@ Click on an instruction name to jump to its section.
0x0c | [`CAST`](#isa-section-cast) |
Type cast |
- 72 |
+ 96 |
{
- `M[dstOffset] = cast(M[aOffset])`
+ `M[dstOffset] = cast(M[aOffset])`
} |
0x0d | [`SET`](#isa-section-set) |
Set a memory word from a constant in the bytecode. |
- 48+N |
+ 64+N |
{
`M[dstOffset] = const`
} |
@@ -128,7 +128,7 @@ Click on an instruction name to jump to its section.
0x0e | [`MOV`](#isa-section-mov) |
Move a word from source memory location to destination`. |
- 64 |
+ 88 |
{
`M[dstOffset] = M[srcOffset]`
} |
@@ -136,7 +136,7 @@ Click on an instruction name to jump to its section.
0x0f | [`CMOV`](#isa-section-cmov) |
Move a word (conditionally chosen) from one memory location to another (`d = cond > 0 ? a : b`). |
- 112 |
+ 152 |
{
`M[dstOffset] = M[condOffset] > 0 ? M[aOffset] : M[bOffset]`
} |
@@ -144,15 +144,15 @@ Click on an instruction name to jump to its section.
0x10 | [`CALLDATACOPY`](#isa-section-calldatacopy) |
Copy calldata into memory. |
- 88 |
+ 120 |
{
- `M[dstOffset:dstOffset+size] = calldata[cdOffset:cdOffset+size]`
+ `M[dstOffset:dstOffset+copySize] = calldata[cdOffset:cdOffset+copySize]`
} |
0x11 | [`SLOAD`](#isa-section-sload) |
Load a word from storage. |
- 64 |
+ 88 |
{
`M[dstOffset] = storage[M[slotOffset]]`
} |
@@ -160,7 +160,7 @@ Click on an instruction name to jump to its section.
0x12 | [`SSTORE`](#isa-section-sstore) |
Write a word to storage. |
- 64 |
+ 88 |
{
`storage[M[slotOffset]] = M[srcOffset]`
} |
@@ -168,25 +168,25 @@ Click on an instruction name to jump to its section.
0x13 | [`EMITNOTEHASH`](#isa-section-emitnotehash) |
Emit a new note hash to be inserted into the notes tree |
- 40 |
+ 56 |
emitNoteHash(M[contentOffset]) |
0x14 | [`EMITNULLIFIER`](#isa-section-emitnullifier) |
Emit a new nullifier to be inserted into the nullifier tree |
- 40 |
+ 56 |
emitNullifier(M[nullifierOffset]) |
0x15 | [`SENDL2TOL1MSG`](#isa-section-sendl2tol1msg) |
Send an L2-to-L1 message |
- 40 |
+ 56 |
sendL2ToL1Message(M[contentOffset]) |
0x16 | [`JUMP`](#isa-section-jump) |
Jump to a location in the bytecode. |
- 32 |
+ 48 |
{
`PC = loc`
} |
@@ -194,7 +194,7 @@ Click on an instruction name to jump to its section.
0x17 | [`JUMPI`](#isa-section-jumpi) |
Conditionally jump to a location in the bytecode. |
- 64 |
+ 88 |
{
`PC = M[condOffset] > 0 ? loc : PC`
} |
@@ -202,26 +202,26 @@ Click on an instruction name to jump to its section.
0x18 | [`RETURN`](#isa-section-return) |
Halt execution with `success`, optionally returning some data. |
- 64 |
+ 88 |
{
- `return(M[offset:offset+size])`
+ `return(M[retOffset:retOffset+retSize])`
} |
0x19 | [`REVERT`](#isa-section-revert) |
Halt execution with `failure`, reverting state changes and optionally returning some data. |
- 64 |
+ 88 |
{
- `revert(M[offset:offset+size])`
+ `revert(M[retOffset:retOffset+retSize])`
} |
0x1a | [`CALL`](#isa-section-call) |
Call into another contract. |
- 208 |
+ 248 |
{`M[successOffset] = call(
- M[l1GasOffset], M[l2GasOffset], M[addrOffset],
+ M[gasOffset], M[gasOffset+1], M[addrOffset],
M[argsOffset], M[argsSize],
M[retOffset], M[retSize])`}
|
@@ -229,10 +229,10 @@ Click on an instruction name to jump to its section.
0x1b | [`STATICCALL`](#isa-section-staticcall) |
Call into another contract, disallowing persistent state modifications. |
- 208 |
+ 248 |
{`M[successOffset] = staticcall(
- M[l1GasOffset], M[l2GasOffset], M[addrOffset],
+ M[gasOffset], M[gasOffset+1], M[addrOffset],
M[argsOffset], M[argsSize],
M[retOffset], M[retSize])`}
|
@@ -240,15 +240,15 @@ Click on an instruction name to jump to its section.
0x1c | [`ULOG`](#isa-section-ulog) |
Emit an unencrypted log with data from the `field` memory page |
- 64 |
+ 88 |
{
- `ulog(M[offset:offset+size])`
+ `ulog(M[logOffset:logOffset+logSize])`
} |
0x1d | [`CHAINID`](#isa-section-chainid) |
Get this rollup's L1 chain ID |
- 40 |
+ 56 |
{
`M[dstOffset] = Globals.chainId`
} |
@@ -256,7 +256,7 @@ Click on an instruction name to jump to its section.
0x1e | [`VERSION`](#isa-section-version) |
Get this rollup's L2 version ID |
- 40 |
+ 56 |
{
`M[dstOffset] = Globals.version`
} |
@@ -264,7 +264,7 @@ Click on an instruction name to jump to its section.
0x1f | [`BLOCKNUMBER`](#isa-section-blocknumber) |
Get this block's number |
- 40 |
+ 56 |
{
`M[dstOffset] = Globals.blocknumber`
} |
@@ -272,7 +272,7 @@ Click on an instruction name to jump to its section.
0x20 | [`TIMESTAMP`](#isa-section-timestamp) |
Get this L2 block's timestamp |
- 40 |
+ 56 |
{
`M[dstOffset] = Globals.timestamp`
} |
@@ -280,7 +280,7 @@ Click on an instruction name to jump to its section.
0x21 | [`COINBASE`](#isa-section-coinbase) |
Get the block's beneficiary address |
- 40 |
+ 56 |
{
`M[dstOffset] = Globals.coinbase`
} |
@@ -288,7 +288,7 @@ Click on an instruction name to jump to its section.
0x22 | [`BLOCKL1GASLIMIT`](#isa-section-blockl1gaslimit) |
Total amount of "L1 gas" that a block can consume |
- 40 |
+ 56 |
{
`M[dstOffset] = Globals.l1GasLimit`
} |
@@ -296,7 +296,7 @@ Click on an instruction name to jump to its section.
0x23 | [`BLOCKL2GASLIMIT`](#isa-section-blockl2gaslimit) |
Total amount of "L2 gas" that a block can consume |
- 40 |
+ 56 |
{
`M[dstOffset] = Globals.l2GasLimit`
} |
@@ -304,7 +304,7 @@ Click on an instruction name to jump to its section.
0x24 | [`NOTESROOT`](#isa-section-notesroot) |
Get the historical note-hash tree root as of the specified block number. |
- 64 |
+ 88 |
{
`M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].note_hash_tree_root`
} |
@@ -312,7 +312,7 @@ Click on an instruction name to jump to its section.
0x25 | [`NULLIFIERSROOT`](#isa-section-nullroot) |
Get the historical nullifier tree root as of the specified block number. |
- 64 |
+ 88 |
{
`M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].nullifier_tree_root`
} |
@@ -320,7 +320,7 @@ Click on an instruction name to jump to its section.
0x26 | [`CONTRACTSROOT`](#isa-section-contractsroot) |
Get the historical contracts tree root as of the specified block number. |
- 64 |
+ 88 |
{
`M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].contracts_tree_root`
} |
@@ -328,7 +328,7 @@ Click on an instruction name to jump to its section.
0x27 | [`MSGSROOT`](#isa-section-msgsroot) |
Get the historical l1-to-l2 messages tree root as of the specified block number. |
- 64 |
+ 88 |
{
`M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].l1_to_l2_messages_tree_root`
} |
@@ -336,7 +336,7 @@ Click on an instruction name to jump to its section.
0x28 | [`NOTESROOT`](#isa-section-notesroot) |
Get the historical note-hash tree root as of the specified block number. |
- 64 |
+ 88 |
{
`M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].note_hash_tree_root`
} |
@@ -344,7 +344,7 @@ Click on an instruction name to jump to its section.
0x29 | [`PUBLICDATAROOT`](#isa-section-publicdataroot) |
Get the historical public data tree root as of the specified block number. |
- 64 |
+ 88 |
{
`M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].public_data_tree_root`
} |
@@ -352,7 +352,7 @@ Click on an instruction name to jump to its section.
0x2a | [`GLOBALSHASH`](#isa-section-globalshash) |
Get the historical global variables hash as of the specified block number. |
- 64 |
+ 88 |
{
`M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].global_variables_hash`
} |
@@ -360,7 +360,7 @@ Click on an instruction name to jump to its section.
0x2b | [`BLOCKSROOT`](#isa-section-blocksroot) |
Get the historical blocks tree root as of the specified block number. |
- 64 |
+ 88 |
{
`M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].archive_root`
} |
@@ -368,7 +368,7 @@ Click on an instruction name to jump to its section.
0x2c | [`GRANDROOT`](#isa-section-grandroot) |
Get the historical grandfather tree root as of the specified block number. |
- 64 |
+ 88 |
{
`M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].grandfather_tree_root`
} |
@@ -376,7 +376,7 @@ Click on an instruction name to jump to its section.
0x2d | [`ORIGIN`](#isa-section-origin) |
Get the transaction's origination address |
- 40 |
+ 56 |
{
`M[dstOffset] = TxContext.origin`
} |
@@ -384,7 +384,7 @@ Click on an instruction name to jump to its section.
0x2e | [`REFUNDEE`](#isa-section-refundee) |
The recipient of fee refunds for this transaction |
- 40 |
+ 56 |
{
`M[dstOffset] = TxContext.refundee`
} |
@@ -392,7 +392,7 @@ Click on an instruction name to jump to its section.
0x2f | [`FEEPERL1GAS`](#isa-section-feeperl1gas) |
The fee to be paid per "L1 gas" - set by the transaction's original caller |
- 40 |
+ 56 |
{
`M[dstOffset] = TxContext.feePerL1Gas`
} |
@@ -400,7 +400,7 @@ Click on an instruction name to jump to its section.
0x30 | [`FEEPERL2GAS`](#isa-section-feeperl2gas) |
The fee to be paid per "L2 gas" - set by the transaction's original caller |
- 40 |
+ 56 |
{
`M[dstOffset] = TxContext.feePerL2Gas`
} |
@@ -408,7 +408,7 @@ Click on an instruction name to jump to its section.
0x31 | [`CALLER`](#isa-section-caller) |
Get the address of the sender (the caller's context) |
- 40 |
+ 56 |
{
`M[dstOffset] = CallContext.sender`
} |
@@ -416,7 +416,7 @@ Click on an instruction name to jump to its section.
0x32 | [`ADDRESS`](#isa-section-address) |
Get the address of the currently executing l2 contract |
- 40 |
+ 56 |
{
`M[dstOffset] = CallContext.storageContractAddress`
} |
@@ -424,7 +424,7 @@ Click on an instruction name to jump to its section.
0x33 | [`PORTAL`](#isa-section-portal) |
Get the address of the l1 portal contract |
- 40 |
+ 56 |
{
`M[dstOffset] = CallContext.portalAddress`
} |
@@ -432,7 +432,7 @@ Click on an instruction name to jump to its section.
0x34 | [`CALLDEPTH`](#isa-section-calldepth) |
Get how many calls deep the current call context is |
- 40 |
+ 56 |
{
`M[dstOffset] = CallContext.calldepth`
} |
@@ -440,7 +440,7 @@ Click on an instruction name to jump to its section.
0x35 | [`L1GAS`](#isa-section-l1gas) |
Remaining "L1 gas" for this call (after this instruction). |
- 40 |
+ 56 |
{
`M[dstOffset] = LatestContext.l1Gas`
} |
@@ -448,7 +448,7 @@ Click on an instruction name to jump to its section.
0x36 | [`L2GAS`](#isa-section-l2gas) |
Remaining "L2 gas" for this call (after this instruction). |
- 40 |
+ 56 |
{
`M[dstOffset] = LatestContext.l2Gas`
} |
@@ -466,17 +466,17 @@ Addition (a + b)
- **Category**: arithmetic
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- - **op-type**: The [type/size](./Types) to check inputs against and tag the output with.
+ - **in-tag**: The [tag/size](./state-model#tags-and-tagged-memory) to check inputs against and tag the destination with.
- **Args**:
- **aOffset**: memory offset of the operation's left input
- **bOffset**: memory offset of the operation's right input
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = M[aOffset] + M[bOffset] mod 2^k`
-- **Tag checks**: `T[aOffset] == T[bOffset] == op-type`
-- **Tag updates**: `T[dstOffset] = op-type`
-- **Bit-size**: 96
+- **Tag checks**: `T[aOffset] == T[bOffset] == in-tag`
+- **Tag updates**: `T[dstOffset] = in-tag`
+- **Bit-size**: 128
-![](./images/bit-formats/ADD.png)
+[![](./images/bit-formats/ADD.png)](./images/bit-formats/ADD.png)
### `SUB` (0x01)
Subtraction (a - b)
@@ -486,17 +486,17 @@ Subtraction (a - b)
- **Category**: arithmetic
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- - **op-type**: The [type/size](./Types) to check inputs against and tag the output with.
+ - **in-tag**: The [tag/size](./state-model#tags-and-tagged-memory) to check inputs against and tag the destination with.
- **Args**:
- **aOffset**: memory offset of the operation's left input
- **bOffset**: memory offset of the operation's right input
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = M[aOffset] - M[bOffset] mod 2^k`
-- **Tag checks**: `T[aOffset] == T[bOffset] == op-type`
-- **Tag updates**: `T[dstOffset] = op-type`
-- **Bit-size**: 96
+- **Tag checks**: `T[aOffset] == T[bOffset] == in-tag`
+- **Tag updates**: `T[dstOffset] = in-tag`
+- **Bit-size**: 128
-![](./images/bit-formats/SUB.png)
+[![](./images/bit-formats/SUB.png)](./images/bit-formats/SUB.png)
### `DIV` (0x02)
Unsigned division (a / b)
@@ -506,17 +506,17 @@ Unsigned division (a / b)
- **Category**: arithmetic
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- - **op-type**: The [type/size](./Types) to check inputs against and tag the output with.
+ - **in-tag**: The [tag/size](./state-model#tags-and-tagged-memory) to check inputs against and tag the destination with.
- **Args**:
- **aOffset**: memory offset of the operation's left input
- **bOffset**: memory offset of the operation's right input
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = M[aOffset] / M[bOffset]`
-- **Tag checks**: `T[aOffset] == T[bOffset] == op-type`
-- **Tag updates**: `T[dstOffset] = op-type`
-- **Bit-size**: 96
+- **Tag checks**: `T[aOffset] == T[bOffset] == in-tag`
+- **Tag updates**: `T[dstOffset] = in-tag`
+- **Bit-size**: 128
-![](./images/bit-formats/DIV.png)
+[![](./images/bit-formats/DIV.png)](./images/bit-formats/DIV.png)
### `EQ` (0x03)
Equality check (a == b)
@@ -526,17 +526,17 @@ Equality check (a == b)
- **Category**: conditional
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- - **op-type**: The [type/size](./Types) to check inputs against and tag the output with.
+ - **in-tag**: The [tag/size](./state-model#tags-and-tagged-memory) to check inputs against and tag the destination with.
- **Args**:
- **aOffset**: memory offset of the operation's left input
- **bOffset**: memory offset of the operation's right input
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = M[aOffset] == M[bOffset] ? 1 : 0`
-- **Tag checks**: `T[aOffset] == T[bOffset] == op-type`
-- **Tag updates**: `T[dstOffset] = op-type`
-- **Bit-size**: 96
+- **Tag checks**: `T[aOffset] == T[bOffset] == in-tag`
+- **Tag updates**: `T[dstOffset] = in-tag`
+- **Bit-size**: 128
-![](./images/bit-formats/EQ.png)
+[![](./images/bit-formats/EQ.png)](./images/bit-formats/EQ.png)
### `LT` (0x04)
Less-than check (a < b)
@@ -546,17 +546,17 @@ Less-than check (a < b)
- **Category**: conditional
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- - **op-type**: The [type/size](./Types) to check inputs against and tag the output with.
+ - **in-tag**: The [tag/size](./state-model#tags-and-tagged-memory) to check inputs against and tag the destination with.
- **Args**:
- **aOffset**: memory offset of the operation's left input
- **bOffset**: memory offset of the operation's right input
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = M[aOffset] < M[bOffset] ? 1 : 0`
-- **Tag checks**: `T[aOffset] == T[bOffset] == op-type`
-- **Tag updates**: `T[dstOffset] = op-type`
-- **Bit-size**: 96
+- **Tag checks**: `T[aOffset] == T[bOffset] == in-tag`
+- **Tag updates**: `T[dstOffset] = in-tag`
+- **Bit-size**: 128
-![](./images/bit-formats/LT.png)
+[![](./images/bit-formats/LT.png)](./images/bit-formats/LT.png)
### `LTE` (0x05)
Less-than-or-equals check (a <= b)
@@ -566,17 +566,17 @@ Less-than-or-equals check (a <= b)
- **Category**: conditional
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- - **op-type**: The [type/size](./Types) to check inputs against and tag the output with.
+ - **in-tag**: The [tag/size](./state-model#tags-and-tagged-memory) to check inputs against and tag the destination with.
- **Args**:
- **aOffset**: memory offset of the operation's left input
- **bOffset**: memory offset of the operation's right input
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = M[aOffset] <= M[bOffset] ? 1 : 0`
-- **Tag checks**: `T[aOffset] == T[bOffset] == op-type`
-- **Tag updates**: `T[dstOffset] = op-type`
-- **Bit-size**: 96
+- **Tag checks**: `T[aOffset] == T[bOffset] == in-tag`
+- **Tag updates**: `T[dstOffset] = in-tag`
+- **Bit-size**: 128
-![](./images/bit-formats/LTE.png)
+[![](./images/bit-formats/LTE.png)](./images/bit-formats/LTE.png)
### `AND` (0x06)
Bitwise AND (a & b)
@@ -586,17 +586,17 @@ Bitwise AND (a & b)
- **Category**: bitwise
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- - **op-type**: The [type/size](./Types) to check inputs against and tag the output with.
+ - **in-tag**: The [tag/size](./state-model#tags-and-tagged-memory) to check inputs against and tag the destination with.
- **Args**:
- **aOffset**: memory offset of the operation's left input
- **bOffset**: memory offset of the operation's right input
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = M[aOffset] AND M[bOffset]`
-- **Tag checks**: `T[aOffset] == T[bOffset] == op-type`
-- **Tag updates**: `T[dstOffset] = op-type`
-- **Bit-size**: 96
+- **Tag checks**: `T[aOffset] == T[bOffset] == in-tag`
+- **Tag updates**: `T[dstOffset] = in-tag`
+- **Bit-size**: 128
-![](./images/bit-formats/AND.png)
+[![](./images/bit-formats/AND.png)](./images/bit-formats/AND.png)
### `OR` (0x07)
Bitwise OR (a | b)
@@ -606,17 +606,17 @@ Bitwise OR (a | b)
- **Category**: bitwise
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- - **op-type**: The [type/size](./Types) to check inputs against and tag the output with.
+ - **in-tag**: The [tag/size](./state-model#tags-and-tagged-memory) to check inputs against and tag the destination with.
- **Args**:
- **aOffset**: memory offset of the operation's left input
- **bOffset**: memory offset of the operation's right input
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = M[aOffset] OR M[bOffset]`
-- **Tag checks**: `T[aOffset] == T[bOffset] == op-type`
-- **Tag updates**: `T[dstOffset] = op-type`
-- **Bit-size**: 96
+- **Tag checks**: `T[aOffset] == T[bOffset] == in-tag`
+- **Tag updates**: `T[dstOffset] = in-tag`
+- **Bit-size**: 128
-![](./images/bit-formats/OR.png)
+[![](./images/bit-formats/OR.png)](./images/bit-formats/OR.png)
### `XOR` (0x08)
Bitwise XOR (a ^ b)
@@ -626,17 +626,17 @@ Bitwise XOR (a ^ b)
- **Category**: bitwise
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- - **op-type**: The [type/size](./Types) to check inputs against and tag the output with.
+ - **in-tag**: The [tag/size](./state-model#tags-and-tagged-memory) to check inputs against and tag the destination with.
- **Args**:
- **aOffset**: memory offset of the operation's left input
- **bOffset**: memory offset of the operation's right input
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = M[aOffset] XOR M[bOffset]`
-- **Tag checks**: `T[aOffset] == T[bOffset] == op-type`
-- **Tag updates**: `T[dstOffset] = op-type`
-- **Bit-size**: 96
+- **Tag checks**: `T[aOffset] == T[bOffset] == in-tag`
+- **Tag updates**: `T[dstOffset] = in-tag`
+- **Bit-size**: 128
-![](./images/bit-formats/XOR.png)
+[![](./images/bit-formats/XOR.png)](./images/bit-formats/XOR.png)
### `NOT` (0x09)
Bitwise NOT (inversion)
@@ -646,16 +646,16 @@ Bitwise NOT (inversion)
- **Category**: bitwise
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- - **op-type**: The [type/size](./Types) to check inputs against and tag the output with.
+ - **in-tag**: The [tag/size](./state-model#tags-and-tagged-memory) to check inputs against and tag the destination with.
- **Args**:
- **aOffset**: memory offset of the operation's input
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = NOT M[aOffset]`
-- **Tag checks**: `T[aOffset] == op-type`
-- **Tag updates**: `T[dstOffset] = op-type`
-- **Bit-size**: 72
+- **Tag checks**: `T[aOffset] == in-tag`
+- **Tag updates**: `T[dstOffset] = in-tag`
+- **Bit-size**: 96
-![](./images/bit-formats/NOT.png)
+[![](./images/bit-formats/NOT.png)](./images/bit-formats/NOT.png)
### `SHL` (0x0a)
Bitwise leftward shift (a << b)
@@ -665,17 +665,17 @@ Bitwise leftward shift (a << b)
- **Category**: bitwise
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- - **op-type**: The [type/size](./Types) to check inputs against and tag the output with.
+ - **in-tag**: The [tag/size](./state-model#tags-and-tagged-memory) to check inputs against and tag the destination with.
- **Args**:
- **aOffset**: memory offset of the operation's left input
- **bOffset**: memory offset of the operation's right input
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = M[aOffset] << M[bOffset]`
-- **Tag checks**: `T[aOffset] == T[bOffset] == op-type`
-- **Tag updates**: `T[dstOffset] = op-type`
-- **Bit-size**: 96
+- **Tag checks**: `T[aOffset] == T[bOffset] == in-tag`
+- **Tag updates**: `T[dstOffset] = in-tag`
+- **Bit-size**: 128
-![](./images/bit-formats/SHL.png)
+[![](./images/bit-formats/SHL.png)](./images/bit-formats/SHL.png)
### `SHR` (0x0b)
Bitwise rightward shift (a >> b)
@@ -685,17 +685,17 @@ Bitwise rightward shift (a >> b)
- **Category**: bitwise
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- - **op-type**: The [type/size](./Types) to check inputs against and tag the output with.
+ - **in-tag**: The [tag/size](./state-model#tags-and-tagged-memory) to check inputs against and tag the destination with.
- **Args**:
- **aOffset**: memory offset of the operation's left input
- **bOffset**: memory offset of the operation's right input
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = M[aOffset] >> M[bOffset]`
-- **Tag checks**: `T[aOffset] == T[bOffset] == op-type`
-- **Tag updates**: `T[dstOffset] = op-type`
-- **Bit-size**: 96
+- **Tag checks**: `T[aOffset] == T[bOffset] == in-tag`
+- **Tag updates**: `T[dstOffset] = in-tag`
+- **Bit-size**: 128
-![](./images/bit-formats/SHR.png)
+[![](./images/bit-formats/SHR.png)](./images/bit-formats/SHR.png)
### `CAST` (0x0c)
Type cast
@@ -705,16 +705,16 @@ Type cast
- **Category**: types
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- - **dest-type**: The [type/size](./Types) to tag the output with when different from `op-type`.
+ - **dst-tag**: The [tag/size](./state-model#tags-and-tagged-memory) to tag the destination with but not to check inputs against.
- **Args**:
- **aOffset**: memory offset of word to cast
- **dstOffset**: memory offset specifying where to store operation's result
-- **Expression**: `M[dstOffset] = cast(M[aOffset])`
-- **Details**: Cast a word in memory based on the `dest-type` specified in the bytecode. Truncates when casting to a smaller type, left-zero-pads when casting to a larger type.
-- **Tag updates**: `T[dstOffset] = dest-type`
-- **Bit-size**: 72
+- **Expression**: `M[dstOffset] = cast(M[aOffset])`
+- **Details**: Cast a word in memory based on the `dst-tag` specified in the bytecode. Truncates when casting to a smaller type, left-zero-pads when casting to a larger type. See [here](./state-model#cast-and-tag-conversions) for more details.
+- **Tag updates**: `T[dstOffset] = dst-tag`
+- **Bit-size**: 96
-![](./images/bit-formats/CAST.png)
+[![](./images/bit-formats/CAST.png)](./images/bit-formats/CAST.png)
### `SET` (0x0d)
Set a memory word from a constant in the bytecode.
@@ -724,16 +724,16 @@ Set a memory word from a constant in the bytecode.
- **Category**: memory
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- - **op-type**: The [type/size](./Types) to check inputs against and tag the output with. `field` type is NOT supported for SET.
+ - **in-tag**: The [type/size](./state-model#tags-and-tagged-memory) to check inputs against and tag the destination with. `field` type is NOT supported for SET.
- **Args**:
- **const**: an N-bit constant value from the bytecode to store in memory (any type except `field`)
- **dstOffset**: memory offset specifying where to store the constant
- **Expression**: `M[dstOffset] = const`
-- **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 `op-type`. It _cannot be 254 (`field` type)_!
-- **Tag updates**: `T[dstOffset] = op-type`
-- **Bit-size**: 48+N
+- **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 `in-tag`. It _cannot be 254 (`field` type)_!
+- **Tag updates**: `T[dstOffset] = in-tag`
+- **Bit-size**: 64+N
-![](./images/bit-formats/SET.png)
+[![](./images/bit-formats/SET.png)](./images/bit-formats/SET.png)
### `MOV` (0x0e)
Move a word from source memory location to destination`.
@@ -748,9 +748,9 @@ Move a word from source memory location to destination`.
- **dstOffset**: memory offset specifying where to store that word
- **Expression**: `M[dstOffset] = M[srcOffset]`
- **Tag updates**: `T[dstOffset] = T[srcOffset]`
-- **Bit-size**: 64
+- **Bit-size**: 88
-![](./images/bit-formats/MOV.png)
+[![](./images/bit-formats/MOV.png)](./images/bit-formats/MOV.png)
### `CMOV` (0x0f)
Move a word (conditionally chosen) from one memory location to another (`d = cond > 0 ? a : b`).
@@ -768,9 +768,9 @@ Move a word (conditionally chosen) from one memory location to another (`d = con
- **Expression**: `M[dstOffset] = M[condOffset] > 0 ? M[aOffset] : M[bOffset]`
- **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 updates**: `T[dstOffset] = M[condOffset] > 0 ? T[aOffset] : T[bOffset]`
-- **Bit-size**: 112
+- **Bit-size**: 152
-![](./images/bit-formats/CMOV.png)
+[![](./images/bit-formats/CMOV.png)](./images/bit-formats/CMOV.png)
### `CALLDATACOPY` (0x10)
Copy calldata into memory.
@@ -782,14 +782,14 @@ Copy calldata into memory.
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- **Args**:
- **cdOffset**: offset into calldata to copy from
- - **size**: number of words to copy
+ - **copySize**: number of words to copy
- **dstOffset**: memory offset specifying where to copy the first word to
-- **Expression**: `M[dstOffset:dstOffset+size] = calldata[cdOffset:cdOffset+size]`
+- **Expression**: `M[dstOffset:dstOffset+copySize] = calldata[cdOffset:cdOffset+copySize]`
- **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 updates**: `T[dstOffset:dstOffset+size] = field`
-- **Bit-size**: 88
+- **Tag updates**: `T[dstOffset:dstOffset+copySize] = field`
+- **Bit-size**: 120
-![](./images/bit-formats/CALLDATACOPY.png)
+[![](./images/bit-formats/CALLDATACOPY.png)](./images/bit-formats/CALLDATACOPY.png)
### `SLOAD` (0x11)
Load a word from storage.
@@ -805,9 +805,9 @@ Load a word from storage.
- **Expression**: `M[dstOffset] = storage[M[slotOffset]]`
- **Details**: Load a word from this contract's persistent public storage into memory.
- **Tag updates**: `T[dstOffset] = field`
-- **Bit-size**: 64
+- **Bit-size**: 88
-![](./images/bit-formats/SLOAD.png)
+[![](./images/bit-formats/SLOAD.png)](./images/bit-formats/SLOAD.png)
### `SSTORE` (0x12)
Write a word to storage.
@@ -822,9 +822,9 @@ Write a word to storage.
- **slotOffset**: memory offset containing the storage slot to store to
- **Expression**: `storage[M[slotOffset]] = M[srcOffset]`
- **Details**: Store a word from memory into this contract's persistent public storage.
-- **Bit-size**: 64
+- **Bit-size**: 88
-![](./images/bit-formats/SSTORE.png)
+[![](./images/bit-formats/SSTORE.png)](./images/bit-formats/SSTORE.png)
### `EMITNOTEHASH` (0x13)
Emit a new note hash to be inserted into the notes tree
@@ -837,9 +837,9 @@ Emit a new note hash to be inserted into the notes tree
- **Args**:
- **noteHashOffset**: memory offset of the note hash
- **Expression**: emitNoteHash(M[contentOffset])
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/EMITNOTEHASH.png)
+[![](./images/bit-formats/EMITNOTEHASH.png)](./images/bit-formats/EMITNOTEHASH.png)
### `EMITNULLIFIER` (0x14)
Emit a new nullifier to be inserted into the nullifier tree
@@ -852,9 +852,9 @@ Emit a new nullifier to be inserted into the nullifier tree
- **Args**:
- **nullifierOffset**: memory offset of nullifier
- **Expression**: emitNullifier(M[nullifierOffset])
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/EMITNULLIFIER.png)
+[![](./images/bit-formats/EMITNULLIFIER.png)](./images/bit-formats/EMITNULLIFIER.png)
### `SENDL2TOL1MSG` (0x15)
Send an L2-to-L1 message
@@ -867,9 +867,9 @@ Send an L2-to-L1 message
- **Args**:
- **contentOffset**: memory offset of the message content
- **Expression**: sendL2ToL1Message(M[contentOffset])
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/SENDL2TOL1MSG.png)
+[![](./images/bit-formats/SENDL2TOL1MSG.png)](./images/bit-formats/SENDL2TOL1MSG.png)
### `JUMP` (0x16)
Jump to a location in the bytecode.
@@ -881,9 +881,9 @@ Jump to a location in the bytecode.
- **loc**: target location to jump to
- **Expression**: `PC = loc`
- **Details**: Target location is an immediate value (a constant in the bytecode).
-- **Bit-size**: 32
+- **Bit-size**: 48
-![](./images/bit-formats/JUMP.png)
+[![](./images/bit-formats/JUMP.png)](./images/bit-formats/JUMP.png)
### `JUMPI` (0x17)
Conditionally jump to a location in the bytecode.
@@ -898,9 +898,9 @@ Conditionally jump to a location in the bytecode.
- **condOffset**: memory offset of the operations 'conditional' input
- **Expression**: `PC = M[condOffset] > 0 ? loc : PC`
- **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.
-- **Bit-size**: 64
+- **Bit-size**: 88
-![](./images/bit-formats/JUMPI.png)
+[![](./images/bit-formats/JUMPI.png)](./images/bit-formats/JUMPI.png)
### `RETURN` (0x18)
Halt execution with `success`, optionally returning some data.
@@ -911,13 +911,13 @@ Halt execution with `success`, optionally returning some data.
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- **Args**:
- - **offset**: memory offset of first word to return
- - **size**: number of words to return
-- **Expression**: `return(M[offset:offset+size])`
+ - **retOffset**: memory offset of first word to return
+ - **retSize**: number of words to return
+- **Expression**: `return(M[retOffset:retOffset+retSize])`
- **Details**: Return control flow to the calling context/contract.
-- **Bit-size**: 64
+- **Bit-size**: 88
-![](./images/bit-formats/RETURN.png)
+[![](./images/bit-formats/RETURN.png)](./images/bit-formats/RETURN.png)
### `REVERT` (0x19)
Halt execution with `failure`, reverting state changes and optionally returning some data.
@@ -928,13 +928,13 @@ Halt execution with `failure`, reverting state changes and optionally returning
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- **Args**:
- - **offset**: memory offset of first word to return
- - **size**: number of words to return
-- **Expression**: `revert(M[offset:offset+size])`
+ - **retOffset**: memory offset of first word to return
+ - **retSize**: number of words to return
+- **Expression**: `revert(M[retOffset:retOffset+retSize])`
- **Details**: Return control flow to the calling context/contract.
-- **Bit-size**: 64
+- **Bit-size**: 88
-![](./images/bit-formats/REVERT.png)
+[![](./images/bit-formats/REVERT.png)](./images/bit-formats/REVERT.png)
### `CALL` (0x1a)
Call into another contract.
@@ -945,8 +945,7 @@ Call into another contract.
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- **Args**:
- - **l1GasOffset**: amount of L1 gas to provide to the callee
- - **l2GasOffset**: amount of L2 gas to provide to the callee
+ - **gasOffset**: offset to two words containing `{l1Gas, l2Gas}`: amount of L1 and L2 gas to provide to the callee
- **addrOffset**: address of the contract to call
- **argsOffset**: memory offset to args (will become the callee's calldata)
- **argsSize**: number of words to pass via callee's calldata
@@ -956,22 +955,22 @@ Call into another contract.
- **Expression**:
{`M[successOffset] = call(
- M[l1GasOffset], M[l2GasOffset], M[addrOffset],
+ M[gasOffset], M[gasOffset+1], M[addrOffset],
M[argsOffset], M[argsSize],
M[retOffset], M[retSize])`}
- **Details**: Creates a new CallContext, triggers execution of the corresponding contract code,
and then resumes execution in the current CallContext. A non-existent contract or one
with no code will return success. Nested call has an incremented `CallContext.calldepth`.
-- **Tag checks**: `T[l1GasOffset] == T[l2GasOffset] == u32`
+- **Tag checks**: `T[gasOffset] == T[gasOffset+1] == u32`
- **Tag updates**:
{`T[successOffset] = u8
T[retOffset:retOffset+retSize] = field`}
-- **Bit-size**: 208
+- **Bit-size**: 248
-![](./images/bit-formats/CALL.png)
+[![](./images/bit-formats/CALL.png)](./images/bit-formats/CALL.png)
### `STATICCALL` (0x1b)
Call into another contract, disallowing persistent state modifications.
@@ -982,8 +981,7 @@ Call into another contract, disallowing persistent state modifications.
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- **Args**:
- - **l1GasOffset**: amount of L1 gas to provide to the callee
- - **l2GasOffset**: amount of L2 gas to provide to the callee
+ - **gasOffset**: offset to two words containing `{l1Gas, l2Gas}`: amount of L1 and L2 gas to provide to the callee
- **addrOffset**: address of the contract to call
- **argsOffset**: memory offset to args (will become the callee's calldata)
- **argsSize**: number of words to pass via callee's calldata
@@ -993,20 +991,20 @@ Call into another contract, disallowing persistent state modifications.
- **Expression**:
{`M[successOffset] = staticcall(
- M[l1GasOffset], M[l2GasOffset], M[addrOffset],
+ M[gasOffset], M[gasOffset+1], M[addrOffset],
M[argsOffset], M[argsSize],
M[retOffset], M[retSize])`}
- **Details**: Same as `CALL`, but the callee is cannot modify persistent state. Disallowed instructions are `SSTORE`, `ULOG`, `CALL`.
-- **Tag checks**: `T[l1GasOffset] == T[l2GasOffset] == u32`
+- **Tag checks**: `T[gasOffset] == T[gasOffset+1] == u32`
- **Tag updates**:
{`T[successOffset] = u8
T[retOffset:retOffset+retSize] = field`}
-- **Bit-size**: 208
+- **Bit-size**: 248
-![](./images/bit-formats/STATICCALL.png)
+[![](./images/bit-formats/STATICCALL.png)](./images/bit-formats/STATICCALL.png)
### `ULOG` (0x1c)
Emit an unencrypted log with data from the `field` memory page
@@ -1017,12 +1015,12 @@ Emit an unencrypted log with data from the `field` memory page
- **Flags**:
- **indirect**: Toggles whether each memory-offset argument is an indirect offset. 0th bit corresponds to 0th offset arg, etc. Indirect offsets result in memory accesses like `M[M[offset]]` instead of the more standard `M[offset]`.
- **Args**:
- - **offset**: memory offset of the data to log
- - **size**: number of words to log
-- **Expression**: `ulog(M[offset:offset+size])`
-- **Bit-size**: 64
+ - **logOffset**: memory offset of the data to log
+ - **logSize**: number of words to log
+- **Expression**: `ulog(M[logOffset:logOffset+logSize])`
+- **Bit-size**: 88
-![](./images/bit-formats/ULOG.png)
+[![](./images/bit-formats/ULOG.png)](./images/bit-formats/ULOG.png)
### `CHAINID` (0x1d)
Get this rollup's L1 chain ID
@@ -1036,9 +1034,9 @@ Get this rollup's L1 chain ID
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = Globals.chainId`
- **Tag updates**: `T[dstOffset] = u32`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/CHAINID.png)
+[![](./images/bit-formats/CHAINID.png)](./images/bit-formats/CHAINID.png)
### `VERSION` (0x1e)
Get this rollup's L2 version ID
@@ -1052,9 +1050,9 @@ Get this rollup's L2 version ID
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = Globals.version`
- **Tag updates**: `T[dstOffset] = u32`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/VERSION.png)
+[![](./images/bit-formats/VERSION.png)](./images/bit-formats/VERSION.png)
### `BLOCKNUMBER` (0x1f)
Get this block's number
@@ -1068,9 +1066,9 @@ Get this block's number
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = Globals.blocknumber`
- **Tag updates**: `T[dstOffset] = u32`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/BLOCKNUMBER.png)
+[![](./images/bit-formats/BLOCKNUMBER.png)](./images/bit-formats/BLOCKNUMBER.png)
### `TIMESTAMP` (0x20)
Get this L2 block's timestamp
@@ -1084,9 +1082,9 @@ Get this L2 block's timestamp
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = Globals.timestamp`
- **Tag updates**: `T[dstOffset] = u64`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/TIMESTAMP.png)
+[![](./images/bit-formats/TIMESTAMP.png)](./images/bit-formats/TIMESTAMP.png)
### `COINBASE` (0x21)
Get the block's beneficiary address
@@ -1100,9 +1098,9 @@ Get the block's beneficiary address
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = Globals.coinbase`
- **Tag updates**: `T[dstOffset] = u32`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/COINBASE.png)
+[![](./images/bit-formats/COINBASE.png)](./images/bit-formats/COINBASE.png)
### `BLOCKL1GASLIMIT` (0x22)
Total amount of "L1 gas" that a block can consume
@@ -1116,9 +1114,9 @@ Total amount of "L1 gas" that a block can consume
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = Globals.l1GasLimit`
- **Tag updates**: `T[dstOffset] = u32`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/BLOCKL1GASLIMIT.png)
+[![](./images/bit-formats/BLOCKL1GASLIMIT.png)](./images/bit-formats/BLOCKL1GASLIMIT.png)
### `BLOCKL2GASLIMIT` (0x23)
Total amount of "L2 gas" that a block can consume
@@ -1132,9 +1130,9 @@ Total amount of "L2 gas" that a block can consume
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = Globals.l2GasLimit`
- **Tag updates**: `T[dstOffset] = u32`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/BLOCKL2GASLIMIT.png)
+[![](./images/bit-formats/BLOCKL2GASLIMIT.png)](./images/bit-formats/BLOCKL2GASLIMIT.png)
### `NOTESROOT` (0x24)
Get the historical note-hash tree root as of the specified block number.
@@ -1149,9 +1147,9 @@ Get the historical note-hash tree root as of the specified block number.
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].note_hash_tree_root`
- **Tag updates**: `T[dstOffset] = field`
-- **Bit-size**: 64
+- **Bit-size**: 88
-![](./images/bit-formats/NOTESROOT.png)
+[![](./images/bit-formats/NOTESROOT.png)](./images/bit-formats/NOTESROOT.png)
### `NULLIFIERSROOT` (0x25)
Get the historical nullifier tree root as of the specified block number.
@@ -1166,9 +1164,9 @@ Get the historical nullifier tree root as of the specified block number.
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].nullifier_tree_root`
- **Tag updates**: `T[dstOffset] = field`
-- **Bit-size**: 64
+- **Bit-size**: 88
-![](./images/bit-formats/NULLIFIERSROOT.png)
+[![](./images/bit-formats/NULLIFIERSROOT.png)](./images/bit-formats/NULLIFIERSROOT.png)
### `CONTRACTSROOT` (0x26)
Get the historical contracts tree root as of the specified block number.
@@ -1183,9 +1181,9 @@ Get the historical contracts tree root as of the specified block number.
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].contracts_tree_root`
- **Tag updates**: `T[dstOffset] = field`
-- **Bit-size**: 64
+- **Bit-size**: 88
-![](./images/bit-formats/CONTRACTSROOT.png)
+[![](./images/bit-formats/CONTRACTSROOT.png)](./images/bit-formats/CONTRACTSROOT.png)
### `MSGSROOT` (0x27)
Get the historical l1-to-l2 messages tree root as of the specified block number.
@@ -1200,9 +1198,9 @@ Get the historical l1-to-l2 messages tree root as of the specified block number.
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].l1_to_l2_messages_tree_root`
- **Tag updates**: `T[dstOffset] = field`
-- **Bit-size**: 64
+- **Bit-size**: 88
-![](./images/bit-formats/MSGSROOT.png)
+[![](./images/bit-formats/MSGSROOT.png)](./images/bit-formats/MSGSROOT.png)
### `NOTESROOT` (0x28)
Get the historical note-hash tree root as of the specified block number.
@@ -1217,9 +1215,9 @@ Get the historical note-hash tree root as of the specified block number.
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].note_hash_tree_root`
- **Tag updates**: `T[dstOffset] = field`
-- **Bit-size**: 64
+- **Bit-size**: 88
-![](./images/bit-formats/NOTESROOT.png)
+[![](./images/bit-formats/NOTESROOT.png)](./images/bit-formats/NOTESROOT.png)
### `PUBLICDATAROOT` (0x29)
Get the historical public data tree root as of the specified block number.
@@ -1234,9 +1232,9 @@ Get the historical public data tree root as of the specified block number.
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].public_data_tree_root`
- **Tag updates**: `T[dstOffset] = field`
-- **Bit-size**: 64
+- **Bit-size**: 88
-![](./images/bit-formats/PUBLICDATAROOT.png)
+[![](./images/bit-formats/PUBLICDATAROOT.png)](./images/bit-formats/PUBLICDATAROOT.png)
### `GLOBALSHASH` (0x2a)
Get the historical global variables hash as of the specified block number.
@@ -1251,9 +1249,9 @@ Get the historical global variables hash as of the specified block number.
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].global_variables_hash`
- **Tag updates**: `T[dstOffset] = field`
-- **Bit-size**: 64
+- **Bit-size**: 88
-![](./images/bit-formats/GLOBALSHASH.png)
+[![](./images/bit-formats/GLOBALSHASH.png)](./images/bit-formats/GLOBALSHASH.png)
### `BLOCKSROOT` (0x2b)
Get the historical blocks tree root as of the specified block number.
@@ -1268,9 +1266,9 @@ Get the historical blocks tree root as of the specified block number.
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].archive_root`
- **Tag updates**: `T[dstOffset] = field`
-- **Bit-size**: 64
+- **Bit-size**: 88
-![](./images/bit-formats/BLOCKSROOT.png)
+[![](./images/bit-formats/BLOCKSROOT.png)](./images/bit-formats/BLOCKSROOT.png)
### `GRANDROOT` (0x2c)
Get the historical grandfather tree root as of the specified block number.
@@ -1285,9 +1283,9 @@ Get the historical grandfather tree root as of the specified block number.
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = HistoricalBlockData[M[blockNumOffset]].grandfather_tree_root`
- **Tag updates**: `T[dstOffset] = field`
-- **Bit-size**: 64
+- **Bit-size**: 88
-![](./images/bit-formats/GRANDROOT.png)
+[![](./images/bit-formats/GRANDROOT.png)](./images/bit-formats/GRANDROOT.png)
### `ORIGIN` (0x2d)
Get the transaction's origination address
@@ -1301,9 +1299,9 @@ Get the transaction's origination address
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = TxContext.origin`
- **Tag updates**: `T[dstOffset] = u32`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/ORIGIN.png)
+[![](./images/bit-formats/ORIGIN.png)](./images/bit-formats/ORIGIN.png)
### `REFUNDEE` (0x2e)
The recipient of fee refunds for this transaction
@@ -1317,9 +1315,9 @@ The recipient of fee refunds for this transaction
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = TxContext.refundee`
- **Tag updates**: `T[dstOffset] = u32`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/REFUNDEE.png)
+[![](./images/bit-formats/REFUNDEE.png)](./images/bit-formats/REFUNDEE.png)
### `FEEPERL1GAS` (0x2f)
The fee to be paid per "L1 gas" - set by the transaction's original caller
@@ -1333,9 +1331,9 @@ The fee to be paid per "L1 gas" - set by the transaction's original caller
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = TxContext.feePerL1Gas`
- **Tag updates**: `T[dstOffset] = u32`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/FEEPERL1GAS.png)
+[![](./images/bit-formats/FEEPERL1GAS.png)](./images/bit-formats/FEEPERL1GAS.png)
### `FEEPERL2GAS` (0x30)
The fee to be paid per "L2 gas" - set by the transaction's original caller
@@ -1349,9 +1347,9 @@ The fee to be paid per "L2 gas" - set by the transaction's original caller
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = TxContext.feePerL2Gas`
- **Tag updates**: `T[dstOffset] = u32`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/FEEPERL2GAS.png)
+[![](./images/bit-formats/FEEPERL2GAS.png)](./images/bit-formats/FEEPERL2GAS.png)
### `CALLER` (0x31)
Get the address of the sender (the caller's context)
@@ -1365,9 +1363,9 @@ Get the address of the sender (the caller's context)
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = CallContext.sender`
- **Tag updates**: `T[dstOffset] = u32`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/CALLER.png)
+[![](./images/bit-formats/CALLER.png)](./images/bit-formats/CALLER.png)
### `ADDRESS` (0x32)
Get the address of the currently executing l2 contract
@@ -1381,9 +1379,9 @@ Get the address of the currently executing l2 contract
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = CallContext.storageContractAddress`
- **Tag updates**: `T[dstOffset] = u32`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/ADDRESS.png)
+[![](./images/bit-formats/ADDRESS.png)](./images/bit-formats/ADDRESS.png)
### `PORTAL` (0x33)
Get the address of the l1 portal contract
@@ -1397,9 +1395,9 @@ Get the address of the l1 portal contract
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = CallContext.portalAddress`
- **Tag updates**: `T[dstOffset] = u32`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/PORTAL.png)
+[![](./images/bit-formats/PORTAL.png)](./images/bit-formats/PORTAL.png)
### `CALLDEPTH` (0x34)
Get how many calls deep the current call context is
@@ -1414,9 +1412,9 @@ Get how many calls deep the current call context is
- **Expression**: `M[dstOffset] = CallContext.calldepth`
- **Details**: Note: security issues with EVM's tx.origin can be resolved by asserting the `calldepth == 0`.
- **Tag updates**: `T[dstOffset] = u8`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/CALLDEPTH.png)
+[![](./images/bit-formats/CALLDEPTH.png)](./images/bit-formats/CALLDEPTH.png)
### `L1GAS` (0x35)
Remaining "L1 gas" for this call (after this instruction).
@@ -1430,9 +1428,9 @@ Remaining "L1 gas" for this call (after this instruction).
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = LatestContext.l1Gas`
- **Tag updates**: `T[dstOffset] = u32`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/L1GAS.png)
+[![](./images/bit-formats/L1GAS.png)](./images/bit-formats/L1GAS.png)
### `L2GAS` (0x36)
Remaining "L2 gas" for this call (after this instruction).
@@ -1446,6 +1444,6 @@ Remaining "L2 gas" for this call (after this instruction).
- **dstOffset**: memory offset specifying where to store operation's result
- **Expression**: `M[dstOffset] = LatestContext.l2Gas`
- **Tag updates**: `T[dstOffset] = u32`
-- **Bit-size**: 40
+- **Bit-size**: 56
-![](./images/bit-formats/L2GAS.png)
+[![](./images/bit-formats/L2GAS.png)](./images/bit-formats/L2GAS.png)
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/ADD.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/ADD.png
index 4dd6dcc56b3..ee1a32d95b7 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/ADD.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/ADD.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/ADDRESS.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/ADDRESS.png
index 2c128e55cc3..4314acef2a1 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/ADDRESS.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/ADDRESS.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/AND.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/AND.png
index 28699de3959..9bfc38479f1 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/AND.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/AND.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKL1GASLIMIT.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKL1GASLIMIT.png
index f9cbd7a4b40..20f5ded9390 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKL1GASLIMIT.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKL1GASLIMIT.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKL2GASLIMIT.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKL2GASLIMIT.png
index 9e1160f7e36..f952f689f04 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKL2GASLIMIT.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKL2GASLIMIT.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKNUMBER.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKNUMBER.png
index 55de72ff390..c7217f8452a 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKNUMBER.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKNUMBER.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKSROOT.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKSROOT.png
index cb678fd654b..d844d63bb4f 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKSROOT.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/BLOCKSROOT.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/CALL.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/CALL.png
index c4a26fb27ef..a0170351666 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/CALL.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/CALL.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/CALLDATACOPY.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/CALLDATACOPY.png
index 305917efe37..133d86a37d9 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/CALLDATACOPY.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/CALLDATACOPY.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/CALLDEPTH.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/CALLDEPTH.png
index 382668bfe4a..1cca7c9e725 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/CALLDEPTH.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/CALLDEPTH.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/CALLER.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/CALLER.png
index a594244415a..dfb24671c96 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/CALLER.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/CALLER.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/CAST.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/CAST.png
index 529a236c900..d663c342ae7 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/CAST.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/CAST.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/CHAINID.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/CHAINID.png
index 2c468671c3f..d197552c9dc 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/CHAINID.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/CHAINID.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/CMOV.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/CMOV.png
index 7c1ac378dd3..a46692edd84 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/CMOV.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/CMOV.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/COINBASE.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/COINBASE.png
index f2e8eb1ff8e..72e2f88758d 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/COINBASE.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/COINBASE.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/CONTRACTSROOT.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/CONTRACTSROOT.png
index ddb3fc79680..47c6cb0f93c 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/CONTRACTSROOT.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/CONTRACTSROOT.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/DIV.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/DIV.png
index 2a30fad2d28..58fee0f6853 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/DIV.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/DIV.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/EMITNOTEHASH.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/EMITNOTEHASH.png
index 3f5f66fc40a..fd31987d317 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/EMITNOTEHASH.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/EMITNOTEHASH.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/EMITNULLIFIER.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/EMITNULLIFIER.png
index d6e841d1c03..50c4328012c 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/EMITNULLIFIER.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/EMITNULLIFIER.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/EQ.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/EQ.png
index 18bd16ed228..426d47621b0 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/EQ.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/EQ.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/FEEPERL1GAS.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/FEEPERL1GAS.png
index fde3846b150..428bb22433d 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/FEEPERL1GAS.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/FEEPERL1GAS.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/FEEPERL2GAS.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/FEEPERL2GAS.png
index d0c1443e816..db94bc190a3 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/FEEPERL2GAS.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/FEEPERL2GAS.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/GLOBALSHASH.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/GLOBALSHASH.png
index b1fd91771f0..0cea4cc32d0 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/GLOBALSHASH.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/GLOBALSHASH.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/GRANDROOT.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/GRANDROOT.png
index 13638898ac8..34d66c5a331 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/GRANDROOT.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/GRANDROOT.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/JUMP.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/JUMP.png
index d2048dc928c..9d9fd47b38b 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/JUMP.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/JUMP.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/JUMPI.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/JUMPI.png
index 1c03b6a42de..326a7971d4a 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/JUMPI.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/JUMPI.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/L1GAS.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/L1GAS.png
index 66a53c795e6..7ec775889c5 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/L1GAS.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/L1GAS.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/L2GAS.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/L2GAS.png
index 1b9668c46bd..fcf79de2f78 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/L2GAS.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/L2GAS.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/LT.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/LT.png
index f6fcdf112fa..59927272c47 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/LT.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/LT.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/LTE.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/LTE.png
index 1af3baea07c..1b0e35cf290 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/LTE.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/LTE.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/MOV.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/MOV.png
index 649465c7d04..4d79281a5e3 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/MOV.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/MOV.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/MSGSROOT.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/MSGSROOT.png
index 62aef1a1e30..d39c81f4564 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/MSGSROOT.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/MSGSROOT.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/NOT.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/NOT.png
index 05ddd512807..34907da432a 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/NOT.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/NOT.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/NOTESROOT.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/NOTESROOT.png
index 9753651fe35..4a8d6b3d9fd 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/NOTESROOT.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/NOTESROOT.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/NULLIFIERSROOT.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/NULLIFIERSROOT.png
index e8de85ffe1c..fc8d2cd1050 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/NULLIFIERSROOT.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/NULLIFIERSROOT.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/OR.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/OR.png
index ebc64c28a15..d796c0b5488 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/OR.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/OR.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/ORIGIN.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/ORIGIN.png
index bcedd1c0a56..f712ff96084 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/ORIGIN.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/ORIGIN.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/PORTAL.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/PORTAL.png
index 19957ac6c8e..2aa7a82f203 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/PORTAL.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/PORTAL.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/PUBLICDATAROOT.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/PUBLICDATAROOT.png
index 21a2fe9b538..44ddaf86bc2 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/PUBLICDATAROOT.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/PUBLICDATAROOT.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/REFUNDEE.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/REFUNDEE.png
index f4f89b595f6..70ccb4c1f5a 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/REFUNDEE.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/REFUNDEE.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/RETURN.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/RETURN.png
index c81b8566e8f..e1bf7d6a19d 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/RETURN.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/RETURN.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/REVERT.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/REVERT.png
index f8de1fe51b4..67c12bd2d06 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/REVERT.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/REVERT.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/SENDL2TOL1MSG.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/SENDL2TOL1MSG.png
index 0e0e529f3ab..04611cd6a43 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/SENDL2TOL1MSG.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/SENDL2TOL1MSG.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/SET.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/SET.png
index 90b07c3bcbe..9d68daa851d 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/SET.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/SET.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/SHL.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/SHL.png
index 78a1ca4e8e8..0c082bc62a6 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/SHL.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/SHL.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/SHR.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/SHR.png
index 0260c3e29e4..ed85ae15c1f 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/SHR.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/SHR.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/SLOAD.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/SLOAD.png
index edb4539d8ca..f9c6540667d 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/SLOAD.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/SLOAD.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/SSTORE.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/SSTORE.png
index efc6e0272ec..5580d4237a7 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/SSTORE.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/SSTORE.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/STATICCALL.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/STATICCALL.png
index 4c48dbd0eeb..e433c5063c3 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/STATICCALL.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/STATICCALL.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/SUB.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/SUB.png
index 1a58fee072d..e6157763289 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/SUB.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/SUB.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/TIMESTAMP.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/TIMESTAMP.png
index 2031f2f6306..8ac215faa81 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/TIMESTAMP.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/TIMESTAMP.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/ULOG.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/ULOG.png
index c0f17fdb67b..1c414f29b53 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/ULOG.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/ULOG.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/VERSION.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/VERSION.png
index 02b61144468..dc95ff9b5ca 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/VERSION.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/VERSION.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/bit-formats/XOR.png b/yellow-paper/docs/public-vm/gen/images/bit-formats/XOR.png
index 7fbb6381452..83610f677e9 100644
Binary files a/yellow-paper/docs/public-vm/gen/images/bit-formats/XOR.png and b/yellow-paper/docs/public-vm/gen/images/bit-formats/XOR.png differ
diff --git a/yellow-paper/docs/public-vm/gen/images/alu/alu.png b/yellow-paper/docs/public-vm/images/alu.png
similarity index 100%
rename from yellow-paper/docs/public-vm/gen/images/alu/alu.png
rename to yellow-paper/docs/public-vm/images/alu.png
diff --git a/yellow-paper/docs/public-vm/gen/images/control-flow/avm-control-flow.png b/yellow-paper/docs/public-vm/images/avm-control-flow.png
similarity index 100%
rename from yellow-paper/docs/public-vm/gen/images/control-flow/avm-control-flow.png
rename to yellow-paper/docs/public-vm/images/avm-control-flow.png
diff --git a/yellow-paper/docs/public-vm/gen/images/state-model/memory.png b/yellow-paper/docs/public-vm/images/memory.png
similarity index 100%
rename from yellow-paper/docs/public-vm/gen/images/state-model/memory.png
rename to yellow-paper/docs/public-vm/images/memory.png
diff --git a/yellow-paper/docs/public-vm/security.md b/yellow-paper/docs/public-vm/security.md
new file mode 100644
index 00000000000..1ebc179d1fd
--- /dev/null
+++ b/yellow-paper/docs/public-vm/security.md
@@ -0,0 +1,4 @@
+# VM threat model, security requirements
+
+An honest Prover must always be able to construct a satisfiable proof for an AVM program, even if the program throws an error.
+This implies constraints produced by the AVM **must** be satisfiable.
\ No newline at end of file
diff --git a/yellow-paper/docs/public-vm/state-model.md b/yellow-paper/docs/public-vm/state-model.md
index 615260cd686..cc92dc820da 100644
--- a/yellow-paper/docs/public-vm/state-model.md
+++ b/yellow-paper/docs/public-vm/state-model.md
@@ -1,12 +1,12 @@
-# The Aztec VM State Model
+# State Model
The goal of this note is to describe the VM state model and to specify "internal" VM abstractions that can be mapped to circuit designs.
-# A memory-only state model
+## A memory-only state model
The AVM possesses three distinct data regions, accessed via distinct VM instructions: memory, calldata and returndata
-![](./gen/images/state-model/memory.png)
+![](./images/memory.png)
All data regions are linear blocks of memory where each memory cell stores a finite field element.
@@ -45,61 +45,130 @@ Indirect memory addressing is required in order to support read/writes into dyna
Memory addresses must be tagged to be a `u32` type.
-# Tagged memory
+## Types and Tagged Memory
-We define a `tag` to refer to the potential maximum value of a cell of main memory. The following tags are supported:
+### Terminology/legend
+- `M[X]`: main memory cell at offset `X`
+- `tag`: a value referring to a memory cell's type (its maximum potential value)
+- `T[X]`: the tag associated with memory cell at offset `X`
+- `in-tag`: an instruction's tag to check input operands against. Present for many but not all instructions.
+- `dst-tag`: the target type of a `CAST` instruction, also used to tag the destination memory cell
+- `ADD`: shorthand for an `ADD` instruction with `in-tag = X`
+- `ADD aOffset bOffset dstOffset`: an full `ADD` instruction with `in-tag = X`. See [here](./InstructionSet#isa-section-add) for more details.
+- `CAST`: a `CAST` instruction with `dst-tag`: `X`. `CAST` is the only instruction with a `dst-tag`. See [here](./InstructionSet#isa-section-cast) for more details.
-| tag value | maximum memory cell value |
-| --------- | ------------------------- |
-| 0 | 0 |
-| 1 | $2^8 - 1$ |
-| 2 | $2^{16} - 1$ |
-| 3 | $2^{32} - 1$ |
-| 4 | $2^{64} - 1$ |
-| 5 | $2^{128} - 1$ |
-| 6 | $p - 1$ |
+### Tags and tagged memory
-Note: $p$ describes the modulus of the finite field that the AVM circuit is defined over (i.e. number of points on the BN254 curve).
+A `tag` refers to the maximum potential value of a cell of main memory. The following tags are supported:
-The purpose of a tag is to inform the VM of the maximum possible length of an operand value that has been loaded from memory.
+| tag value | maximum memory cell value | shorthand |
+| --------- | ------------------------- | ------------- |
+| 0 | 0 | uninitialized |
+| 1 | $2^8 - 1$ | `u8` |
+| 2 | $2^{16} - 1$ | `u16` |
+| 3 | $2^{32} - 1$ | `u32` |
+| 4 | $2^{64} - 1$ | `u64` |
+| 5 | $2^{128} - 1$ | `u128` |
+| 6 | $p - 1$ | `field` |
+| 7 | reserved | reserved |
-Multiple AVM instructions explicitly operate over range-constrained input parameters (e.g. ADD32). The maximum allowable value for an instruction's input parameters is defined via an _instruction tag_. Two potential scenarios result:
+> Note: $p$ describes the modulus of the finite field that the AVM circuit is defined over (i.e. number of points on the BN254 curve).
+> Note: `u32` is used for offsets into the VM's 32-bit addressable main memory
-1. A VM instruction's tag value matches the input parameter tag values
-2. A VM instruction's tag value does not match the input parameter tag values
+The purpose of a tag is to inform the VM of the maximum possible length of an operand value that has been loaded from memory.
-If case 2 is triggered, an error flag is raised.
+#### Checking input operand tags
----
+Many AVM instructions explicitly operate over range-constrained input parameters (e.g. `ADD`). The maximum allowable value for an instruction's input parameters is defined via an `in-tag` (instruction/input tag). Two potential scenarios result:
-### Writing into memory
+1. A VM instruction's tag value matches the input parameter tag values
+2. A VM instruction's tag value does _not_ match the input parameter tag values
-It is required that all VM instructions that write into main memory explicitly define the tag of the output value and ensure the value is appropriately constrained to be consistent with the assigned tag.
+If case 2 is triggered, an error flag is raised and the current call's execution reverts.
----
+#### Writing into memory
-### MOV and tag conversions
+It is required that all VM instructions that write into main memory explicitly define the tag of the destination value and ensure the value is appropriately constrained to be consistent with the assigned tag. You can see an instruction's "**Tag updates**" in its section of the instruction set document (see [here for `ADD`](./InstructionSet#isa-section-add) and [here for `CAST`](./InstructionSet#isa-section-cast)).
-The MOV instruction copies data from between memory cell, perserving tags.
+#### Standard tagging example: `ADD`
-The only VM instruction that can be used to cast between tags is CAST. There are 2 modes to MOV:
+```
+# ADD aOffset bOffset dstOffset
+assert T[aOffset] == T[bOffset] == u32 // check inputs against in-tag, revert on mismatch
+T[dstOffset] = u32 // tag destination with in-tag
+M[dstOffset] = M[aOffset] + M[bOffset] // perform the addition
+```
-1. The destination tag describes a maximum value that is _less than_ the source tag
-2. The destination tag describes a maximum value that is _greater than or equal to_ the source tag
+#### `MOV` and tag preservation
-For Case 1, range constraints must be applied to ensure the destination value is consistent with the source value after tag truncations have been applied.
-
-Case 2 is trivial as no additional consistency checks must be performed between soruce and destination values.
+The `MOV` instruction copies data from one memory cell to another, preserving tags. In other words, the destination cell's tag will adopt the value of the source:
+```
+# MOV srcOffset dstOffset
+T[dstOffset] = T[srcOffset] // preserve tag
+M[dstOffset] = M[srcOffset] // perform the move
+```
----
+Note that `MOV` does not have an `in-tag` and therefore does not need to make any assertions regarding the source memory cell's type.
-### Calldata/returndata and tag conversions
+#### `CAST` and tag conversions
-All elements in calldata/returndata are implicitly tagged as field elements (i.e. maximum value is $p - 1$). To perform a tag conversion, calldata/returndata must be copied into main memory, followed by an appropriate MOV instruction.
+The only VM instruction that can be used to cast between tags is `CAST`. Two potential scenarios result:
-## VM threat model, security requirements
+1. The destination tag describes a maximum value that is _less than_ the source tag
+2. The destination tag describes a maximum value that is _greater than or equal to_ the source tag
-TODO: move this somewhere else, doesn't quite fit.
+For Case 1, range constraints must be applied to ensure the destination value is consistent with the source value after tag truncations have been applied.
-An honest Prover must always be able to construct a satsisfiable proof for an AVM program, even if the program throws an error.
-This implies constraints produced by the AVM **must** be satisfiable.
+Case 2 is trivial as no additional consistency checks must be performed between source and destination values.
+
+```
+# CAST srcOffset dstOffset
+T[dstOffset] = u64 // tag destination with dst-tag
+M[dstOffset] = cast(M[srcOffset]) // perform cast
+```
+
+#### Indirect `MOV` and extra tag checks
+
+A `MOV` instruction may flag its source and/or destination offsets as "indirect". An indirect memory access performs `M[M[offset]]` instead of the standard `M[offset]`. Memory offsets must be `u32`s since main memory is a 32-bit addressable space, and so indirect memory accesses include additional checks.
+
+Additional checks for a `MOV` with an indirect source offset:
+```
+# MOV srcOffset dstOffset // with indirect source
+assert T[srcOffset] == u32 // enforce that `M[srcOffset]` is itself a valid memory offset
+T[dstOffset] = T[T[srcOffset]] // tag destination to match indirect source tag
+M[dstOffset] = M[M[srcOffset]] // perform move from indirect source
+```
+
+Additional checks for a `MOV` with an indirect destination offset:
+```
+# MOV srcOffset dstOffset // with indirect destination
+assert T[dstOffset] == u32 // enforce that `M[dstOffset]` is itself a valid memory offset
+T[T[dstOffset]] = T[srcOffset] // tag indirect destination to match source tag
+M[M[dstOffset]] = M[srcOffset] // perform move to indirect destination
+```
+
+Additional checks for a `MOV` with both indirect source and destination offsets:
+```
+# MOV srcOffset dstOffset // with indirect source and destination
+assert T[srcOffset] == T[dstOffset] == u32 // enforce that `M[*Offset]` are valid memory offsets
+T[T[dstOffset]] = T[T[srcOffset]] // tag indirect destination to match indirect source tag
+M[M[dstOffset]] = M[M[srcOffset]] // perform move to indirect destination
+```
+
+#### Calldata/returndata and tag conversions
+
+All elements in calldata/returndata are implicitly tagged as field elements (i.e. maximum value is $p - 1$). To perform a tag conversion, calldata/returndata must be copied into main memory (via [`CALLDATACOPY`](./InstructionSet#isa-section-calldatacopy) or [`RETURN`'s `offset` and `size`](./InstructionSet#isa-section-return)), followed by an appropriate `CAST` instruction.
+```
+# Copy calldata to memory and cast a word to u64
+CALLDATACOPY cdOffset size offsetA // copy calldata to memory at offsetA
+CAST offsetA dstOffset // cast first copied word to a u64
+```
+This would perform the following:
+```
+# CALLDATACOPY cdOffset size offsetA
+T[offsetA:offsetA+size] = field // CALLDATACOPY assigns the field tag
+M[offsetA:offsetA+size] = calldata[cdOffset:cdOffset+size] // copy calldata to memory
+# CAST offsetA dstOffset
+T[offsetA] = u64 // CAST assigns a new tag
+M[dstOffset] = cast(offsetA) // perform the cast operation
+```
\ No newline at end of file
diff --git a/yellow-paper/docs/public-vm/tagged-memory.md b/yellow-paper/docs/public-vm/tagged-memory.md
deleted file mode 100644
index a72c693da93..00000000000
--- a/yellow-paper/docs/public-vm/tagged-memory.md
+++ /dev/null
@@ -1,60 +0,0 @@
-# Tagged Memory - An instruction-set centric explanation
-
-## Explanation of Tagged Memory
-Every word in memory will have an associated `type-tag` (unset, u8, u16, u32, u64, u128, field). For memory address `a`, we refer to the corresponding memory word's `type-tag` as `T[a]`.
-
-Every instruction will be flagged with an `op-type` in bytecode (u8, u16, u32, u64, u128, field).
-
-If an instruction uses a "source operand" as a memory location (e.g. `z = M[s0] + y`), the VM first retrieves the `type-tag` referenced by the operand (`T[s0]`) and enforces that it matches `op-type`. The VM enforces this for all source operands used for direct memory reads.
-
-If an instruction uses a "dest operand" as a memory location (e.g. `M[d0] = x + y`), when the VM assigns a word to that memory location, it also assigns the corresponding `type-tag` (`T[d0] = op-type`). The VM performs this tag assignment for all dest operands used for direct memory writes.
-
-**If an instruction fails any of its operand type-tag-checks, the current call's execution reverts!**
-
-### `ADD<32>` example
-`ADD<32>` is an `ADD` instruction with `op-type` u32. As elaborated on later, an `ADD` performs `M[d0] = M[s0] + M[s1]`. In this case, both `s0` and `s1` are "source operands" used for direct memory reads to retrieve inputs to an addition. So, the VM enforces the `op-type(u32) == T[s0] == T[s1]`. `d0` here is a "dest operand" used for a direct memory write to store the output of the addition. So, the VM tags memory location `d0` with `type-tag` of u32: `T[d0] = op-type(u32)`.
-
-Here is a summary of what is happening for `ADD<32>`:
-```
-assert T[s0] == u32 // enforce that source memory locations' type-tags == op-type
-assert T[s1] == u32
-T[d0] = u32 // tag destination memory location as op-type
-M[d0] = M[s0] + M[s1]
-```
-
-
-### Type tags and `CASTs`
-
-`CAST` is different from other instructions in that it will be flagged with an additional `dest-type`. So, a `CAST` will assign `dest-type` (instead of `op-type`) to the memory location specified by its "dest operand" `d0`. `CAST<32, 64>` enforces that `T[s0]` matches u32 (the `op-type`) and assigns `T[d0] = u64` (the `dest-type`).
-
-Here is a summary of what is happening for a `CAST<32, 64>`:
-```
-assert T[s0] == u32 // enforce that source memory location's type-tags == op-type
-T[d0] = u64 // tag destination memory location as dest-type
-M[d0] = M[s0]
-```
-
-### Type tags and indirect `MOVs`
-A basic `MOV` instruction performs direct memory accesses and operates in the same as a simple `ADD` instruction as outlined above. A simple `MOV<64>` would do:
-```
-assert T[s0] == u64 // enforce that source memory location's type-tag == op-type
-T[d0] = u64 // tag destination memory location with op-type
-M[d0] = M[s0]
-```
-
-Consider a `MOV<64, s0-indirect>`, which treats s0 as an indirect memory pointer to perform `M[d0] = M[M[s0]]`. Here, the VM first needs to enforce that `M[s0]` is a valid memory address (has type u32), and it then needs to perform the standard check that resulting word has type matching `op-type`:
-```
-assert T[s0] == u32 // enforce that the direct source memory location contains a valid address (type-tag == u32)
-assert T[M[s0]] == u64 // enforce that the indirect source memory location's type-tag == op-type
-T[d0] = u64 // tag destination memory location with op-type
-M[d0] = M[M[s0]]
-```
-
-Similarly, a `MOV<64, d0-indirect>` treats d0 as an indirect memory pointer to perform `M[M[d0]] = M[s0]`, and here the VM first needs to enforce that `M[d0]` is a valid memory address (has type u32) before assigning the destination location its type tag:
-```
-assert T[s0] == u64 // enforce that source memory location's type-tag == op-type
-assert T[d0] == u32 // enforce that the direct destination memory location contains a valid address (type-tag == u32)
-T[M[d0]] = u64 // tag indirect destination memory location with op-type
-M[M[d0]] = M[s0]
-```
-
diff --git a/yellow-paper/src/preprocess/InstructionSet/InstructionSet.js b/yellow-paper/src/preprocess/InstructionSet/InstructionSet.js
index 6da9d78749c..844a89c369b 100644
--- a/yellow-paper/src/preprocess/InstructionSet/InstructionSet.js
+++ b/yellow-paper/src/preprocess/InstructionSet/InstructionSet.js
@@ -7,8 +7,8 @@ const TOPICS_IN_SECTIONS = [
"Name", "Summary", "Category", "Flags", "Args", "Expression", "Details", "Tag checks", "Tag updates", "Bit-size",
];
-const OP_TYPE_DESCRIPTION = "The [type/size](./Types) to check inputs against and tag the output with.";
-const DEST_TYPE_DESCRIPTION = "The [type/size](./Types) to tag the output with when different from `op-type`.";
+const IN_TAG_DESCRIPTION = "The [tag/size](./state-model#tags-and-tagged-memory) to check inputs against and tag the destination with.";
+const DST_TAG_DESCRIPTION = "The [tag/size](./state-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. 0th 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 INSTRUCTION_SET_RAW = [
@@ -18,7 +18,7 @@ const INSTRUCTION_SET_RAW = [
"Category": "arithmetic",
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
- {"name": "op-type", "description": OP_TYPE_DESCRIPTION},
+ {"name": "in-tag", "description": IN_TAG_DESCRIPTION},
],
"#memreads": "2",
"#memwrites": "1",
@@ -30,8 +30,8 @@ const INSTRUCTION_SET_RAW = [
"Expression": "`M[dstOffset] = M[aOffset] + M[bOffset] mod 2^k`",
"Summary": "Addition (a + b)",
"Details": "",
- "Tag checks": "`T[aOffset] == T[bOffset] == op-type`",
- "Tag updates": "`T[dstOffset] = op-type`",
+ "Tag checks": "`T[aOffset] == T[bOffset] == in-tag`",
+ "Tag updates": "`T[dstOffset] = in-tag`",
},
{
"id": "sub",
@@ -39,7 +39,7 @@ const INSTRUCTION_SET_RAW = [
"Category": "arithmetic",
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
- {"name": "op-type", "description": OP_TYPE_DESCRIPTION},
+ {"name": "in-tag", "description": IN_TAG_DESCRIPTION},
],
"#memreads": "2",
"#memwrites": "1",
@@ -51,8 +51,8 @@ const INSTRUCTION_SET_RAW = [
"Expression": "`M[dstOffset] = M[aOffset] - M[bOffset] mod 2^k`",
"Summary": "Subtraction (a - b)",
"Details": "",
- "Tag checks": "`T[aOffset] == T[bOffset] == op-type`",
- "Tag updates": "`T[dstOffset] = op-type`",
+ "Tag checks": "`T[aOffset] == T[bOffset] == in-tag`",
+ "Tag updates": "`T[dstOffset] = in-tag`",
},
{
"id": "div",
@@ -60,7 +60,7 @@ const INSTRUCTION_SET_RAW = [
"Category": "arithmetic",
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
- {"name": "op-type", "description": OP_TYPE_DESCRIPTION},
+ {"name": "in-tag", "description": IN_TAG_DESCRIPTION},
],
"#memreads": "2",
"#memwrites": "1",
@@ -72,8 +72,8 @@ const INSTRUCTION_SET_RAW = [
"Expression": "`M[dstOffset] = M[aOffset] / M[bOffset]`",
"Summary": "Unsigned division (a / b)",
"Details": "",
- "Tag checks": "`T[aOffset] == T[bOffset] == op-type`",
- "Tag updates": "`T[dstOffset] = op-type`",
+ "Tag checks": "`T[aOffset] == T[bOffset] == in-tag`",
+ "Tag updates": "`T[dstOffset] = in-tag`",
},
{
"id": "eq",
@@ -81,7 +81,7 @@ const INSTRUCTION_SET_RAW = [
"Category": "conditional",
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
- {"name": "op-type", "description": OP_TYPE_DESCRIPTION},
+ {"name": "in-tag", "description": IN_TAG_DESCRIPTION},
],
"#memreads": "2",
"#memwrites": "1",
@@ -93,8 +93,8 @@ const INSTRUCTION_SET_RAW = [
"Expression": "`M[dstOffset] = M[aOffset] == M[bOffset] ? 1 : 0`",
"Summary": "Equality check (a == b)",
"Details": "",
- "Tag checks": "`T[aOffset] == T[bOffset] == op-type`",
- "Tag updates": "`T[dstOffset] = op-type`",
+ "Tag checks": "`T[aOffset] == T[bOffset] == in-tag`",
+ "Tag updates": "`T[dstOffset] = in-tag`",
},
{
"id": "lt",
@@ -102,7 +102,7 @@ const INSTRUCTION_SET_RAW = [
"Category": "conditional",
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
- {"name": "op-type", "description": OP_TYPE_DESCRIPTION},
+ {"name": "in-tag", "description": IN_TAG_DESCRIPTION},
],
"#memreads": "2",
"#memwrites": "1",
@@ -114,8 +114,8 @@ const INSTRUCTION_SET_RAW = [
"Expression": "`M[dstOffset] = M[aOffset] < M[bOffset] ? 1 : 0`",
"Summary": "Less-than check (a < b)",
"Details": "",
- "Tag checks": "`T[aOffset] == T[bOffset] == op-type`",
- "Tag updates": "`T[dstOffset] = op-type`",
+ "Tag checks": "`T[aOffset] == T[bOffset] == in-tag`",
+ "Tag updates": "`T[dstOffset] = in-tag`",
},
{
"id": "lte",
@@ -123,7 +123,7 @@ const INSTRUCTION_SET_RAW = [
"Category": "conditional",
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
- {"name": "op-type", "description": OP_TYPE_DESCRIPTION},
+ {"name": "in-tag", "description": IN_TAG_DESCRIPTION},
],
"#memreads": "2",
"#memwrites": "1",
@@ -135,8 +135,8 @@ const INSTRUCTION_SET_RAW = [
"Expression": "`M[dstOffset] = M[aOffset] <= M[bOffset] ? 1 : 0`",
"Summary": "Less-than-or-equals check (a <= b)",
"Details": "",
- "Tag checks": "`T[aOffset] == T[bOffset] == op-type`",
- "Tag updates": "`T[dstOffset] = op-type`",
+ "Tag checks": "`T[aOffset] == T[bOffset] == in-tag`",
+ "Tag updates": "`T[dstOffset] = in-tag`",
},
{
"id": "and",
@@ -144,7 +144,7 @@ const INSTRUCTION_SET_RAW = [
"Category": "bitwise",
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
- {"name": "op-type", "description": OP_TYPE_DESCRIPTION},
+ {"name": "in-tag", "description": IN_TAG_DESCRIPTION},
],
"#memreads": "2",
"#memwrites": "1",
@@ -156,8 +156,8 @@ const INSTRUCTION_SET_RAW = [
"Expression": "`M[dstOffset] = M[aOffset] AND M[bOffset]`",
"Summary": "Bitwise AND (a & b)",
"Details": "",
- "Tag checks": "`T[aOffset] == T[bOffset] == op-type`",
- "Tag updates": "`T[dstOffset] = op-type`",
+ "Tag checks": "`T[aOffset] == T[bOffset] == in-tag`",
+ "Tag updates": "`T[dstOffset] = in-tag`",
},
{
"id": "or",
@@ -165,7 +165,7 @@ const INSTRUCTION_SET_RAW = [
"Category": "bitwise",
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
- {"name": "op-type", "description": OP_TYPE_DESCRIPTION},
+ {"name": "in-tag", "description": IN_TAG_DESCRIPTION},
],
"#memreads": "2",
"#memwrites": "1",
@@ -177,8 +177,8 @@ const INSTRUCTION_SET_RAW = [
"Expression": "`M[dstOffset] = M[aOffset] OR M[bOffset]`",
"Summary": "Bitwise OR (a | b)",
"Details": "",
- "Tag checks": "`T[aOffset] == T[bOffset] == op-type`",
- "Tag updates": "`T[dstOffset] = op-type`",
+ "Tag checks": "`T[aOffset] == T[bOffset] == in-tag`",
+ "Tag updates": "`T[dstOffset] = in-tag`",
},
{
"id": "xor",
@@ -186,7 +186,7 @@ const INSTRUCTION_SET_RAW = [
"Category": "bitwise",
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
- {"name": "op-type", "description": OP_TYPE_DESCRIPTION},
+ {"name": "in-tag", "description": IN_TAG_DESCRIPTION},
],
"#memreads": "2",
"#memwrites": "1",
@@ -198,8 +198,8 @@ const INSTRUCTION_SET_RAW = [
"Expression": "`M[dstOffset] = M[aOffset] XOR M[bOffset]`",
"Summary": "Bitwise XOR (a ^ b)",
"Details": "",
- "Tag checks": "`T[aOffset] == T[bOffset] == op-type`",
- "Tag updates": "`T[dstOffset] = op-type`",
+ "Tag checks": "`T[aOffset] == T[bOffset] == in-tag`",
+ "Tag updates": "`T[dstOffset] = in-tag`",
},
{
"id": "not",
@@ -207,7 +207,7 @@ const INSTRUCTION_SET_RAW = [
"Category": "bitwise",
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
- {"name": "op-type", "description": OP_TYPE_DESCRIPTION},
+ {"name": "in-tag", "description": IN_TAG_DESCRIPTION},
],
"#memreads": "1",
"#memwrites": "1",
@@ -218,8 +218,8 @@ const INSTRUCTION_SET_RAW = [
"Expression": "`M[dstOffset] = NOT M[aOffset]`",
"Summary": "Bitwise NOT (inversion)",
"Details": "",
- "Tag checks": "`T[aOffset] == op-type`",
- "Tag updates": "`T[dstOffset] = op-type`",
+ "Tag checks": "`T[aOffset] == in-tag`",
+ "Tag updates": "`T[dstOffset] = in-tag`",
},
{
"id": "shl",
@@ -227,7 +227,7 @@ const INSTRUCTION_SET_RAW = [
"Category": "bitwise",
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
- {"name": "op-type", "description": OP_TYPE_DESCRIPTION},
+ {"name": "in-tag", "description": IN_TAG_DESCRIPTION},
],
"#memreads": "2",
"#memwrites": "1",
@@ -239,8 +239,8 @@ const INSTRUCTION_SET_RAW = [
"Expression": "`M[dstOffset] = M[aOffset] << M[bOffset]`",
"Summary": "Bitwise leftward shift (a << b)",
"Details": "",
- "Tag checks": "`T[aOffset] == T[bOffset] == op-type`",
- "Tag updates": "`T[dstOffset] = op-type`",
+ "Tag checks": "`T[aOffset] == T[bOffset] == in-tag`",
+ "Tag updates": "`T[dstOffset] = in-tag`",
},
{
"id": "shr",
@@ -248,7 +248,7 @@ const INSTRUCTION_SET_RAW = [
"Category": "bitwise",
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
- {"name": "op-type", "description": OP_TYPE_DESCRIPTION},
+ {"name": "in-tag", "description": IN_TAG_DESCRIPTION},
],
"#memreads": "2",
"#memwrites": "1",
@@ -260,8 +260,8 @@ const INSTRUCTION_SET_RAW = [
"Expression": "`M[dstOffset] = M[aOffset] >> M[bOffset]`",
"Summary": "Bitwise rightward shift (a >> b)",
"Details": "",
- "Tag checks": "`T[aOffset] == T[bOffset] == op-type`",
- "Tag updates": "`T[dstOffset] = op-type`",
+ "Tag checks": "`T[aOffset] == T[bOffset] == in-tag`",
+ "Tag updates": "`T[dstOffset] = in-tag`",
},
{
"id": "cast",
@@ -269,7 +269,7 @@ const INSTRUCTION_SET_RAW = [
"Category": "types",
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
- {"name": "dest-type", "description": DEST_TYPE_DESCRIPTION},
+ {"name": "dst-tag", "description": DST_TAG_DESCRIPTION},
],
"#memreads": "1",
"#memwrites": "1",
@@ -277,11 +277,11 @@ const INSTRUCTION_SET_RAW = [
{"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])`",
+ "Expression": "`M[dstOffset] = cast(M[aOffset])`",
"Summary": "Type cast",
- "Details": "Cast a word in memory based on the `dest-type` specified in the bytecode. Truncates when casting to a smaller type, left-zero-pads when casting to a larger type.",
+ "Details": "Cast a word in memory based on the `dst-tag` specified in the bytecode. Truncates when casting to a smaller type, left-zero-pads when casting to a larger type. See [here](./state-model#cast-and-tag-conversions) for more details.",
"Tag checks": "",
- "Tag updates": "`T[dstOffset] = dest-type`",
+ "Tag updates": "`T[dstOffset] = dst-tag`",
},
{
"id": "set",
@@ -289,7 +289,7 @@ const INSTRUCTION_SET_RAW = [
"Category": "memory",
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
- {"name": "op-type", "description": "The [type/size](./Types) to check inputs against and tag the output with. `field` type is NOT supported for SET."},
+ {"name": "in-tag", "description": "The [type/size](./state-model#tags-and-tagged-memory) to check inputs against and tag the destination with. `field` type is NOT supported for SET."},
],
"#memreads": "0",
"#memwrites": "1",
@@ -299,9 +299,9 @@ const INSTRUCTION_SET_RAW = [
],
"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 `op-type`. It _cannot be 254 (`field` type)_!",
+ "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 `in-tag`. It _cannot be 254 (`field` type)_!",
"Tag checks": "",
- "Tag updates": "`T[dstOffset] = op-type`",
+ "Tag updates": "`T[dstOffset] = in-tag`",
},
{
"id": "mov",
@@ -354,14 +354,14 @@ const INSTRUCTION_SET_RAW = [
"#memwrites": "`s1`",
"Args": [
{"name": "cdOffset", "description": "offset into calldata to copy from"},
- {"name": "size", "description": "number of words to copy", "mode": "immediate", "type": "u24"},
+ {"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+size] = calldata[cdOffset:cdOffset+size]`",
+ "Expression": "`M[dstOffset:dstOffset+copySize] = 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+size] = field`",
+ "Tag updates": "`T[dstOffset:dstOffset+copySize] = field`",
},
{
"id": "sload",
@@ -463,7 +463,7 @@ const INSTRUCTION_SET_RAW = [
"#memreads": "0",
"#memwrites": "0",
"Args": [
- {"name": "loc", "description": "target location to jump to", "mode": "immediate", "type": "u24"},
+ {"name": "loc", "description": "target location to jump to", "mode": "immediate", "type": "u32"},
],
"Expression": "`PC = loc`",
"Summary": "Jump to a location in the bytecode.",
@@ -481,7 +481,7 @@ const INSTRUCTION_SET_RAW = [
"#memreads": "3",
"#memwrites": "0",
"Args": [
- {"name": "loc", "description": "target location conditionally jump to", "mode": "immediate", "type": "u24"},
+ {"name": "loc", "description": "target location conditionally jump to", "mode": "immediate", "type": "u32"},
{"name": "condOffset", "description": "memory offset of the operations 'conditional' input"},
],
"Expression": "`PC = M[condOffset] > 0 ? loc : PC`",
@@ -500,10 +500,10 @@ const INSTRUCTION_SET_RAW = [
"#memreads": "`s1`",
"#memwrites": "0",
"Args": [
- {"name": "offset", "description": "memory offset of first word to return"},
- {"name": "size", "description": "number of words to return", "mode": "immediate", "type": "u24"},
+ {"name": "retOffset", "description": "memory offset of first word to return"},
+ {"name": "retSize", "description": "number of words to return", "mode": "immediate", "type": "u32"},
],
- "Expression": "`return(M[offset:offset+size])`",
+ "Expression": "`return(M[retOffset:retOffset+retSize])`",
"Summary": "Halt execution with `success`, optionally returning some data.",
"Details": "Return control flow to the calling context/contract.",
"Tag checks": "",
@@ -519,10 +519,10 @@ const INSTRUCTION_SET_RAW = [
"#memreads": "`s1`",
"#memwrites": "0",
"Args": [
- {"name": "offset", "description": "memory offset of first word to return"},
- {"name": "size", "description": "number of words to return", "mode": "immediate", "type": "u24"},
+ {"name": "retOffset", "description": "memory offset of first word to return"},
+ {"name": "retSize", "description": "number of words to return", "mode": "immediate", "type": "u32"},
],
- "Expression": "`revert(M[offset:offset+size])`",
+ "Expression": "`revert(M[retOffset:retOffset+retSize])`",
"Summary": "Halt execution with `failure`, reverting state changes and optionally returning some data.",
"Details": "Return control flow to the calling context/contract.",
"Tag checks": "",
@@ -535,21 +535,20 @@ const INSTRUCTION_SET_RAW = [
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
],
- "#memreads": "5",
+ "#memreads": "7",
"#memwrites": "`1+retSize`",
"Args": [
- {"name": "l1GasOffset", "description": "amount of L1 gas to provide to the callee"},
- {"name": "l2GasOffset", "description": "amount of L2 gas to provide to the callee"},
+ {"name": "gasOffset", "description": "offset to two words containing `{l1Gas, l2Gas}`: amount of L1 and L2 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": "u24"},
+ {"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": "u24"},
+ {"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"},
],
"Expression":`
M[successOffset] = call(
- M[l1GasOffset], M[l2GasOffset], M[addrOffset],
+ M[gasOffset], M[gasOffset+1], M[addrOffset],
M[argsOffset], M[argsSize],
M[retOffset], M[retSize])
`,
@@ -557,7 +556,7 @@ M[successOffset] = call(
"Details": `Creates a new CallContext, triggers execution of the corresponding contract code,
and then resumes execution in the current CallContext. A non-existent contract or one
with no code will return success. Nested call has an incremented \`CallContext.calldepth\`.`,
- "Tag checks": "`T[l1GasOffset] == T[l2GasOffset] == u32`",
+ "Tag checks": "`T[gasOffset] == T[gasOffset+1] == u32`",
"Tag updates": `
T[successOffset] = u8
T[retOffset:retOffset+retSize] = field
@@ -570,27 +569,26 @@ T[retOffset:retOffset+retSize] = field
"Flags": [
{"name": "indirect", "description": INDIRECT_FLAG_DESCRIPTION},
],
- "#memreads": "5",
+ "#memreads": "7",
"#memwrites": "`1+retSize`",
"Args": [
- {"name": "l1GasOffset", "description": "amount of L1 gas to provide to the callee"},
- {"name": "l2GasOffset", "description": "amount of L2 gas to provide to the callee"},
+ {"name": "gasOffset", "description": "offset to two words containing `{l1Gas, l2Gas}`: amount of L1 and L2 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": "u24"},
+ {"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": "u24"},
+ {"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"},
],
"Expression": `
M[successOffset] = staticcall(
- M[l1GasOffset], M[l2GasOffset], M[addrOffset],
+ M[gasOffset], M[gasOffset+1], M[addrOffset],
M[argsOffset], M[argsSize],
M[retOffset], M[retSize])
`,
"Summary": "Call into another contract, disallowing persistent state modifications.",
"Details": "Same as `CALL`, but the callee is cannot modify persistent state. Disallowed instructions are `SSTORE`, `ULOG`, `CALL`.",
- "Tag checks": "`T[l1GasOffset] == T[l2GasOffset] == u32`",
+ "Tag checks": "`T[gasOffset] == T[gasOffset+1] == u32`",
"Tag updates": `
T[successOffset] = u8
T[retOffset:retOffset+retSize] = field
@@ -606,10 +604,10 @@ T[retOffset:retOffset+retSize] = field
"#memreads": "`s1`",
"#memwrites": "0",
"Args": [
- {"name": "offset", "description": "memory offset of the data to log"},
- {"name": "size", "description": "number of words to log", "mode": "immediate", "type": "u24"},
+ {"name": "logOffset", "description": "memory offset of the data to log"},
+ {"name": "logSize", "description": "number of words to log", "mode": "immediate", "type": "u32"},
],
- "Expression": "`ulog(M[offset:offset+size])`",
+ "Expression": "`ulog(M[logOffset:logOffset+logSize])`",
"Summary": "Emit an unencrypted log with data from the `field` memory page",
"Details": "",
"Tag checks": "",
diff --git a/yellow-paper/src/preprocess/InstructionSet/InstructionSize.js b/yellow-paper/src/preprocess/InstructionSet/InstructionSize.js
index 0cefffcf327..f6cac342791 100644
--- a/yellow-paper/src/preprocess/InstructionSet/InstructionSize.js
+++ b/yellow-paper/src/preprocess/InstructionSet/InstructionSize.js
@@ -1,7 +1,8 @@
const OPCODE_SIZE = 8;
const FLAG_SIZE = 8;
+const RESERVED_SIZE = 8;
-const DEFAULT_OPERAND_SIZE = 24; // for direct/indirect memory offsets
+const DEFAULT_OPERAND_SIZE = 32; // for direct/indirect memory offsets
function argSize(arg) {
if (arg['mode'] && arg['mode'] == 'immediate') {
@@ -31,7 +32,7 @@ function toOpcode(index) {
* 1 byte for dest-type
*/
function instructionSize(instr) {
- let size = OPCODE_SIZE;
+ let size = OPCODE_SIZE + RESERVED_SIZE;
let numUntypedImmediates = 0;
for (let arg of instr['Args']) {
const aSize = argSize(arg);
@@ -59,6 +60,9 @@ function instructionBitFormat(instr, index) {
'code': toOpcode(index),
'size': OPCODE_SIZE,
},
+ 'Reserved': {
+ 'size': RESERVED_SIZE,
+ },
'Args': [],
'Flags': [],
};
diff --git a/yellow-paper/src/preprocess/InstructionSet/genBitFormats.js b/yellow-paper/src/preprocess/InstructionSet/genBitFormats.js
index 99bdc4c34f8..c406f70a85e 100644
--- a/yellow-paper/src/preprocess/InstructionSet/genBitFormats.js
+++ b/yellow-paper/src/preprocess/InstructionSet/genBitFormats.js
@@ -10,6 +10,7 @@ function run() {
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/yellow-paper/src/preprocess/InstructionSet/InstructionSetMarkdownGen.js b/yellow-paper/src/preprocess/InstructionSet/genMarkdown.js
similarity index 96%
rename from yellow-paper/src/preprocess/InstructionSet/InstructionSetMarkdownGen.js
rename to yellow-paper/src/preprocess/InstructionSet/genMarkdown.js
index b9a689749cd..e26940ef03f 100644
--- a/yellow-paper/src/preprocess/InstructionSet/InstructionSetMarkdownGen.js
+++ b/yellow-paper/src/preprocess/InstructionSet/genMarkdown.js
@@ -19,7 +19,7 @@ function stripBraces(str) {
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 InstructionSetMarkdownGen.tsx and InstructionSet.js)\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;
@@ -106,7 +106,7 @@ function markdownInstructionSetSection(pathToGenDir) {
}
const bitFormatPath = `./images/bit-formats/${name.replace(/`/g, '')}.png`;
if (fs.existsSync(`${pathToGenDir}/${bitFormatPath}`)) {
- subsection += `\n![](${bitFormatPath})`;
+ subsection += `\n[![](${bitFormatPath})](${bitFormatPath})`;
}
markdown += `\n${subsection}\n`;
}
diff --git a/yellow-paper/src/preprocess/index.js b/yellow-paper/src/preprocess/index.js
index 71c4227df06..fe2167bdf09 100644
--- a/yellow-paper/src/preprocess/index.js
+++ b/yellow-paper/src/preprocess/index.js
@@ -1,4 +1,4 @@
-const {generateInstructionSet} = require('./InstructionSet/InstructionSetMarkdownGen');
+const {generateInstructionSet} = require('./InstructionSet/genMarkdown');
async function run() {
await generateInstructionSet();