sbt-how-it-works #494
+223
−10
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,201 @@ | ||
| --- | ||
| title: "SBT: How it works" | ||
| sidebarTitle: "How it works" | ||
| --- | ||
|
|
||
| import { Aside } from '/snippets/aside.jsx'; | ||
|
|
||
| This article describes the basic ideas and processes behind the implementation of SBT (Soul-Bound Token) in the TON Blockchain. | ||
|
|
||
| SBT is a variation of an NFT Item, but has some differences. | ||
|
|
||
| <Aside type="note"> | ||
| It is important to keep in mind that SBT standards provide only a general scheme of interaction, leaving the specific implementation of related contracts to developers. | ||
| </Aside> | ||
|
|
||
| **Nota bene: in all schemes below you will see the `query id` field. Nowadays the field is almost deprecated, and protocols itself doesn't need it. | ||
| It is mostly used for easier off-chain parsing and other web2 processing**. | ||
|
|
||
| ## Bound to single owner | ||
|
|
||
| The `owner` is set at mint time and never changes. Below is a simple explanation of the key operations and their message flows. | ||
skywardboundd marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ## Prove ownership | ||
skywardboundd marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| Allows the `owner` to ask the SBT to send a proof to a target contract confirming that they own this SBT. You may include arbitrary `forward_payload` and optionally attach `content`. | ||
skywardboundd marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ```tlb title="TL-B" | ||
| ;; Inbound message to SBT | ||
| prove_ownership#04ded148 query_id:uint64 dest:MsgAddress | ||
| forward_payload:^Cell with_content:Bool = InternalMsgBody; | ||
| ;; SBT response to the target contract (if checks pass) | ||
| ownership_proof#0524c7ae query_id:uint64 item_id:uint256 owner:MsgAddress | ||
| data:^Cell revoked_at:uint64 content:(Maybe ^Cell) = InternalMsgBody; | ||
| ``` | ||
skywardboundd marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| `Inbound to SBT`. Prove ownership message contains the following data: | ||
skywardboundd marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| | Name | Type | Description | | ||
| | ----------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `query_id` | `uint64` | Links the request `prove_ownership` and the response `ownership_proof` to each other. To ensure this process works correctly, always use a unique query ID. | | ||
| | `dest` | `MsgAddress` | Address of the target contract to receive the proof. | | ||
| | `forward_payload` | `Cell` | Arbitrary data forwarded to the target contract. | | ||
| | `with_content` | `Bool` | If `true`, attach SBT `content`. | | ||
|
|
||
| `SBT -> dest (target contract)`. Ownership proof message contains the following data: | ||
|
|
||
| | Name | Type | Description | | ||
| | ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ||
| | `query_id` | `uint64` | Links the request `prove_ownership` and this `ownership_proof` response to each other. To ensure this process works correctly, always use a unique query ID. | | ||
| | `item_id` | `uint256` | Identifier of the SBT item. | | ||
| | `owner` | `MsgAddress` | Current owner address. | | ||
| | `data` | `Cell` | Custom data forwarded to the target contract, equal to `forward_payload`. | | ||
| | `revoked_at` | `uint64` | Revoke time if SBT is revoked, `0` otherwise. | | ||
| | `content` | `maybe Cell` | SBT content if it was requested with `with_content=true`. | | ||
skywardboundd marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| Rejected if the sender is not the `owner`. | ||
|
||
|
|
||
| ```mermaid | ||
| sequenceDiagram | ||
| participant U as Owner | ||
| participant S as SBT | ||
| participant D as dest (target contract) | ||
| U->>S: prove_ownership | ||
| alt owner | ||
| S->>D: ownership_proof | ||
| else not owner | ||
| S-->>U: reject | ||
| end | ||
| ``` | ||
|
|
||
| ## Request current owner | ||
|
|
||
| Any initiator may ask the SBT to send the current `owner` (and optionally the `content`) to a target contract. | ||
|
|
||
| ```tlb title="TL-B" | ||
| ;; Inbound message to SBT | ||
| request_owner#d0c3bfea query_id:uint64 dest:MsgAddress | ||
| forward_payload:^Cell with_content:Bool = InternalMsgBody; | ||
| ;; SBT response to the target contract | ||
| owner_info#0dd607e3 query_id:uint64 item_id:uint256 initiator:MsgAddress owner:MsgAddress | ||
| data:^Cell revoked_at:uint64 content:(Maybe ^Cell) = InternalMsgBody; | ||
| ``` | ||
|
|
||
| `Inbound to SBT`. Request owner message contains the following data: | ||
|
|
||
| | Name | Type | Description | | ||
| | ----------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `query_id` | `uint64` | Links the request `request_owner` and the response `owner_info` to each other. To ensure this process works correctly, always use a unique query ID. | | ||
| | `dest` | `MsgAddress` | Address of the target contract to receive the response. | | ||
| | `forward_payload` | `Cell` | Arbitrary data forwarded to the target contract. | | ||
| | `with_content` | `Bool` | If `true`, attach SBT `content` in the response. | | ||
|
|
||
| `SBT -> dest (target contract)`. Owner info message contains the following data: | ||
|
|
||
| | Name | Type | Description | | ||
| | ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `query_id` | `uint64` | Links the request `request_owner` and this `owner_info` response to each other. To ensure this process works correctly, always use a unique query ID. | | ||
| | `item_id` | `uint256` | Identifier of the SBT item. | | ||
| | `initiator` | `MsgAddress` | Address of the requester. | | ||
| | `owner` | `MsgAddress` | Current owner address. | | ||
| | `data` | `Cell` | Custom data forwarded to the target, equals to `forward_payload`. | | ||
| | `revoked_at` | `uint64` | Revoke time if revoked, `0` otherwise. | | ||
| | `content` | `maybe Cell` | SBT content if it was requested. | | ||
|
|
||
| ```mermaid | ||
| sequenceDiagram | ||
| participant I as Initiator | ||
| participant S as SBT | ||
| participant D as dest (target contract) | ||
| I->>S: request_owner | ||
| S->>D: owner_info | ||
| ``` | ||
|
|
||
| ## Destroy | ||
skywardboundd marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| The `owner` can destroy the SBT contract. This clears the `owner` and `authority` fields, and sends remaining balance back to the sender via an `excesses` message. | ||
|
|
||
| ```tlb title="TL-B" | ||
| ;; Internal message to SBT | ||
| destroy#1f04537a query_id:uint64 = InternalMsgBody; | ||
| ;; Excess returned to the sender | ||
| excesses#d53276db query_id:uint64 = InternalMsgBody; | ||
| ``` | ||
skywardboundd marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| `Inbound to SBT`. Destroy message contains the following data: | ||
|
|
||
| | Name | Type | Description | | ||
| | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `query_id` | `uint64` | Links the request `destroy` and the response `excesses` to each other. To ensure this process works correctly, always use a unique query ID. | | ||
|
|
||
| `SBT -> sender`. Excesses message contains the following data: | ||
|
|
||
| | Name | Type | Description | | ||
| | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `query_id` | `uint64` | Links the request `destroy` and this `excesses` response to each other. To ensure this process works correctly, always use a unique query ID. | | ||
|
|
||
| Rejected if the sender is not the `owner`. | ||
|
|
||
| ```mermaid | ||
| sequenceDiagram | ||
| participant U as Owner | ||
| participant S as SBT | ||
| U->>S: destroy(query_id) | ||
| alt owner | ||
| S->>S: owner = null, authority = null | ||
| S-->>U: excesses(query_id) | ||
| else not owner | ||
| S-->>U: reject | ||
| end | ||
| ``` | ||
|
|
||
| ## Revoke SBT | ||
skywardboundd marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| The `authority` can mark the SBT as revoked. Revoking twice is disallowed. | ||
|
|
||
| ```tlb title="TL-B" | ||
| ;; Inbound message to SBT | ||
| revoke#6f89f5e3 query_id:uint64 = InternalMsgBody; | ||
| ``` | ||
|
|
||
| `Inbound to SBT`. Revoke message contains the following data: | ||
|
|
||
| | Name | Type | Description | | ||
| | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | | ||
| | `query_id` | `uint64` | Identifies the `revoke` request for off-chain parsing. To ensure this process works correctly, always use a unique query ID. | | ||
|
|
||
| Rejected if: | ||
|
|
||
| - the sender is not the `authority`; | ||
| - the SBT was already revoked. | ||
|
|
||
| ```mermaid | ||
| sequenceDiagram | ||
| participant A as Authority | ||
| participant S as SBT | ||
| A->>S: revoke(query_id) | ||
| alt A == authority and not revoked | ||
| S->>S: revoked_at = now | ||
| else not authority or already revoked | ||
| S-->>A: reject | ||
| end | ||
| ``` | ||
|
|
||
| ### Quick field reference | ||
skywardboundd marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| - `item_id`: identifier of the SBT item (analogous to an NFT item) | ||
| - `owner`: current owner | ||
| - `authority`: the address allowed to revoke the SBT | ||
| - `content`: SBT content (may be attached optionally) | ||
| - `revoked_at`: Unix timestamp of revoke (`0` means not revoked) | ||
|
|
||
| ## See more: | ||
|
|
||
| - SBT Standard [TEP-85](https://github.com/ton-blockchain/TEPs/blob/c5bfe285ef91810fab02c5352593f5a1455458bf/text/0085-sbt-standard.md) | ||
skywardboundd marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
Empty file.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.