diff --git a/docs/learn/archive/tvm-instructions.mdx b/docs/learn/archive/tvm-instructions.mdx index 0b9eba7619..510d20cbb1 100644 --- a/docs/learn/archive/tvm-instructions.mdx +++ b/docs/learn/archive/tvm-instructions.mdx @@ -953,7 +953,7 @@ These primitives are completely similar to their non-prefix code counterparts ([ | **`FB02`** | `RAWRESERVE` | _`x y - `_ | Creates an output action which would reserve exactly `x` nanograms (if `y=0`), at most `x` nanograms (if `y=2`), or all but `x` nanograms (if `y=1` or `y=3`), from the remaining balance of the account. It is roughly equivalent to creating an outbound message carrying `x` nanograms (or `b-x` nanograms, where `b` is the remaining balance) to oneself, so that the subsequent output actions would not be able to spend more money than the remainder. Bit `+2` in `y` means that the external action does not fail if the specified amount cannot be reserved; instead, all remaining balance is reserved. Bit `+8` in `y` means `x:=-x` before performing any further actions. Bit `+4` in `y` means that `x` is increased by the original balance of the current account (before the compute phase), including all extra currencies, before performing any other checks and actions. Currently `x` must be a non-negative integer, and `y` must be in the range `0...15`. | `526` | | **`FB03`** | `RAWRESERVEX` | _`x D y - `_ | Similar to [`RAWRESERVE`](#instr-rawreserve), but also accepts a dictionary `D` (represented by a _Cell_ or _Null_) with extra currencies. In this way currencies other than Grams can be reserved. | `526` | | **`FB04`** | `SETCODE` | _`c - `_ | Creates an output action that would change this smart contract code to that given by _Cell_ `c`. Notice that this change will take effect only after the successful termination of the current run of the smart contract. | `526` | -| **`FB06`** | `SETLIBCODE` | _`c x - `_ | Creates an output action that would modify the collection of this smart contract libraries by adding or removing library with code given in _Cell_ `c`. If `x=0`, the library is actually removed if it was previously present in the collection (if not, this action does nothing). If `x=1`, the library is added as a private library, and if `x=2`, the library is added as a public library (and becomes available to all smart contracts if the current smart contract resides in the masterchain); if the library was present in the collection before, its public/private status is changed according to `x`. Values of `x` other than `0...2` are invalid. | `526` | +| **`FB06`** | `SETLIBCODE` | _`c x - `_ | Creates an output action that would modify the collection of this smart contract libraries by adding or removing library with code given in _Cell_ `c`. If `x=0`, the library is actually removed if it was previously present in the collection (if not, this action does nothing). If `x=1`, the library is added as a private library, and if `x=2`, the library is added as a public library (and becomes available to all smart contracts if the current smart contract resides in the masterchain); if the library was present in the collection before, its public/private status is changed according to `x`. Also, `16` can be added to `x` to enable bounce transaction on failure. Values of `x` other than `0...2 (+16 possible)` are invalid. | `526` | | **`FB07`** | `CHANGELIB` | _`h x - `_ | Creates an output action similarly to [`SETLIBCODE`](#instr-setlibcode), but instead of the library code accepts its hash as an unsigned 256-bit integer `h`. If `x!=0` and the library with hash `h` is absent from the library collection of this smart contract, this output action will fail. | `526` | ## 12 Debug primitives diff --git a/docs/learn/tvm-instructions/instructions.csv b/docs/learn/tvm-instructions/instructions.csv index 63f06f94a3..60c2ecf583 100644 --- a/docs/learn/tvm-instructions/instructions.csv +++ b/docs/learn/tvm-instructions/instructions.csv @@ -935,7 +935,7 @@ SENDRAWMSG,,#FB00,app_actions,FB00,SENDRAWMSG,c x - ,526,"Sends a raw message co RAWRESERVE,,#FB02,app_actions,FB02,RAWRESERVE,x y - ,526,"Creates an output action which would reserve exactly `x` nanograms (if `y=0`), at most `x` nanograms (if `y=2`), or all but `x` nanograms (if `y=1` or `y=3`), from the remaining balance of the account. It is roughly equivalent to creating an outbound message carrying `x` nanograms (or `b-x` nanograms, where `b` is the remaining balance) to oneself, so that the subsequent output actions would not be able to spend more money than the remainder. Bit `+2` in `y` means that the external action does not fail if the specified amount cannot be reserved; instead, all remaining balance is reserved. Bit `+8` in `y` means `x:=-x` before performing any further actions. Bit `+4` in `y` means that `x` is increased by the original balance of the current account (before the compute phase), including all extra currencies, before performing any other checks and actions. Currently `x` must be a non-negative integer, and `y` must be in the range `0...15`." RAWRESERVEX,,#FB03,app_actions,FB03,RAWRESERVEX,x D y - ,526,"Similar to `RAWRESERVE`, but also accepts a dictionary `D` (represented by a _Cell_ or _Null_) with extra currencies. In this way currencies other than Grams can be reserved." SETCODE,,#FB04,app_actions,FB04,SETCODE,c - ,526,Creates an output action that would change this smart contract code to that given by _Cell_ `c`. Notice that this change will take effect only after the successful termination of the current run of the smart contract. -SETLIBCODE,,#FB06,app_actions,FB06,SETLIBCODE,c x - ,526,"Creates an output action that would modify the collection of this smart contract libraries by adding or removing library with code given in _Cell_ `c`. If `x=0`, the library is actually removed if it was previously present in the collection (if not, this action does nothing). If `x=1`, the library is added as a private library, and if `x=2`, the library is added as a public library (and becomes available to all smart contracts if the current smart contract resides in the masterchain); if the library was present in the collection before, its public/private status is changed according to `x`. Values of `x` other than `0...2` are invalid." +SETLIBCODE,,#FB06,app_actions,FB06,SETLIBCODE,c x - ,526,"Creates an output action that would modify the collection of this smart contract libraries by adding or removing library with code given in _Cell_ `c`. If `x=0`, the library is actually removed if it was previously present in the collection (if not, this action does nothing). If `x=1`, the library is added as a private library, and if `x=2`, the library is added as a public library (and becomes available to all smart contracts if the current smart contract resides in the masterchain); if the library was present in the collection before, its public/private status is changed according to `x`. Also, `16` can be added to `x` to enable bounce transaction on failure. Values of `x` other than `0...2 (+16 possible)` are invalid." CHANGELIB,,#FB07,app_actions,FB07,CHANGELIB,h x - ,526,"Creates an output action similarly to `SETLIBCODE`, but instead of the library code accepts its hash as an unsigned 256-bit integer `h`. If `x!=0` and the library with hash `h` is absent from the library collection of this smart contract, this output action will fail." DEBUG,,#FE nn:(#<= 239),debug,FEnn,{nn} DEBUG,-,26,`0 <= nn < 240` DEBUGSTR,,#FEF n:(## 4) ssss:((n * 8 + 8) * Bit),debug,FEFnssss,"{string} DEBUGSTR diff --git a/docs/learn/tvm-instructions/instructions/app-specific.mdx b/docs/learn/tvm-instructions/instructions/app-specific.mdx index 32ed1de9e2..1feb266d5c 100644 --- a/docs/learn/tvm-instructions/instructions/app-specific.mdx +++ b/docs/learn/tvm-instructions/instructions/app-specific.mdx @@ -98,5 +98,5 @@ import { appSpecificOpcodes as opcodes } from '@site/src/data/opcodes'; | **`FB02`** | `RAWRESERVE` | _`x y - `_ | Creates an output action which would reserve exactly `x` nanograms (if `y=0`), at most `x` nanograms (if `y=2`), or all but `x` nanograms (if `y=1` or `y=3`), from the remaining balance of the account. It is roughly equivalent to creating an outbound message carrying `x` nanograms (or `b-x` nanograms, where `b` is the remaining balance) to oneself, so that the subsequent output actions would not be able to spend more money than the remainder. Bit `+2` in `y` means that the external action does not fail if the specified amount cannot be reserved; instead, all remaining balance is reserved. Bit `+8` in `y` means `x:=-x` before performing any further actions. Bit `+4` in `y` means that `x` is increased by the original balance of the current account (before the compute phase), including all extra currencies, before performing any other checks and actions. Currently `x` must be a non-negative integer, and `y` must be in the range `0...15`. | `526` | | **`FB03`** | `RAWRESERVEX` | _`x D y - `_ | Similar to [`RAWRESERVE`](#instr-rawreserve), but also accepts a dictionary `D` (represented by a _Cell_ or _Null_) with extra currencies. In this way currencies other than Grams can be reserved. | `526` | | **`FB04`** | `SETCODE` | _`c - `_ | Creates an output action that would change this smart contract code to that given by _Cell_ `c`. Notice that this change will take effect only after the successful termination of the current run of the smart contract. | `526` | -| **`FB06`** | `SETLIBCODE` | _`c x - `_ | Creates an output action that would modify the collection of this smart contract libraries by adding or removing library with code given in _Cell_ `c`. If `x=0`, the library is actually removed if it was previously present in the collection (if not, this action does nothing). If `x=1`, the library is added as a private library, and if `x=2`, the library is added as a public library (and becomes available to all smart contracts if the current smart contract resides in the masterchain); if the library was present in the collection before, its public/private status is changed according to `x`. Values of `x` other than `0...2` are invalid. | `526` | +| **`FB06`** | `SETLIBCODE` | _`c x - `_ | Creates an output action that would modify the collection of this smart contract libraries by adding or removing library with code given in _Cell_ `c`. If `x=0`, the library is actually removed if it was previously present in the collection (if not, this action does nothing). If `x=1`, the library is added as a private library, and if `x=2`, the library is added as a public library (and becomes available to all smart contracts if the current smart contract resides in the masterchain); if the library was present in the collection before, its public/private status is changed according to `x`. Also, `16` can be added to `x` to enable bounce transaction on failure. Values of `x` other than `0...2 (+16 possible)` are invalid. | `526` | | **`FB07`** | `CHANGELIB` | _`h x - `_ | Creates an output action similarly to [`SETLIBCODE`](#instr-setlibcode), but instead of the library code accepts its hash as an unsigned 256-bit integer `h`. If `x!=0` and the library with hash `h` is absent from the library collection of this smart contract, this output action will fail. | `526` | diff --git a/docs/learn/tvm-instructions/tvm-exit-codes.md b/docs/learn/tvm-instructions/tvm-exit-codes.md index 11e0f5d6f6..723781097e 100644 --- a/docs/learn/tvm-instructions/tvm-exit-codes.md +++ b/docs/learn/tvm-instructions/tvm-exit-codes.md @@ -8,29 +8,36 @@ If TVM exits with an arbitrary 16-bit unsigned integer `exit_code`. `exit_code` The list of standard exit codes contains all universal TVM exit codes defined for TON Blockchain. Alternative exit codes should be sought in the source code of corresponded contract. ::: -| Exit Code | TVM Phase | Description | -|----------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `0` | Compute Phase | Standard successful execution exit code. | -| `1` | Compute Phase | Alternative successful execution exit code. | -| `2` | Compute Phase | Stack underflow. Last op-code consumed more elements than there are on the stacks. 1 | -| `3` | Compute Phase | Stack overflow. More values have been stored on a stack than allowed by this version of TVM. | -| `4` | Compute Phase | Integer overflow. Integer does not fit into −2256 ≤ x < 2256 or a division by zero has occurred. | -| `5` | Compute Phase | Integer out of expected range. | -| `6` | Compute Phase | Invalid opcode. Instruction is unknown in the current TVM version. | -| `7` | Compute Phase | Type check error. An argument to a primitive is of an incorrect value type. 1 | -| `8` | Compute Phase | Cell overflow. Writing to builder is not possible since after operation there would be more than 1023 bits or 4 references. | -| `9` | Compute Phase | Cell underflow. Read from slice primitive tried to read more bits or references than there are. | -| `10` | Compute Phase | Dictionary error. Error during manipulation with dictionary (hashmaps). | +| Exit Code | TVM Phase | Description +| --------- | ------------- | ------------- +| `0` | Compute Phase | Standard successful execution exit code. +| `1` | Compute Phase | Alternative successful execution exit code. +| `2` | Compute Phase | Stack underflow. Last op-code consumed more elements than there are on the stacks. 1 +| `3` | Compute Phase | Stack overflow. More values have been stored on a stack than allowed by this version of TVM. +| `4` | Compute Phase | Integer overflow. Integer does not fit into −2256 ≤ x < 2256 or a division by zero has occurred. +| `5` | Compute Phase | Integer out of expected range. +| `6` | Compute Phase | Invalid opcode. Instruction is unknown in the current TVM version. +| `7` | Compute Phase | Type check error. An argument to a primitive is of an incorrect value type. 1 +| `8` | Compute Phase | Cell overflow. Writing to builder is not possible since after operation there would be more than 1023 bits or 4 references. +| `9` | Compute Phase | Cell underflow. Read from slice primitive tried to read more bits or references than there are. +| `10` | Compute Phase | Dictionary error. Error during manipulation with dictionary (hashmaps). | `11` | Compute Phase | Most oftenly caused by trying to call get-method whose id wasn't found in the code (missing `method_id` modifier or wrong get-method name specified when trying to call it). In [TVM docs](https://ton.org/tvm.pdf) its described as "Unknown error, may be thrown by user programs". | -| `12` | Compute Phase | Thrown by TVM in situations deemed impossible. | -| `13` | Compute Phase | Out of gas error. Thrown by TVM when the remaining gas becomes negative. | -| `-14` | Compute Phase | It means out of gas error, same as `13`. Negative, because it [cannot be faked](https://github.com/ton-blockchain/ton/blob/20758d6bdd0c1327091287e8a620f660d1a9f4da/crypto/vm/vm.cpp#L492) | -| `32` | Action Phase | Action list is invalid. Set during action phase if c5 register after execution contains unparsable object. | -| `-32` | Action Phase | (the same as prev 32) - Method ID not found. Returned by TonLib during an attempt to execute non-existent get method. | -| `33` | Action Phase | Action list is too long. | -| `34` | Action Phase | Action is invalid or not supported. Set during action phase if current action cannot be applied.
| -| `36` | Action Phase | Invalid Source address in outbound message. | -| `37` | Action Phase | Not enough TON. Message sends too much TON (or there is not enough TON after deducting fees). | -| `38` | Action Phase | Not enough extra-currencies. | +| `12` | Compute Phase | Thrown by TVM in situations deemed impossible. +| `13` | Compute Phase | Out of gas error. Thrown by TVM when the remaining gas becomes negative. +| `-14` | Compute Phase | It means out of gas error, same as `13`. Negative, because it [cannot be faked](https://github.com/ton-blockchain/ton/blob/20758d6bdd0c1327091287e8a620f660d1a9f4da/crypto/vm/vm.cpp#L492) +| `32` | Action Phase | Action list is invalid. Set during action phase if c5 register after execution contains unparsable object. +| `-32` | Action Phase | (the same as prev 32) - Method ID not found. Returned by TonLib during an attempt to execute non-existent get method. +| `33` | Action Phase | Action list is too long. +| `34` | Action Phase | Action is invalid or not supported. Set during action phase if current action cannot be applied. +| `35` | Action Phase | Invalid Source address in outbound message. +| `36` | Action Phase | Invalid Destinastion address in outbound message. +| `37` | Action Phase | Not enough TON. Message sends too much TON (or there is not enough TON after deducting fees) +| `38` | Action Phase | Not enough extra-currencies. +| `40` | Action Phase | Not enough funds to process a message. This error is thrown when there is only enough gas to cover part of the message, but does not cover it completely. +| `43` | Action Phase | The maximum number of cells in the library is exceeded or the maximum depth of the Merkle tree is exceeded. 1 If you encounter such exception in a _func_ contract it probably means a type error in `asm` declarations. + +:::info +Often you can see the exit code `0xffff`. This usually means that the received opcode is unknown to the contract. When writing contracts, this code is set by the developer himself. +::: \ No newline at end of file diff --git a/src/data/opcodes/app_specific.json b/src/data/opcodes/app_specific.json index 925d7e7d13..f963dd2150 100644 --- a/src/data/opcodes/app_specific.json +++ b/src/data/opcodes/app_specific.json @@ -525,7 +525,7 @@ "doc_fift": "SETLIBCODE", "doc_stack": "c x -", "doc_gas": 526, - "doc_description": "Creates an output action that would modify the collection of this smart contract libraries by adding or removing library with code given in _Cell_ `c`. If `x=0`, the library is actually removed if it was previously present in the collection (if not, this action does nothing). If `x=1`, the library is added as a private library, and if `x=2`, the library is added as a public library (and becomes available to all smart contracts if the current smart contract resides in the masterchain); if the library was present in the collection before, its public/private status is changed according to `x`. Values of `x` other than `0...2` are invalid." + "doc_description": "Creates an output action that would modify the collection of this smart contract libraries by adding or removing library with code given in _Cell_ `c`. If `x=0`, the library is actually removed if it was previously present in the collection (if not, this action does nothing). If `x=1`, the library is added as a private library, and if `x=2`, the library is added as a public library (and becomes available to all smart contracts if the current smart contract resides in the masterchain); if the library was present in the collection before, its public/private status is changed according to `x`. Also, `16` can be added to `x` to enable bounce transaction on failure. Values of `x` other than `0...2 (+16 possible)` are invalid." }, { "name": "CHANGELIB", diff --git a/src/data/opcodes/opcodes.json b/src/data/opcodes/opcodes.json index ec1166d187..f8ee55416c 100644 --- a/src/data/opcodes/opcodes.json +++ b/src/data/opcodes/opcodes.json @@ -8071,7 +8071,7 @@ "doc_fift": "SETLIBCODE", "doc_stack": "c x -", "doc_gas": 526, - "doc_description": "Creates an output action that would modify the collection of this smart contract libraries by adding or removing library with code given in _Cell_ `c`. If `x=0`, the library is actually removed if it was previously present in the collection (if not, this action does nothing). If `x=1`, the library is added as a private library, and if `x=2`, the library is added as a public library (and becomes available to all smart contracts if the current smart contract resides in the masterchain); if the library was present in the collection before, its public/private status is changed according to `x`. Values of `x` other than `0...2` are invalid." + "doc_description": "Creates an output action that would modify the collection of this smart contract libraries by adding or removing library with code given in _Cell_ `c`. If `x=0`, the library is actually removed if it was previously present in the collection (if not, this action does nothing). If `x=1`, the library is added as a private library, and if `x=2`, the library is added as a public library (and becomes available to all smart contracts if the current smart contract resides in the masterchain); if the library was present in the collection before, its public/private status is changed according to `x`. Also, `16` can be added to `x` to enable bounce transaction on failure. Values of `x` other than `0...2 (+16 possible)` are invalid." }, { "name": "CHANGELIB",