diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 706aef19..703d7e28 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -5,11 +5,10 @@ on: branches: - master pull_request: - release: - types: [published] jobs: test: uses: FuelLabs/github-actions/.github/workflows/mdbook-docs.yml@master with: docs-src-path: 'src' + spellcheck-config-path: '.spellcheck.yml' diff --git a/.spellcheck.yml b/.spellcheck.yml new file mode 100644 index 00000000..61a17f4c --- /dev/null +++ b/.spellcheck.yml @@ -0,0 +1,29 @@ +matrix: + - name: SPCheck + aspell: + lang: en + dictionary: + encoding: utf-8 + wordlists: + - spell-check-custom-words.txt + pipeline: + - pyspelling.filters.context: + context_visible_first: true + escapes: \\[\\`~] + delimiters: + # Ignore all code blocks + - open: '(?s)^(?P *`{3,}\s*(\w+\s*,?\s*)+.*?)$' + close: '^( *`{3,})$' + - pyspelling.filters.markdown: + markdown_extensions: + - pymdownx.superfences: + - pyspelling.filters.html: + comments: false + ignores: + - code + - pre + sources: + - 'src/*.md' + - 'src/**/*.md' + default_encoding: utf-8 + \ No newline at end of file diff --git a/spell-check-custom-words.txt b/spell-check-custom-words.txt new file mode 100644 index 00000000..54a722c6 --- /dev/null +++ b/spell-check-custom-words.txt @@ -0,0 +1,270 @@ +ABI +ABIs +ASM +IDE +IDEs +LSP +namespace +ALU +APIs +JSON +BrowserStack +CLI +Deserialization +deserializing +DApp +subcurrency +Subcurrency +intrinsics +Intrinsics +workspace +workspaces +Workspaces +neovim +EVM +EVM's +EOA +ERC +Ethereum +Ethereum's +FVM +FuelVM +Fuelup +Github +GraphQL +Infura +JSON +LSP +Merkle +PoA +PoS +PoW +RPC +SDK +SDK's +SDKs +SauceLabs +Sepolia +Structs +Sway +TAI +TODO +TypeScript +UTF +UTXO +UTXOs +Utils +VM +VSCode +abigen +args +async +backend +backtraces +blockchain +blockchain's +bytecode +codespace +codespaces +config +cryptographic +customizable +customizations +dapp +dev +dropdown +enum +enums +env +forc +frontend +fuelup +fullstack +graphQL +graphql +http +https +js +localhost +mainnet +mempool +merkle +monorepo +monorepos +natively +npm +nvm +onboarding +params +pnpm +prerelease +queryable +quickstart +relayer +relayers +repo +repos +runnable +stateful +struct +structs +struct's +testnet +testnets +toolchain +toolchains +urql +validator +validators +superABI +superABIs +SuperABIs +supertraits +compositional +typeclass +turbofish +DSL +TOML +IPFS +Bitwise +Bitwise +runtime +runtimes +formatter +deployable +Utils +ETH +initializer +initializers +destructuring +instantiation +VMs +superset +CEI +pre +entrancy +interoperable +blockchains +keccak +SHA +UI +backtrace +Collateralized +collateralized +submodule +DEX +TypeChain +inlines +inlining +MiB +FuelVM's +deterministically +CLI +VS +GraphViz +DOT +DCA +AST +GitHub +decrypt +subcommand +subcommands +Subcommands +supertrait +supertraits +Supertraits +incrementor +monomorphization +Booleans +boolean +Orchestrator +orchestrator +growable +arity +tuple's +unary +SRC +DEX +FuelLabs +PRs +codebase +PostgreSQL +Postgres +MacOS +macOS +backends +hoc +semver +SQLx +Homebrew +Changelog +lookups +namespaces +YAML +WASM +WebAssembly +dApp +dApps +JWT +Schemas +schemas +AssemblyScript +indexable +Macbook +Dockerized +TLDR +IaaS +Updatable +coinbase +Coinbase +postcondition +Postcondition +Cryptocurrency +cryptocurrency +ECDSA +EcDSA +secp +Secp +Bitfield +SMT +SMTs +subtrees +subtree +prepended +unhashed +preimage +FIPS +EdDSA +curve25519 +blazingly +pseudocode +Pseudocode +endian +KiB +SUT +Celestia +encodings +callee +inlined +parsable +underflows +bitmask +XORs +XOR +ORs +ANDs +rhs +lhs +scalable +Scalable +Exponentiate +exponentiate +Executablity +executablity +Unwritable +unwritable +untrusted +intra +OOB +unspendable +priori diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 21b83464..5f6d59e2 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -9,7 +9,7 @@ - [Input](./tx-format/input.md) - [Output](./tx-format/output.md) - [Witness](./tx-format/witness.md) - - [TXPointer](./tx-format/tx-pointer.md) + - [Transaction Pointer](./tx-format/tx-pointer.md) - [Computing Identifiers](./identifiers/index.md) - [Asset ID](./identifiers/asset.md) - [Contract ID](./identifiers/contract-id.md) diff --git a/src/abi/argument-encoding.md b/src/abi/argument-encoding.md index 510e6226..21ca8ff7 100644 --- a/src/abi/argument-encoding.md +++ b/src/abi/argument-encoding.md @@ -40,9 +40,9 @@ These types are encoded in-place. Here's how to encode them. We define `enc(X)` **Example:** Encoding `42` yields: `0x000000000000002a`, which is the hexadecimal representation of the decimal number `42`, right-aligned to 8 bytes. -Encoding `u128::MAX - 1` yields: `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFE`, it's right-alined to 16 bytes +Encoding `u128::MAX - 1` yields: `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFE`, it's right-aligned to 16 bytes -## Boolean +## `Boolean` `enc(X)` is `0` if `X` is false or `1` if `X` is true, left-padded with zero-bytes. Total length must be 8 bytes. Similar to the `u8` encoding. @@ -54,7 +54,7 @@ Encoding `true` yields: 0x0000000000000001 ``` -## B256 +## `B256` `b256` is a fixed size bit array of length 256. Used for 256-bit hash digests and other 256-bit types. It is encoded as-is. @@ -66,7 +66,7 @@ Encoding `0xc7fd1d987ada439fc085cfa3c49416cf2b504ac50151e3c2335d60595cb90745` yi 0xc7fd1d987ada439fc085cfa3c49416cf2b504ac50151e3c2335d60595cb90745 ``` -## Address +## `Address` A 256-bit (32-byte) address, encoded in the same way as a `b256` argument: encoded as-is. diff --git a/src/abi/receipts.md b/src/abi/receipts.md index 1fbfdf7c..1543bcd3 100644 --- a/src/abi/receipts.md +++ b/src/abi/receipts.md @@ -17,19 +17,19 @@ Upon execution of ABI calls, i.e scripts being executed, a JSON object represent All receipts will have a `type` property: - `type`: String; the type of the receipt. Can be one of: - - [Call](#call-receipt) - - [Return](#return-receipt) - - [ReturnData](#returndata-receipt) - - [Panic](#panic-receipt) - - [Revert](#revert-receipt) - - [Log](#log-receipt) - - [Mint](#mint-receipt) - - [Burn](#burn-receipt) - - [LogData](#logdata-receipt) - - [Transfer](#transfer-receipt) - - [TransferOut](#transferout-receipt) - - [ScriptResult](#scriptresult-receipt) - - [MessageOut](#messageout-receipt) + - [`Call`](#call-receipt) + - [`Return`](#return-receipt) + - [`ReturnData`](#returndata-receipt) + - [`Panic`](#panic-receipt) + - [`Revert`](#revert-receipt) + - [`Log`](#log-receipt) + - [`Mint`](#mint-receipt) + - [`Burn`](#burn-receipt) + - [`LogData`](#logdata-receipt) + - [`Transfer`](#transfer-receipt) + - [`TransferOut`](#transferout-receipt) + - [`ScriptResult`](#scriptresult-receipt) + - [`MessageOut`](#messageout-receipt) Then, each receipt type will have its own properties. Some of these properties are related to the FuelVM's registers, as specified in more detail [here](../fuel-vm/instruction-set.md). @@ -56,7 +56,7 @@ _Important note:_ For the JSON representation of receipts, we represent 64-bit u } ``` -## Return Receipt +## `Return` Receipt - `type`: `Return`. - `id`: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context; `null` otherwise. @@ -74,7 +74,7 @@ _Important note:_ For the JSON representation of receipts, we represent 64-bit u } ``` -## Call Receipt +## `Call` Receipt - `type`: `Call`. - `from`: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context; `null` otherwise. @@ -102,7 +102,7 @@ _Important note:_ For the JSON representation of receipts, we represent 64-bit u } ``` -## Log Receipt +## `Log` Receipt - `type`: `Log`. - `id`: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context. `null` otherwise. @@ -126,7 +126,7 @@ _Important note:_ For the JSON representation of receipts, we represent 64-bit u } ``` -## Mint Receipt +## `Mint` Receipt - `type`: `Mint`. - `sub_id`: Hexadecimal string representation of the 256-bit (32-byte) asset sub identifier ID; derived from register `$rB`. @@ -146,7 +146,7 @@ _Important note:_ For the JSON representation of receipts, we represent 64-bit u } ``` -## Burn Receipt +## `Burn` Receipt - `type`: `Burn`. - `sub_id`: Hexadecimal string representation of the 256-bit (32-byte) asset sub identifier ID; derived from register `$rB`. @@ -166,7 +166,7 @@ _Important note:_ For the JSON representation of receipts, we represent 64-bit u } ``` -## LogData Receipt +## `LogData` Receipt - `type`: `LogData`. - `id`: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context. `null` otherwise. @@ -194,7 +194,7 @@ _Important note:_ For the JSON representation of receipts, we represent 64-bit u } ``` -## ReturnData Receipt +## `ReturnData` Receipt - `type`: `ReturnData`. - `id`: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context. `null` otherwise. @@ -218,7 +218,7 @@ _Important note:_ For the JSON representation of receipts, we represent 64-bit u } ``` -## Revert Receipt +## `Revert` Receipt - `type`: `Revert`. - `id`: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context. `null` otherwise. @@ -236,7 +236,7 @@ _Important note:_ For the JSON representation of receipts, we represent 64-bit u } ``` -## Transfer Receipt +## `Transfer` Receipt - `type`: `Transfer`. - `from`: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context. `null` otherwise. @@ -258,7 +258,7 @@ _Important note:_ For the JSON representation of receipts, we represent 64-bit u } ``` -## TransferOut Receipt +## `TransferOut` Receipt - `type`: `TransferOut`. - `from`: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context. `null` otherwise. @@ -280,7 +280,7 @@ _Important note:_ For the JSON representation of receipts, we represent 64-bit u } ``` -## ScriptResult Receipt +## `ScriptResult` Receipt - `type`: `ScriptResult`. - `result`: Hexadecimal string representation of a 64-bit unsigned integer; `0` if script exited successfully, `any` otherwise. @@ -294,7 +294,7 @@ _Important note:_ For the JSON representation of receipts, we represent 64-bit u } ``` -## MessageOut Receipt +## `MessageOut` Receipt - `type`: `MessageOut`. - `sender`: Hexadecimal string representation of the 256-bit (32-byte) address of the message sender: `MEM[$fp, 32]`. diff --git a/src/fuel-vm/index.md b/src/fuel-vm/index.md index 533e8442..7984d09e 100644 --- a/src/fuel-vm/index.md +++ b/src/fuel-vm/index.md @@ -7,7 +7,7 @@ - [Instruction Set](#instruction-set) - [VM Initialization](#vm-initialization) - [Contexts](#contexts) -- [Predicate Estmation](#predicate-estimation) +- [Predicate Estimation](#predicate-estimation) - [Predicate Verification](#predicate-verification) - [Script Execution](#script-execution) - [Call Frames](#call-frames) @@ -45,12 +45,12 @@ Of the 64 registers (6-bit register address space), the first `16` are reserved: | `0x04` | `$ssp` | stack start pointer | Memory address of bottom of current writable stack area. | | `0x05` | `$sp` | stack pointer | Memory address on top of current writable stack area (points to free memory). | | `0x06` | `$fp` | frame pointer | Memory address of beginning of current call frame. | -| `0x07` | `$hp` | heap pointer | Memory address below the current bottom of the heap (points to used/oob memory). | +| `0x07` | `$hp` | heap pointer | Memory address below the current bottom of the heap (points to used/OOB memory). | | `0x08` | `$err` | error | Error codes for particular operations. | | `0x09` | `$ggas` | global gas | Remaining gas globally. | | `0x0A` | `$cgas` | context gas | Remaining gas in the context. | | `0x0B` | `$bal` | balance | Received balance for this context. | -| `0x0C` | `$is` | instrs start | Pointer to the start of the currently-executing code. | +| `0x0C` | `$is` | instructions start | Pointer to the start of the currently-executing code. | | `0x0D` | `$ret` | return value | Return value or pointer. | | `0x0E` | `$retl` | return length | Return value length in bytes. | | `0x0F` | `$flag` | flags | Flags register. | @@ -104,7 +104,7 @@ There are 4 _contexts_ in the FuelVM: [predicate estimation](#predicate-estimati ## Predicate Estimation -For any input of type [`InputType.Coin`](../tx-format/index.md) or [`InputType.Message`](../tx-format/index.md), a non-zero `predicateLength` field means the UTXO being spent is a [P2SH](https://en.bitcoin.it/wiki/P2SH) rather than a [P2PKH](https://en.bitcoin.it/P2PKH) output. +For any input of type [`InputType.Coin`](../tx-format/index.md) or [`InputType.Message`](../tx-format/index.md), a non-zero `predicateLength` field means the UTXO being spent is a [`P2SH`](https://en.bitcoin.it/wiki/P2SH) rather than a [`P2PKH`](https://en.bitcoin.it/P2PKH) output. For each such input in the transaction, the VM is [initialized](#vm-initialization), then: @@ -125,7 +125,7 @@ After successful execution, `predicateGasUsed` is set to `MAX_GAS_PER_PREDICATE ## Predicate Verification -For any input of type [`InputType.Coin`](../tx-format/input.md#inputcoin) or [`InputType.Message`](../tx-format/input.md#inputmessage), a non-zero `predicateLength` field means the UTXO being spent is a [P2SH](https://en.bitcoin.it/P2SH) rather than a [P2PKH](https://en.bitcoin.it/P2PKH) output. +For any input of type [`InputType.Coin`](../tx-format/input.md#inputcoin) or [`InputType.Message`](../tx-format/input.md#inputmessage), a non-zero `predicateLength` field means the UTXO being spent is a [`P2SH`](https://en.bitcoin.it/P2SH) rather than a [`P2PKH`](https://en.bitcoin.it/P2PKH) output. For each such input in the transaction, the VM is [initialized](#vm-initialization), then: diff --git a/src/fuel-vm/instruction-set.md b/src/fuel-vm/instruction-set.md index e6fdf670..4d0245d4 100644 --- a/src/fuel-vm/instruction-set.md +++ b/src/fuel-vm/instruction-set.md @@ -2,121 +2,121 @@ - [Reading Guide](#reading-guide) - [Arithmetic/Logic (ALU) Instructions](#arithmeticlogic-alu-instructions) - - [ADD: Add](#add-add) - - [ADDI: Add immediate](#addi-add-immediate) - - [AND: AND](#and-and) - - [ANDI: AND immediate](#andi-and-immediate) - - [DIV: Divide](#div-divide) - - [DIVI: Divide immediate](#divi-divide-immediate) - - [EQ: Equals](#eq-equals) - - [EXP: Exponentiate](#exp-exponentiate) - - [EXPI: Exponentiate immediate](#expi-exponentiate-immediate) - - [GT: Greater than](#gt-greater-than) - - [LT: Less than](#lt-less-than) - - [MLOG: Math logarithm](#mlog-math-logarithm) - - [MOD: Modulus](#mod-modulus) - - [MODI: Modulus immediate](#modi-modulus-immediate) - - [MOVE: Move](#move-move) - - [MOVI: Move immediate](#movi-move-immediate) - - [MROO: Math root](#mroo-math-root) - - [MUL: Multiply](#mul-multiply) - - [MULI: Multiply immediate](#muli-multiply-immediate) - - [MLDV: Fused multiply-divide](#mldv-fused-multiply-divide) - - [NOOP: No operation](#noop-no-operation) - - [NOT: Invert](#not-invert) - - [OR: OR](#or-or) - - [ORI: OR immediate](#ori-or-immediate) - - [SLL: Shift left logical](#sll-shift-left-logical) - - [SLLI: Shift left logical immediate](#slli-shift-left-logical-immediate) - - [SRL: Shift right logical](#srl-shift-right-logical) - - [SRLI: Shift right logical immediate](#srli-shift-right-logical-immediate) - - [SUB: Subtract](#sub-subtract) - - [SUBI: Subtract immediate](#subi-subtract-immediate) - - [SUBI: Subtract immediate](#subi-subtract-immediate) - - [WDCM: 128-bit integer comparison](#wdcm-128-bit-integer-comparison) - - [WQCM: 256-bit integer comparison](#wqcm-256-bit-integer-comparison) - - [WDOP: Misc 128-bit integer operations](#wdop-misc-128-bit-integer-operations) - - [WQOP: Misc 256-bit integer operations](#wqop-misc-256-bit-integer-operations) - - [WDML: Multiply 128-bit integers](#wdml-multiply-128-bit-integers) - - [WQML: Multiply 256-bit integers](#wqml-multiply-256-bit-integers) - - [WDDV: 128-bit integer division](#wddv-128-bit-integer-division) - - [WQDV: 256-bit integer division](#wqdv-256-bit-integer-division) - - [WDMD: 128-bit integer fused multiply-divide](#wdmd-128-bit-integer-fused-multiply-divide) - - [WQMD: 256-bit integer fused multiply-divide](#wqmd-256-bit-integer-fused-multiply-divide) - - [WDAM: Modular 128-bit integer addition](#wdam-modular-128-bit-integer-addition) - - [WQAM: Modular 256-bit integer addition](#wqam-modular-256-bit-integer-addition) - - [WDMM: Modular 128-bit integer multiplication](#wdmm-modular-128-bit-integer-multiplication) - - [WQMM: Modular 256-bit integer multiplication](#wqmm-modular-256-bit-integer-multiplication) - - [XOR: XOR](#xor-xor) - - [XORI: XOR immediate](#xori-xor-immediate) + - [`ADD`: Add](#add-add) + - [`ADDI`: Add immediate](#addi-add-immediate) + - [`AND`: AND](#and-and) + - [`ANDI`: AND immediate](#andi-and-immediate) + - [`DIV`: Divide](#div-divide) + - [`DIVI`: Divide immediate](#divi-divide-immediate) + - [`EQ`: Equals](#eq-equals) + - [`EXP`: Exponentiate](#exp-exponentiate) + - [`EXPI`: Exponentiate immediate](#expi-exponentiate-immediate) + - [`GT`: Greater than](#gt-greater-than) + - [`LT`: Less than](#lt-less-than) + - [`MLOG`: Math logarithm](#mlog-math-logarithm) + - [`MOD`: Modulus](#mod-modulus) + - [`MODI`: Modulus immediate](#modi-modulus-immediate) + - [`MOVE`: Move](#move-move) + - [`MOVI`: Move immediate](#movi-move-immediate) + - [`MROO`: Math root](#mroo-math-root) + - [`MUL`: Multiply](#mul-multiply) + - [`MULI`: Multiply immediate](#muli-multiply-immediate) + - [`MLDV`: Fused multiply-divide](#mldv-fused-multiply-divide) + - [`NOOP`: No operation](#noop-no-operation) + - [`NOT`: Invert](#not-invert) + - [`OR`: OR](#or-or) + - [`ORI`: OR immediate](#ori-or-immediate) + - [`SLL`: Shift left logical](#sll-shift-left-logical) + - [`SLLI`: Shift left logical immediate](#slli-shift-left-logical-immediate) + - [`SRL`: Shift right logical](#srl-shift-right-logical) + - [`SRLI`: Shift right logical immediate](#srli-shift-right-logical-immediate) + - [`SUB`: Subtract](#sub-subtract) + - [`SUBI`: Subtract immediate](#subi-subtract-immediate) + - [`SUBI`: Subtract immediate](#subi-subtract-immediate) + - [`WDCM`: 128-bit integer comparison](#wdcm-128-bit-integer-comparison) + - [`WQCM`: 256-bit integer comparison](#wqcm-256-bit-integer-comparison) + - [`WDOP`: Misc 128-bit integer operations](#wdop-misc-128-bit-integer-operations) + - [`WQOP`: Misc 256-bit integer operations](#wqop-misc-256-bit-integer-operations) + - [`WDML`: Multiply 128-bit integers](#wdml-multiply-128-bit-integers) + - [`WQML`: Multiply 256-bit integers](#wqml-multiply-256-bit-integers) + - [`WDDV`: 128-bit integer division](#wddv-128-bit-integer-division) + - [`WQDV`: 256-bit integer division](#wqdv-256-bit-integer-division) + - [`WDMD`: 128-bit integer fused multiply-divide](#wdmd-128-bit-integer-fused-multiply-divide) + - [`WQMD`: 256-bit integer fused multiply-divide](#wqmd-256-bit-integer-fused-multiply-divide) + - [`WDAM`: Modular 128-bit integer addition](#wdam-modular-128-bit-integer-addition) + - [`WQAM`: Modular 256-bit integer addition](#wqam-modular-256-bit-integer-addition) + - [`WDMM`: Modular 128-bit integer multiplication](#wdmm-modular-128-bit-integer-multiplication) + - [`WQMM`: Modular 256-bit integer multiplication](#wqmm-modular-256-bit-integer-multiplication) + - [`XOR`: XOR](#xor-xor) + - [`XORI`: XOR immediate](#xori-xor-immediate) - [Control Flow Instructions](#control-flow-instructions) - - [JMP: Jump](#jmp-jump) - - [JI: Jump immediate](#ji-jump-immediate) - - [JNE: Jump if not equal](#jne-jump-if-not-equal) - - [JNEI: Jump if not equal immediate](#jnei-jump-if-not-equal-immediate) - - [JNZI: Jump if not zero immediate](#jnzi-jump-if-not-zero-immediate) - - [JMPB: Jump relative backwards](#jmpb-jump-relative-backwards) - - [JMPF: Jump relative forwards](#jmpf-jump-relative-forwards) - - [JNZB: Jump if not zero relative backwards](#jnzb-jump-if-not-zero-relative-backwards) - - [JNZF: Jump if not zero relative forwards](#jnzf-jump-if-not-zero-relative-forwards) - - [JNEB: Jump if not equal relative backwards](#jneb-jump-if-not-equal-relative-backwards) - - [JNEF: Jump if not equal relative forwards](#jnef-jump-if-not-equal-relative-forwards) - - [RET: Return from context](#ret-return-from-context) + - [`JMP`: Jump](#jmp-jump) + - [`JI`: Jump immediate](#ji-jump-immediate) + - [`JNE`: Jump if not equal](#jne-jump-if-not-equal) + - [`JNEI`: Jump if not equal immediate](#jnei-jump-if-not-equal-immediate) + - [`JNZI`: Jump if not zero immediate](#jnzi-jump-if-not-zero-immediate) + - [`JMPB`: Jump relative backwards](#jmpb-jump-relative-backwards) + - [`JMPF`: Jump relative forwards](#jmpf-jump-relative-forwards) + - [`JNZB`: Jump if not zero relative backwards](#jnzb-jump-if-not-zero-relative-backwards) + - [`JNZF`: Jump if not zero relative forwards](#jnzf-jump-if-not-zero-relative-forwards) + - [`JNEB`: Jump if not equal relative backwards](#jneb-jump-if-not-equal-relative-backwards) + - [`JNEF`: Jump if not equal relative forwards](#jnef-jump-if-not-equal-relative-forwards) + - [`RET`: Return from context](#ret-return-from-context) - [Memory Instructions](#memory-instructions) - - [ALOC: Allocate memory](#aloc-allocate-memory) - - [CFE: Extend call frame](#cfe-extend-call-frame) - - [CFEI: Extend call frame immediate](#cfei-extend-call-frame-immediate) - - [CFS: Shrink call frame](#cfs-shrink-call-frame) - - [CFSI: Shrink call frame immediate](#cfsi-shrink-call-frame-immediate) - - [LB: Load byte](#lb-load-byte) - - [LW: Load word](#lw-load-word) - - [MCL: Memory clear](#mcl-memory-clear) - - [MCLI: Memory clear immediate](#mcli-memory-clear-immediate) - - [MCP: Memory copy](#mcp-memory-copy) - - [MCPI: Memory copy immediate](#mcpi-memory-copy-immediate) - - [MEQ: Memory equality](#meq-memory-equality) - - [POPH: Pop a set of high registers from stack](#poph-pop-a-set-of-high-registers-from-stack) - - [POPL: Pop a set of low registers from stack](#popl-pop-a-set-of-low-registers-from-stack) - - [PSHH: Push a set of high registers to stack](#pshh-push-a-set-of-high-registers-to-stack) - - [PSHL: Push a set of low registers to stack](#pshl-push-a-set-of-low-registers-to-stack) - - [SB: Store byte](#sb-store-byte) - - [SW: Store word](#sw-store-word) + - [`ALOC`: Allocate memory](#aloc-allocate-memory) + - [`CFE`: Extend call frame](#cfe-extend-call-frame) + - [`CFEI`: Extend call frame immediate](#cfei-extend-call-frame-immediate) + - [`CFS`: Shrink call frame](#cfs-shrink-call-frame) + - [`CFSI`: Shrink call frame immediate](#cfsi-shrink-call-frame-immediate) + - [`LB`: Load byte](#lb-load-byte) + - [`LW`: Load word](#lw-load-word) + - [`MCL`: Memory clear](#mcl-memory-clear) + - [`MCLI`: Memory clear immediate](#mcli-memory-clear-immediate) + - [`MCP`: Memory copy](#mcp-memory-copy) + - [`MCPI`: Memory copy immediate](#mcpi-memory-copy-immediate) + - [`MEQ`: Memory equality](#meq-memory-equality) + - [`POPH`: Pop a set of high registers from stack](#poph-pop-a-set-of-high-registers-from-stack) + - [`POPL`: Pop a set of low registers from stack](#popl-pop-a-set-of-low-registers-from-stack) + - [`PSHH`: Push a set of high registers to stack](#pshh-push-a-set-of-high-registers-to-stack) + - [`PSHL`: Push a set of low registers to stack](#pshl-push-a-set-of-low-registers-to-stack) + - [`SB`: Store byte](#sb-store-byte) + - [`SW`: Store word](#sw-store-word) - [Contract Instructions](#contract-instructions) - - [BAL: Balance of contract ID](#bal-balance-of-contract-id) - - [BHEI: Block height](#bhei-block-height) - - [BHSH: Block hash](#bhsh-block-hash) - - [BURN: Burn existing coins](#burn-burn-existing-coins) - - [CALL: Call contract](#call-call-contract) - - [CB: Coinbase contract id](#cb-coinbase-contract-id) - - [CCP: Code copy](#ccp-code-copy) - - [CROO: Code Merkle root](#croo-code-merkle-root) - - [CSIZ: Code size](#csiz-code-size) - - [LDC: Load code from an external contract](#ldc-load-code-from-an-external-contract) - - [LOG: Log event](#log-log-event) - - [LOGD: Log data event](#logd-log-data-event) - - [MINT: Mint new coins](#mint-mint-new-coins) - - [RETD: Return from context with data](#retd-return-from-context-with-data) - - [RVRT: Revert](#rvrt-revert) - - [SMO: Send message to output](#smo-send-message-out) - - [SCWQ: State clear sequential 32 byte slots](#scwq-state-clear-sequential-32-byte-slots) - - [SRW: State read word](#srw-state-read-word) - - [SRWQ: State read sequential 32 byte slots](#srwq-state-read-sequential-32-byte-slots) - - [SWW: State write word](#sww-state-write-word) - - [SWWQ: State write sequential 32 byte slots](#swwq-state-write-sequential-32-byte-slots) - - [TIME: Timestamp at height](#time-timestamp-at-height) - - [TR: Transfer coins to contract](#tr-transfer-coins-to-contract) - - [TRO: Transfer coins to output](#tro-transfer-coins-to-output) + - [`BAL`: Balance of contract ID](#bal-balance-of-contract-id) + - [`BHEI`: Block height](#bhei-block-height) + - [`BHSH`: Block hash](#bhsh-block-hash) + - [`BURN`: Burn existing coins](#burn-burn-existing-coins) + - [`CALL`: Call contract](#call-call-contract) + - [`CB`: Coinbase contract id](#cb-coinbase-contract-id) + - [`CCP`: Code copy](#ccp-code-copy) + - [`CROO`: Code Merkle root](#croo-code-merkle-root) + - [`CSIZ`: Code size](#csiz-code-size) + - [`LDC`: Load code from an external contract](#ldc-load-code-from-an-external-contract) + - [`LOG`: Log event](#log-log-event) + - [`LOGD`: Log data event](#logd-log-data-event) + - [`MINT`: Mint new coins](#mint-mint-new-coins) + - [`RETD`: Return from context with data](#retd-return-from-context-with-data) + - [`RVRT`: Revert](#rvrt-revert) + - [`SMO`: Send message to output](#smo-send-message-out) + - [`SCWQ`: State clear sequential 32 byte slots](#scwq-state-clear-sequential-32-byte-slots) + - [`SRW`: State read word](#srw-state-read-word) + - [`SRWQ`: State read sequential 32 byte slots](#srwq-state-read-sequential-32-byte-slots) + - [`SWW`: State write word](#sww-state-write-word) + - [`SWWQ`: State write sequential 32 byte slots](#swwq-state-write-sequential-32-byte-slots) + - [`TIME`: Timestamp at height](#time-timestamp-at-height) + - [`TR`: Transfer coins to contract](#tr-transfer-coins-to-contract) + - [`TRO`: Transfer coins to output](#tro-transfer-coins-to-output) - [Cryptographic Instructions](#cryptographic-instructions) - - [ECK1: Secp251k1 signature recovery](#eck1-secp256k1-signature-recovery) - - [ECR1: Secp256r1 signature recovery](#ecr1-secp256r1-signature-recovery) - - [ED19: edDSA curve25519 verification](#ed19-eddsa-curve25519-verification) - - [K256: keccak-256](#k256-keccak-256) - - [S256: SHA-2-256](#s256-sha-2-256) + - [`ECK1`: Secp251k1 signature recovery](#eck1-secp256k1-signature-recovery) + - [`ECR1`: Secp256r1 signature recovery](#ecr1-secp256r1-signature-recovery) + - [`ED19`: EdDSA curve25519 verification](#ed19-eddsa-curve25519-verification) + - [`K256`: keccak-256](#k256-keccak-256) + - [`S256`: SHA-2-256](#s256-sha-2-256) - [Other Instructions](#other-instructions) - - [ECAL: Call external function](#ecal-call-external-function) - - [FLAG: Set flags](#flag-set-flags) - - [GM: Get metadata](#gm-get-metadata) - - [GTF: Get transaction fields](#gtf-get-transaction-fields) + - [`ECAL`: Call external function](#ecal-call-external-function) + - [`FLAG`: Set flags](#flag-set-flags) + - [`GM`: Get metadata](#gm-get-metadata) + - [`GTF`: Get transaction fields](#gtf-get-transaction-fields) ## Reading Guide @@ -180,7 +180,7 @@ If an operation would overflow, so that the result doesn't fit into the target f Results below zero are also considered overflows. If the [`F_WRAPPING`](./index.md#flags) flag is set, instead `$of` is set to `true` or the overflowing part of the result, depending on the operation. -### ADD: Add +### `ADD`: Add | | | |-------------|------------------------| @@ -198,7 +198,7 @@ Panic if: `$err` is cleared. -### ADDI: Add immediate +### `ADDI`: Add immediate | | | |-------------|-----------------------------------------| @@ -216,7 +216,7 @@ Panic if: `$err` is cleared. -### AND: AND +### `AND`: AND | | | |-------------|-----------------------------| @@ -232,7 +232,7 @@ Panic if: `$of` and `$err` are cleared. -### ANDI: AND immediate +### `ANDI`: AND immediate | | | |-------------|-------------------------------------------------| @@ -250,7 +250,7 @@ Panic if: `$of` and `$err` are cleared. -### DIV: Divide +### `DIV`: Divide | | | |-------------|-------------------------| @@ -270,7 +270,7 @@ Otherwise, `$err` is cleared. `$of` is cleared. -### DIVI: Divide immediate +### `DIVI`: Divide immediate | | | |-------------|--------------------------------------------| @@ -290,7 +290,7 @@ Otherwise, `$err` is cleared. `$of` is cleared. -### EQ: Equals +### `EQ`: Equals | | | |-------------|--------------------------------------| @@ -306,7 +306,7 @@ Panic if: `$of` and `$err` are cleared. -### EXP: Exponentiate +### `EXP`: Exponentiate | | | |-------------|----------------------------------------------| @@ -324,7 +324,7 @@ If the result cannot fit in 8 bytes, `$of` is set to `1` and `$rA` is instead se `$err` is cleared. -### EXPI: Exponentiate immediate +### `EXPI`: Exponentiate immediate | | | |-------------|---------------------------------------------------------| @@ -342,7 +342,7 @@ If the result cannot fit in 8 bytes, `$of` is set to `1` and `$rA` is instead se `$err` is cleared. -### GT: Greater than +### `GT`: Greater than | | | |-------------|------------------------------------------| @@ -358,7 +358,7 @@ Panic if: `$of` and `$err` are cleared. -### LT: Less than +### `LT`: Less than | | | |-------------|---------------------------------------| @@ -374,7 +374,7 @@ Panic if: `$of` and `$err` are cleared. -### MLOG: Math logarithm +### `MLOG`: Math logarithm | | | |-------------|----------------------------------------------| @@ -394,7 +394,7 @@ If `$rC <= 1`, both `$rA` and `$of` are cleared and `$err` is set to `true`. Otherwise, `$of` and `$err` are cleared. -### MOD: Modulus +### `MOD`: Modulus | | | |-------------|------------------------------------| @@ -412,7 +412,7 @@ If `$rC == 0`, both `$rA` and `$of` are cleared and `$err` is set to `true`. Otherwise, `$of` and `$err` are cleared. -### MODI: Modulus immediate +### `MODI`: Modulus immediate | | | |-------------|--------------------------------------------------------| @@ -430,7 +430,7 @@ If `imm == 0`, both `$rA` and `$of` are cleared and `$err` is set to `true`. Otherwise, `$of` and `$err` are cleared. -### MOVE: Move +### `MOVE`: Move | | | |-------------|------------------------------------| @@ -446,7 +446,7 @@ Panic if: `$of` and `$err` are cleared. -### MOVI: Move immediate +### `MOVI`: Move immediate | | | |-------------|------------------------------------------| @@ -462,11 +462,11 @@ Panic if: `$of` and `$err` are cleared. -### MROO: Math root +### `MROO`: Math root | | | |-------------|----------------------------------------------| -| Description | The (integer) `$rC`th root of `$rB`. | +| Description | The (integer) `$rCth` root of `$rB`. | | Operation | ```$rA = math.floor(math.root($rB, $rC));``` | | Syntax | `mroo $rA, $rB, $rC` | | Encoding | `0x00 rA rB rC -` | @@ -480,7 +480,7 @@ If `$rC == 0`, both `$rA` and `$of` are cleared and `$err` is set to `true`. Otherwise, `$of` and `$err` are cleared. -### MUL: Multiply +### `MUL`: Multiply | | | |-------------|---------------------------| @@ -498,7 +498,7 @@ Panic if: `$err` is cleared. -### MULI: Multiply immediate +### `MULI`: Multiply immediate | | | |-------------|-----------------------------------------------| @@ -516,7 +516,7 @@ Panic if: `$err` is cleared. -### MLDV: Fused multiply-divide +### `MLDV`: Fused multiply-divide | | | |-------------|--------------------------------------------------------------------------------------| @@ -532,7 +532,7 @@ If the result of after the division doesn't fit into a register, `$of` is assign `$err` is cleared. -### NOOP: No operation +### `NOOP`: No operation | | | |-------------|------------------------| @@ -544,7 +544,7 @@ If the result of after the division doesn't fit into a register, `$of` is assign `$of` and `$err` are cleared. -### NOT: Invert +### `NOT`: Invert | | | |-------------|-------------------------| @@ -560,7 +560,7 @@ Panic if: `$of` and `$err` are cleared. -### OR: OR +### `OR`: OR | | | |-------------|----------------------------| @@ -576,7 +576,7 @@ Panic if: `$of` and `$err` are cleared. -### ORI: OR immediate +### `ORI`: OR immediate | | | |-------------|------------------------------------------------| @@ -594,7 +594,7 @@ Panic if: `$of` and `$err` are cleared. -### SLL: Shift left logical +### `SLL`: Shift left logical | | | |-------------|---------------------------------------| @@ -610,7 +610,7 @@ Panic if: `$of` and `$err` are cleared. -### SLLI: Shift left logical immediate +### `SLLI`: Shift left logical immediate | | | |-------------|-----------------------------------------------| @@ -626,7 +626,7 @@ Panic if: `$of` and `$err` are cleared. -### SRL: Shift right logical +### `SRL`: Shift right logical | | | |-------------|----------------------------------------| @@ -642,7 +642,7 @@ Panic if: `$of` and `$err` are cleared. -### SRLI: Shift right logical immediate +### `SRLI`: Shift right logical immediate | | | |-------------|------------------------------------------------| @@ -658,7 +658,7 @@ Panic if: `$of` and `$err` are cleared. -### SUB: Subtract +### `SUB`: Subtract | | | |-------------|--------------------------------------------------| @@ -676,7 +676,7 @@ Panic if: `$err` is cleared. -### SUBI: Subtract immediate +### `SUBI`: Subtract immediate | | | |-------------|--------------------------------------------------| @@ -694,7 +694,7 @@ Panic if: `$err` is cleared. -### WDCM: 128-bit integer comparison +### `WDCM`: 128-bit integer comparison | | | |-------------|-------------------------------------------------------------------------------| @@ -710,19 +710,19 @@ Bits | Short name | Description ---------|------------|------------------------------------- `...XXX` | `mode` | Compare mode selection `.XX...` | `reserved` | Reserved and must be zero -`X.....` | `indirect` | Is rhs operand ($rC) indirect or not +`X.....` | `indirect` | Is rhs operand (`$rC`) indirect or not Then the actual operation that's performed: `mode` | Name | Description -------|------|------------------------------------------------------------- -0 | eq | Equality (`==`) -1 | ne | Inequality (`!=`) -2 | lt | Less than (`<`) -3 | gt | Greater than (`>`) -4 | lte | Less than or equals (`<=`) -5 | gte | Greater than or equals (`>=`) -6 | lzc | Leading zero count the lhs argument (`lzcnt`). Discards rhs. +0 | `eq` | Equality (`==`) +1 | `ne` | Inequality (`!=`) +2 | `lt` | Less than (`<`) +3 | `gt` | Greater than (`>`) +4 | `lte` | Less than or equals (`<=`) +5 | `gte` | Greater than or equals (`>=`) +6 | `lzc` | Leading zero count the lhs argument (`lzcnt`). Discards rhs. 7 | - | Reserved and must not be used The leading zero count can be used to compute rounded-down log2 of a number using the following formula `TOTAL_BITS - 1 - lzc(n)`. Note that `log2(0)` is undefined, and will lead to integer overflow with this method. @@ -736,7 +736,7 @@ Panic if: - `$rB + 16` overflows or `> VM_MAX_RAM` - `indirect == 1` and `$rC + 16` overflows or `> VM_MAX_RAM` -### WQCM: 256-bit integer comparison +### `WQCM`: 256-bit integer comparison | | | |-------------|-------------------------------------------------------------------------------| @@ -757,7 +757,7 @@ Panic if: - `$rB + 32` overflows or `> VM_MAX_RAM` - `indirect == 1` and `$rC + 32` overflows or `> VM_MAX_RAM` -### WDOP: Misc 128-bit integer operations +### `WDOP`: Misc 128-bit integer operations | | | |-------------|-----------------------------------------------------------------------------------| @@ -773,20 +773,20 @@ Bits | Short name | Description ---------|------------|------------------------------------- `...XXX` | `op` | Operation selection, see below `.XX...` | `reserved` | Reserved and must be zero -`X.....` | `indirect` | Is rhs operand ($rC) indirect or not +`X.....` | `indirect` | Is rhs operand (`$rC`) indirect or not Then the actual operation that's performed: `op` | Name | Description -----|------|--------------------------- -0 | add | Add -1 | sub | Subtract -2 | not | Invert bits (discards rhs) -3 | or | Bitwise or -4 | xor | Bitwise exclusive or -5 | and | Bitwise and -6 | shl | Shift left (logical) -7 | shr | Shift right (logical) +0 | `add` | Add +1 | `sub` | Subtract +2 | `not` | Invert bits (discards rhs) +3 | `or` | Bitwise or +4 | `xor` | Bitwise exclusive or +5 | `and` | Bitwise and +6 | `shl` | Shift left (logical) +7 | `shr` | Shift right (logical) Operations behave `$of` and `$err` similarly to their 64-bit counterparts, except that `$of` is set to `1` instead of the overflowing part. @@ -797,7 +797,7 @@ Panic if: - `$rB + 16` overflows or `> VM_MAX_RAM` - `indirect == 1` and `$rC + 16` overflows or `> VM_MAX_RAM` -### WQOP: Misc 256-bit integer operations +### `WQOP`: Misc 256-bit integer operations | | | |-------------|-----------------------------------------------------------------------------------| @@ -818,7 +818,7 @@ Panic if: - `$rB + 32` overflows or `> VM_MAX_RAM` - `indirect == 1` and `$rC + 32` overflows or `> VM_MAX_RAM` -### WDML: Multiply 128-bit integers +### `WDML`: Multiply 128-bit integers | | | |-------------|----------------------------------------------------------------------------------------| @@ -833,8 +833,8 @@ The six-bit immediate value is used to select operating mode, as follows: Bits | Short name | Description ---------|-------------|------------------------------------- `..XXXX` | `reserved` | Reserved and must be zero -`.X....` | `indirect0` | Is lhs operand ($rB) indirect or not -`X.....` | `indirect1` | Is rhs operand ($rC) indirect or not +`.X....` | `indirect0` | Is lhs operand (`$rB`) indirect or not +`X.....` | `indirect1` | Is rhs operand (`$rC`) indirect or not `$of` is set to `1` in case of overflow, and cleared otherwise. @@ -847,7 +847,7 @@ Panic if: - `indirect0 == 1` and `$rB + 16` overflows or `> VM_MAX_RAM` - `indirect1 == 1` and `$rC + 16` overflows or `> VM_MAX_RAM` -### WQML: Multiply 256-bit integers +### `WQML`: Multiply 256-bit integers | | | |-------------|----------------------------------------------------------------------------------------| @@ -870,7 +870,7 @@ Panic if: - `indirect0 == 1` and `$rB + 32` overflows or `> VM_MAX_RAM` - `indirect1 == 1` and `$rC + 32` overflows or `> VM_MAX_RAM` -### WDDV: 128-bit integer division +### `WDDV`: 128-bit integer division | | | |-------------|---------------------------------------------------------------------------------| @@ -885,7 +885,7 @@ The six-bit immediate value is used to select operating mode, as follows: Bits | Short name | Description ---------|------------|------------------------------------- `.XXXXX` | `reserved` | Reserved and must be zero -`X.....` | `indirect` | Is rhs operand ($rC) indirect or not +`X.....` | `indirect` | Is rhs operand (`$rC`) indirect or not `$of` is cleared. @@ -898,7 +898,7 @@ Panic if: - `$rB + 16` overflows or `> VM_MAX_RAM` - `indirect == 1` and `$rC + 16` overflows or `> VM_MAX_RAM` -### WQDV: 256-bit integer division +### `WQDV`: 256-bit integer division | | | |-------------|---------------------------------------------------------------------------------| @@ -921,7 +921,7 @@ Panic if: - `$rB + 32` overflows or `> VM_MAX_RAM` - `indirect == 1` and `$rC + 32` overflows or `> VM_MAX_RAM` -### WDMD: 128-bit integer fused multiply-divide +### `WDMD`: 128-bit integer fused multiply-divide | | | |-------------|----------------------------------------------------------------------------------------| @@ -944,7 +944,7 @@ Panic if: - `$rC + 16` overflows or `> VM_MAX_RAM` - `$rD + 16` overflows or `> VM_MAX_RAM` -### WQMD: 256-bit integer fused multiply-divide +### `WQMD`: 256-bit integer fused multiply-divide | | | |-------------|----------------------------------------------------------------------------------------| @@ -967,7 +967,7 @@ Panic if: - `$rC + 32` overflows or `> VM_MAX_RAM` - `$rD + 32` overflows or `> VM_MAX_RAM` -### WDAM: Modular 128-bit integer addition +### `WDAM`: Modular 128-bit integer addition | | | |-------------|--------------------------------------------------------------------------------------| @@ -988,7 +988,7 @@ Panic if: - `$rC + 16` overflows or `> VM_MAX_RAM` - `$rD + 16` overflows or `> VM_MAX_RAM` -### WQAM: Modular 256-bit integer addition +### `WQAM`: Modular 256-bit integer addition | | | |-------------|--------------------------------------------------------------------------------------| @@ -1009,7 +1009,7 @@ Panic if: - `$rC + 32` overflows or `> VM_MAX_RAM` - `$rD + 32` overflows or `> VM_MAX_RAM` -### WDMM: Modular 128-bit integer multiplication +### `WDMM`: Modular 128-bit integer multiplication | | | |-------------|--------------------------------------------------------------------------------------| @@ -1030,7 +1030,7 @@ Panic if: - `$rC + 16` overflows or `> VM_MAX_RAM` - `$rD + 16` overflows or `> VM_MAX_RAM` -### WQMM: Modular 256-bit integer multiplication +### `WQMM`: Modular 256-bit integer multiplication | | | |-------------|--------------------------------------------------------------------------------------| @@ -1051,7 +1051,7 @@ Panic if: - `$rC + 32` overflows or `> VM_MAX_RAM` - `$rD + 32` overflows or `> VM_MAX_RAM` -### XOR: XOR +### `XOR`: XOR | | | |-------------|-----------------------------| @@ -1067,7 +1067,7 @@ Panic if: `$of` and `$err` are cleared. -### XORI: XOR immediate +### `XORI`: XOR immediate | | | |-------------|-------------------------------------------------| @@ -1085,7 +1085,7 @@ Panic if: ## Control Flow Instructions -### JMP: Jump +### `JMP`: Jump | | | |-------------|-----------------------------------------------------| @@ -1099,7 +1099,7 @@ Panic if: - `$is + $rA * 4 > VM_MAX_RAM - 1` -### JI: Jump immediate +### `JI`: Jump immediate | | | |-------------|------------------------------------------------| @@ -1113,7 +1113,7 @@ Panic if: - `$is + imm * 4 > VM_MAX_RAM - 1` -### JNE: Jump if not equal +### `JNE`: Jump if not equal | | | |-------------|--------------------------------------------------------------------------------------| @@ -1127,7 +1127,7 @@ Panic if: - `$is + $rC * 4 > VM_MAX_RAM - 1` and the jump would be performed (i.e. `$rA != $rB`) -### JNEI: Jump if not equal immediate +### `JNEI`: Jump if not equal immediate | | | |-------------|--------------------------------------------------------------------------------------| @@ -1141,7 +1141,7 @@ Panic if: - `$is + imm * 4 > VM_MAX_RAM - 1` and the jump would be performed (i.e. `$rA != $rB`) -### JNZI: Jump if not zero immediate +### `JNZI`: Jump if not zero immediate | | | |-------------|----------------------------------------------------------------------------------------| @@ -1155,7 +1155,7 @@ Panic if: - `$is + imm * 4 > VM_MAX_RAM - 1`and the jump would be performed (i.e. `$rA != $zero`) -### JMPB: Jump relative backwards +### `JMPB`: Jump relative backwards | | | |-------------|------------------------------------------| @@ -1169,7 +1169,7 @@ Panic if: - `$pc - ($rA + imm + 1) * 4 < 0` -### JMPF: Jump relative forwards +### `JMPF`: Jump relative forwards | | | |-------------|----------------------------------------| @@ -1183,7 +1183,7 @@ Panic if: - `$pc + ($rA + imm + 1) * 4 > VM_MAX_RAM - 1` -### JNZB: Jump if not zero relative backwards +### `JNZB`: Jump if not zero relative backwards | | | |-------------|-------------------------------------------------------------------------------| @@ -1197,7 +1197,7 @@ Panic if: - `$pc - ($rB + imm + 1) * 4 < 0` -### JNZF: Jump if not zero relative forwards +### `JNZF`: Jump if not zero relative forwards | | | |-------------|-------------------------------------------------------------------------------| @@ -1211,7 +1211,7 @@ Panic if: - `$pc + ($rB + imm + 1) * 4 > VM_MAX_RAM - 1` -### JNEB: Jump if not equal relative backwards +### `JNEB`: Jump if not equal relative backwards | | | |-------------|-----------------------------------------------------------------------------| @@ -1225,7 +1225,7 @@ Panic if: - `$pc - ($rC + imm + 1) * 4 < 0` -### JNEF: Jump if not equal relative forwards +### `JNEF`: Jump if not equal relative forwards | | | |-------------|-----------------------------------------------------------------------------| @@ -1239,7 +1239,7 @@ Panic if: - `$pc + ($rC + imm + 1) * 4 > VM_MAX_RAM - 1` -### RET: Return from context +### `RET`: Return from context | | | |-------------|---------------------------------------------------------------| @@ -1288,7 +1288,7 @@ Then pop the call frame and restore all registers _except_ `$ggas`, `$cgas`, `$r All these instructions advance the program counter `$pc` by `4` after performing their operation. -### ALOC: Allocate memory +### `ALOC`: Allocate memory | | | |-------------|-------------------------------------------| @@ -1303,7 +1303,7 @@ Panic if: - `$hp - $rA` underflows - `$hp - $rA < $sp` -### CFE: Extend call frame +### `CFE`: Extend call frame | | | |-------------|----------------------------------------| @@ -1318,7 +1318,7 @@ Panic if: - `$sp + $rA` overflows - `$sp + $rA > $hp` -### CFEI: Extend call frame immediate +### `CFEI`: Extend call frame immediate | | | |-------------|--------------------------------------------------------------| @@ -1333,7 +1333,7 @@ Panic if: - `$sp + imm` overflows - `$sp + imm > $hp` -### CFS: Shrink call frame +### `CFS`: Shrink call frame | | | |-------------|----------------------------------------| @@ -1348,7 +1348,7 @@ Panic if: - `$sp - $rA` underflows - `$sp - $rA < $ssp` -### CFSI: Shrink call frame immediate +### `CFSI`: Shrink call frame immediate | | | |-------------|--------------------------------------------------------------| @@ -1363,7 +1363,7 @@ Panic if: - `$sp - imm` underflows - `$sp - imm < $ssp` -### LB: Load byte +### `LB`: Load byte | | | |-------------|--------------------------------------------------------------| @@ -1379,7 +1379,7 @@ Panic if: - `$rB + imm + 1` overflows - `$rB + imm + 1 > VM_MAX_RAM` -### LW: Load word +### `LW`: Load word | | | |-------------|--------------------------------------------------------------| @@ -1395,7 +1395,7 @@ Panic if: - `$rB + (imm * 8) + 8` overflows - `$rB + (imm * 8) + 8 > VM_MAX_RAM` -### MCL: Memory clear +### `MCL`: Memory clear | | | |-------------|--------------------------| @@ -1411,7 +1411,7 @@ Panic if: - `$rA + $rB > VM_MAX_RAM` - The memory range `MEM[$rA, $rB]` does not pass [ownership check](./index.md#ownership) -### MCLI: Memory clear immediate +### `MCLI`: Memory clear immediate | | | |-------------|--------------------------| @@ -1427,7 +1427,7 @@ Panic if: - `$rA + imm > VM_MAX_RAM` - The memory range `MEM[$rA, imm]` does not pass [ownership check](./index.md#ownership) -### MCP: Memory copy +### `MCP`: Memory copy | | | |-------------|--------------------------------------| @@ -1446,7 +1446,7 @@ Panic if: - The memory ranges `MEM[$rA, $rC]` and `MEM[$rB, $rC]` overlap - The memory range `MEM[$rA, $rC]` does not pass [ownership check](./index.md#ownership) -### MCPI: Memory copy immediate +### `MCPI`: Memory copy immediate | | | |-------------|--------------------------------------| @@ -1465,7 +1465,7 @@ Panic if: - The memory ranges `MEM[$rA, imm]` and `MEM[$rB, imm]` overlap - The memory range `MEM[$rA, imm]` does not pass [ownership check](./index.md#ownership) -### MEQ: Memory equality +### `MEQ`: Memory equality | | | |-------------|---------------------------------------------| @@ -1483,7 +1483,7 @@ Panic if: - `$rB + $rD > VM_MAX_RAM` - `$rC + $rD > VM_MAX_RAM` -### PSHH: Push a set of high registers to stack +### `PSHH`: Push a set of high registers to stack | | | |-------------|-----------------------------------------------------------------------------------| @@ -1498,7 +1498,7 @@ Panic if: - `$sp + popcnt(imm)*8` overflows - `$sp + popcnt(imm)*8 > $hp` -### PSHL: Push a set of low registers to stack +### `PSHL`: Push a set of low registers to stack | | | |-------------|-----------------------------------------------------------------------------------| @@ -1513,7 +1513,7 @@ Panic if: - `$sp + popcnt(imm)*8` overflows - `$sp + popcnt(imm)*8 > $hp` -### POPH: Pop a set of high registers from stack +### `POPH`: Pop a set of high registers from stack | | | |-------------|---------------------------------------------------------------------------------------| @@ -1528,7 +1528,7 @@ Panic if: - `$sp - popcnt(imm)*8` overflows - `$sp - popcnt(imm)*8 < $ssp` -### POPL: Pop a set of low registers from stack +### `POPL`: Pop a set of low registers from stack | | | |-------------|---------------------------------------------------------------------------------------| @@ -1543,7 +1543,7 @@ Panic if: - `$sp - popcnt(imm)*8` overflows - `$sp - popcnt(imm)*8 < $ssp` -### SB: Store byte +### `SB`: Store byte | | | |-------------|-------------------------------------------------------------------------------------| @@ -1559,7 +1559,7 @@ Panic if: - `$rA + imm + 1 > VM_MAX_RAM` - The memory range `MEM[$rA + imm, 1]` does not pass [ownership check](./index.md#ownership) -### SW: Store word +### `SW`: Store word | | | |-------------|--------------------------------------------------------------------| @@ -1577,9 +1577,9 @@ Panic if: ## Contract Instructions -All these instructions advance the program counter `$pc` by `4` after performing their operation, except for [CALL](#call-call-contract), [RETD](#retd-return-from-context-with-data) and [RVRT](#rvrt-revert). +All these instructions advance the program counter `$pc` by `4` after performing their operation, except for [CALL](#call-call-contract), [`RETD`](#retd-return-from-context-with-data) and [`RVRT`](#rvrt-revert). -### BAL: Balance of contract ID +### `BAL`: Balance of contract ID | | | |-------------|------------------------------------------------------------------------------| @@ -1601,7 +1601,7 @@ Panic if: - `$rC + 32 > VM_MAX_RAM` - Contract with ID `MEM[$rC, 32]` is not in `tx.inputs` -### BHEI: Block height +### `BHEI`: Block height | | | |-------------|----------------------------| @@ -1615,7 +1615,7 @@ Panic if: - `$rA` is a [reserved register](./index.md#semantics) -### BHSH: Block hash +### `BHSH`: Block hash | | | |-------------|--------------------------------------| @@ -1633,7 +1633,7 @@ Panic if: Block header hashes for blocks with height greater than or equal to current block height are zero (```0x00**32```). -### BURN: Burn existing coins +### `BURN`: Burn existing coins | | | |-------------|-------------------------------------------------------------| @@ -1655,7 +1655,7 @@ For output with contract ID `MEM[$fp, 32]`, decrease balance of asset ID `constr This modifies the `balanceRoot` field of the appropriate output. -Append a receipt to the list of receipts, modifying tx.receiptsRoot: +Append a receipt to the list of receipts, modifying `tx.receiptsRoot`: | name | type | description | |---------------|---------------|--------------------------------------------| @@ -1666,7 +1666,7 @@ Append a receipt to the list of receipts, modifying tx.receiptsRoot: | `pc` | `uint64` | Value of register `$pc`. | | `is` | `uint64` | Value of register `$is`. | -### CALL: Call contract +### `CALL`: Call contract | | | |-------------|------------------------| @@ -1725,7 +1725,7 @@ A [call frame](./index.md#call-frames) is pushed at `$sp`. In addition to fillin This modifies the `balanceRoot` field of the appropriate output(s). -### CB: Coinbase contract id +### `CB`: Coinbase contract id | | | |-------------|---------------------------------------------------------------------------------------------------------------------| @@ -1741,7 +1741,7 @@ Panic if: - `$rA + 32 > VM_MAX_RAM` - The memory range `MEM[$rA, 32]` does not pass [ownership check](./index.md#ownership) -### CCP: Code copy +### `CCP`: Code copy | | | |-------------|--------------------------------------------------------------------------------------------------------------------------------------------------| @@ -1763,7 +1763,7 @@ Panic if: - The memory range `MEM[$rA, $rD]` does not pass [ownership check](./index.md#ownership) - Contract with ID `MEM[$rB, 32]` is not in `tx.inputs` -### CROO: Code Merkle root +### `CROO`: Code Merkle root | | | |-------------|---------------------------------------------------------------------------------------------------------------------------------------| @@ -1784,7 +1784,7 @@ Panic if: Code root computation is defined [here](../identifiers/contract-id.md). -### CSIZ: Code size +### `CSIZ`: Code size | | | |-------------|-----------------------------------------------------------------------------------------------------------| @@ -1801,7 +1801,7 @@ Panic if: - `$rB + 32 > VM_MAX_RAM` - Contract with ID `MEM[$rB, 32]` is not in `tx.inputs` -### LDC: Load code from an external contract +### `LDC`: Load code from an external contract | | | |-------------|---------------------------------------------------------------------------------------------------------------------------------------------------| @@ -1825,7 +1825,7 @@ Increment `$fp->codesize`, `$ssp` by `$rC` padded to word alignment. Then set `$ This instruction can be used to concatenate the code of multiple contracts together. It can only be used when the stack area of the call frame is unused (i.e. prior to being used). -### LOG: Log event +### `LOG`: Log event | | | |-------------|--------------------------------| @@ -1848,7 +1848,7 @@ Append a receipt to the list of receipts, modifying `tx.receiptsRoot`: | `pc` | `uint64` | Value of register `$pc`. | | `is` | `uint64` | Value of register `$is`. | -### LOGD: Log data event +### `LOGD`: Log data event | | | |-------------|---------------------------------| @@ -1879,7 +1879,7 @@ Panics if: - `$rC + $rD` overflows - `$rA + $rD > VM_MAX_RAM` -### MINT: Mint new coins +### `MINT`: Mint new coins | | | |-------------|-------------------------------------------------------------| @@ -1901,7 +1901,7 @@ For output with contract ID `MEM[$fp, 32]`, increase balance of asset ID `constr This modifies the `balanceRoot` field of the appropriate output. -Append a receipt to the list of receipts, modifying tx.receiptsRoot: +Append a receipt to the list of receipts, modifying `tx.receiptsRoot`: | name | type | description | |---------------|---------------|--------------------------------------------| @@ -1912,7 +1912,7 @@ Append a receipt to the list of receipts, modifying tx.receiptsRoot: | `pc` | `uint64` | Value of register `$pc`. | | `is` | `uint64` | Value of register `$is`. | -### RETD: Return from context with data +### `RETD`: Return from context with data | | | |-------------|-------------------------------------------------------------------------| @@ -1964,7 +1964,7 @@ Then pop the call frame and restore all registers _except_ `$ggas`, `$cgas`, `$r 1. `$pc = $pc + 4` (advance program counter from where we called) -### RVRT: Revert +### `RVRT`: Revert | | | |-------------|-----------------------------------------------------------------------| @@ -1994,10 +1994,10 @@ Then append an additional receipt to the list of receipts, modifying `tx.receipt Cease VM execution and revert script effects. After a revert: -1. All [OutputContract](../tx-format/output.md#outputcontract) outputs will have the same `balanceRoot` and `stateRoot` as on initialization. -1. All [OutputVariable](../tx-format/output.md#outputvariable) outputs will have `to`, `amount`, and `asset_id` of zero. +1. All [`OutputContract`](../tx-format/output.md#outputcontract) outputs will have the same `balanceRoot` and `stateRoot` as on initialization. +1. All [`OutputVariable`](../tx-format/output.md#outputvariable) outputs will have `to`, `amount`, and `asset_id` of zero. -### SMO: Send message out +### `SMO`: Send message out | | | |-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -2034,7 +2034,7 @@ Append a receipt to the list of receipts, modifying `tx.receiptsRoot`: In an external context, decrease `MEM[balanceOfStart(0), 8]` by `$rD`. In an internal context, decrease asset ID 0 balance of output with contract ID `MEM[$fp, 32]` by `$rD`. This modifies the `balanceRoot` field of the appropriate contract that had its' funds deducted. -### SCWQ: State clear sequential 32 byte slots +### `SCWQ`: State clear sequential 32 byte slots | | | |-------------|-------------------------------------------------------------------------------| @@ -2053,7 +2053,7 @@ Panic if: Register `$rB` will be set to `false` if any storage slot in the requested range was already unset (default) and `true` if all the slots were set. -### SRW: State read word +### `SRW`: State read word | | | |-------------|---------------------------------------------------| @@ -2074,7 +2074,7 @@ Panic if: Register `$rB` will be set to `false` if the requested slot is unset (default) and `true` if it's set. -### SRWQ: State read sequential 32 byte slots +### `SRWQ`: State read sequential 32 byte slots | | | |-------------|----------------------------------------------------------------------------| @@ -2097,7 +2097,7 @@ Panic if: Register `$rB` will be set to `false` if any storage slot in the requested range is unset (default) and `true` if all the slots are set. -### SWW: State write word +### `SWW`: State write word | | | |-------------|---------------------------------------------------------------------------------| @@ -2115,9 +2115,9 @@ Panic if: - `$rB` is a [reserved register](./index.md#semantics) - `$fp == 0` (in the script context) -The last 24 bytes of `STATE[MEM[$rA, 32]]` are set to `0`. Register `$rB` will be set to the number of new slots written, i.e. `1` if the slot was previously unset, and `0` if it alreaady contained a value. +The last 24 bytes of `STATE[MEM[$rA, 32]]` are set to `0`. Register `$rB` will be set to the number of new slots written, i.e. `1` if the slot was previously unset, and `0` if it already contained a value. -### SWWQ: State write sequential 32 byte slots +### `SWWQ`: State write sequential 32 byte slots | | | |-------------|-----------------------------------------------------------------------------| @@ -2139,7 +2139,7 @@ Panic if: Register `$rB` will be set to the number of storage slots that were previously unset, and were set by this operation. -### TIME: Timestamp at height +### `TIME`: Timestamp at height | | | |-------------|-----------------------------------------| @@ -2156,7 +2156,7 @@ Panic if: Gets the timestamp of the block at height `$rB`. Time is in [TAI64](https://cr.yp.to/libtai/tai64.html) format. -### TR: Transfer coins to contract +### `TR`: Transfer coins to contract | | | |-------------|---------------------------------------------------------------------------| @@ -2196,7 +2196,7 @@ For output with contract ID `MEM[$rA, 32]`, increase balance of asset ID `MEM[$r This modifies the `balanceRoot` field of the appropriate output(s). -### TRO: Transfer coins to output +### `TRO`: Transfer coins to output | | | |-------------|-------------------------------------------------------------------------------------| @@ -2246,7 +2246,7 @@ This modifies the `balanceRoot` field of the appropriate output(s). All these instructions advance the program counter `$pc` by `4` after performing their operation. -### ECK1: Secp256k1 signature recovery +### `ECK1`: Secp256k1 signature recovery | | | |-------------|-----------------------------------------------------------------------------------------------------------------------------| @@ -2272,7 +2272,7 @@ If the signature cannot be verified, `MEM[$rA, 64]` is set to `0` and `$err` is To get the address from the public key, hash the public key with [SHA-2-256](../protocol/cryptographic-primitives.md#hashing). -### ECR1: Secp256r1 signature recovery +### `ECR1`: Secp256r1 signature recovery | | | |-------------|-----------------------------------------------------------------------------------------------------------------------------| @@ -2298,7 +2298,7 @@ If the signature cannot be verified, `MEM[$rA, 64]` is set to `0` and `$err` is To get the address from the public key, hash the public key with [SHA-2-256](../protocol/cryptographic-primitives.md#hashing). -### ED19: edDSA curve25519 verification +### `ED19`: EdDSA curve25519 verification | | | |-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| @@ -2321,7 +2321,7 @@ Verification are specified [here](../protocol/cryptographic-primitives.md#eddsa- If there is an error in verification, `$err` is set to `1`, otherwise `$err` is cleared. -### K256: keccak-256 +### `K256`: keccak-256 | | | |-------------|-------------------------------------------------------| @@ -2339,7 +2339,7 @@ Panic if: - `$rB + $rC > VM_MAX_RAM` - The memory range `MEM[$rA, 32]` does not pass [ownership check](./index.md#ownership) -### S256: SHA-2-256 +### `S256`: SHA-2-256 | | | |-------------|------------------------------------------------------| @@ -2361,7 +2361,7 @@ Panic if: All these instructions advance the program counter `$pc` by `4` after performing their operation. -### ECAL: Call external function +### `ECAL`: Call external function | | | |-------------|--------------------------------------------------------------------------| @@ -2377,7 +2377,7 @@ Panic if: - The external function panics. -### FLAG: Set flags +### `FLAG`: Set flags | | | |-------------|-----------------------| @@ -2391,7 +2391,7 @@ Panic if: - Any reserved flags are set -### GM: Get metadata +### `GM`: Get metadata | | | |-------------|---------------------------| @@ -2435,7 +2435,7 @@ Panic if: Set `$rA` to the index of the currently-verifying predicate. -### GTF: Get transaction fields +### `GTF`: Get transaction fields | | | |-------------|-------------------------| diff --git a/src/protocol/cryptographic-primitives.md b/src/protocol/cryptographic-primitives.md index bc43d0b5..89151577 100644 --- a/src/protocol/cryptographic-primitives.md +++ b/src/protocol/cryptographic-primitives.md @@ -11,7 +11,7 @@ All hashing is done with SHA-2-256 (also known as SHA-256), defined in [FIPS 180-4](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf). -## HashDigest +## `HashDigest` Output of the [hashing](#hashing) function. Exactly 256 bits (32 bytes) long. @@ -27,7 +27,7 @@ Nodes contain a single field: | name | type | description | |------|---------------------------|-------------| -| `v` | [HashDigest](#hashdigest) | Node value. | +| `v` | [`HashDigest`](#hashdigest) | Node value. | The base case (an empty tree) is defined as the [hash](#hashing) of the empty string: @@ -55,9 +55,9 @@ Leaves and internal nodes are hashed differently: the one-byte `0x00` is prepend | name | type | description | |------------|-------------------------------|-----------------------------------------------------------------| -| `root` | [HashDigest](#hashdigest)`[]` | The expected root of the Merkle tree. | +| `root` | [`HashDigest`](#hashdigest)`[]` | The expected root of the Merkle tree. | | `data` | Bytes | The data of the leaf (unhashed). | -| `siblings` | [HashDigest](#hashdigest)`[]` | Sibling hash values, ordered starting from the leaf's neighbor. | +| `siblings` | [`HashDigest`](#hashdigest)`[]` | Sibling hash values, ordered starting from the leaf's neighbor. | A proof for a leaf in a [binary Merkle tree](#binary-merkle-tree), as per Section 2.1.1 of [Certificate Transparency (RFC-6962)](https://tools.ietf.org/html/rfc6962#section-2.1.1). @@ -77,7 +77,7 @@ Nodes contain a single field: | name | type | description | |------|---------------------------|-------------| -| `v` | [HashDigest](#hashdigest) | Node value. | +| `v` | [`HashDigest`](#hashdigest) | Node value. | In the base case, where a sparse Merkle tree has `height = 0`, the root of a tree is defined as the [hash](#hashing) of the empty string: @@ -125,7 +125,7 @@ A proof into an SMT is structured as: | name | type | description | |--------------------|-------------------------------|--------------------------------------------------------------------------| | `depth` | `uint16` | Depth of the leaf node. The root node is at depth `0`. Must be `<= 256`. | -| `siblings` | [HashDigest](#hashdigest)`[]` | Sibling hash values, ordered starting from the leaf's neighbor. | +| `siblings` | [`HashDigest`](#hashdigest)`[]` | Sibling hash values, ordered starting from the leaf's neighbor. | | `includedSiblings` | `byte[32]` | Bitfield of explicitly included sibling hashes. | The `includedSiblings` is ordered by most-significant-byte first, with each byte ordered by most-significant-bit first. The lowest bit corresponds to the leaf node level. @@ -134,7 +134,7 @@ A specification describing a suite of test vectors and outputs of a Sparse Merkl ## ECDSA Public-Key Cryptography -Consensus-critical data is authenticated using [ECDSA](https://www.secg.org/sec1-v2.pdf), with the curve [secp256k1](https://en.bitcoin.it/wiki/Secp256k1). A highly-optimized library is available in C (), with wrappers in Go () and Rust (). +Consensus-critical data is authenticated using [ECDSA](https://www.secg.org/sec1-v2.pdf), with the curve [secp256k1](https://en.bitcoin.it/wiki/Secp256k1). A highly-optimized library is available in [C](https://github.com/bitcoin-core/secp256k1), with wrappers in [Go](https://pkg.go.dev/github.com/ethereum/go-ethereum/crypto/secp256k1) and [Rust](https://docs.rs/crate/secp256k1). Public keys are encoded in uncompressed form, as the concatenation of the `x` and `y` values. No prefix is needed to distinguish between encoding schemes as this is the only encoding supported. diff --git a/src/protocol/tx-validity.md b/src/protocol/tx-validity.md index 393eea94..24ce8bb5 100644 --- a/src/protocol/tx-validity.md +++ b/src/protocol/tx-validity.md @@ -1,6 +1,6 @@ # Transaction Validity -- [Transaction Lifecycle](#transaction-lifecycle) +- [Transaction Life Cycle](#transaction-life-cycle) - [Access Lists](#access-lists) - [VM Precondition Validity Rules](#vm-precondition-validity-rules) - [Base Sanity Checks](#base-sanity-checks) @@ -13,7 +13,7 @@ - [Correct Change](#correct-change) - [State Changes](#state-changes) -## Transaction Lifecycle +## Transaction Life Cycle Once a transaction is seen, it goes through several stages of validation, in this order: @@ -54,7 +54,7 @@ This section defines _VM precondition validity rules_ for transactions: the bare For a transaction `tx`, UTXO set `state`, contract set `contracts`, and message set `messages`, the following checks must pass. -> **Note:** [InputMessages](../tx-format/input.md#inputmessage) where `input.dataLength > 0` are not dropped from the `messages` message set until they are included in a transaction of type `TransactionType.Script` with a `ScriptResult` receipt where `result` is equal to `0` indicating a successful script exit. +> **Note:** [`InputMessages`](../tx-format/input.md#inputmessage) where `input.dataLength > 0` are not dropped from the `messages` message set until they are included in a transaction of type `TransactionType.Script` with a `ScriptResult` receipt where `result` is equal to `0` indicating a successful script exit. ### Base Sanity Checks @@ -330,10 +330,11 @@ max_fee = gas_to_fee(max_gas, tx.gasPrice) ``` The cost of the transaction `cost(tx)` must lie within the range defined by [`min_fee`, `max_fee`]. `min_gas` is defined as the sum of all intrinsic costs of the transaction known prior to execution. The definition of `max_gas` illustrates that the delta between minimum gas and maximum gas is the sum of: -- The remaining allocation of witness bytes, converted to gas + +- The remaining allocation of witness bytes, converted to gas - The user-defined `tx.gasLimit` -Note that `gasLimit` applies to transactions of type `Script`. `gasLimit` is not applicable for transactions of type `Create` and is defined to equal `0` in the above formula. +Note that `gasLimit` applies to transactions of type `Script`. `gasLimit` is not applicable for transactions of type `Create` and is defined to equal `0` in the above formula. A transaction cost `cost(tx)`, in gas, greater than `max_gas` is invalid and must be rejected; this signifies that the user must provide a higher gas limit for the given transaction. `min_fee` is the minimum reward the producer is guaranteed to collect, and `max_fee` is the maximum reward the producer is potentially eligible to collect. In practice, the user is always charged intrinsic fees; thus, `unspentGas` is the remainder of `max_gas` after intrinsic fees and the variable cost of execution. Calculating a conversion from `unspentGas` to an unspent fee describes the reward the producer will collect in addition to `min_fee`. diff --git a/src/tx-format/index.md b/src/tx-format/index.md index 34962fc4..b53e214d 100644 --- a/src/tx-format/index.md +++ b/src/tx-format/index.md @@ -4,18 +4,18 @@ The Fuel Transaction Format. - [Consensus Parameters](./consensus_parameters.md) - [Transaction](./transaction.md) - - [TransactionScript](./transaction.md#transactionscript) - - [TransactionCreate](./transaction.md#transactioncreate) - - [TransactionMint](./transaction.md#transactionmint) + - [`TransactionScript`](./transaction.md#transactionscript) + - [`TransactionCreate`](./transaction.md#transactioncreate) + - [`TransactionMint`](./transaction.md#transactionmint) - [Input](./input.md) - - [InputCoin](./input.md#inputcoin) - - [InputContract](./input.md#inputcontract) - - [InputMessage](./input.md#inputmessage) + - [`InputCoin`](./input.md#inputcoin) + - [`InputContract`](./input.md#inputcontract) + - [`InputMessage`](./input.md#inputmessage) - [Output](./output.md) - - [OutputCoin](./output.md#outputcoin) - - [OutputContract](./output.md#outputcontract) - - [OutputChange](./output.md#outputchange) - - [OutputVariable](./output.md#outputvariable) - - [OutputContractCreated](./output.md#outputcontractcreated) -- [Witness](./witness.md) -- [TXPointer](./tx-pointer.md) + - [`OutputCoin`](./output.md#outputcoin) + - [`OutputContract`](./output.md#outputcontract) + - [`OutputChange`](./output.md#outputchange) + - [`OutputVariable`](./output.md#outputvariable) + - [`OutputContractCreated`](./output.md#outputcontractcreated) +- [`Witness`](./witness.md) +- [`TXPointer`](./tx-pointer.md) diff --git a/src/tx-format/input.md b/src/tx-format/input.md index 306728bf..072fd679 100644 --- a/src/tx-format/input.md +++ b/src/tx-format/input.md @@ -10,14 +10,14 @@ enum InputType : uint8 { | name | type | description | |--------|---------------------------------------------------------------------------------------------------|----------------| -| `type` | [InputType](#input) | Type of input. | -| `data` | One of [InputCoin](#inputcoin), [InputContract](#inputcontract), or [InputMessage](#inputmessage) | Input data. | +| `type` | [`InputType`](#input) | Type of input. | +| `data` | One of [`InputCoin`](#inputcoin), [`InputContract`](#inputcontract), or [`InputMessage`](#inputmessage) | Input data. | Transaction is invalid if: - `type > InputType.Message` -## InputCoin +## `InputCoin` | name | type | description | |-----------------------|------------------------------|------------------------------------------------------------------------| @@ -26,7 +26,7 @@ Transaction is invalid if: | `owner` | `byte[32]` | Owning address or predicate root. | | `amount` | `uint64` | Amount of coins. | | `asset_id` | `byte[32]` | Asset ID of the coins. | -| `txPointer` | [TXPointer](./tx-pointer.md) | Points to the TX whose output is being spent. | +| `txPointer` | [`TXPointer`](./tx-pointer.md) | Points to the TX whose output is being spent. | | `witnessIndex` | `uint8` | Index of witness that authorizes spending the coin. | | `maturity` | `uint32` | UTXO being spent must have been created at least this many blocks ago. | | `predicateGasUsed` | `uint64` | Gas used by predicate. | @@ -57,7 +57,7 @@ If `h` is the block height the UTXO being spent was created, transaction is inva The predicate root is computed [here](../identifiers/predicate-id.md). -## InputContract +## `InputContract` | name | type | description | |---------------|------------------------------|-------------------------------------------------------------------------| @@ -65,7 +65,7 @@ The predicate root is computed [here](../identifiers/predicate-id.md). | `outputIndex` | `uint8` | Index of transaction output. | | `balanceRoot` | `byte[32]` | Root of amount of coins owned by contract before transaction execution. | | `stateRoot` | `byte[32]` | State root of contract before transaction execution. | -| `txPointer` | [TXPointer](./tx-pointer.md) | Points to the TX whose output is being spent. | +| `txPointer` | [`TXPointer`](./tx-pointer.md) | Points to the TX whose output is being spent. | | `contractID` | `byte[32]` | Contract ID. | Transaction is invalid if: @@ -78,7 +78,7 @@ Transaction is invalid if: > > **Note:** when executing a script, `txID`, `outputIndex`, `balanceRoot`, and `stateRoot` are initialized to the transaction ID, output index, amount, and state root of the contract with ID `contractID`, and `txPointer` is initialized to the TX whose output is being spent. -## InputMessage +## `InputMessage` | name | type | description | |-----------------------|------------|---------------------------------------------------------| diff --git a/src/tx-format/output.md b/src/tx-format/output.md index 9fa55290..5618e603 100644 --- a/src/tx-format/output.md +++ b/src/tx-format/output.md @@ -12,14 +12,14 @@ enum OutputType : uint8 { | name | type | description | |--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| -| `type` | [OutputType](#output) | Type of output. | -| `data` | One of [OutputCoin](#outputcoin), [OutputContract](#outputcontract), [OutputChange](#outputchange), [OutputVariable](#outputvariable), or [OutputContractCreated](#outputcontractcreated). | Output data. | +| `type` | [`OutputType`](#output) | Type of output. | +| `data` | One of [`OutputCoin`](#outputcoin), [`OutputContract`](#outputcontract), [`OutputChange`](#outputchange), [`OutputVariable`](#outputvariable), or [`OutputContractCreated`](#outputcontractcreated). | Output data. | Transaction is invalid if: - `type > OutputType.ContractCreated` -## OutputCoin +## `OutputCoin` | name | type | description | |------------|------------|--------------------------------------| @@ -27,7 +27,7 @@ Transaction is invalid if: | `amount` | `uint64` | Amount of coins to send. | | `asset_id` | `byte[32]` | Asset ID of coins. | -## OutputContract +## `OutputContract` | name | type | description | |---------------|------------|------------------------------------------------------------------------| @@ -50,7 +50,7 @@ The balance root `balanceRoot` is the root of the [SMT](../protocol/cryptographi The state root `stateRoot` is the root of the [SMT](../protocol/cryptographic-primitives.md#sparse-merkle-tree) of storage slots. Each storage slot is a `byte[32]`, keyed by a `byte[32]`. -## OutputChange +## `OutputChange` | name | type | description | |------------|------------|--------------------------------------| @@ -68,7 +68,7 @@ Transaction is invalid if: This output type indicates that the output's amount may vary based on transaction execution, but is otherwise identical to a [Coin](#outputcoin) output. An `amount` of zero after transaction execution indicates that the output is unspendable and can be pruned from the UTXO set. -## OutputVariable +## `OutputVariable` | name | type | description | |------------|------------|--------------------------------------| @@ -82,7 +82,7 @@ This output type indicates that the output's amount may vary based on transactio This output type indicates that the output's amount and owner may vary based on transaction execution, but is otherwise identical to a [Coin](#outputcoin) output. An `amount` of zero after transaction execution indicates that the output is unspendable and can be pruned from the UTXO set. -## OutputContractCreated +## `OutputContractCreated` | name | type | description | |--------------|------------|---------------------------------| diff --git a/src/tx-format/policy.md b/src/tx-format/policy.md index d3a28c89..ca2c572e 100644 --- a/src/tx-format/policy.md +++ b/src/tx-format/policy.md @@ -12,15 +12,15 @@ enum PolicyType : uint32 { | name | type | description | |--------|---------------------------------------------------------------------------------------|--------------| -| `data` | One of [GasPrice](#gasprice), [WitnessLimit](#witnesslimit), or [Maturity](#maturity) | Policy data. | +| `data` | One of [`GasPrice`](#gasprice), [`WitnessLimit`](#witnesslimit), or [`Maturity`](#maturity) | Policy data. | -## GasPrice +## `GasPrice` | name | type | description | |------------|----------|---------------------------| | `gasPrice` | `uint64` | Gas price for transaction | -## WitnessLimit +## `WitnessLimit` | name | type | description | |----------------|----------|----------------------------------------------------------------| @@ -32,17 +32,17 @@ Transaction is invalid if: - `len(tx.witnesses) > witnessLimit` -## Maturity +## `Maturity` | name | type | description | |------------|----------|------------------------------------------| -| `maturity` | `uint32` | Block until which tx cannot be included. | +| `maturity` | `uint32` | Block until which the transaction cannot be included. | Transaction is invalid if: - `blockheight() < maturity` -## MaxFee +## `MaxFee` | name | type | description | |-----------|----------|-----------------------------------------------------------------| diff --git a/src/tx-format/transaction.md b/src/tx-format/transaction.md index b1729f22..e4e2aa09 100644 --- a/src/tx-format/transaction.md +++ b/src/tx-format/transaction.md @@ -10,8 +10,8 @@ enum TransactionType : uint8 { | name | type | description | |--------|---------------------------------------------------------------------------------------------------------------------------------|-------------------| -| `type` | [TransactionType](#transaction) | Transaction type. | -| `data` | One of [TransactionScript](#transactionscript), [TransactionCreate](#transactioncreate), or [TransactionMint](#transactionmint) | Transaction data. | +| `type` | [`TransactionType`](#transaction) | Transaction type. | +| `data` | One of [`TransactionScript`](#transactionscript), [`TransactionCreate`](#transactioncreate), or [`TransactionMint`](#transactionmint) | Transaction data. | Transaction is invalid if: @@ -35,7 +35,7 @@ When serializing a transaction, fields are serialized as follows (with inner str When deserializing a transaction, the reverse is done. If there are insufficient bytes or too many bytes, the transaction is invalid. -## TransactionScript +## `TransactionScript` ```c++ enum ReceiptType : uint8 { @@ -67,7 +67,7 @@ enum ReceiptType : uint8 { | `receiptsRoot` | `byte[32]` | Merkle root of receipts. | | `script` | `byte[]` | Script to execute. | | `scriptData` | `byte[]` | Script input data (parameters). | -| `policies` | [Policy](./policy.md)`[]` | List of policies, sorted by PolicyType. | +| `policies` | [Policy](./policy.md)`[]` | List of policies, sorted by `PolicyType`. | | `inputs` | [Input](./input.md)`[]` | List of inputs. | | `outputs` | [Output](./output.md)`[]` | List of outputs. | | `witnesses` | [Witness](./witness.md)`[]` | List of witnesses. | @@ -100,7 +100,7 @@ Transaction is invalid if: The receipts root `receiptsRoot` is the root of the [binary Merkle tree](../protocol/cryptographic-primitives.md#binary-merkle-tree) of receipts. If there are no receipts, its value is set to the root of the empty tree, i.e. `0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`. -## TransactionCreate +## `TransactionCreate` | name | type | description | |------------------------|-----------------------------|---------------------------------------------------| @@ -145,16 +145,16 @@ Transaction is invalid if: Creates a contract with contract ID as computed [here](../identifiers/contract-id.md). -## TransactionMint +## `TransactionMint` The transaction is created by the block producer and is not signed. Since it is not usable outside of block creation or execution, all fields must be fully set upon creation without any zeroing. This means that the transaction ID must also include the correct `txPointer` value, not zeroed out. | name | type | description | |------------------|-------------------------------|------------------------------------------------------| -| `txPointer` | [TXPointer](./tx-pointer.md) | The location of the `Mint` transaction in the block. | -| `inputContract` | [InputContract](./input.md) | The contract utxo that assets are minted to. | -| `outputContract` | [OutputContract](./output.md) | The contract utxo that assets are being minted to. | +| `txPointer` | [`TXPointer`](./tx-pointer.md) | The location of the `Mint` transaction in the block. | +| `inputContract` | [`InputContract`](./input.md) | The contract UTXO that assets are minted to. | +| `outputContract` | [`OutputContract`](./output.md) | The contract UTXO that assets are being minted to. | | `mintAmount` | `uint64` | The amount of funds minted. | | `mintAssetId` | `byte[32]` | The asset IDs corresponding to the minted amount. | diff --git a/src/tx-format/tx-pointer.md b/src/tx-format/tx-pointer.md index 878f627d..cddf2dfb 100644 --- a/src/tx-format/tx-pointer.md +++ b/src/tx-format/tx-pointer.md @@ -1,4 +1,4 @@ -# TXPointer +# `TXPointer` The location of the transaction in the block. It can be used by UTXOs as a reference to the transaction or by the transaction itself to make it unique.