docs(FLOW-16): Document precision loss in cross-VM amount conversions

[liobrasil]

Summary

Fixes #31

Documents the precision loss that occurs when converting between EVM's uint256 (18 decimals) and Cadence's UFix64 (8 decimals).

Key points:

• Precision beyond 8 decimal places is truncated
• Example: 1.123456789012345678 FLOW → 1.12345678 FLOW
• Not exploitable (truncation favors protocol, users receive slightly less)
• Minimum deposit requirement mitigates dust loss (~0.0000001% max)

Changes:

• Added precision note to Cadence contract header
• Added precision warning to ufix64FromUInt256() docstring
• Added precision note to Solidity contract header

Test plan

• All 70 Solidity tests pass
• All 4 Cadence test suites pass

🤖 Generated with Claude Code

[claude]

Code Review Summary

This PR effectively documents an important precision loss limitation in cross-VM amount conversions. The documentation is clear, accurate, and addresses issue #31.

---

✅ Strengths

1. Clear Documentation

The precision loss is documented in three strategic locations:

• Cadence contract header (FlowYieldVaultsEVM.cdc:28-33): High-level overview
• Conversion function (ufix64FromUInt256:1879-1880): Implementation-level warning
• Solidity contract header (FlowYieldVaultsRequests.sol:34-37): EVM-side awareness

2. Accurate Technical Details

• Correctly identifies 18 decimal (uint256) → 8 decimal (UFix64) truncation
• Provides concrete example: 1.123456789012345678 FLOW → 1.12345678 FLOW
• Accurately states this is not exploitable (favors protocol, not users)

3. Security Analysis

The documentation correctly notes:

• Truncation causes users to receive slightly less, not more (no exploit vector)
• 1 FLOW minimum deposit makes dust loss negligible (~0.0000001% max)
• Aligns with defensive security best practices

---

📝 Minor Suggestions

1. Math Precision in Example

In FlowYieldVaultsRequests.sol:36:

Example: 1.123456789012345678 FLOW → 1.12345678 FLOW (loss of ~9e-9 FLOW).

The stated loss ~9e-9 FLOW is slightly misleading. The actual loss is:

• Lost portion: 0.000000009012345678 FLOW ≈ 9.01e-9 FLOW
• As percentage: ~0.0000008% of the amount

Suggestion: Consider being more precise:

Example: 1.123456789012345678 FLOW → 1.12345678 FLOW (loss of 9.01...e-9 FLOW, ~0.0000008%).

2. Consistency Between Comments

The Cadence contract (line 33) states:

the 1 FLOW minimum deposit makes any dust loss negligible (~0.0000001% maximum).

This percentage seems to be calculated as (1e-8 FLOW / 1 FLOW minimum) * 100% = 0.000001%, not 0.0000001%.

Suggestion: Verify and align the percentage calculations:

• For 1 FLOW deposit: 1e-8 / 1 = 0.000001% (1e-6%)
• Or clarify if this refers to a different scenario

3. Return Value Documentation Enhancement

In FlowYieldVaultsEVM.cdc:1883, the return documentation states:

@return The converted amount in UFix64 format (truncated to 8 decimals)

Suggestion: Consider adding that precision beyond 8 decimals is permanently lost:

@return The converted amount in UFix64 format (precision beyond 8 decimals is permanently truncated)

This emphasizes the irreversibility of the conversion.

---

🔍 Code Quality Assessment

Category	Rating	Notes
Documentation	⭐⭐⭐⭐⭐	Excellent placement and clarity
Security	⭐⭐⭐⭐⭐	Correctly identifies non-exploitability
Accuracy	⭐⭐⭐⭐☆	Minor math clarifications suggested
Test Coverage	⭐⭐⭐⭐⭐	PR indicates all tests pass
Best Practices	⭐⭐⭐⭐⭐	Follows documentation standards

---

✅ Recommendation

APPROVE with minor suggestions for mathematical precision in the examples. The changes are:

• ✅ Safe: Documentation-only, no logic changes
• ✅ Important: Addresses a real limitation users should understand
• ✅ Well-placed: Strategic locations for maximum visibility
• ✅ Accurate: Correctly characterizes the security implications

The minor suggestions above are optional refinements and don't block merging.

---

🔒 Security Validation

I verified that:

• ✅ No logic changes that could introduce vulnerabilities
• ✅ Truncation behavior correctly characterized as non-exploitable
• ✅ User impact clearly documented (users receive less, not more)
• ✅ Mitigation strategy acknowledged (minimum deposit requirement)

Great work documenting this limitation! 🚀