fix(sdk-coin-flrp): correct gas calculation for Flare C-chain atomic imports

[bitgo-ai-agent-dev]

What

• Add three coreth gas constants to iface.ts: ATOMIC_TX_BASE_GAS (10,000), TX_BYTES_GAS (1), SECP256K1_VERIFY_GAS (1,000), and 25% volatility-padding fraction constants BASE_FEE_PADDING_NUMERATOR / DENOMINATOR.
• Add computeAtomicImportFee(txSizeBytes, numSigs, cChainBaseFeeNFLR) utility in utils.ts implementing the full coreth formula:
  gas = ATOMIC_TX_BASE_GAS + txSizeBytes + numSigs × 1,000 ; fee = gas × baseFee × 1.25
• Add ImportInCTxBuilder.cChainBaseFee(baseFeeNFLR) setter that, when supplied, auto-computes the correct import fee internally using a temporary serialisation to measure tx size, superseding any previous .fee() value.
• Export computeAtomicImportFee from src/lib/index.ts so server-side callers can use it standalone.
• Raise maxImportFee on FlareP (mainnet) and FlarePTestnet from 10,000,000 to 20,000,000 nFLR in statics/src/networks.ts, covering a 1,000 gwei base fee with 25% padding.
• Add test/unit/lib/atomicImportGas.ts with unit tests for the gas constants, the formula, and cChainBaseFee() integration including the exact Coston2 failure scenario from the ticket (500 gwei base fee).

Why

Atomic imports from P-chain to Flare C-chain were failing with "inputs < outputs + requiredFee" when the C-chain base fee was elevated (observed at 500 gwei on Coston2). The SDK was computing ~5,700 gas per import by omitting the coreth AtomicTxBaseCost = 10,000 constant, resulting in a fee of only ~2,850,000 nFLR instead of the required ~5,655,000 nFLR. Any import failed regardless of amount. The fix adds the missing base cost, the 25% volatility-padding multiplier (guards against base-fee movement between signing and broadcast), and a cChainBaseFee() entry point so callers can pass the live base fee instead of a pre-computed total.

Test plan

• computeAtomicImportFee(311n, 1n, 500n) returns 7_069_375n (ticket scenario, padded)
• cChainBaseFee(500n) on a 1-of-1 import builds a tx whose fee > 1,000,000 nFLR (much more than old underprice)
• cChainBaseFee(500n) produces higher fee than cChainBaseFee(25n) on same inputs
• cChainBaseFee() supersedes any previously set .fee() value
• Existing signFlowTest and all current importInCTxBuilder tests continue to pass (they use explicit .fee())

Ticket: CECHO-1821

[linear-code]

CECHO-1821

[ArunBala-Bitgo]

@claude review this PR

[github-actions]

Claude finished @ArunBala-Bitgo's task —— View job

---

Code Review for Flare Atomic Import Gas Calculation Fix

Tasks

• Review gas constants and formula implementation
• Analyze ImportInCTxBuilder changes
• Check utility functions and exports
• Review test coverage and scenarios
• Assess statics changes
• Provide overall feedback and recommendations

Gas Constants and Formula Analysis ✅

The implementation in iface.ts and utils.ts correctly mirrors the coreth gas calculation constants:

Constants (lines 215-241 in iface.ts):

• ATOMIC_TX_BASE_GAS = 10_000n - Matches coreth's AtomicTxBaseCost
• TX_BYTES_GAS = 1n - Matches coreth's TxBytesGas
• SECP256K1_VERIFY_GAS = 1_000n - Matches coreth's Secp256k1FxVerifyCost
• Padding constants use proper 125/100 fraction for 25% buffer

Formula Implementation (utils.ts:58-62):

const gas = ATOMIC_TX_BASE_GAS + TX_BYTES_GAS * txSizeBytes + SECP256K1_VERIFY_GAS * numSigs;
const rawFee = gas * cChainBaseFeeNFLR;
return (rawFee * BASE_FEE_PADDING_NUMERATOR) / BASE_FEE_PADDING_DENOMINATOR;

ImportInCTxBuilder Analysis ✅

New cChainBaseFee() Method (ImportInCTxBuilder.ts:49-52):

• Well-documented method that accepts both bigint and string parameters
• Correctly supersedes any previous .fee() call as documented
• Integration is clean and follows builder pattern

Fee Computation Logic (lines 174-176):

• Properly gates fee computation when _cChainBaseFeeNFLR is set
• Uses internal _computeFeeFromBaseFee() method for calculation

Private Fee Computation (lines 266-286):

• Smart approach: builds temporary transaction with fee=0 to measure byte size
• Correctly calculates numSigs as sum of thresholds across UTXOs
• Uses the exported computeAtomicImportFee() utility function

Utility Functions and Exports ✅

Export Addition (index.ts:5):

• Correctly exports computeAtomicImportFee for standalone server-side usage
• Follows existing export patterns in the module

Test Coverage Analysis ✅

Comprehensive Test Suite (atomicImportGas.ts):

• Constants validation (lines 18-35): Verifies all gas constants match expected values
• Formula unit tests (lines 38-104): Covers the exact ticket scenario (311 bytes, 1 sig, 500 gwei = 7,069,375 nFLR)
• Scaling properties: Tests linear scaling with base fee and signature count
• Integration tests (lines 107-241): Tests cChainBaseFee() with real transaction building
• Edge cases: Tests fee superseding, multisig scenarios, different base fee levels

Notable Test Quality:

• Uses exact values from the ticket scenario for regression testing
• Validates the old formula would have produced insufficient fees
• Tests both 1-of-1 (MPC) and 2-of-3 multisig scenarios
• Verifies fee scaling properties mathematically

Statics Changes Analysis ✅

Network Configuration Updates:

• FlareP.maxImportFee: 10000000 → 20000000 nFLR
• FlarePTestnet.maxImportFee: 10000000 → 20000000 nFLR
• Updated comments to clearly explain the rationale: "covers 1000 gwei base fee with 25% padding"

These changes are necessary to accommodate the corrected (higher) import fees at elevated base fees.

Overall Assessment

✅ Strengths

1. Correct Implementation: The gas calculation formula accurately mirrors coreth's implementation
2. Comprehensive Testing: Excellent test coverage including the exact failure scenario from the ticket
3. Clean API Design: The cChainBaseFee() method provides a clear interface for dynamic fee computation
4. Proper Documentation: Good inline comments explaining the coreth formula and padding rationale
5. Backward Compatibility: Existing .fee() usage continues to work; new method is additive
6. Smart Engineering: Using temporary transaction serialization to measure byte size is elegant

🔍 Minor Observations

1. Type Safety: Good use of bigint throughout for precise gas calculations
2. Error Handling: Appropriate validation of UTXO balance vs computed fees
3. Constants: Well-documented constants with clear mapping to coreth source

✅ Security Considerations

• No security issues identified
• Proper input validation on fee parameters
• No credential handling concerns in the gas calculation logic

📋 Recommendations

1. Consider adding JSDoc to computeAtomicImportFee() for better IDE support
2. The implementation is production-ready - addresses the core issue completely

This PR effectively resolves CECHO-1821 by implementing the missing AtomicTxBaseCost and providing a robust interface for dynamic fee computation with proper volatility padding.

---

Job Run | Branch: fix/CECHO-1821-flare-atomic-import-gas-calculation

[Copilot]

Pull request overview

This PR updates the Flare P→C atomic import fee calculation in sdk-coin-flrp to match the coreth gas/fee model (including the missing atomic base gas) and adds an integration path (cChainBaseFee) for callers to supply a live C-chain base fee so the SDK can compute the correct required import fee.

Changes:

• Introduces coreth-derived atomic import gas constants and a computeAtomicImportFee() helper, and exports it for standalone use.
• Adds ImportInCTxBuilder.cChainBaseFee() to compute/override the import fee internally using a temporary serialization for tx size.
• Raises Flare P-chain maxImportFee limits and adds unit tests covering the formula and builder integration scenarios.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
modules/statics/src/networks.ts	Raises maxImportFee for Flare P mainnet/testnet to accommodate higher base fees with padding.
modules/sdk-coin-flrp/src/lib/iface.ts	Adds exported gas/padding constants used for atomic import fee computation.
modules/sdk-coin-flrp/src/lib/utils.ts	Adds computeAtomicImportFee() implementing the coreth fee formula.
modules/sdk-coin-flrp/src/lib/ImportInCTxBuilder.ts	Adds cChainBaseFee() and internal fee derivation based on base fee + tx size + signature count.
modules/sdk-coin-flrp/src/lib/index.ts	Re-exports computeAtomicImportFee() for external/server-side callers.
modules/sdk-coin-flrp/test/unit/lib/atomicImportGas.ts	Adds unit/integration tests for constants, fee formula, and builder behavior under elevated base fee.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.