You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Nov 28, 2025. It is now read-only.
In this pattern, your contract first receives the Pyth data, then forwards it to the Pyth contract for validation, and finally gets the validated prices back.
139
-
This approach is useful when you want to transfer jettons to your contract while also providing price data.
140
-
<Callouttype="info"emoji="ℹ️">
141
-
This data flow is simplified. In reality, the "Jetton Wallet" step consists of a sequence of transactions: User's jetton wallet → EVAA jetton wallet → EVAA master. These internal details are omitted here to highlight the main flow and the interaction with Pyth.
142
-
</Callout>
137
+
In this pattern, your contract first receives the Pyth data, then forwards it to the Pyth contract for validation, and finally gets the validated prices back.
138
+
This approach is useful when you want to transfer jettons to your contract while also providing price data.
139
+
<Callouttype="info"emoji="ℹ️">
140
+
This data flow is simplified. In reality, the "Jetton Wallet" step consists
141
+
of a sequence of transactions: User's jetton wallet → EVAA jetton wallet →
142
+
EVAA master. These internal details are omitted here to highlight the main
143
+
flow and the interaction with Pyth.
144
+
</Callout>
143
145
144
146
They both are demonstrated in the [Pyth Connector example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/pyth-connector). <br/>
145
-
These same patterns are also used in the [EVAA Protocol code](https://github.com/evaafi/contracts/tree/v8) for implementing following operations:
147
+
These same patterns are also used in the [EVAA Protocol code](https://github.com/evaafi/contracts/tree/v8) for implementing following operations:
148
+
146
149
- Pyth proxy pattern: liquidate TON / supply_withdraw TON.
@@ -151,7 +154,9 @@ Choose the pattern that best fits your use case and how you want to handle asset
151
154
Each operation described above can result in either a successful outcome or an error. It is important to consider and handle both scenarios for every pattern.
152
155
153
156
### Pyth proxy: Success
157
+
154
158
#### EVAA flow
159
+
155
160
In the EVAA protocol, the operations that implement the Pyth proxy pattern are <b>`liquidate (TON)`</b> and <b>`supply_withdraw (TON)`</b>. In these cases, the user sends a request to the Pyth contract using the native TON asset. As a result of the operation, the user may receive either TON or JETTON tokens back, depending on the outcome of the transaction.
156
161
157
162
```mermaid
@@ -174,8 +179,8 @@ sequenceDiagram
174
179
-[process the supply_withdraw operation (TON): master.fc](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L192-L211)
175
180
-[process the liquidate operation (TON): master.fc](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L171-L190)
176
181
177
-
178
182
#### Pyth Connector flow
183
+
179
184
The Pyth Connector example also has a similar flow. It has two main operations: proxy and onchain-getter.
180
185
They have no practical purpose other than to demonstrate the patterns described above.
181
186
The data flow is practically the same as the EVAA protocol, only operation codes are different.
@@ -201,6 +206,7 @@ sequenceDiagram
201
206
-[process the connector_proxy_operation: proxy_operation.fc](https://github.com/pyth-network/pyth-examples/blob/main/price_feeds/ton/pyth-connector/contracts/PythConnector/operations/proxy_operation.fc#L17-L40)
202
207
203
208
### Pyth proxy: Error handling
209
+
204
210
In the Pyth proxy pattern, when an error occurs (i.e., Pyth cannot process the request and sends a `response_error` with op 0x10002), the error report is sent directly back to the user who initiated the transaction, not to a contract. This is different from the on-chain getter pattern, where the error is returned to the EVAA Master contract for further handling and potential refund logic. In the proxy case, the user receives the error response from the Pyth contract, including the error code and the original query ID, allowing the user to identify and handle the failure on their side.
205
211
206
212
```mermaid
@@ -214,7 +220,9 @@ sequenceDiagram
214
220
```
215
221
216
222
### Pyth onchain-getter: Success
223
+
217
224
#### EVAA flow
225
+
218
226
```mermaid
219
227
sequenceDiagram
220
228
autonumber
@@ -241,6 +249,7 @@ sequenceDiagram
241
249
-[handle pyth response: liquidate_jetton and supply_withdraw_jetton](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L131-L167)
242
250
243
251
#### Pyth Connector flow
252
+
244
253
Pyth Connector's onchain-getter operation has a simplified flow compared to the EVAA protocol.
245
254
246
255
```mermaid
@@ -260,6 +269,7 @@ sequenceDiagram
260
269
note over P: Pyth Contract validates update data and <br/> sends prices with payload to Pyth Connector contract
261
270
note over M: Pyth Connector validates sender <br/> parses payload and <br/> processes the transaction
262
271
```
272
+
263
273
- Related code (GitHub):
264
274
-[entry for jetton-transfer notification: pyth_connector.fc](https://github.com/pyth-network/pyth-examples/blob/main/price_feeds/ton/pyth-connector/contracts/PythConnector/pyth_connector.fc#L109)
Pyth sends an error response (`response_error`, op 0x10002) when it cannot process the price feed update request. This can happen if the request is malformed, contains invalid or outdated feed data, or if the requested feeds are unavailable. In such cases, the error response includes an error code and the original operation payload, allowing the original sender to handle the failure and refund the user if necessary.
272
283
273
284
#### EVAA flow
285
+
274
286
The error response is sent directly back to the user who initiated the transaction, not to a contract. This is different from the proxy case, where the error is returned to the EVAA Master contract for further handling and potential refund logic. In the onchain-getter case, the user receives the error response from the Pyth contract, including the error code and the original query ID, allowing the user to identify and handle the failure on their side.
275
287
276
288
```mermaid
@@ -294,7 +306,9 @@ sequenceDiagram
294
306
-[refund the supply_withdraw_jetton operation: master-supply-withdrawal.fc](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/core/master-supply-withdrawal.fc#L899-L935)
295
307
296
308
#### Pyth Connector
309
+
297
310
The Pyth Connector error handling flow looks the same as the EVAA protocol.
311
+
298
312
```mermaid
299
313
sequenceDiagram
300
314
autonumber
@@ -309,9 +323,10 @@ sequenceDiagram
309
323
P-->>M: response_error (op 0x10002)
310
324
M-->>U: refund with error code
311
325
```
312
-
-[entry point for the Pyth error message: pyth_connector.fc](https://github.com/pyth-network/pyth-examples/blob/main/price_feeds/ton/pyth-connector/contracts/PythConnector/pyth_connector.fc#L31)
313
-
-[validate sender and detect onchain_getter_operation: pyth_connector.fc](https://github.com/pyth-network/pyth-examples/blob/main/price_feeds/ton/pyth-connector/contracts/PythConnector/pyth_connector.fc#L32-L43)
314
-
-[handle the operation failure, refund jettons: onchain_getter_operation.fc](https://github.com/pyth-network/pyth-examples/blob/main/price_feeds/ton/pyth-connector/contracts/PythConnector/operations/onchain_getter_operation.fc#L21-L35)
326
+
327
+
-[entry point for the Pyth error message: pyth_connector.fc](https://github.com/pyth-network/pyth-examples/blob/main/price_feeds/ton/pyth-connector/contracts/PythConnector/pyth_connector.fc#L31)
328
+
-[validate sender and detect onchain_getter_operation: pyth_connector.fc](https://github.com/pyth-network/pyth-examples/blob/main/price_feeds/ton/pyth-connector/contracts/PythConnector/pyth_connector.fc#L32-L43)
329
+
-[handle the operation failure, refund jettons: onchain_getter_operation.fc](https://github.com/pyth-network/pyth-examples/blob/main/price_feeds/ton/pyth-connector/contracts/PythConnector/operations/onchain_getter_operation.fc#L21-L35)
0 commit comments