test(bridge): verify Pi Network 7-decimal convention against Horizon API - #62
Conversation
Fixes Pi-Defi-world#21 - Cited source for Pi Network 7-decimal precision (Stellar Horizon fixed-point format) in wpi-token lib.rs and relayer amount.ts - Added integration test suite in amount.test.ts verifying conversion of realistic Pi Horizon deposit amounts to stroops and 1:1 wPi mint amounts - Added contract unit test in test.rs verifying DECIMALS equals 7 and matches on-chain decimals() accessor
📝 WalkthroughWalkthroughThe change documents Pi Network’s seven-decimal precision, verifies the token contract’s decimal configuration, derives relayer conversion constants from that precision, and adds representative conversion, round-trip, and deposit peg tests. ChangesPi precision consistency
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@relayer/test/amount.test.ts`:
- Around line 81-91: Update the wPi mint amount test around the current
depositStroops and mintedStroops assertions to exercise the actual mint flow or
mock the contract invocation. Assert that the mint_from_deposit payload uses
depositStroops unchanged and that the resulting minted balance equals
depositStroops, removing the direct assignment that makes the test tautological.
In `@Stellar-contracts-v1/wpi-token/src/lib.rs`:
- Around line 21-24: Update the amount-precision documentation at
Stellar-contracts-v1/wpi-token/src/lib.rs lines 21-24,
relayer/src/util/amount.ts lines 6-8, and relayer/test/amount.test.ts lines
59-61 to cite authoritative Pi schema, fixture, or documentation evidence for
7-decimal amounts; if no such evidence exists, explicitly label the examples and
DECIMALS = 7 behavior as project assumptions rather than Pi Horizon API
guarantees.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 9af91811-d72d-416a-8db0-9c6a91cfe0d4
📒 Files selected for processing (4)
Stellar-contracts-v1/wpi-token/src/lib.rsStellar-contracts-v1/wpi-token/src/test.rsrelayer/src/util/amount.tsrelayer/test/amount.test.ts
| it('wPi mint amount equals raw Pi deposit stroops (1:1 peg)', () => { | ||
| // The relayer reads amountStroops from the Pi Horizon payment and passes | ||
| // it directly to the contract's mint_from_deposit. A correct DECIMALS | ||
| // value means no scaling is needed; a wrong value would silently scale | ||
| // by 10^(wrong - correct). | ||
| const piDeposit = '50.0000000'; | ||
| const depositStroops = decimalToStroops(piDeposit); | ||
| expect(depositStroops).toBe(500_000_000n); | ||
|
|
||
| const mintedStroops = depositStroops; // 1:1 peg | ||
| expect(stroopsToDecimal(mintedStroops)).toBe(piDeposit); |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Exercise the actual mint path instead of copying the input.
const mintedStroops = depositStroops makes this test tautological. It cannot detect a relayer scaling bug or an incorrect contract payload. Invoke the real mint flow, or mock the contract call and assert that the payload and resulting balance equal depositStroops.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@relayer/test/amount.test.ts` around lines 81 - 91, Update the wPi mint amount
test around the current depositStroops and mintedStroops assertions to exercise
the actual mint flow or mock the contract invocation. Assert that the
mint_from_deposit payload uses depositStroops unchanged and that the resulting
minted balance equals depositStroops, removing the direct assignment that makes
the test tautological.
| /// Source: Pi Network Horizon API — the `amount` field in `/operations` and | ||
| /// `/payments` responses uses a fixed 7-decimal string representation | ||
| /// (e.g. "3.1415926"), consistent with Stellar's documented stroops model | ||
| /// (https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/assets#amount-precision). |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== files =="
git ls-files | rg 'Stellar-contracts-v1/wpi-token/src/lib\.rs|relayer/src/util/amount\.ts|relayer/test/amount\.test\.ts|README|docs|pi|amount' || true
echo "== target snippets =="
for f in Stellar-contracts-v1/wpi-token/src/lib.rs relayer/src/util/amount.ts relayer/test/amount.test.ts; do
if [ -f "$f" ]; then
echo "--- $f ---"
sed -n '1,80p' "$f"
fi
done
echo "== amount-related references =="
rg -n "decimal|stroops|Pi Network Horizon|/payments|/operations|amount" -S .Repository: Pi-Defi-world/Wpi
Length of output: 38776
🌐 Web query:
Pi Network Horizon API operations amounts fixed 7 decimal format documentation
💡 Result:
The Pi Network, which utilizes a blockchain architecture based on the Stellar protocol, employs a fixed decimal system for its token operations to ensure precision and support for micropayments [1][2][3]. Key technical aspects include: 1. Fixed 7 Decimal Precision: Pi Network utilizes a 7-decimal place system for its tokens [4][1][2]. This means that 1 Pi is equivalent to 10,000,000 smallest base units (i.e., 10^7 units) [4][1][3]. 2. API Amount Representation: In interactions with the Horizon API—the interface used for submitting transactions and querying ledger data—amounts are typically represented as strings in JSON objects to maintain this precision [5][6]. Applications are expected to adhere to this 7-decimal format when specifying values in transactions or processing payment data [4][7]. 3. Technical Implementation: Because the underlying system treats these values as integers (the smallest units) to prevent floating-point errors, clients must perform the necessary conversion [5][1]. For example, when submitting a payment, an amount like 1.5 Pi must be represented as a string with the correct precision ("1.5000000") or calculated against the base unit [4][7]. 4. Documentation Context: While the Pi Network documentation emphasizes this 7-decimal convention for its ecosystem [4], it relies on the standard Stellar Horizon API infrastructure [8][9]. Developers are encouraged to use official Stellar or Pi SDKs, which handle the formatting and serialization of these amounts automatically, rather than constructing raw API calls manually [8][7]. For developers implementing integrations, ensuring that input amounts are rounded or validated to a maximum of 7 decimal places is critical to avoiding "Invalid payment amount" errors [7].
Citations:
- 1: https://www.mexc.com/news/1100377
- 2: https://www.mexc.co/news/1036307
- 3: https://www.mexc.co/news/1132616
- 4: https://github.com/PiNetwork/PiRC/blob/main/PiRC2/9-subscription-setup-guide.md
- 5: Proposal: Standardize "amount" representation in client libraries and api stellar/stellar-protocol#20
- 6: https://developers.stellar.org/docs/data/apis/horizon/api-reference/resources/operations/object/buy-offer
- 7: https://github.com/onenoly1010/quantum-pi-forge-fixed/blob/main/docs/PI_NETWORK_INTEGRATION.md
- 8: https://developers.stellar.org/docs/data/apis/horizon
- 9: https://x.com/jojo102102/status/2080140338413662604
🌐 Web query:
Pi Network Horizon API native token amount string representation 7 decimal places
💡 Result:
The Pi Network Horizon API, which is based on the Stellar Horizon API, represents native token amounts as a string containing a decimal number, typically with 7 decimal places [1][2][3]. Internally, assets on the network are stored as 64-bit integers (int64) [4]. These integer values are scaled by a factor of 10,000,000 (ten million) to represent human-friendly units [4]. For example, the smallest unit of an asset, known as a stroop, is represented by the integer 1, which corresponds to 0.0000001 in the decimal string representation [4]. When interacting with the Horizon API, it is standard practice to use this decimal string format to ensure precision is maintained [2][4][3]. Developers should avoid using floating-point numbers in their applications to represent these amounts, as this can lead to precision loss; using "big number" libraries or handling amounts as strings is recommended [4]. The string representation in API responses is consistent with this fixed-precision scaling, allowing for up to 7 decimal places [3].
Citations:
- 1: https://developers.stellar.org/docs/data/apis/horizon/api-reference/structure/response-format
- 2: Proposal: Standardize "amount" representation in client libraries and api stellar/stellar-protocol#20
- 3: https://docs.rs/crate/substrate-stellar-sdk/latest
- 4: https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/assets
🌐 Web query:
Pi Network Open Consensus RPC /payments response amount field
💡 Result:
In the Pi Network platform API, the amount field in the PaymentDTO object (returned by the /payments endpoints) is defined as a number [1][2]. It is important to distinguish between the Pi Platform API and the Pi Blockchain RPC server: 1. Pi Platform API: This is the server-side API used by applications to manage the lifecycle of payments (e.g., U2A payments). The /payments/{payment_id} endpoint returns a PaymentDTO object, where the amount field is specified as a number [1][2]. This API is separate from the low-level blockchain RPC. 2. Pi Blockchain RPC Server: This is the recently released infrastructure (as of April 2026) that allows direct interaction with the Pi blockchain [3][4]. While this RPC server supports standard JSON-RPC calls for querying blockchain data, the PaymentDTO structure used in the application-level Platform API remains distinct from the raw transaction data queried via blockchain RPC nodes [5][4]. If you are working with the Pi Platform API, you should expect the amount field to be a numeric value representing the payment amount [1][2]. If you are working with raw blockchain transactions via the RPC server, you would typically parse transaction data according to standard blockchain RPC patterns rather than the PaymentDTO structure [5][6].
Citations:
- 1: https://pi-apps.github.io/pi-sdk-docs/platform/PlatformAPI
- 2: https://github.com/pi-apps/pi-platform-docs/blob/master/platform_API.md
- 3: https://www.gate.com/news/detail/pi-network-testnet-rpc-server-is-ready-and-the-smart-contract-ecosystem-19952878
- 4: https://minepi.com/blog/rpc-server/
- 5: https://pibazar.eu/technical-evolution-of-pi-network-rpc-server-and-smart-contracts/
- 6: https://coinsprobe.com/pi-network-launches-public-rpc-server-on-testnet-smart-contracts-are-now-one-step-closer/
🌐 Web query:
site:pi-network.github.io "amountStroops" OR "amount:" Pi Network
💡 Result:
I couldn’t find a direct match on pi-network.github.io for amountStroops or amount:.
Related Pi docs do show an amount field in payment flows, and Pi transaction amounts are commonly represented in stroops (1 π = 10^7 stroops). (pi-apps.github.io)
If you want, I can broaden the search to GitHub repos or Pi SDK docs.
Citations:
🌐 Web query:
Pi Network SDK documentation /payments amount stroops
💡 Result:
In the Pi Network SDK, payments do not use "stroops" as the unit for the amount field [1][2][3]. The Pi SDK documentation specifies that the amount field in the paymentData object represents the amount of Pi to be paid as a number in whole units of Pi (e.g., 3.14) [1][2][3]. The term "stroops" is a unit specific to the Stellar blockchain, where one XLM is equal to 10,000,000 stroops [4]. While Pi Network's underlying blockchain technology shares architectural roots with Stellar, the Pi SDK abstracts these complexities, allowing developers to work directly with human-readable, decimal Pi values [5][2]. Developers should provide the amount as a standard number in their createPayment calls [1][3].
Citations:
- 1: https://pi-apps.github.io/pi-sdk-docs/platform/SdkReference
- 2: https://github.com/pi-apps/pi-platform-docs
- 3: https://pi-apps.github.io/community-developer-guide/docs/gettingStarted/quickStart/
- 4: https://stellar.github.io/js-stellar-sdk/guides/02-send-a-payment/
- 5: https://github.com/pi-apps/pi-platform-docs/blob/master/payments.md
🌐 Web query:
Pi Network blockchain RPC get_transaction response transaction hash amount
💡 Result:
As of July 2026, Pi Network provides a public Remote Procedure Call (RPC) server on the Pi Testnet to facilitate developer interaction with the blockchain, including querying transaction data [1][2]. The Pi RPC interface utilizes the JSON-RPC 2.0 standard [3]. While developers can access the network via the public Testnet endpoint at https://rpc.testnet.minepi.com [1][2], specific method details for retrieving transactions (often referenced in developer documentation as getTransactions or similar) are intended to allow auditing of transaction history and verification of payments [3]. In a standard JSON-RPC transaction query, the request typically requires the transaction hash as an input parameter, and the response provides a structured JSON object containing the transaction details, including the sender, receiver, amount, and fee [3][4][5]. Important considerations for using Pi Network RPC: - Access: The RPC server is currently available on the Testnet [1]. Access to Mainnet RPC is generally restricted to authorized SDKs and partners to maintain security during the network's development phases [6]. - Tools: Developers interact with the RPC server using standard tools like curl or various programming libraries (JavaScript, Python, Rust) by sending JSON-RPC 2.0 formatted requests [3]. - Information Availability: For end-users, the Pi Block Explorer remains the primary tool for verifying transaction status, hash, and amount without needing to interface directly with the RPC API [4][5]. For the most accurate and up-to-date schema for specific RPC method responses, developers should consult the official Pi developer resources and documentation available through the Pi Developer Portal [6].
Citations:
- 1: https://minepi.com/blog/rpc-server/
- 2: https://coinsprobe.com/pi-network-launches-public-rpc-server-on-testnet-smart-contracts-are-now-one-step-closer/
- 3: https://pibazar.eu/technical-evolution-of-pi-network-rpc-server-and-smart-contracts/
- 4: https://pinetwork.atlassian.net/wiki/spaces/WIKI/pages/933822465/Pi+Block+Explorer
- 5: https://www.bitget.com/wiki/pi-network-block-explorer
- 6: https://www.bitget.com/wiki/pi-network-rpc-url
Add authoritative Pi evidence for the DECIMALS = 7 contract.
The Stellar precision link does not establish the Pi Horizon payment schema, and the relayer already relies on this contract for mint_from_deposit. Update the cited sites to reference a Pi schema/fixture/document for 7-decimal amounts, or explicitly mark the samples as project assumptions rather than authoritative API behavior.
Stellar-contracts-v1/wpi-token/src/lib.rs#L21-L24relayer/src/util/amount.ts#L6-L8relayer/test/amount.test.ts#L59-L61
📍 Affects 3 files
Stellar-contracts-v1/wpi-token/src/lib.rs#L21-L24(this comment)relayer/src/util/amount.ts#L6-L8relayer/test/amount.test.ts#L59-L61
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@Stellar-contracts-v1/wpi-token/src/lib.rs` around lines 21 - 24, Update the
amount-precision documentation at Stellar-contracts-v1/wpi-token/src/lib.rs
lines 21-24, relayer/src/util/amount.ts lines 6-8, and
relayer/test/amount.test.ts lines 59-61 to cite authoritative Pi schema,
fixture, or documentation evidence for 7-decimal amounts; if no such evidence
exists, explicitly label the examples and DECIMALS = 7 behavior as project
assumptions rather than Pi Horizon API guarantees.
2 participants
Closes #21
Summary by CodeRabbit
Bug Fixes
Tests
Documentation