Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Revamp of Exit codes page #383

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion pages/book/debug.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -440,7 +440,7 @@ it('throws specific exit code', async () => {
});
```

Note, that to track down transactions with a certain exit code, you only need to specify `exitCode` field in `toHaveTransaction(){:typescript}` method of `expect(){:typescript}`.
Note, that to track down transactions with a certain exit code, you only need to specify `exitCode` field in object argument to the `toHaveTransaction(){:typescript}` method of `expect(){:typescript}`.

However, it's useful to narrow the scope by specifying the recipient address `to`, such that Jest would look only at the transaction caused by our message to the contract.

Expand Down
577 changes: 399 additions & 178 deletions pages/book/exit-codes.mdx

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion pages/book/operators.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ Unary operators can be one of the two types:

### Non-null assert, `!!` [#unary-non-null-assert]

Unary double-exclamation mark (_non-null assertion_) operator `!!{:tact}` is a postfix operator, which enforces non-null values and allows direct access to the value of the optional variable if it's not `null{:tact}`. Raises a compilation error otherwise. Can be applied to any optional variable regardless of its non-null type.
Unary double-exclamation mark (_non-null assertion_) operator `!!{:tact}` is a postfix operator, which enforces non-`null{:tact}` values and allows direct access to the value of the optional variable if it's not `null{:tact}`. Otherwise, raises a compilation error if the compiler can track it, and if not — throws an exception with [exit code 128](/book/exit-codes#128): `Null reference exception`. Can be applied to any optional variable regardless of its non-`null{:tact}` type.

<Callout>

Expand Down
2 changes: 1 addition & 1 deletion pages/book/optionals.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ You can make any variable or a field an optional by adding a question mark (`?{:

Optional variables or optional fields that are not defined hold the `null{:tact}` value by default. You cannot access them without checking for `null{:tact}` first. But if you're certain they are not `null{:tact}` at a given moment, use the [non-null assertion operator `!!{:tact}`](/book/operators#unary-non-null-assert) to access their value.

Trying to access the value of an optional variable or an optional field without using [`!!{:tact}`](/book/operators#unary-non-null-assert) or without checking for `null{:tact}` beforehand will result in a compilation error.
Trying to access the value of an optional variable or an optional field without using [`!!{:tact}`](/book/operators#unary-non-null-assert) or without checking for `null{:tact}` beforehand will result in a compilation error if the compiler can track it, and if not — in an exception with [exit code 128](/book/exit-codes#128): `Null reference exception`.

Example of optionals:

Expand Down
6 changes: 3 additions & 3 deletions pages/book/structs-and-messages.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -100,9 +100,9 @@ message Add {
}
```

Messages are almost the same thing as [Structs](#structs) with the only difference that Messages have a 32-bit integer header in their serialization containing their unique numeric id. This allows Messages to be used with [receivers](/book/receive) since the contract can tell different types of messages apart based on this id.
Messages are almost the same thing as [Structs](#structs) with the only difference that Messages have a 32-bit integer header in their serialization containing their unique numeric id, commonly referred to as an _opcode_ (operation code). This allows Messages to be used with [receivers](/book/receive) since the contract can tell different types of messages apart based on this id.

Tact automatically generates those unique ids for every received Message, but this can be manually overwritten:
Tact automatically generates those unique ids (opcodes) for every received Message, but this can be manually overwritten:

```tact
// This Message overwrites its unique id with 0x7362d09c
Expand All @@ -111,7 +111,7 @@ message(0x7362d09c) TokenNotification {
}
```

This is useful for cases where you want to handle certain opcodes (operation codes) of a given smart contract, such as [Jetton standard](https://github.com/ton-blockchain/TEPs/blob/master/text/0074-jettons-standard.md). The short-list of opcodes this contract is able to process is [given here in FunC](https://github.com/ton-blockchain/token-contract/blob/main/ft/op-codes.fc). They serve as an interface to the smart contract.
This is useful for cases where you want to handle certain opcodes of a given smart contract, such as [Jetton standard](https://github.com/ton-blockchain/TEPs/blob/master/text/0074-jettons-standard.md). The short-list of opcodes this contract is able to process is [given here in FunC](https://github.com/ton-blockchain/token-contract/blob/main/ft/op-codes.fc). They serve as an interface to the smart contract.

<Callout>

Expand Down
2 changes: 1 addition & 1 deletion pages/ref/core-advanced.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -196,7 +196,7 @@ fun nativeSendMessage(cell: Cell, mode: Int);
fun nativeReserve(amount: Int, mode: Int);
```

Calls native `raw_reserve` function with specified amount and mode. The `raw_reserve` is a function that creates an output action to reserve a specific amount of [nanoToncoins](book/integers#nanotoncoin) from the remaining balance of the account.
Calls native `raw_reserve` function with specified amount and mode. The `raw_reserve` is a function that creates an output action to reserve a specific amount of [nanoToncoins](/book/integers#nanotoncoin) from the remaining balance of the account.

It has the following signature in FunC:

Expand Down
22 changes: 21 additions & 1 deletion pages/ref/core-debug.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -92,13 +92,20 @@ dump(null);
dump(emit("msg".asComment())); // As emit() function doesn't return a value, dump() would print #DEBUG#: void.
```

<Callout>

**Useful link:**\
[Debug with `dump(){:tact}`](/book/debug#tests-dump)

</Callout>

## dumpStack

```tact
fun dumpStack();
```

Prints all the values of [persistent state variables](/book/contracts#variables) to the contract's debug console. Evaluated only if `debug` option is set in the [configuration file](/book/config), otherwise does nothing.
Prints all the values of [persistent state variables](/book/contracts#variables) to the contract's debug console. Evaluated only if the `debug` option in the [configuration file](/book/config) is set to `true{:json}`, otherwise does nothing.

Usage example:

Expand All @@ -113,6 +120,13 @@ contract DumpsterFire {
}
```

<Callout>

**Useful link:**\
[Debug with `dump(){:tact}`](/book/debug#tests-dump)

</Callout>

## throw

```tact
Expand All @@ -129,6 +143,8 @@ fun nativeThrow(code: Int);

Throws an exception with an error code equal to `code`. Execution of the current context stops (the statements after `nativeThrow` won't be executed) and control will be passed to the first [`try...catch{:tact}` block](/book/statements#try-catch) in the call stack. If no `try{:tact}` or `try...catch{:tact}` block exists among caller functions, [TVM](https://docs.ton.org/learn/tvm-instructions/tvm-overview) will terminate the transaction.

Attempts to specify the `code` outside of $0 - 65535$ range cause an exception with [exit code 5](/book/exit-codes#5): `Integer out of expected range`.

Usage examples:

```tact {2,7}
Expand All @@ -153,6 +169,8 @@ fun nativeThrowIf(code: Int, condition: Bool);

Similar to [`nativeThrow(){:tact}`](#nativethrow), but throws an exception conditionally, when `condition` is equal to `true{:tact}`. Doesn't throw otherwise.

Attempts to specify the `code` outside of $0 - 65535$ range cause an exception with [exit code 5](/book/exit-codes#5): `Integer out of expected range`.

Usage examples:

```tact {2,7}
Expand All @@ -176,6 +194,8 @@ fun nativeThrowUnless(code: Int, condition: Bool);

Similar to [`nativeThrow(){:tact}`](#nativethrow), but throws an exception conditionally, when `condition` is equal to `false{:tact}`. Doesn't throw otherwise.

Attempts to specify the `code` outside of $0 - 65535$ range cause an exception with [exit code 5](/book/exit-codes#5): `Integer out of expected range`.

Usage examples:

```tact {2,7}
Expand Down
6 changes: 5 additions & 1 deletion pages/ref/core-strings.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,8 @@ Returns a [`Slice{:tact}`][slice] out of the decoded [Base64](https://en.wikiped

Note, that this function is limited and only takes the first $1023$ bits of data from the given [`String{:tact}`][p], without throwing an exception when the [`String{:tact}`][p] is larger (i.e. contains more than $1023$ bits of data).

If the given [`String{:tact}`][p] contains characters not from the Base64 set, an exception with [exit code 134](/book/exit-codes#134) will be thrown: `Invalid argument`.

Usage example:

```tact
Expand Down Expand Up @@ -263,6 +265,8 @@ Returns a new [`Slice{:tact}`][slice] out of the decoded [Base64](https://en.wik

Note, that this function is limited and only takes the first $1023$ bits of data from the given [`Slice{:tact}`][slice], without throwing an exception if the [`Slice{:tact}`][slice] has more data (i.e., when it has any references).

If the given [`Slice{:tact}`][slice] contains characters not from the Base64 set, an exception with [exit code 134](/book/exit-codes#134) will be thrown: `Invalid argument`.

Usage example:

```tact
Expand Down Expand Up @@ -296,7 +300,7 @@ Extension function for the [`Int{:tact}`][int].

Returns a [`String{:tact}`][p] from an [`Int{:tact}`][int] value using a [fixed-point representation](https://en.wikipedia.org/wiki/Fixed-point_arithmetic) of a fractional number, where `self` is a significant part of the number and `digits` is a number of digits in the fractional part.

More precisely, `digits` is an exponentiation parameter of $10^{-\mathrm{digits}}$ expression, which gives the represented fractional number when multiplied by the actual [`Int{:tact}`][int] value. Parameter `digits` is required to be in the semi-closed interval: $0 <=$ `digits` $< 78$, otherwise an exception with [exit code 134](/book/exit-codes#134) will be thrown: `Invalid argument`.
More precisely, `digits` is an exponentiation parameter of $10^{-\mathrm{digits}}$ expression, which gives the represented fractional number when multiplied by the actual [`Int{:tact}`][int] value. Parameter `digits` is required to be in the closed interval: $0 <$ `digits` $< 78$, otherwise an exception with [exit code 134](/book/exit-codes#134) will be thrown: `Invalid argument`.

Usage example:

Expand Down
Loading