From eff9a2d630f87dc01d78cad2b00cdfc6df127f1e Mon Sep 17 00:00:00 2001 From: master_jedy Date: Tue, 2 Sep 2025 01:06:28 +0200 Subject: [PATCH 1/8] add pyth patterns info Signed-off-by: master_jedy --- pages/price-feeds/use-real-time-data/ton.mdx | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/pages/price-feeds/use-real-time-data/ton.mdx b/pages/price-feeds/use-real-time-data/ton.mdx index 53dd0473..65ce580d 100644 --- a/pages/price-feeds/use-real-time-data/ton.mdx +++ b/pages/price-feeds/use-real-time-data/ton.mdx @@ -124,6 +124,22 @@ This code snippet does the following: 4. Prepares the update data and calculates the update fee. 5. Updates the price feeds on the TON contract. +When providing Pyth data to your contract, there are typically two main scenarios: either you call a method supplying TON, or you transfer jettons. + +They both are demonstrated in the [Pyth Connector example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/pyth_connector). +These same patterns are also used in the [EVAA Protocol code](https://github.com/evaafi/contracts). + +1. **Pyth Proxy Call Pattern** + **Flow:** *User → Pyth → Your-Contract* + Use this method if you only need to send TON to your contract or simply call a contract method, without involving jettons. + +2. **Onchain Getter Pattern** + **Flow:** *User → User-Jetton-Wallet → Your-Contract → Pyth → Your-Contract* + 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. + This approach is useful when you want to transfer jettons to your contract while also providing price data. + +Choose the pattern that best fits your use case and how you want to handle assets and price updates in your application. + ## Additional Resources You may find these additional resources helpful for developing your TON application: @@ -134,3 +150,5 @@ You may find these additional resources helpful for developing your TON applicat - [Pyth TON SDK](https://github.com/pyth-network/pyth-crosschain/tree/main/target_chains/ton/sdk) - [Pyth TON SDK Example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/sdk_js_usage) - [Pyth TON Send USD Example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/send_usd) +- [Pyth Connector Example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/pyth_connector) +- [EVAA Protocol Code](https://github.com/evaafi/contracts) From 5e32248294ec792b0723fbeb8aee88db6b6d1e2a Mon Sep 17 00:00:00 2001 From: master_jedy Date: Tue, 2 Sep 2025 14:32:31 +0200 Subject: [PATCH 2/8] fix minor issues Signed-off-by: master_jedy --- pages/price-feeds/use-real-time-data/ton.mdx | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/pages/price-feeds/use-real-time-data/ton.mdx b/pages/price-feeds/use-real-time-data/ton.mdx index 65ce580d..2fcc1930 100644 --- a/pages/price-feeds/use-real-time-data/ton.mdx +++ b/pages/price-feeds/use-real-time-data/ton.mdx @@ -126,15 +126,21 @@ This code snippet does the following: When providing Pyth data to your contract, there are typically two main scenarios: either you call a method supplying TON, or you transfer jettons. -They both are demonstrated in the [Pyth Connector example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/pyth_connector). -These same patterns are also used in the [EVAA Protocol code](https://github.com/evaafi/contracts). +They both are demonstrated in the [Pyth Connector example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/pyth-connector). + +These same patterns are also used in the +[EVAA Protocol code](https://github.com/evaafi/contracts/tree/v8). 1. **Pyth Proxy Call Pattern** **Flow:** *User → Pyth → Your-Contract* + Use this method if you only need to send TON to your contract or simply call a contract method, without involving jettons. 2. **Onchain Getter Pattern** - **Flow:** *User → User-Jetton-Wallet → Your-Contract → Pyth → Your-Contract* + **Flow:** *User → User-JW → Your-Contract-JW → Your-Contract → Pyth → Your-Contract* + + > JW = Jetton Wallet + 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. This approach is useful when you want to transfer jettons to your contract while also providing price data. @@ -150,5 +156,5 @@ You may find these additional resources helpful for developing your TON applicat - [Pyth TON SDK](https://github.com/pyth-network/pyth-crosschain/tree/main/target_chains/ton/sdk) - [Pyth TON SDK Example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/sdk_js_usage) - [Pyth TON Send USD Example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/send_usd) -- [Pyth Connector Example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/pyth_connector) -- [EVAA Protocol Code](https://github.com/evaafi/contracts) +- [Pyth Connector Example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/pyth-connector) +- [EVAA Protocol Code](https://github.com/evaafi/contracts/tree/v8) From 16ed2bfc4bf3f30fec8c26db1d9b009c03fc56ac Mon Sep 17 00:00:00 2001 From: master_jedy Date: Thu, 4 Sep 2025 16:28:56 +0200 Subject: [PATCH 3/8] add more info about patterns Signed-off-by: master_jedy --- pages/price-feeds/use-real-time-data/ton.mdx | 108 ++++++++++++++++--- 1 file changed, 95 insertions(+), 13 deletions(-) diff --git a/pages/price-feeds/use-real-time-data/ton.mdx b/pages/price-feeds/use-real-time-data/ton.mdx index 2fcc1930..98e8991d 100644 --- a/pages/price-feeds/use-real-time-data/ton.mdx +++ b/pages/price-feeds/use-real-time-data/ton.mdx @@ -124,27 +124,109 @@ This code snippet does the following: 4. Prepares the update data and calculates the update fee. 5. Updates the price feeds on the TON contract. -When providing Pyth data to your contract, there are typically two main scenarios: either you call a method supplying TON, or you transfer jettons. + +# Patterns for Providing Pyth Data to Your Contract + +There are typically two main scenarios: either you call a method supplying TON, or you transfer jettons. + +- **TON proxy**: `User → Pyth → EVAA Master → ... (further processing)` +Use this method if you only need to send TON to your contract or simply call a contract method, without involving jettons. + +- **Jetton on-chain getter**: `User → Jetton Wallet → EVAA Master → Pyth → EVAA Master → ... (further processing)` +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. +This approach is useful when you want to transfer jettons to your contract while also providing price data. + *Note: This diagram 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.* They both are demonstrated in the [Pyth Connector example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/pyth-connector). +These same patterns are also used in the [EVAA Protocol code](https://github.com/evaafi/contracts/tree/v8). -These same patterns are also used in the -[EVAA Protocol code](https://github.com/evaafi/contracts/tree/v8). +Choose the pattern that best fits your use case and how you want to handle assets and price updates in your application. -1. **Pyth Proxy Call Pattern** - **Flow:** *User → Pyth → Your-Contract* +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. - Use this method if you only need to send TON to your contract or simply call a contract method, without involving jettons. +## Pyth proxy: Success +In the EVAA protocol, the operations that implement the Pyth proxy pattern are `liquidate (TON)` and `supply_withdraw (TON)`. 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. -2. **Onchain Getter Pattern** - **Flow:** *User → User-JW → Your-Contract-JW → Your-Contract → Pyth → Your-Contract* - - > JW = Jetton Wallet +```mermaid +sequenceDiagram + autonumber + participant "U" as "User" + participant "P" as "Pyth Contract" + participant "M" as "EVAA Master" - 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. - This approach is useful when you want to transfer jettons to your contract while also providing price data. + note over "M": master.fc:121 — received from Pyth (op 5) + "U"->>"P": request (0x3 liquidate_master or 0x4 supply_withdraw_master) + "P"-->>"M": op 5 parse_price_feed_updates (prices) + note over "M": Master accepts and processes the transaction +``` + +- Related code (GitHub): + - [master.fc: entry for Pyth message](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L121) + - [Pyth proxy: supply_withdraw (TON) in master.fc](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L192-L211) + - [Pyth proxy: liquidate (TON) in master.fc](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L171-L190) + + +## Pyth proxy: Error handling +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. + +```mermaid +sequenceDiagram + autonumber + participant "U" as "User" + participant "P" as "Pyth Contract" + + "U"->>"P": request + "P"-->>"U": response_error (op 0x10002) with error_code and query_id +``` + + +## Pyth onchain-getter: Success + +```mermaid +sequenceDiagram + autonumber + participant "U" as "User" + participant "JW" as "Jetton Wallet" + participant "M" as "EVAA Master" + participant "P" as "Pyth Contract" + + "U"->>"JW": transfer with forward_payload + note right of "U": op: liquidate_master or supply_withdraw_master_jetton + "JW"->>"M": transfer_notification + "M"->>"P": op 5 parse_price_feed_updates
+ update_data + target_feeds
+ op_payload(liquidate_master_jetton_process / supply_withdraw_master_jetton) + "P"-->>"M": op 5 parse_price_feed_updates
(prices, pyth_sender = M) + note over "M": Master accepts and processes the transaction +``` + +- Related code (GitHub): + - [Entry: master.fc (pyth_parse_price_feed_updates)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L121) + - [Onchain-getter branches: liquidate jetton and supply_withdraw jetton](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L131-L167) + - [Request to Pyth (liquidate jetton)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/core/master-liquidate.fc#L728-L742) + - [Request to Pyth (supply_withdraw jetton)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/core/master-supply-withdrawal.fc#L446-L461) + +## Pyth onchain-getter: Pyth error +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 (EVAA Master contract) to handle the failure and refund the user if necessary. + +```mermaid +sequenceDiagram + autonumber + participant "U" as "User" + participant "JW" as "Jetton Wallet" + participant "M" as "EVAA Master" + participant "P" as "Pyth Contract" + + "U"->>"JW": transfer with forward_payload + "JW"->>"M": transfer_notification + "M"->>"P": request (op 5 parse_price_feed_updates) + "P"-->>"M": response_error (op 0x10002) + "M"-->>"U": refund with error code +``` + +- Related code (GitHub): + - [Error entry: master.fc (pyth_response_error)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L92-L119) + - [Refund (liquidate jetton)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/core/master-liquidate.fc#L753-L786) + - [Refund (supply_withdraw jetton)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/core/master-supply-withdrawal.fc#L899-L935) -Choose the pattern that best fits your use case and how you want to handle assets and price updates in your application. ## Additional Resources From ce855c0109d94eccd0361fd0a430ae63cb90c31b Mon Sep 17 00:00:00 2001 From: master_jedy Date: Thu, 4 Sep 2025 16:38:13 +0200 Subject: [PATCH 4/8] minor fix Signed-off-by: master_jedy --- pages/price-feeds/use-real-time-data/ton.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pages/price-feeds/use-real-time-data/ton.mdx b/pages/price-feeds/use-real-time-data/ton.mdx index 98e8991d..8e8afc7b 100644 --- a/pages/price-feeds/use-real-time-data/ton.mdx +++ b/pages/price-feeds/use-real-time-data/ton.mdx @@ -137,8 +137,10 @@ In this pattern, your contract first receives the Pyth data, then forwards it to This approach is useful when you want to transfer jettons to your contract while also providing price data. *Note: This diagram 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.* -They both are demonstrated in the [Pyth Connector example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/pyth-connector). -These same patterns are also used in the [EVAA Protocol code](https://github.com/evaafi/contracts/tree/v8). +They both are demonstrated in the [Pyth Connector example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/pyth-connector).
+These same patterns are also used in the [EVAA Protocol code](https://github.com/evaafi/contracts/tree/v8) for implementing following operations: +- Pyth proxy pattern: liquidate TON / supply_withdraw TON. +- Onchain-getter pattern: liquidate jetton / supply_withdraw jetton. Choose the pattern that best fits your use case and how you want to handle assets and price updates in your application. From 41c0c96e7c2e36b07a796d707318277b78e7d3d1 Mon Sep 17 00:00:00 2001 From: master_jedy Date: Sat, 6 Sep 2025 14:33:57 +0200 Subject: [PATCH 5/8] fix review issues Signed-off-by: master_jedy --- pages/price-feeds/use-real-time-data/ton.mdx | 82 ++++++++++---------- 1 file changed, 42 insertions(+), 40 deletions(-) diff --git a/pages/price-feeds/use-real-time-data/ton.mdx b/pages/price-feeds/use-real-time-data/ton.mdx index 8e8afc7b..2b2dc9bf 100644 --- a/pages/price-feeds/use-real-time-data/ton.mdx +++ b/pages/price-feeds/use-real-time-data/ton.mdx @@ -2,7 +2,7 @@ description: Consume Pyth Network prices in TON applications --- -import { Tabs } from "nextra/components"; +import { Tabs, Callout } from "nextra/components"; # How to Use Real-Time Data in TON Contracts @@ -125,7 +125,7 @@ This code snippet does the following: 5. Updates the price feeds on the TON contract. -# Patterns for Providing Pyth Data to Your Contract +## Patterns for Providing Pyth Data to Your Contract There are typically two main scenarios: either you call a method supplying TON, or you transfer jettons. @@ -135,7 +135,9 @@ Use this method if you only need to send TON to your contract or simply call a c - **Jetton on-chain getter**: `User → Jetton Wallet → EVAA Master → Pyth → EVAA Master → ... (further processing)` 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. This approach is useful when you want to transfer jettons to your contract while also providing price data. - *Note: This diagram 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.* + +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. + They both are demonstrated in the [Pyth Connector example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/pyth-connector).
These same patterns are also used in the [EVAA Protocol code](https://github.com/evaafi/contracts/tree/v8) for implementing following operations: @@ -146,20 +148,20 @@ Choose the pattern that best fits your use case and how you want to handle asset 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. -## Pyth proxy: Success +### Pyth proxy: Success In the EVAA protocol, the operations that implement the Pyth proxy pattern are `liquidate (TON)` and `supply_withdraw (TON)`. 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. ```mermaid sequenceDiagram autonumber - participant "U" as "User" - participant "P" as "Pyth Contract" - participant "M" as "EVAA Master" - - note over "M": master.fc:121 — received from Pyth (op 5) - "U"->>"P": request (0x3 liquidate_master or 0x4 supply_withdraw_master) - "P"-->>"M": op 5 parse_price_feed_updates (prices) - note over "M": Master accepts and processes the transaction + participant U as User + participant P as Pyth Contract + participant M as EVAA Master + + note over M: master.fc:121 — received from Pyth (op 5) + U->>P: request (0x3 liquidate_master or 0x4 supply_withdraw_master) + P-->>M: op 5 parse_price_feed_updates (prices) + note over M: Master accepts and processes the transaction ``` - Related code (GitHub): @@ -168,36 +170,36 @@ sequenceDiagram - [Pyth proxy: liquidate (TON) in master.fc](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L171-L190) -## Pyth proxy: Error handling +### Pyth proxy: Error handling 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. ```mermaid sequenceDiagram autonumber - participant "U" as "User" - participant "P" as "Pyth Contract" + participant U as User + participant P as Pyth Contract - "U"->>"P": request - "P"-->>"U": response_error (op 0x10002) with error_code and query_id + U->>P: request + P-->>U: response_error (op 0x10002) with error_code and query_id ``` -## Pyth onchain-getter: Success +### Pyth onchain-getter: Success ```mermaid sequenceDiagram autonumber - participant "U" as "User" - participant "JW" as "Jetton Wallet" - participant "M" as "EVAA Master" - participant "P" as "Pyth Contract" - - "U"->>"JW": transfer with forward_payload - note right of "U": op: liquidate_master or supply_withdraw_master_jetton - "JW"->>"M": transfer_notification - "M"->>"P": op 5 parse_price_feed_updates
+ update_data + target_feeds
+ op_payload(liquidate_master_jetton_process / supply_withdraw_master_jetton) - "P"-->>"M": op 5 parse_price_feed_updates
(prices, pyth_sender = M) - note over "M": Master accepts and processes the transaction + participant U as User + participant JW as Jetton Wallet + participant M as EVAA Master + participant P as Pyth Contract + + U->>JW: transfer with forward_payload + note right of U: op: liquidate_master or supply_withdraw_master_jetton + JW->>M: transfer_notification + M->>P: op 5 parse_price_feed_updates
+ update_data + target_feeds
+ op_payload(liquidate_master_jetton_process / supply_withdraw_master_jetton) + P-->>M: op 5 parse_price_feed_updates
(prices, pyth_sender = M) + note over M: Master accepts and processes the transaction ``` - Related code (GitHub): @@ -206,22 +208,22 @@ sequenceDiagram - [Request to Pyth (liquidate jetton)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/core/master-liquidate.fc#L728-L742) - [Request to Pyth (supply_withdraw jetton)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/core/master-supply-withdrawal.fc#L446-L461) -## Pyth onchain-getter: Pyth error +### Pyth onchain-getter: Pyth error 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 (EVAA Master contract) to handle the failure and refund the user if necessary. ```mermaid sequenceDiagram autonumber - participant "U" as "User" - participant "JW" as "Jetton Wallet" - participant "M" as "EVAA Master" - participant "P" as "Pyth Contract" - - "U"->>"JW": transfer with forward_payload - "JW"->>"M": transfer_notification - "M"->>"P": request (op 5 parse_price_feed_updates) - "P"-->>"M": response_error (op 0x10002) - "M"-->>"U": refund with error code + participant U as User + participant JW as Jetton Wallet + participant M as EVAA Master + participant P as Pyth Contract + + U->>JW: transfer with forward_payload + JW->>M: transfer_notification + M->>P: request (op 5 parse_price_feed_updates) + P-->>M: response_error (op 0x10002) + M-->>U: refund with error code ``` - Related code (GitHub): From d2547528cf71a330dbad84909ba8540bc1a8de02 Mon Sep 17 00:00:00 2001 From: master_jedy Date: Sat, 6 Sep 2025 14:46:30 +0200 Subject: [PATCH 6/8] remove trailing whitespaces Signed-off-by: master_jedy --- pages/price-feeds/use-real-time-data/ton.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/price-feeds/use-real-time-data/ton.mdx b/pages/price-feeds/use-real-time-data/ton.mdx index 2b2dc9bf..3b05dbcf 100644 --- a/pages/price-feeds/use-real-time-data/ton.mdx +++ b/pages/price-feeds/use-real-time-data/ton.mdx @@ -132,8 +132,8 @@ There are typically two main scenarios: either you call a method supplying TON, - **TON proxy**: `User → Pyth → EVAA Master → ... (further processing)` Use this method if you only need to send TON to your contract or simply call a contract method, without involving jettons. -- **Jetton on-chain getter**: `User → Jetton Wallet → EVAA Master → Pyth → EVAA Master → ... (further processing)` -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. +- **Jetton on-chain getter**: `User → Jetton Wallet → EVAA Master → Pyth → EVAA Master → ... (further processing)` +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. This approach is useful when you want to transfer jettons to your contract while also providing price data. 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. From 71fdd5cb5a53397de2ffbf34704609945b2c6798 Mon Sep 17 00:00:00 2001 From: master_jedy Date: Thu, 6 Nov 2025 16:00:41 +0100 Subject: [PATCH 7/8] clarify evaa flow, add pyth connector flow Signed-off-by: master_jedy --- pages/price-feeds/use-real-time-data/ton.mdx | 127 +++++++++++++++---- 1 file changed, 103 insertions(+), 24 deletions(-) diff --git a/pages/price-feeds/use-real-time-data/ton.mdx b/pages/price-feeds/use-real-time-data/ton.mdx index 3b05dbcf..4c23beca 100644 --- a/pages/price-feeds/use-real-time-data/ton.mdx +++ b/pages/price-feeds/use-real-time-data/ton.mdx @@ -149,6 +149,7 @@ Choose the pattern that best fits your use case and how you want to handle asset 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. ### Pyth proxy: Success +#### EVAA flow In the EVAA protocol, the operations that implement the Pyth proxy pattern are `liquidate (TON)` and `supply_withdraw (TON)`. 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. ```mermaid @@ -158,18 +159,45 @@ sequenceDiagram participant P as Pyth Contract participant M as EVAA Master - note over M: master.fc:121 — received from Pyth (op 5) - U->>P: request (0x3 liquidate_master or 0x4 supply_withdraw_master) - P-->>M: op 5 parse_price_feed_updates (prices) - note over M: Master accepts and processes the transaction + note over M: master.fc:121 — received from Pyth (op 0x5) + U->>P: op 0x5 parse_price_feed_updates (price feeds + update data)
payload (op 0x3 liquidate_master | 0x4 supply_withdraw_master) + note right of U: send request to Pyth Contract with update data and operation payload
destination address is EVAA Master contract + P-->>M: op 0x5 parse_price_feed_updates (price feeds + prices)
payload (op 0x3 liquidate_master | 0x4 supply_withdraw_master) + note right of P: Pyth Contract validates update data and
sends prices with payload to EVAA Master contract + note over M: EVAA Master validates sender
parses payload and
processes the transaction ``` - Related code (GitHub): - - [master.fc: entry for Pyth message](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L121) - - [Pyth proxy: supply_withdraw (TON) in master.fc](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L192-L211) - - [Pyth proxy: liquidate (TON) in master.fc](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L171-L190) + - [entry for the Pyth message: master.fc](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L121) + - [process the supply_withdraw operation (TON): master.fc](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L192-L211) + - [process the liquidate operation (TON): master.fc](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L171-L190) +#### Pyth Connector flow +The Pyth Connector example also has a similar flow. It has two main operations: proxy and onchain-getter. +They have no practical purpose other than to demonstrate the patterns described above. +The data flow is practically the same as the EVAA protocol, only operation codes are different. + +```mermaid +sequenceDiagram + autonumber + participant U as User + participant P as Pyth Contract + participant M as Pyth Connector + + note over M: pyth_connector.fc:78 — received from Pyth (op 0x5) + U->>P: op 0x5 parse_price_feed_updates (price feeds + update data)
payload (op 0x4 connector_proxy_operation) + note right of U: send request to the Pyth Contract with update data and operation payload
destination address is the Pyth Connector contract + P-->>M: op 0x5 parse_price_feed_updates (price feeds + prices)
payload (op 0x4 connector_proxy_operation) + note right of P: Pyth Contract validates update data and
sends prices with payload to Pyth Connector contract + note over M: Pyth Connector validates sender
parses payload and
processes the transaction +``` + +- Related code (GitHub): + - [entry for the Pyth message: pyth-connector.fc](https://github.com/pyth-network/pyth-examples/blob/main/price_feeds/ton/pyth-connector/contracts/PythConnector/pyth_connector.fc#L78) + - [detect the connector_proxy_operation: pyth-connector.fc](https://github.com/pyth-network/pyth-examples/blob/main/price_feeds/ton/pyth-connector/contracts/PythConnector/pyth_connector.fc#L97) + - [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) + ### Pyth proxy: Error handling 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. @@ -183,9 +211,8 @@ sequenceDiagram P-->>U: response_error (op 0x10002) with error_code and query_id ``` - ### Pyth onchain-getter: Success - +#### EVAA flow ```mermaid sequenceDiagram autonumber @@ -194,22 +221,55 @@ sequenceDiagram participant M as EVAA Master participant P as Pyth Contract - U->>JW: transfer with forward_payload - note right of U: op: liquidate_master or supply_withdraw_master_jetton - JW->>M: transfer_notification - M->>P: op 5 parse_price_feed_updates
+ update_data + target_feeds
+ op_payload(liquidate_master_jetton_process / supply_withdraw_master_jetton) - P-->>M: op 5 parse_price_feed_updates
(prices, pyth_sender = M) - note over M: Master accepts and processes the transaction + U->>JW: op transfer_jetton, forward_payload
(liquidate_master_jetton | supply_withdraw_master_jetton) + note right of U: transfer jetton with forward payload: + JW->>M: op transfer_notification, forward_payload
(liquidate_master_jetton | supply_withdraw_master_jetton) + note right of JW: transfer notification with forward payload: + M->>P: op 0x5 parse_price_feed_updates + update data + target feeds
+ payload(liquidate_master_jetton_process | supply_withdraw_master_jetton_process) + P-->>M: op 0x5 parse_price_feed_updates(price feeds + prices)
+ payload(liquidate_master_jetton_process | supply_withdraw_master_jetton_process) + note over P: Pyth Contract validates update data and
sends prices with payload to EVAA Master contract + note over M: EVAA Master validates sender
parses payload and
processes the transaction ``` - Related code (GitHub): - - [Entry: master.fc (pyth_parse_price_feed_updates)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L121) - - [Onchain-getter branches: liquidate jetton and supply_withdraw jetton](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L131-L167) - - [Request to Pyth (liquidate jetton)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/core/master-liquidate.fc#L728-L742) - - [Request to Pyth (supply_withdraw jetton)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/core/master-supply-withdrawal.fc#L446-L461) + - [entry for jetton-transfer notification: master.fc](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L502) + - [request to Pyth (op liquidate_jetton)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/core/master-liquidate.fc#L728-L742) + - [request to Pyth (op supply_withdraw jetton)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/core/master-supply-withdrawal.fc#L446-L461) + - [entry point for Pyth response: master.fc (op pyth_parse_price_feed_updates)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L121) + - [handle pyth response: liquidate_jetton and supply_withdraw_jetton](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L131-L167) + +#### Pyth Connector flow +Pyth Connector's onchain-getter operation has a simplified flow compared to the EVAA protocol. + +```mermaid +sequenceDiagram + autonumber + participant U as User + participant JW as Jetton Wallet + participant M as Pyth Connector + participant P as Pyth Contract + + U->>JW: op transfer_jetton, forward_payload: (onchain_getter_operation) + note right of U: transfer jetton with forward payload + JW->>M: op transfer_notification, forward_payload: (onchain_getter_operation) + note right of JW: transfer notification with forward payload + M->>P: op 0x5 parse_price_feed_updates + update data + target feeds
+ payload(onchain_getter_operation) + P-->>M: op 0x5 parse_price_feed_updates(price feeds + prices)
+ payload(onchain_getter_operation) + note over P: Pyth Contract validates update data and
sends prices with payload to Pyth Connector contract + note over M: Pyth Connector validates sender
parses payload and
processes the transaction +``` +- Related code (GitHub): + - [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) + - [onchain_getter_operation request: pyth-connector.fc](https://github.com/pyth-network/pyth-examples/blob/main/price_feeds/ton/pyth-connector/contracts/PythConnector/pyth_connector.fc#L126) + - [send request to the Pyth Contract: 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#L71) + - [entry for the Pyth response: pyth-connector.fc](https://github.com/pyth-network/pyth-examples/blob/main/price_feeds/ton/pyth-connector/contracts/PythConnector/pyth_connector.fc#L78) + - [onchain_getter_operation process: pyth-connector.fc](https://github.com/pyth-network/pyth-examples/blob/main/price_feeds/ton/pyth-connector/contracts/PythConnector/pyth_connector.fc#L90) ### Pyth onchain-getter: Pyth error -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 (EVAA Master contract) to handle the failure and refund the user if necessary. +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. + +#### EVAA flow +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. ```mermaid sequenceDiagram @@ -221,16 +281,35 @@ sequenceDiagram U->>JW: transfer with forward_payload JW->>M: transfer_notification - M->>P: request (op 5 parse_price_feed_updates) + M->>P: request (op 0x5 parse_price_feed_updates) P-->>M: response_error (op 0x10002) M-->>U: refund with error code ``` - Related code (GitHub): - - [Error entry: master.fc (pyth_response_error)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L92-L119) - - [Refund (liquidate jetton)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/core/master-liquidate.fc#L753-L786) - - [Refund (supply_withdraw jetton)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/core/master-supply-withdrawal.fc#L899-L935) + - [entry point for the Pyth error message: master.fc (pyth_response_error)](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L92-L119) + - [refund the liquidate jetton operation: master-liquidate.fc](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/core/master-liquidate.fc#L753-L786) + - [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) +#### Pyth Connector +The Pyth Connector error handling flow looks the same as the EVAA protocol. +```mermaid +sequenceDiagram + autonumber + participant U as User + participant JW as Jetton Wallet + participant M as Pyth Connector + participant P as Pyth Contract + + U->>JW: transfer with forward_payload + JW->>M: transfer_notification + M->>P: request (op 0x5 parse_price_feed_updates) + P-->>M: response_error (op 0x10002) + M-->>U: refund with error code +``` + - [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) + - [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) + - [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) ## Additional Resources From 4842f7693511540dc929cb24e30589e90e680c5f Mon Sep 17 00:00:00 2001 From: master_jedy Date: Fri, 7 Nov 2025 13:51:18 +0100 Subject: [PATCH 8/8] fix pre-commit Signed-off-by: master_jedy --- .../pull-integration/ton.mdx | 39 +++++++++++++------ 1 file changed, 27 insertions(+), 12 deletions(-) diff --git a/pages/price-feeds/core/use-real-time-data/pull-integration/ton.mdx b/pages/price-feeds/core/use-real-time-data/pull-integration/ton.mdx index 500e0356..d179e017 100644 --- a/pages/price-feeds/core/use-real-time-data/pull-integration/ton.mdx +++ b/pages/price-feeds/core/use-real-time-data/pull-integration/ton.mdx @@ -126,23 +126,26 @@ This code snippet does the following: 4. Prepares the update data and calculates the update fee. 5. Updates the price feeds on the TON contract. - ## Patterns for Providing Pyth Data to Your Contract There are typically two main scenarios: either you call a method supplying TON, or you transfer jettons. - **TON proxy**: `User → Pyth → EVAA Master → ... (further processing)` -Use this method if you only need to send TON to your contract or simply call a contract method, without involving jettons. + Use this method if you only need to send TON to your contract or simply call a contract method, without involving jettons. - **Jetton on-chain getter**: `User → Jetton Wallet → EVAA Master → Pyth → EVAA Master → ... (further processing)` -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. -This approach is useful when you want to transfer jettons to your contract while also providing price data. - -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. - + 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. + This approach is useful when you want to transfer jettons to your contract while also providing price data. + + 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. + They both are demonstrated in the [Pyth Connector example](https://github.com/pyth-network/pyth-examples/tree/main/price_feeds/ton/pyth-connector).
-These same patterns are also used in the [EVAA Protocol code](https://github.com/evaafi/contracts/tree/v8) for implementing following operations: +These same patterns are also used in the [EVAA Protocol code](https://github.com/evaafi/contracts/tree/v8) for implementing following operations: + - Pyth proxy pattern: liquidate TON / supply_withdraw TON. - Onchain-getter pattern: liquidate jetton / supply_withdraw jetton. @@ -151,7 +154,9 @@ Choose the pattern that best fits your use case and how you want to handle asset 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. ### Pyth proxy: Success + #### EVAA flow + In the EVAA protocol, the operations that implement the Pyth proxy pattern are `liquidate (TON)` and `supply_withdraw (TON)`. 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. ```mermaid @@ -174,8 +179,8 @@ sequenceDiagram - [process the supply_withdraw operation (TON): master.fc](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L192-L211) - [process the liquidate operation (TON): master.fc](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L171-L190) - #### Pyth Connector flow + The Pyth Connector example also has a similar flow. It has two main operations: proxy and onchain-getter. They have no practical purpose other than to demonstrate the patterns described above. The data flow is practically the same as the EVAA protocol, only operation codes are different. @@ -201,6 +206,7 @@ sequenceDiagram - [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) ### Pyth proxy: Error handling + 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. ```mermaid @@ -214,7 +220,9 @@ sequenceDiagram ``` ### Pyth onchain-getter: Success + #### EVAA flow + ```mermaid sequenceDiagram autonumber @@ -241,6 +249,7 @@ sequenceDiagram - [handle pyth response: liquidate_jetton and supply_withdraw_jetton](https://github.com/evaafi/contracts/blob/d9138cb24f03b53522774351aceb38c51a047eee/contracts/master.fc#L131-L167) #### Pyth Connector flow + Pyth Connector's onchain-getter operation has a simplified flow compared to the EVAA protocol. ```mermaid @@ -260,6 +269,7 @@ sequenceDiagram note over P: Pyth Contract validates update data and
sends prices with payload to Pyth Connector contract note over M: Pyth Connector validates sender
parses payload and
processes the transaction ``` + - Related code (GitHub): - [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) - [onchain_getter_operation request: pyth-connector.fc](https://github.com/pyth-network/pyth-examples/blob/main/price_feeds/ton/pyth-connector/contracts/PythConnector/pyth_connector.fc#L126) @@ -268,9 +278,11 @@ sequenceDiagram - [onchain_getter_operation process: pyth-connector.fc](https://github.com/pyth-network/pyth-examples/blob/main/price_feeds/ton/pyth-connector/contracts/PythConnector/pyth_connector.fc#L90) ### Pyth onchain-getter: Pyth error + 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. #### EVAA flow + 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. ```mermaid @@ -294,7 +306,9 @@ sequenceDiagram - [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) #### Pyth Connector + The Pyth Connector error handling flow looks the same as the EVAA protocol. + ```mermaid sequenceDiagram autonumber @@ -309,9 +323,10 @@ sequenceDiagram P-->>M: response_error (op 0x10002) M-->>U: refund with error code ``` - - [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) - - [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) - - [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) + +- [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) +- [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) +- [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) ## Additional Resources