Skip to content

Commit d8bf132

Browse files
memearchivariusmemearchivarius
authored
Rework & proofread smart contract documentation #3 (#1084)
* init upd * mid-patch * Update sending-messages.md * Update internal-messages.md * Update internal-messages.md * Update message-modes-cookbook.mdx * forgotten part * Update external-messages.md * Update external-messages.md * conv resolve
1 parent 4e05dc7 commit d8bf132

File tree

6 files changed

+413
-360
lines changed

6 files changed

+413
-360
lines changed

‎docs/v3/documentation/smart-contracts/message-management/ecosystem-messages-layout.mdx‎

Lines changed: 133 additions & 154 deletions
Original file line numberDiff line numberDiff line change
@@ -1,197 +1,176 @@
1-
import ConceptImage from '@site/src/components/conceptImage';
2-
import ThemedImage from '@theme/ThemedImage';
3-
4-
# Ecosystem Messages Layout
1+
import ConceptImage from "@site/src/components/conceptImage";
2+
import ThemedImage from "@theme/ThemedImage";
53

4+
# Ecosystem messages layout
65

76
## Sending messages
8-
<br></br>
7+
98
<div class="text--center">
10-
<ThemedImage
11-
alt=""
12-
sources={{
13-
light: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_1.svg?raw=true',
14-
dark: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_1_dark.svg?raw=true',
15-
}}
16-
/>
9+
<ThemedImage
10+
alt="Diagram of message sending flow"
11+
sources={{
12+
light:
13+
"/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_1.svg?raw=true",
14+
dark: "/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_1_dark.svg?raw=true",
15+
}}
16+
/>
1717
</div>
18-
<br></br>
1918

2019
## Deploying a contract
21-
<br></br>
20+
2221
<div class="text--center">
23-
<ThemedImage
24-
alt=""
25-
sources={{
26-
light: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_2.svg?raw=true',
27-
dark: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_2_dark.svg?raw=true',
28-
}}
29-
/>
22+
<ThemedImage
23+
alt="Diagram of contract deployment process"
24+
sources={{
25+
light:
26+
"/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_2.svg?raw=true",
27+
dark: "/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_2_dark.svg?raw=true",
28+
}}
29+
/>
3030
</div>
31-
<br></br>
3231

3332
## Burn jettons
3433

35-
* [modern_jetton](https://github.com/EmelyanenkoK/modern_jetton/blob/master/contracts/op-codes.func) smart contract
36-
37-
<br></br>
38-
<div class="text--center">
39-
<ThemedImage
40-
alt=""
41-
sources={{
42-
light: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_3.svg?raw=true',
43-
dark: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_3_dark.svg?raw=true',
44-
}}
45-
/>
46-
</div>
47-
<br></br>
48-
34+
- Implementation: [modern_jetton](https://github.com/EmelyanenkoK/modern_jetton/blob/master/contracts/op-codes.func) smart contract
35+
<div class="text--center">
36+
<ThemedImage
37+
alt="Diagram of jetton burning process"
38+
sources={{
39+
light:
40+
"/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_3.svg?raw=true",
41+
dark: "/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_3_dark.svg?raw=true",
42+
}}
43+
/>
44+
</div>
4945

5046
## Request jetton wallet address
5147

52-
* [modern_jetton](https://github.com/EmelyanenkoK/modern_jetton/blob/master/contracts/op-codes.func) smart contract
53-
54-
<br></br>
55-
<div class="text--center">
56-
<ThemedImage
57-
alt=""
58-
sources={{
59-
light: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_4.svg?raw=true',
60-
dark: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_4_dark.svg?raw=true',
61-
}}
62-
/>
63-
</div>
64-
<br></br>
48+
- Implementation: [modern_jetton](https://github.com/EmelyanenkoK/modern_jetton/blob/master/contracts/op-codes.func) smart contract
49+
<div class="text--center">
50+
<ThemedImage
51+
alt="Diagram of wallet address request flow"
52+
sources={{
53+
light:
54+
"/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_4.svg?raw=true",
55+
dark: "/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_4_dark.svg?raw=true",
56+
}}
57+
/>
58+
</div>
6559

6660
## Transfer jettons
6761

68-
* [modern_jetton](https://github.com/EmelyanenkoK/modern_jetton/blob/master/contracts/op-codes.func) smart contract
69-
70-
<br></br>
71-
<div class="text--center">
72-
<ThemedImage
73-
alt=""
74-
sources={{
75-
light: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_5.svg?raw=true',
76-
dark: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_5_dark.svg?raw=true',
77-
}}
78-
/>
79-
</div>
80-
<br></br>
62+
- Implementation: [modern_jetton](https://github.com/EmelyanenkoK/modern_jetton/blob/master/contracts/op-codes.func) smart contract
63+
<div class="text--center">
64+
<ThemedImage
65+
alt="Diagram of jetton transfer process"
66+
sources={{
67+
light:
68+
"/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_5.svg?raw=true",
69+
dark: "/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_5_dark.svg?raw=true",
70+
}}
71+
/>
72+
</div>
8173

8274
## Mint jettons
8375

84-
* [minter-contract](https://github.com/ton-blockchain/minter-contract/blob/main/contracts/imports/op-codes.fc) smart contract
85-
86-
<br></br>
87-
<div class="text--center">
88-
<ThemedImage
89-
alt=""
90-
sources={{
91-
light: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_6.png?raw=true',
92-
dark: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_6_dark.png?raw=true',
93-
}}
94-
/>
95-
</div>
96-
<br></br>
76+
- Implementation: [minter-contract](https://github.com/ton-blockchain/minter-contract/blob/main/contracts/imports/op-codes.fc) smart contract
77+
<div class="text--center">
78+
<ThemedImage
79+
alt="Diagram of jetton minting process"
80+
sources={{
81+
light:
82+
"/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_6.png?raw=true",
83+
dark: "/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_6_dark.png?raw=true",
84+
}}
85+
/>
86+
</div>
9787

9888
## Prove SBT ownership to contract
9989

100-
* [nft_contracts](https://github.com/getgems-io/nft-contracts/blob/main/packages/contracts/sources/op-codes.fc) smart contract
101-
102-
<br></br>
103-
<div class="text--center">
104-
<ThemedImage
105-
alt=""
106-
sources={{
107-
light: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_7.svg?raw=true',
108-
dark: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_7_dark.svg?raw=true',
109-
}}
110-
/>
111-
</div>
112-
<br></br>
90+
- Implementation: [nft_contract](https://github.com/getgems-io/nft-contracts/blob/main/packages/contracts/sources/op-codes.fc) smart contract
91+
<div class="text--center">
92+
<ThemedImage
93+
alt="Diagram of SBT ownership verification"
94+
sources={{
95+
light:
96+
"/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_7.svg?raw=true",
97+
dark: "/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_7_dark.svg?raw=true",
98+
}}
99+
/>
100+
</div>
113101

114102
## Transfer NFT
115103

116-
* [nft_contracts](https://github.com/getgems-io/nft-contracts/blob/main/packages/contracts/sources/op-codes.fc) smart contract
117-
118-
<br></br>
119-
<div class="text--center">
120-
<ThemedImage
121-
alt=""
122-
sources={{
123-
light: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_8.svg?raw=true',
124-
dark: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_8_dark.svg?raw=true',
125-
}}
126-
/>
127-
</div>
128-
<br></br>
104+
- Implementation: [nft_contract](https://github.com/getgems-io/nft-contracts/blob/main/packages/contracts/sources/op-codes.fc) smart contract
105+
<div class="text--center">
106+
<ThemedImage
107+
alt="Diagram of NFT transfer process"
108+
sources={{
109+
light:
110+
"/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_8.svg?raw=true",
111+
dark: "/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_8_dark.svg?raw=true",
112+
}}
113+
/>
114+
</div>
129115

130116
## Mint NFT
131-
:::info
132-
Does not specified by NFT standard for /ton-blockchain /token-contract
133-
:::
134-
<br></br>
135-
<div class="text--center">
136-
<ThemedImage
137-
alt=""
138-
sources={{
139-
light: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_9.svg?raw=true',
140-
dark: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_9_dark.svg?raw=true',
141-
}}
142-
/>
143-
</div>
144-
<br></br>
145117

146-
## Batch mint NFT
147118
:::info
148-
Does not specified by NFT standard for /ton-blockchain /token-contract
149-
:::
150-
<br></br>
151-
<div class="text--center">
152-
<ThemedImage
153-
alt=""
154-
sources={{
155-
light: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_10.svg?raw=true',
156-
dark: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_10_dark.svg?raw=true',
157-
}}
158-
/>
159-
</div>
160-
<br></br>
119+
Not specified by NFT standard in /ton-blockchain/token-contract
120+
:::
161121

162-
## Destroy SBT by User
163-
164-
* [nft_contracts](https://github.com/getgems-io/nft-contracts/blob/main/packages/contracts/sources/op-codes.fc) smart contract
165-
166-
<br></br>
167122
<div class="text--center">
168-
<ThemedImage
169-
alt=""
170-
sources={{
171-
light: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_11.svg?raw=true',
172-
dark: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_11_dark.svg?raw=true',
173-
}}
174-
/>
123+
<ThemedImage
124+
alt="Diagram of NFT minting process"
125+
sources={{
126+
light:
127+
"/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_9.svg?raw=true",
128+
dark: "/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_9_dark.svg?raw=true",
129+
}}
130+
/>
175131
</div>
176-
<br></br>
177132

178-
## Destroy SBT by Admin
133+
## Batch mint NFT
179134

180-
* [nft_contracts](https://github.com/getgems-io/nft-contracts/blob/main/packages/contracts/sources/op-codes.fc) smart contract
135+
:::info
136+
Not specified by NFT standard in /ton-blockchain/token-contract
137+
:::
181138

182-
<br></br>
183139
<div class="text--center">
184-
<ThemedImage
185-
alt=""
186-
sources={{
187-
light: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_12.svg?raw=true',
188-
dark: '/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_12_dark.svg?raw=true',
189-
}}
190-
/>
140+
<ThemedImage
141+
alt="Diagram of batch NFT minting process"
142+
sources={{
143+
light:
144+
"/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_10.svg?raw=true",
145+
dark: "/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_10_dark.svg?raw=true",
146+
}}
147+
/>
191148
</div>
192-
<br></br>
193-
194149

150+
## Destroy SBT by User
195151

152+
- Implementation: [nft_contracts](https://github.com/getgems-io/nft-contracts/blob/main/packages/contracts/sources/op-codes.fc) smart contract
153+
<div class="text--center">
154+
<ThemedImage
155+
alt="Diagram of user-initiated SBT destruction"
156+
sources={{
157+
light:
158+
"/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_11.svg?raw=true",
159+
dark: "/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_11_dark.svg?raw=true",
160+
}}
161+
/>
162+
</div>
196163

164+
## Destroy SBT by Admin
197165

166+
- Implementation: [nft_contracts](https://github.com/getgems-io/nft-contracts/blob/main/packages/contracts/sources/op-codes.fc) smart contract
167+
<div class="text--center">
168+
<ThemedImage
169+
alt="Diagram of admin-initiated SBT destruction"
170+
sources={{
171+
light:
172+
"/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_12.svg?raw=true",
173+
dark: "/img/docs/ecosystem-messages-layout/ecosystem_messages_layout_12_dark.svg?raw=true",
174+
}}
175+
/>
176+
</div>

‎docs/v3/documentation/smart-contracts/message-management/external-messages.md‎

Lines changed: 10 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,21 @@
11
# External messages
22

3-
4-
External messages are `sent from the outside` to the smart contracts residing in TON Blockchain to make them perform certain actions.
3+
External messages are `sent from the outside` to the smart contracts residing in TON Blockchain to make them perform certain actions.
54

65
For instance, a wallet smart contract expects to receive external messages containing orders (e.g., internal messages to be sent from the wallet smart contract) signed by the wallet's owner. When such an external message is received by the wallet smart contract, it first checks the signature, then accepts the message (by running the TVM primitive `ACCEPT`), and then performs whatever actions are required.
76

8-
:::danger
9-
Notice that all external messages `must be protected` against replay attacks. The validators normally remove an external message from the pool of suggested external messages (received from the network); however, in some situations `another validator` could process the same external message twice (thus creating a second transaction for the same external message, leading to the duplication of the original action). Even worse, a `malicious actor could extract` the external message from the block containing the processing transaction and re-send it later. This could force a wallet smart contract to repeat a payment, for example.
10-
:::
7+
## Replay protection
118

12-
13-
export const Highlight = ({children, color}) => (
14-
<span
15-
style={{
16-
backgroundColor: color,
17-
borderRadius: '2px',
18-
color: '#4a080b',
19-
padding: '0.2rem',
20-
}}>
21-
{children}
22-
</span>
23-
);
9+
:::caution
10+
Stay vigilant and check replay protection in contracts for external-in messages.
11+
:::
2412

13+
Notice that all external messages must be protected against replay attacks. The validators normally remove an external message from the pool of suggested external messages (received from the network); however, in some situations another validator could process the same external message twice (thus creating a second transaction for the same external message, leading to the duplication of the original action). Even worse, a `malicious actor could extract` the external message from the block containing the processing transaction and re-send it later. This could force a wallet smart contract to repeat a payment.
2514

26-
The <Highlight color="#ffeced">simplest way to protect smart contracts from replay attacks</Highlight> related to external messages is to store a 32-bit counter `cur-seqno` in the persistent data of the smart contract, and to expect a `req-seqno` value in (the signed part of) any inbound external messages. Then an external message is accepted only if both the signature is valid and `req-seqno` equals `cur-seqno`. After successful processing, the `cur-seqno` value in the persistent data is increased by one, so the <Highlight color="#ffeced">same external message will never be accepted again</Highlight>.
15+
The simplest way to protect smart contracts from replay attacks related to external messages is to store a 32-bit counter `cur-seqno` in the persistent data of the smart contract, and to expect a `req-seqno` value in (the signed part of) any inbound external messages. Then an external message is accepted only if both the signature is valid and `req-seqno` equals `cur-seqno`. After successful processing, the `cur-seqno` value in the persistent data is increased by one, so the same external message will never be accepted again.
2716

28-
And <Highlight color="#ffeced">One could also</Highlight> include an `expire-at` field in the external message, and accept an external message only if the current Unix time is less than the value of this field. This approach can be used in conjunction with `seqno`; alternatively, the receiving smart contract could store the set of (the hashes of) all recent (not expired) accepted external messages in its persistent data, and reject a new external message if it is a duplicate of one of the stored messages. Some garbage collection of expired messages in this set should also be performed to avoid bloating the persistent data.
17+
And one could also include an `expire-at` field in the external message, and accept an external message only if the current Unix time is less than the value of this field. This approach can be used in conjunction with `seqno`; alternatively, the receiving smart contract could store the set of (the hashes of) all recent (not expired) accepted external messages in its persistent data, and reject a new external message if it is a duplicate of one of the stored messages. Some garbage collection of expired messages in this set should also be performed to avoid bloating the persistent data.
2918

30-
:::note
31-
In general, an external message begins with a 256-bit signature (if needed), a 32-bit `req-seqno` (if needed), a 32-bit `expire-at` (if needed), and possibly a 32-bit `op` and other required parameters depending on `op`. The layout of external messages does not need to be as standardized as that of internal messages because external messages are not used for interaction between different smart contracts (written by different developers and managed by different owners).
19+
:::note
20+
In general, an external message begins with a 256-bit signature (if needed), a 32-bit `req-seqno` (if needed), a 32-bit `expire-at` (if needed), and possibly a 32-bit `op` and other required parameters depending on `op`. The layout of external messages does not need to be as standardized as that of internal messages because external messages are not used for interaction between different smart contracts (written by different developers and managed by different owners).
3221
:::

0 commit comments

Comments
 (0)