Stack input
offset: offset in the memory in bytes.
value: 1-byte value to write in the memory (the least significant byte of the 32-byte stack value).

Reproduce in playground.

Error cases
The state changes done by the current context are reverted in those cases:

Not enough gas.
Not enough values on the stack.
Gas
static_gas = 3
dynamic_gas = memory_expansion_cost
The memory expansion cost explanation can be found here.

Feature Request

Describe the Feature Request

Implement the serie of SWAPX Swap Operations.

Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

Notes

All values are treated as two’s complement signed 256-bit integers. Note the overflow semantic when −2255 is negated.

Stack input

a: integer numerator.
b: integer denominator.

Stack output

a % b: integer result of the signed integer modulo. If the denominator is 0, the result will be 0.

Examples

Input Output
1 10 1
2 3
Input Output
1 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF8 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFE
2 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD
Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

SINCE GROUP
Frontier Stop and Arithmetic Operations
Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

SINCE GROUP Frontier Stop and Arithmetic Operations Index 1 is top of the stack. See PUSH.

Notes

All values are treated as two’s complement signed 256-bit integers. Note the overflow semantic when −2255 is negated.

Stack input

a: integer. b: integer. c: integer.

Stack output

a + b % c: integer result of the addition integer modulo.

Examples

Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

Since

Frontier

Group

Environmental Information

Description

0x3a - GASPRICE: Get price of gas in current environment

Index 1 is top of the stack. See PUSH.

Stack output

1. price: gas price in wei per gas.

Example

Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Stack overflow.

Possible implementation

Rename the intrinsic_gas_cost field of the ExecutionContext to gas_price. This value is constant and should not have any helper to update it.

Update compute_intrinsic_gas_cost to compute the true intrinsic gas cost using the call_context.calldata.

The intrinsic gas cost is 21,000 per transaction plus the cost of input data (16 gas per non-zero byte and 4 gas per zero byte)

Return a felt and not an updated context:

(self: model.ExecutionContext*) -> felt {
        let base_cost = Constants.TRANSACTION_INTRINSIC_GAS_COST;
        let calldata_cost = self.call_context.calldata_len * 16  // this is not accurate, but for this snippet, because some bytes are 0s
        return base_cost + calldata_cost

In places where compute_intrinsic_gas_cost was used, use compute_intrinsic_gas_cost then increment_gas_used.

SINCE GROUP
Frontier Stop and Arithmetic Operations
Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

SINCE GROUP Frontier Stop and Arithmetic Operations Index 1 is top of the stack. See PUSH.

Notes

All values are treated as two’s complement signed 256-bit integers. Note the overflow semantic when −2255 is negated.

Stack input

a: integer. b: integer. c: integer.

Stack output

a * b % c: integer result of the addition integer modulo.

Examples

Reproduce in playground

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

Stack input
a: integer.
Stack output
a == 0: 1 if a is 0, 0 otherwise.
Examples
Input Output Input Output
1 10 0 1 0 1
Reproduce in playground.

Error cases
The state changes done by the current context are reverted in those cases:

Not enough gas.
Not enough values on the stack.

SINCE GROUP
Frontier - Comparison & Bitwise Logic Operations
Reproduce in playground.

Stack input

1. a: left side integer.
2. b: right side integer.

Stack output

1. a < b: 1 if the left side is smaller, 0 otherwise.

Examples

Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

Since

Frontier

Group

Stack, Memory, Storage and Flow Operations

Description

0x54 - SLOAD

Index 1 is top of the stack. See PUSH.

Stack input

1. key: 32-byte key in storage.

Stack output

1. value: 32-byte value corresponding to that key. 0 if that key was never written before.

Examples

Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

Gas

The static cost is 0. If the accessed address is warm, the dynamic cost is 100. Otherwise the dynamic cost is 2100. See section access sets.

Since

Frontier

Group

Block Information

Description

0x44 - DIFFICULTY: Get the block's difficulty

Index 1 is top of the stack. See PUSH.

Stack output

1. difficulty: current block difficulty.

Example

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Stack overflow.

@all-contributors please add @abdelhamidbakhta projectManagement

Since

Frontier

Group

Block Information

Description

0x45 - GASLIMIT: Get the block's gas limit

Index 1 is top of the stack. See PUSH.

Stack output

1. gasLimit: gas limit.

Example

Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Stack overflow.

Feature Request

Describe the Feature Request

Implement the serie of DUPX Duplication Operations.

@all-contributors please add @abdelhamidbakhta for infrastructure, tests, doc and code

Since

Byzantium

Group

Environmental Information

Description

0x3e - RETURNDATACOPY: Copy output data from the previous call to memory

Index 1 is top of the stack. See PUSH.

Notes

A sub context can be created with CALL, CALLCODE, DELEGATECALL or STATICCALL.

Stack input

1. destOffset: byte offset in the memory where the result will be copied.
2. offset: byte offset in the return data from the last executed sub context to copy.
3. size: byte size to copy.

Examples

Return data

0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

Reproduce in playground

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.
• Reading offset equal of higher than RETURNDATASIZE.

Gas

minimum_word_size = (size + 31) / 32
static_gas = 3

dynamic_gas = 3 * minimum_word_size + memory_expansion_cost

The memory expansion cost explanation can be found here.

Feature Request

Implement EQ (0x14) opcode

Since

Frontier

Group

Stack, Memory, Storage and Flow Operations

Description

0x5b - JUMPDEST

Mark a valid destination for JUMP or JUMPI. This operation has no effect on machine state during execution.

Since

Frontier

Group

Block Information

Description

0x43 - NUMBER: Get the block's number

Index 1 is top of the stack. See PUSH.

Stack output

1. blockNumber: current block number.

Example

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Stack overflow.

Notes
Each instruction occupies one byte. In the case of a PUSH instruction, the bytes that need to be pushed are encoded after that, it thus increases the codesize accordingly.

Stack output
size: byte size of the code.

Reproduce in playground.

Error cases
The state changes done by the current context are reverted in those cases:

Not enough gas.
Stack overflow.

Since

Frontier

Group

Stack, Memory, Storage and Flow Operations

Description

0x5a - GAS

Index 1 is top of the stack. See PUSH.

Stack output
gas: remaining gas (after this instruction).
Example
See in playground.

Error cases
The state changes done by the current context are reverted in those cases:

Not enough gas.
Stack overflow.

Since

Frontier

Group

Environmental Information

Description

0x37 - CALLDATACOPY

Index 1 is top of the stack. See PUSH.

Notes

For out of bound bytes, 0s will be copied.

Stack input

1. destOffset: byte offset in the memory where the result will be copied.
2. offset: byte offset in the calldata to copy.
3. size: byte size to copy.

Examples

Calldata

0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

Gas

minimum_word_size = (size + 31) / 32
static_gas = 3

dynamic_gas = 3 * minimum_word_size + memory_expansion_cost

The memory expansion cost explanation can be found here.

Since

Frontier

Group

System Operations

Description

Equivalent to any other opcode not present in this reference, but guaranteed to remain an invalid instruction. Equivalent to REVERT (since Byzantium fork) with 0,0 as stack parameters, except that all the gas given to the current context is consumed.

Gas
All the remaining gas in this context is consumed.

Stack output

1. chainId: chain id of the network.

Notes
Here are some chain ids (source):

Id Chain
1 Mainnet
3 Ropsten
4 Rinkeby
5 Goerli
6 Kotti
61 Classic
63 Mordor
212 Astor
2018 Dev
Stack output
chainId: chain id of the network.

Reproduce in playground.

Error cases
The state changes done by the current context are reverted in those cases:

Not enough gas.
Stack overflow.

Since

Frontier

Group

Environmental Information

Description

0x3f - EXTCODEHASH

Possible implementation

1. contract_account.bytecode() to retrieve the code of the given contract
2. take inspiration from SHA3 to compute the hash of the bytecode_len, bytecode array.

Since

Byzantium

Group

Environmental Information

Description

0x3d - RETURNDATASIZE

Index 1 is top of the stack. See PUSH.

Notes

A sub context can be created with CALL, CALLCODE, DELEGATECALL or STATICCALL.

Stack output

1. size: byte size of the return data from the last executed sub context.

Example

Reproduce in playground

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Stack overflow.

Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

Stack input
a: integer numerator.
b: integer denominator.
Stack output
a % b: integer result of the integer modulo. If the denominator is 0, the result will be 0.
Examples
Input Output Input Output
1 10 1 1 17 2
2 3 2 5
Reproduce in playground.

Error cases
The state changes done by the current context are reverted in those cases:

Not enough gas.
Not enough values on the stack.

Since

Istanbul

Group

Block Information

Description

0x47 - SELFBALANCE

Index 1 is top of the stack. See PUSH.

Notes

Semantically equivalent of calling BALANCE with ADDRESS as parameter, but with a reduced gas cost.

Stack output

1. balance: balance of the current account in wei.

Example

Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Stack overflow.

Since

Frontier

Group

Stack, Memory, Storage and Flow Operations

Description

0x55 - SSTORE

Index 1 is top of the stack. See PUSH.

Stack input

1. key: 32-byte key in storage.
2. value: 32-byte value to store.

Examples

Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.
• The current execution context is from a STATICCALL (since Byzantium fork).

Gas

Definitions:

• value: value from the stack input.
• current_value: current value of the storage slot.
• original_value: value of the storage slot before the current transaction.

static_gas = 0
if value == current_value

if key is warm

base_dynamic_gas = 100

else

base_dynamic_gas = 100

else if current_value == original_value

if original_value == 0

base_dynamic_gas = 20000

else

base_dynamic_gas = 2900

else

base_dynamic_gas = 100

On top of the cost above, 2100 is added to base_dynamic_gas if the slot is cold. See section access sets.

Gas refunds

if value != current_value

if current_value == original_value

if original_value != 0 and value == 0

gas_refunds += 4800

else

if original_value != 0

if current_value == 0

gas_refunds -= 4800

else if value == 0

gas_refunds += 4800

if value == original_value

if original_value == 0

if key is warm

gas_refunds += 20000 - 100

else

gas_refunds += 19900

else

if key is warm

gas_refunds += 5000 - 2100 - 100

else

gas_refunds += 4900

Stack input
i: byte offset starting from the most significant byte.
x: 32-byte value.
Stack output
y: the indicated byte at the least significant position. If the byte offset is out of range, the result is 0.

Reproduce in playground.

Error cases
The state changes done by the current context are reverted in those cases:

Not enough gas.
Not enough values on the stack.

Since

Frontier

Group

Block Information

Description

0x40 - BLOCKHASH: Get the hash of one of the 256 most recent complete blocks

Index 1 is top of the stack. See PUSH.

Stack input

1. blockNumber: block number to get the hash from. Valid range is the last 256 blocks (not including the current one). Current block number can be queried with NUMBER.

Stack output

1. hash: hash of the chosen block, or 0 if the block number is not in the valid range.

Examples

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

Since

Frontier

Group

Stack, Memory, Storage and Flow Operations

Description

0x59 - MSIZE

Get the size of active memory in bytes

The memory is always fully accessible. What this instruction tracks is the highest offset that was accessed in the current execution. A first write or read to a bigger offset will trigger a memory expansion, which will cost gas. The size is always a multiple of a word (32 bytes).

Stack output
size: current memory size in bytes (higher offset accessed until now + 1).

Error cases
The state changes done by the current context are reverted in those cases:

Not enough gas.
Stack overflow.

@all-contributors please add @0xMentorNotAPseudo for tests, doc, code

Implement 0x11 - GT opcode

Since

Frontier

Group

Stack, Memory, Storage and Flow Operations

Description

0x56 - JUMP

Index 1 is top of the stack. See PUSH.

Notes
The program counter (PC) is a byte offset in the deployed code. It indicates which instruction will be executed next. When an ADD is executed, for example, the PC is incremented by 1, since the instruction is 1 byte. The PUSH instructions are bigger than one byte, and so will increment the counter accordingly.

The JUMP instruction alters the program counter, thus breaking the linear path of the execution to another point in the deployed code. It is used to implement functionalities like functions.

Stack input
counter: byte offset in the deployed code where execution will continue from. Must be a JUMPDEST instruction.
Example
See in playground.

Error cases
The state changes done by the current context are reverted in those cases:

Not enough gas.
Not enough values on the stack.
Counter offset is not a JUMPDEST. The error is generated even if the JUMP would not have been done.

Notes
Shift the bits towards the most significant one. The bits moved after the 256th one are discarded, the new bits are set to 0.

Stack input
shift: number of bits to shift to the left.
value: 32 bytes to shift.
Stack output
value << shift: the shifted value. If shift is bigger than 255, returns 0.

Reproduce in playground.

Error cases
The state changes done by the current context are reverted in those cases:

Not enough gas.
Not enough values on the stack.

Feature Request

Describe the Feature Request

Currently MSTORE operation only account for static gas cost (3). It should also take into consideration dynamic gas cost related to memory expansion.

Memory expansion works as explained in this section: https://www.evm.codes/about#memoryexpansion

Describe Preferred Solution

Implement gas accounting that compute the dynamic gas cost of MSTORE.

Related Code

• memory_operations

Since

Frontier

Group

Stack Memory Storage and Flow Operations

Description

0x50 - POP

Index 1 is top of the stack. See PUSH.

Stack input

1. y: a stack item.

Example

Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

WIP: story to refine but generally speaking - design & refactor tests.

• Integrations tests are missing
• Unit tests and especially tests/cases should be reviewed.

For example, we have test_arithmetic_operations which is IMO an integration test by chaining every arithmetic operation into one big operation. Same for test_duplication_operations. We can't do the same for test_comparison_operations.

Suggestion: the unit test scope of an opcode should be the opcode itself.

We should avoid using 00x.json as the fixture's name. To allow the factorization of tests, payload of fixture should also accept an array of scenarios instead of just one scenario.

Since

Frontier

Group

Environmental Information

Description

0x3b - EXTCODESIZE

Index 1 is top of the stack. See PUSH.

Stack input

1. address: 20-byte address of the contract to query.

Stack output

1. size: byte size of the code.

Example

Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

Gas

The static cost is 0. If the accessed address is warm, the dynamic cost is 100. Otherwise the dynamic cost is 2600. See section access sets.

Notes
Shift the bits towards the least significant one. The bits moved before the first one are discarded, the new bits are set to 0 if the previous most significant bit was 0, otherwise the new bits are set to 1.

Stack input
shift: number of bits to shift to the right.
value: integer to shift.
Stack output
value >> shift: the shifted value.

Reproduce in playground.

Error cases
The state changes done by the current context are reverted in those cases:

Not enough gas.
Not enough values on the stack.

Since

London

Group

Block Information

Description

0x48 - BASEFEE

Index 1 is top of the stack. See PUSH.

Stack output

1. baseFee: base fee in wei.

Example

Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Stack overflow.

Since

Frontier

Group

Environmental Information

Description

0x39 - CODECOPY: Copy code running in current environment to memory

Index 1 is top of the stack. See PUSH.

Notes

For out of bound bytes, 0s will be copied.

Stack input

1. destOffset: byte offset in the memory where the result will be copied.
2. offset: byte offset in the code to copy.
3. size: byte size to copy.

Examples

Code

0x7DFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7F

Reproduce in playground.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

Gas

minimum_word_size = (size + 31) / 32
static_gas = 3

dynamic_gas = 3 * minimum_word_size + memory_expansion_cost

The memory expansion cost explanation can be found here.

Since

Frontier

Group

Stack, Memory, Storage and Flow Operations

Description

0x58 - PC

Notes
The program counter (PC) is a byte offset in the deployed code. It indicates which instruction will be executed next. When an ADD is executed, for example, the PC is incremented by 1, since the instruction is 1 byte. The PUSH instructions are bigger than one byte, and so will increment the counter accordingly.

Stack output
counter: PC of this instruction in the current program.
Example
See in playground.

Error cases
The state changes done by the current context are reverted in those cases:

Not enough gas.
Stack overflow.

Since

Frontier

Group

Stack, Memory, Storage and Flow Operations

Description

0x57 - JUMPI

Index 1 is top of the stack. See PUSH.

Notes
The program counter (PC) is a byte offset in the deployed code. It indicates which instruction will be executed next. When an ADD is executed, for example, the PC is incremented by 1, since the instruction is 1 byte. The PUSH instructions are bigger than one byte, and so will increment the counter accordingly.

The JUMPI instruction may alter the program counter, thus breaking the linear path of the execution to another point in the deployed code. It is used to implement functionalities like loops and conditions.

Stack input
counter: byte offset in the deployed code where execution will continue from. Must be a JUMPDEST instruction.
b: the program counter will be altered with the new value only if this value is different from 0. Otherwise, the program counter is simply incremented and the next instruction will be executed.
Example
See in playground.

Error cases
The state changes done by the current context are reverted in those cases:

Not enough gas.
Not enough values on the stack.
Counter offset is not a JUMPDEST. The error is generated only if the JUMP would have been done.

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Stack overflow.

Stack output
address: miner's 20-byte address.
Example
Input Output
1 0x5B38Da6a701c568545dCfcB03FcB875f56beddC4
Error cases
The state changes done by the current context are reverted in those cases:

Not enough gas.
Stack overflow.

Since

Frontier

Group

Environmental Information

Description

0x3c - EXTCODECOPY: Copy an account's code to memory

Index 1 is top of the stack. See PUSH.

Notes

For out of bound bytes, 0s will be copied.

Stack input

1. address: 20-byte address of the contract to query.
2. destOffset: byte offset in the memory where the result will be copied.
3. offset: byte offset in the code to copy.
4. size: byte size to copy.

Examples

Code

0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

Reproduce in playground

Error cases

The state changes done by the current context are reverted in those cases:

• Not enough gas.
• Not enough values on the stack.

Gas

minimum_word_size = (size + 31) / 32
static_gas = 0

dynamic_gas = 3 * minimum_word_size + memory_expansion_cost + address_access_cost

The memory expansion cost explanation can be found here. If the accessed address is warm, address_access_cost is 100, otherwise it is 2600. See section access sets.