debug proxy op, add proxy op test, update readme

Signed-off-by: master_jedy <[email protected]>

Author: masterjedy

price_feeds/ton/pyth-connector/README.md

@@ -1,35 +1,74 @@
 # Pyth-connector example
-Provides onchain-getter: **User -> User JettonWallet -> App -> Pyth -> App -> ...** and proxy call: **User -> Pyth -> App -> ...** pyth usage examples. 
+This example provides two main usage patterns for interacting with Pyth:
 
-This example can be used as a standalone module that provides tools for sandbox testing by exporting functions for deploying and configuring a local Pyth contract.
+- **On-chain getter:**  
+  `User → User JW → App JW → App → Pyth → App → ...`
 
-It demonstrates techniques for using the Pyth oracle in financial applications.
+- **Proxy call:**  
+  `User → Pyth → App → ...`
 
-The demonstration is fully sandboxed and does not require real on-chain contracts on either testnet or mainnet.
-Using the Hermes client is also not required — prices can be generated locally, for example: **{TON: 3.12345, USDC: 0.998, USDT: 0.999}**.
+You can use this example as a standalone module for sandbox testing. It exports functions to deploy and configure a local Pyth contract, making it easy to experiment without connecting to real on-chain contracts on testnet or mainnet.
 
-This is achieved by using a patched Pyth contract that accepts simplified prices without a Merkle trie proof, and therefore does not verify the authenticity of the prices.
-Important: This patched contract is intended for testing purposes only. The production version must use the authentic Pyth contract deployed on the mainnet.
+This example uses a patched Pyth contract intended only for testing purposes in a local development environment. It accepts simplified prices without requiring a Merkle trie proof, so price authenticity is not verified.
 
-## Project structure
+<div style="border-radius: 8px; border: 1px solid #ffd700; background: #fffbe6; padding: 16px; margin: 16px 0;">
+  <strong>Important:</strong> This patched contract is for <strong>testing purposes only</strong>. For production, always use the official Pyth contract deployed on mainnet.
+</div>
+
+The demonstration is fully sandboxed. You do not need the Hermes client, prices can be generated locally, for example:  **`{ TON: 3.456, USDC: 0.998, USDT: 0.999 }`**
+
+## Project Structure
+
+- `contracts/` — Source code of the smart contracts and their dependencies.
+- `wrappers/` — TypeScript contract wrappers (implementing `Contract` from ton-core), including serialization/deserialization and compilation utilities.
+- `tests/` — Unit and integration tests for the contracts.
+- `scripts/` — Deployment and utility scripts.
 
-- `contracts` - source code of all the smart contracts of the project and their dependencies.
-- `wrappers` - wrapper classes (implementing `Contract` from ton-core) for the contracts, including any [de]serialization primitives and compilation functions.
-- `tests` - tests for the contracts.
-- `scripts` - scripts used by the project, mainly the deployment scripts.
 
 ## How to use
-First you need to install dependencies, node v22 is required, you can use nvm to install it: `nvm use 22` .
-Then install dependencies, just run `yarn`
+
+1. **Install Node.js version 22**  
+   It is recommended to use [nvm](https://github.com/nvm-sh/nvm) for managing Node.js versions.  
+   If you don't have nvm installed, run:
+   ```bash
+   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+   source ~/.bashrc
+   ```
+   Then install and use Node.js 22:
+   ```bash
+   nvm install 22
+   nvm use 22
+   ```
+
+2. **Install Yarn** (if not already installed):
+   ```bash
+   npm install -g yarn
+   ```
+
+3. **Install project dependencies**  
+   In the project root directory, run:
+   ```bash
+   yarn install
+   ```
+
+After these steps, you are ready to build, test, and use the example. See the sections below for more commands.
 
 ### Build
-to build the module you can run `yarn build`
+to build the module you can run:
+   ```bash 
+   yarn build
+   ```
 
 ### Contracts
-To prebuild contracts run`yarn contracts`
+To prebuild contracts run:
+   ```bash 
+   yarn contracts
+   ```
 
 ### Test
-`yarn test:unit`
+   ```bash
+    yarn test:unit
+   ```
 
 ### Deploy
 You don't need to deploy this example's contracts to testnet/mainnet,

price_feeds/ton/pyth-connector/contracts/PythConnector/constants/constants.fc

@@ -22,6 +22,8 @@ const int RESERVE::REGULAR = 0;
 const int RESERVE::AT_MOST = 2;
 ;;; in the case of action fail - bounce transaction. No effect if RESERVE_AT_MOST (+2) is used. TVM UPGRADE 2023-07.
 const int RESERVE::BOUNCE_ON_ACTION_FAIL = 16;
+;;; Creates an output action which would reserve all the remaining balance of the current smart contract (instead of the value originally indicated in the message).
+const int RESERVE::APPEND_BALANCE = 4;
 
 
 const int FEE::SUPPLY_MARGIN = 100000000; ;; 0.1 TON margin

price_feeds/ton/pyth-connector/contracts/PythConnector/operations/proxy_operation.fc

@@ -14,12 +14,15 @@
     return (transferred_amount);
 }
 
-;; todo: test, debug
 () proxy_operation_process(int my_balance, int msg_value, slice initial_sender, cell prices_dict, int query_id, cell operation_payload) impure {
     var (transferred_amount) = parse_proxy_operation_payload(operation_payload);
-    throw_unless(ERROR::NOT_ENOUGH_TRANSFERRED, msg_value < transferred_amount + FEE::SUPPLY_MARGIN);
 
-    raw_reserve(my_balance + transferred_amount, RESERVE::REGULAR);
+    ;; check that the msg value is enough to cover the transferred amount and supply margin, 
+    ;; which is supposed to be pyth connector fee
+    throw_unless(ERROR::NOT_ENOUGH_TRANSFERRED, msg_value >= transferred_amount + FEE::SUPPLY_MARGIN);
+    
+    ;; reserve the transferred amount
+    raw_reserve(transferred_amount, RESERVE::APPEND_BALANCE);
 
     emit_log(LOG::PROXY_OPERATION_PROCESSING,
         begin_cell()
@@ -32,6 +35,6 @@
     send_message(
         initial_sender, 0,
         begin_cell().store_query_id(query_id).store_ref(makeTextBody("Thank you!")).end_cell(),
-        SENDMODE::CARRY_ALL_BALANCE
+        SENDMODE::CARRY_ALL_BALANCE ;; only balance remaining after reserve is sent to the initial sender
     );
 }

price_feeds/ton/pyth-connector/contracts/PythConnector/pyth_connector.fc

@@ -100,7 +100,6 @@
         }
 
         throw(ERROR::UNSUPPORTED_OPERATION);
-
     }
 
     int query_id = in_msg_body~load_query_id();

price_feeds/ton/pyth-connector/tests/PythConnector.spec.ts

@@ -1,5 +1,5 @@
 import { Blockchain, EventAccountCreated, SandboxContract, TreasuryContract } from '@ton/sandbox';
-import { Address, beginCell, Cell, Dictionary, toNano } from '@ton/core';
+import { Address, beginCell, Cell, Dictionary, SendMode, toNano } from '@ton/core';
 import { PythConnector } from '../wrappers/PythConnector';
 import '@ton/test-utils';
 
@@ -16,7 +16,7 @@ import {
     TEST_FEED_NAMES, TEST_FEEDS, TEST_FEEDS_MAP
 } from "./utils/assets";
 import { packNamedPrices } from "./utils/prices";
-import { makeOnchainGetterPayload, makeTransferMessage } from "./utils/messages";
+import { makeOnchainGetterPayload, makePythProxyMessage, makePythProxyPayloadMessage, makeTransferMessage, parsePythProxyLogBody } from "./utils/messages";
 import { EventMessageSent } from "@ton/sandbox/dist/event/Event";
 
 dotenv.config();
@@ -27,10 +27,6 @@ const HERMES_ENDPOINT = 'https://hermes.pyth.network';
 export type OraclesInfo = {
     pythAddress: Address;
     feedsMap: Dictionary<bigint, Buffer>,
-    // pricesTtl: number,
-    // pythComputeBaseGas: bigint,
-    // pythComputePerUpdateGas: bigint,
-    // pythSingleUpdateFee: bigint,
 };
 
 describe('Generated Prices', () => {
@@ -137,10 +133,6 @@ describe('PythConnector', () => {
         oraclesInfo = {
             feedsMap: TEST_FEEDS_MAP,
             pythAddress: pyth.address,
-            // pricesTtl: 180,
-            // pythComputeBaseGas: 100n,
-            // pythComputePerUpdateGas: 200n,
-            // pythSingleUpdateFee: 300n,
         } as OraclesInfo;
 
         pythConnector = await deployPythConnector(blockchain, deployer, pyth.address);
@@ -254,7 +246,107 @@ describe('PythConnector', () => {
         });
     })
 
-    it.skip('should succeed pyth proxy operation', async () => {
+    it('should succeed pyth proxy operation', async () => {
+        await pythConnector.sendConfigure(deployer.getSender(),{
+            value: toNano('0.05'), 
+            pythAddress: pyth.address, 
+            feedsMap: TEST_FEEDS_MAP
+        });
+
+        // technically, prices are not important for current implementation of pyth proxy operation
+        // but we pass them to pyth contract for demonstration purposes
+        const updateDataCell = packNamedPrices({TON: 3.1, USDT: 0.99, USDC: 1.01}, () => blockchain.now!);
+        const pythPriceIds = composeFeedsCell(defaultFeeds);
+
+        const queryId = 0x123456n;
+
+        const pythFee = toNano('0.0234');
+        const transferredAmount = toNano('0.5');
+        const supplyMargin = toNano('0.1');
+
+        // need to cover pyth fee, transferred amount and supply margin
+        const sentValue = pythFee + transferredAmount + supplyMargin;
+
+        const proxyPayload = makePythProxyPayloadMessage({
+            queryId,
+            transferredAmount,
+        });
+
+        const minPublishTime = blockchain.now! - 10;
+        const maxPublishTime = blockchain.now! + 180;
+
+        const msgToPyth = makePythProxyMessage({
+            updateDataCell,
+            pythPriceIds,
+            minPublishTime,
+            maxPublishTime,
+            targetAddress: pythConnector.address,
+            queryId,
+            proxyPayload,
+            transferredAmount,
+        });
+        console.log({
+            'Alice wallet': aliceWallet.address, 
+            'Pyth contract': pyth.address, 
+            'Pyth connector': pythConnector.address
+        });
+
+        const balanceBefore = (await blockchain.getContract(pythConnector.address)).balance;
+
+        const result = await aliceWallet.send({
+            value: sentValue,
+            to: pyth.address,
+            sendMode: SendMode.PAY_GAS_SEPARATELY + SendMode.IGNORE_ERRORS,
+            body: msgToPyth,
+        });
+
+        const balanceAfter = (await blockchain.getContract(pythConnector.address)).balance;
+
+        // alice sent message to pyth
+        expect(result.transactions).toHaveTransaction({
+            from: aliceWallet.address,
+            to: pyth.address,
+            success: true,
+        });
+
+        // pyth validated feeds and sent prices to pyth connector
+        expect(result.transactions).toHaveTransaction({
+            from: pyth.address,
+            to: pythConnector.address,
+            success: true,
+        });
+
+        // Check that the pyth-connector balance increased by the transferred amount (within a small tolerance)
+        const expectedBalance = balanceBefore + transferredAmount;
+        const delta = Math.abs(Number(balanceAfter - expectedBalance));
+        console.log({
+            balanceBefore, 
+            balanceAfter,
+            expectedBalance,
+            delta
+        });
+
+        expect(delta).toBeLessThanOrEqual(Number(toNano('0.00001')));
+
+        // remaining balance sent back to alice
+        expect(result.transactions).toHaveTransaction({
+            from: pythConnector.address,
+            to: aliceWallet.address,
+            success: true,
+        });
+
+        console.log('externals: ', result.externals);
+
+        // expect connector emitted proxy-operation log into externals
+        const LOG_PROXY_OPERATION_PROCESSING = 128 + 12;
+        const hasProxyLog = result.externals.some((m: any) => {
+            const src = (m.info as any).src?.toString?.();
+            if (src !== pythConnector.address.toString()) return false;
+            const logInfo = parsePythProxyLogBody(m.body);
+            console.log('logInfo: ', logInfo);
+            return logInfo.op === LOG_PROXY_OPERATION_PROCESSING;
+        });
 
+        expect(hasProxyLog).toBe(true);
     })
 });

price_feeds/ton/pyth-connector/tests/utils/messages.ts

@@ -1,4 +1,4 @@
-import { Address, beginCell, Cell } from "@ton/core";
+import { Address, beginCell, Cell, Dictionary } from "@ton/core";
 import { JETTON_OPCODES, OPCODES } from "./opcodes";
 
 export function makeOnchainGetterPayload(args: {
@@ -16,7 +16,7 @@ export function makeOnchainGetterPayload(args: {
         .storeUint(args.maxStaleness, 64)
         .storeRef(args.updateDataCell)
         .storeRef(args.pythPriceIds)
-        .storeRef(beginCell().endCell())
+        .storeRef(args.operationBody)
         .endCell();
 }
 
@@ -40,4 +40,58 @@ export function makeTransferMessage(args: {
         .storeBit(1)
         .storeRef(args.notificationBody)
         .endCell();
-}
+}
+
+export function makePythProxyPayloadMessage(args: {
+    queryId: number | bigint,
+    transferredAmount: number | bigint,
+}) {
+    return beginCell()
+        .storeUint(OPCODES.PROXY_OPERATION, 32)
+        .storeUint(args.queryId, 64)
+        .storeRef(
+            beginCell()
+                .storeUint(args.transferredAmount, 64)
+                .endCell()
+        )
+        .endCell();
+}
+
+export function parsePythProxyLogBody(cell: Cell): {    
+    queryId: number,
+    op: number,
+    dictCell: Cell,
+} {
+    const s = cell.beginParse();
+    const op = s.loadUint(8);  
+    expect(s.remainingRefs).toBeGreaterThan(0); 
+    const s2 = s.loadRef().beginParse();
+    const queryId = Number(s2.loadUintBig(64));
+    const dictCell = s2.loadRef();
+
+    return { queryId, op, dictCell };
+}
+
+export const PYTH_UPDATE_FEEDS_OP_CODE = 5;
+
+export function makePythProxyMessage(args: {
+    updateDataCell: Cell,
+    pythPriceIds: Cell,
+    minPublishTime: number,
+    maxPublishTime: number,
+    targetAddress: Address,
+    queryId: number | bigint,
+    proxyPayload: Cell,
+    transferredAmount: number | bigint,
+}) {
+    return beginCell()
+        .storeUint(PYTH_UPDATE_FEEDS_OP_CODE, 32)
+        .storeRef(args.updateDataCell)
+        .storeRef(args.pythPriceIds)
+        .storeUint(args.minPublishTime, 64)
+        .storeUint(args.maxPublishTime, 64)
+        .storeAddress(args.targetAddress)
+        .storeRef(args.proxyPayload)
+        .endCell();
+}
+