Skip to content
This repository has been archived by the owner on Dec 12, 2024. It is now read-only.

Commit

Permalink
feat: add new getter configuration options to book/config (#302)
Browse files Browse the repository at this point in the history
And adjust descriptions of `book/contracts#interfaces`
  • Loading branch information
novusnota authored Jul 5, 2024
1 parent f67542c commit a4a29a7
Show file tree
Hide file tree
Showing 2 changed files with 89 additions and 3 deletions.
68 changes: 68 additions & 0 deletions pages/book/config.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,72 @@ If set to `true{:json}`, enables support of [external](/book/external) message r

</Callout>

#### `ipfsAbiGetter` [#options-ipfsabigetter]

`false{:json}` by default.

If set to `true{:json}`, enables generation of a [getter](/book/contracts#getter-functions) with IPFS links describing the contract's ABI.

```json filename="tact.config.json" {8,14}
{
"projects": [
{
"name": "some_prefix",
"path": "./contract.tact",
"output": "./contract_output",
"options": {
"ipfsAbiGetter": true
}
},
{
"name": "ContractUnderBlueprint",
"options": {
"ipfsAbiGetter": true
}
}
]
}
```

<Callout>

Read more on the dedicated page: [OTP-003: Self-ABI reporting](/ref/evolution/OTP-003).

</Callout>

#### `interfacesGetter` [#options-interfacesgetter]

`false{:json}` by default.

If set to `true{:json}`, enables generation of a [getter](/book/contracts#getter-functions) with a list of interfaces provided by the contract.

```json filename="tact.config.json" {8,14}
{
"projects": [
{
"name": "some_prefix",
"path": "./contract.tact",
"output": "./contract_output",
"options": {
"interfacesGetter": true
}
},
{
"name": "ContractUnderBlueprint",
"options": {
"interfacesGetter": true
}
}
]
}
```

<Callout>

Read more: [Supported interfaces](/book/contracts#interfaces).

</Callout>

#### `experimental` [#options-experimental]

Experimental options that might be removed in the future. Use with caution!
Expand Down Expand Up @@ -334,6 +400,8 @@ In [Blueprint][bp], `mode` is always set to `"full"{:json}` and cannot be overwr
"debug": false,
"masterchain": false,
"external": false,
"ipfsAbiGetter": true,
"interfacesGetter": true,
"experimental": {
"inline": false
}
Expand Down
24 changes: 21 additions & 3 deletions pages/book/contracts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Furthermore, contracts can inherit all the declarations and definitions from [tr

It's hard to figure out what a contract does and what [receivers](#receiver-functions) and [getters](#getter-functions) it has without looking at its source code. Sometimes the source is unavailable or inaccessible, and all that's left is to try to disassemble the contract and introspect it that way, which is a very messy and error-prone approach with diminishing returns and no real reproducibility.

In order to resolve this issue, an [OTP-001: Supported Interfaces](/ref/evolution/OTP-001) was created. In accordance to it, every Tact contract reports the list of supported interfaces as a return value of a special `supported_interfaces` [getter](#get-functions). That [getter](#getter-functions) is accessible off-chain using any TON Blockchain explorer — one just needs to specify `supported_interfaces` as a method to execute and get a list of hexadecimal values in return.
In order to resolve this issue, an [OTP-001: Supported Interfaces](/ref/evolution/OTP-001) was created. In accordance to it, Tact contracts [can report](/book/config#options-interfacesgetter) the list of supported interfaces as a return value of a special `supported_interfaces` [getter](#get-functions). That [getter](#getter-functions) is accessible off-chain using any TON Blockchain explorer — one just needs to specify `supported_interfaces` as a method to execute and get a list of hexadecimal values in return.

These hexadecimal values are truncated to the first 128 bit of [SHA-256](https://en.wikipedia.org/wiki/SHA-2#Hash_standard) hashes of the original [`String{:tact}`][p] values of the supported interfaces. The first value in this list **must** be equal to $\mathrm{0x5cec3d5d2cae7b1e84ec39d64a851b66}$ in [hexadecimal notation](/book/integers#hexadecimal), which is the first half of the SHA-256 hash for `"org.ton.introspection.v0"{:tact}`. If the first value is wrong, you must stop trying to introspect the contract, as it doesn't conform to the [Supported Interfaces](/ref/evolution/OTP-001) proposal.

Expand All @@ -56,9 +56,9 @@ trait Misc {
}
```

Tact has a small set of interfaces specified for all contracts under specific conditions:
Tact has a small set of interfaces provided under specific conditions:

* `"org.ton.abi.ipfs.v0"{:tact}`, in accordance to [OTP-003: Self-ABI Reporting](/ref/evolution/OTP-003)
* `"org.ton.abi.ipfs.v0"{:tact}`, in accordance to [OTP-003: Self-ABI Reporting](/ref/evolution/OTP-003) — opt-in via [`ipfsAbiGetter`](/book/config#options-ipfsabigetter) config property
* `"org.ton.deploy.lazy.v0"{:tact}`, in accordance to [OTP-005: Argument-addressable contracts](/ref/evolution/OTP-005)
* `"org.ton.debug.v0"{:tact}`, but only if [debug mode](/book/debug#debug-mode) is enabled
* `"org.ton.chain.any.v0"{:tact}` if [masterchain](/book/masterchain) support is enabled, and `"org.ton.chain.workchain.v0"{:tact}` otherwise
Expand All @@ -70,6 +70,24 @@ Some [traits][trait] in [standard libraries](/ref/standard-libraries) define the
* [`Stoppable{:tact}`](/ref/stdlib-stoppable#stoppable) trait specifies `"org.ton.stoppable"{:tact}`
* [`Resumable{:tact}`](/ref/stdlib-stoppable#resumable) trait specifies `"org.ton.resumable"{:tact}`

To enable `supported_interfaces` [getter](#getter-functions) generation and use `@interface(){:tact}` attribute in your Tact contracts, modify a [`tact.config.json`](/book/config) file in the root of your project (or create it if it didn't exist yet), and [set the `interfacesGetter` property to `true{:json}`](/book/config#options-interfacesgetter).

If you're working on a [Blueprint][bp]-based project, you can enable `supported_interfaces` in the compilation configs of your contracts, which are located in a directory named `wrappers/`:

```typescript filename="wrappers/YourContractName.compile.ts" {7}
import { CompilerConfig } from '@ton/blueprint';

export const compile: CompilerConfig = {
lang: 'tact',
target: 'contracts/your_contract_name.tact',
options: {
interfacesGetter: true, // ← that's the stuff!
}
};
```

In addition to that, [`tact.config.json`](/book/config) may still be used in [Blueprint][bp] projects. In such cases values specified in [`tact.config.json`](/book/config) act as default unless modified in the `wrappers/`.

<Callout type="warning" emoji="⚠️">

Be aware that adding an interface does not guarantee that the contract actually implements any particular functionality, or that it implements it in any particular way. It's just an off-chain, verifiable promise that a contract _might_ have some specific code in it. It's up to you to trust, but verify, such claims.
Expand Down

0 comments on commit a4a29a7

Please sign in to comment.