EEI: Specify trap conditions

Author: chfast

Diff for: eth_interface.md

@@ -42,6 +42,10 @@ offset.
 
 *nothing*
 
+**Trap conditions**
+
+- store to memory at `resultOffset` results in out of bounds access.
+
 ## getExternalBalance
 
 Gets balance of the given account and loads it into memory at the given
@@ -56,6 +60,11 @@ offset.
 
 *nothing*
 
+**Trap conditions**
+
+- load from memory at `addressOffset` results in out of bounds access,
+- store to memory at `resultOffset` results in out of bounds access.
+
 ## getBlockHash
 
 Gets the hash of one of the 256 most recent complete blocks.
@@ -71,6 +80,10 @@ Gets the hash of one of the 256 most recent complete blocks.
 
 *Note:* in case of failure, the output memory pointed by `resultOffset` is unchanged.
 
+**Trap conditions**
+
+- store to memory at `resultOffset` results in out of bounds access (also checked on failure).
+
 ## call
 
 Sends a message with arbitrary data to a given address path
@@ -87,6 +100,12 @@ Sends a message with arbitrary data to a given address path
 
 `result` **i32** Returns 0 on success, 1 on failure and 2 on `revert`
 
+**Trap conditions**
+
+- load `address` from memory at `addressOffset` results in out of bounds access,
+- load `u128` from memory at `valueOffset` results in out of bounds access,
+- load `dataLength` number of bytes from memory at `dataOffset` results in out of bounds access.
+
 ## callDataCopy
 
 Copies the input data in current environment to memory. This pertains to
@@ -102,6 +121,11 @@ the input data passed with the message call instruction or transaction.
 
 *nothing*
 
+**Trap conditions**
+
+- load `length` number of bytes from input data buffer at `dataOffset` results in out of bounds access,
+- store `length` number of bytes to memory at `resultOffset` results in out of bounds access.
+
 ## getCallDataSize
 
 Get size of input data in current environment. This pertains to the input
@@ -131,6 +155,12 @@ data passed with the message call instruction or transaction.
 
 `result` **i32** Returns 0 on success, 1 on failure and 2 on `revert`
 
+**Trap conditions**
+
+- load `address` from memory at `addressOffset` results in out of bounds access,
+- load `u128` from memory at `valueOffset` results in out of bounds access,
+- load `dataLength` number of bytes from memory at `dataOffset` results in out of bounds access.
+
 ## callDelegate
 
 Message-call into this account with an alternative account’s code, but
@@ -147,6 +177,11 @@ persisting the current values for sender and value.
 
 `result` **i32** Returns 0 on success, 1 on failure and 2 on `revert`
 
+**Trap conditions**
+
+- load `address` from memory at `addressOffset` results in out of bounds access,
+- load `dataLength` number of bytes from memory at `dataOffset` results in out of bounds access.
+
 ## callStatic
 
 Sends a message with arbitrary data to a given address path, but disallow state
@@ -164,6 +199,11 @@ value.
 
 `result` **i32** Returns 0 on success, 1 on failure and 2 on `revert`
 
+**Trap conditions**
+
+- load `address` from memory at `addressOffset` results in out of bounds access,
+- load `dataLength` number of bytes from memory at `dataOffset` results in out of bounds access.
+
 ## storageStore
 
 Store 256-bit a value in memory to persistent storage
@@ -177,6 +217,11 @@ Store 256-bit a value in memory to persistent storage
 
 *nothing*
 
+**Trap conditions**
+
+- load `u256` from memory at `pathOffset` results in out of bounds access,
+- load `u256` from memory at `valueOffset` results in out of bounds access.
+
 ## storageLoad
 
 Loads a 256-bit a value to memory from persistent storage
@@ -190,6 +235,11 @@ Loads a 256-bit a value to memory from persistent storage
 
 *nothing*
 
+**Trap conditions**
+
+- load `u256` from memory at `pathOffset` results in out of bounds access,
+- store `u256` to memory at `resultOffset` results in out of bounds access.
+
 ## getCaller
 
 Gets caller address and loads it into memory at the given offset. This is
@@ -203,6 +253,10 @@ the address of the account that is directly responsible for this execution.
 
 *nothing*
 
+**Trap conditions**
+
+- store `address` to memory at `resultOffset` results in out of bounds access.
+
 ## getCallValue
 
 Gets the deposited value by the instruction/transaction responsible for
@@ -216,6 +270,10 @@ this execution and loads it into memory at the given location.
 
 *nothing*
 
+**Trap conditions**
+
+- store `u128` to memory at `resultOffset` results in out of bounds access.
+
 ## codeCopy
 
 Copies the code running in current environment to memory.
@@ -230,6 +288,11 @@ Copies the code running in current environment to memory.
 
 *nothing*
 
+**Trap conditions**
+
+- load `length` number of bytes from the current code buffer at `codeOffset` results in out of bounds access,
+- store `length` number of bytes to memory at `resultOffset` results in out of bounds access.
+
 ## getCodeSize
 
 Gets the size of code running in current environment.
@@ -254,6 +317,10 @@ Gets the block’s beneficiary address and loads into memory.
 
 *nothing*
 
+**Trap conditions**
+
+- store `address` to memory at `resultOffset` results in out of bounds access.
+
 ## create
 
 Creates a new contract with a given value.
@@ -262,7 +329,7 @@ Creates a new contract with a given value.
 
 -   `valueOffset` **i32ptr** the memory offset to load the value from (`u128`)
 -   `dataOffset` **i32ptr** the memory offset to load the code for the new contract from (`bytes`)
--   `length` **i32** the data length
+-   `dataLength` **i32** the data length
 -   `resultOffset` **i32ptr** the memory offset to write the new contract address to (`address`)
 
 *Note*: `create` will clear the return buffer in case of success or may fill it with data coming from `revert`.
@@ -271,6 +338,12 @@ Creates a new contract with a given value.
 
 `result` **i32** Returns 0 on success, 1 on failure and 2 on `revert`
 
+**Trap conditions**
+
+- load `u128` from memory at `valueOffset` results in out of bounds access,
+- load `dataLength` number of bytes from memory at `dataOffset` results in out of bounds access.
+- store `address` to memory at `resultOffset` results in out of bounds access.
+
 ## getBlockDifficulty
 
 Get the block’s difficulty.
@@ -283,6 +356,10 @@ Get the block’s difficulty.
 
 *nothing*
 
+**Trap conditions**
+
+- store `u256` to memory at `resultOffset` results in out of bounds access.
+
 ## externalCodeCopy
 
 Copies the code of an account to memory.
@@ -298,6 +375,12 @@ Copies the code of an account to memory.
 
 *nothing*
 
+**Trap conditions**
+
+- load `address` from memory at `addressOffset` results in out of bounds access,
+- load `length` number of bytes from the account code buffer at `codeOffset` results in out of bounds access,
+- store `length` number of bytes to memory at `resultOffset` results in out of bounds access.
+
 ## getExternalCodeSize
 
 Get size of an account’s code.
@@ -310,6 +393,10 @@ Get size of an account’s code.
 
 `extCodeSize` **i32**
 
+**Trap conditions**
+
+- load `address` from memory at `addressOffset` results in out of bounds access.
+
 ## getGasLeft
 
 Returns the current gasCounter
@@ -340,20 +427,24 @@ Gets price of gas in current environment.
 
 **Parameters**
 
--   `valueOffset` **i32ptr** the memory offset to write the value to (`u128`)
+-   `resultOffset` **i32ptr** the memory offset to write the value to (`u128`)
 
 **Returns**
 
 *nothing*
 
+**Trap conditions**
+
+- store `u128` to memory at `resultOffset` results in out of bounds access.
+
 ## log
 
 Creates a new log in the current environment
 
 **Parameters**
 
 -   `dataOffset` **i32ptr** the memory offset to load data from (`bytes`)
--   `length` **i32** the data length
+-   `dataLength` **i32** the data length
 -   `numberOfTopics` **i32** the number of topics following (0 to 4)
 -   `topic1` **i32ptr** the memory offset to load topic1 from (`u256`)
 -   `topic2` **i32ptr** the memory offset to load topic2 from (`u256`)
@@ -364,6 +455,15 @@ Creates a new log in the current environment
 
 *nothing*
 
+**Trap conditions**
+
+- load `dataLength` number of bytes from memory at `dataOffset` results in out of bounds access,
+- `numberOfTopics` is negative or greater than 4,
+- load `u256` from memory at `topic1` results in out of bounds access,
+- load `u256` from memory at `topic2` results in out of bounds access,
+- load `u256` from memory at `topic3` results in out of bounds access,
+- load `u256` from memory at `topic4` results in out of bounds access.
+
 ## getBlockNumber
 
 Get the block’s number.
@@ -390,32 +490,44 @@ account with non-empty associated code.
 
 *nothing*
 
+**Trap conditions**
+
+- store `address` to memory at `resultOffset` results in out of bounds access.
+
 ## finish
 
 Set the returning output data for the execution. This will cause a trap and the execution will be aborted immediately.
 
 **Parameters**
 
 -   `dataOffset` **i32ptr** the memory offset of the output data (`bytes`)
--   `length` **i32** the length of the output data
+-   `dataLength` **i32** the length of the output data
 
 **Returns**
 
 *doesn't return*
 
+**Trap conditions**
+
+- load `dataLength` number of bytes from memory at `dataOffset` results in out of bounds access.
+
 ## revert
 
 Set the returning output data for the execution. This will cause a trap and the execution will be aborted immediately.
 
 **Parameters**
 
 -   `dataOffset` **i32ptr** the memory offset of the output data (`bytes`)
--   `length` **i32** the length of the output data
+-   `dataLength` **i32** the length of the output data
 
 **Returns**
 
 *doesn't return*
 
+**Trap conditions**
+
+- load `dataLength` number of bytes from memory at `dataOffset` results in out of bounds access.
+
 ## getReturnDataSize
 
 Get size of current return data buffer to memory. This contains the return data
@@ -446,6 +558,11 @@ from last executed `call`, `callCode`, `callDelegate`, `callStatic` or `create`.
 
 **Returns**
 
+**Trap conditions**
+
+- load `length` number of bytes from input data buffer at `dataOffset` results in out of bounds access,
+- store `length` number of bytes to memory at `resultOffset` results in out of bounds access.
+
 *nothing*
 
 ## selfDestruct
@@ -461,6 +578,10 @@ beneficiary address. This will cause a trap and the execution will be aborted im
 
 *doesn't return*
 
+**Trap conditions**
+
+- load `address` from memory at `addressOffset` results in out of bounds access.
+
 ## getBlockTimestamp
 
 Get the block’s timestamp.