clarify evaa flow, add pyth connector flow

masterjedy · masterjedy · commit 71fdd5cb5a53 · 2025-11-06T16:00:41.000+01:00
Signed-off-by: master_jedy &lt;yura.zarudny@gmail.com&gt;
diff --git 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 <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.
 
 ```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)<br/>payload (op 0x3 liquidate_master | 0x4 supply_withdraw_master)
+  note right of U: send request to Pyth Contract with update data and operation payload<br/>destination address is EVAA Master contract
+  P-->>M: op 0x5 parse_price_feed_updates (price feeds + prices)<br/>payload (op 0x3 liquidate_master | 0x4 supply_withdraw_master)
+  note right of P: Pyth Contract validates update data and <br/> sends prices with payload to EVAA Master contract
+  note over M: EVAA Master validates sender <br/> parses payload and <br/> 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)<br/>payload (op 0x4 connector_proxy_operation)
+  note right of U: send request to the Pyth Contract with update data and operation payload<br/>destination address is the Pyth Connector contract
+  P-->>M: op 0x5 parse_price_feed_updates (price feeds + prices)<br/>payload (op 0x4 connector_proxy_operation)
+  note right of P: Pyth Contract validates update data and <br/> sends prices with payload to Pyth Connector contract
+  note over M: Pyth Connector validates sender <br/> parses payload and <br/> 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<br/>+ update_data + target_feeds<br/>+ op_payload(liquidate_master_jetton_process / supply_withdraw_master_jetton)
-  P-->>M: op 5 parse_price_feed_updates<br/>(prices, pyth_sender = M)
-  note over M: Master accepts and processes the transaction
+  U->>JW: op transfer_jetton, forward_payload<br/>(liquidate_master_jetton | supply_withdraw_master_jetton)
+  note right of U: transfer jetton with forward payload:
+  JW->>M: op transfer_notification, forward_payload<br/>(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<br/>+ payload(liquidate_master_jetton_process | supply_withdraw_master_jetton_process)
+  P-->>M: op 0x5 parse_price_feed_updates(price feeds + prices)<br/>+ payload(liquidate_master_jetton_process | supply_withdraw_master_jetton_process)
+  note over P: Pyth Contract validates update data and <br/> sends prices with payload to EVAA Master contract
+  note over M: EVAA Master validates sender <br/> parses payload and <br/> 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<br/>+ payload(onchain_getter_operation)
+  P-->>M: op 0x5 parse_price_feed_updates(price feeds + prices)<br/>+ payload(onchain_getter_operation)
+  note over P: Pyth Contract validates update data and <br/> sends prices with payload to Pyth Connector contract
+  note over M: Pyth Connector validates sender <br/> parses payload and <br/> 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
 
