feat: Sapphire testnet as HONOR deposit source chain

[rube-de]

closes #245

Register Sapphire testnet (23295) as an ERC-20 deposit source chain for HONOR. The accounting chain doubles as its own deposit source: chain config, RPC wiring, discovery, sweeps, credits, and withdrawals all on one chain.

What changed beyond config

• contract: gasLimitNativeSweep 21,000 -> 25,000 (measured native transfer on Sapphire: 22,140 gas; the old limit failed every native sweep and the gas-funding leg of every ERC-20 sweep). VERSION -> 2 so the upgrade task acts.
• RPC identity gate: every configured endpoint must report its filed chain ID at startup, re-verified every 5 minutes. A mismatch leaves the chain unserved, never mis-served. All chain-facing consumers route through the gate, including the withdrawal broadcaster.
• withdrawal safety: duplicate-broadcast proof requires a status-1 receipt for the exact signed bytes, so reverted receipts and mempool entries never mark a withdrawal paid. A per-chain nonce gate refuses to sign into spent nonces, admission thresholds come from the contract's own gas limits, and catch-up targets derive from the latest nonce so a stuck resolved withdrawal is recoverable (stuck-nonce alarm included).
• /deposits/address lists minimums only for verified chains with registered assets. 23295 advertises HONOR only, no native ROSE.

Gas funding is sized from the contract's sweep gas limit at the signing price plus 30% headroom; the static per-chain amounts stay as fallback when the contract read fails. Known tradeoff: the sweep is signed at the pre-funding gas price, so a spike during funding gives a slow sweep, not an out-of-gas one.

The rubetest shadow-deployment harness stays in the repo for re-rehearsing the rollout. The localnet mirror (23293) only exists when SAPPHIRE_CHAIN_ID selects it.

Verification

• full CI gate list green locally: format, lint, typecheck, solidity build, bytecode size budget, validate-upgrade, ABI presence, OpenAPI drift, pytest (716 passed), hardhat (98 in-process + 60 against sapphire-localnet)
• live rehearsal on an isolated testnet app and proxy: boot checks (3-chain identity, signer publish, HONOR registration, gas price publish), deposit -> gas funding -> sweep -> credit, withdrawal, machine-restart sweep recovery
• permissionless front-run of a withdrawal: the exact-hash check resolved it correctly
• V1 -> V2 upgrade rehearsed on a live shadow proxy: state preserved, version gate skips on re-run

Deploy

A startup version gate refuses to run against an implementation below REQUIRED_ACCOUNTING_VERSION (2), so token registration cannot precede the proxy upgrade. After merge:

• hardhat upgrade --network sapphire-testnet (add --output-safe if the owner is a Safe)
• tag privana/v1.0.3-testnet
• update the compose digest, redeploy ROFL

PR REVIEW

[Copilot]

Pull request overview

Registers Sapphire testnet (23295) as an HONOR ERC-20 deposit source chain and supports “same-chain” operation where the accounting chain is also the deposit source, with additional safety hardening around RPC endpoint identity, gas-funding sizing, and withdrawal broadcast correctness.

Changes:

• Add an RPC identity gate (rpc_identity) that probes eth_chainId at startup and periodically re-verifies endpoints, wiring all chain-facing services through verified_web3.
• Improve sweep gas funding by sizing from contract sweep gas-limit constants (with headroom) and aligning sweep signing gas price with the funding leg.
• Harden withdrawal broadcasting by proving duplicates via status-1 receipts for exact signed payload hashes, adding nonce readiness gating, and adding stuck-nonce alarming; expand test coverage accordingly.

Reviewed changes

Copilot reviewed 37 out of 37 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
test/py/test_withdrawals.py	Adds extensive tests for withdrawal duplicate-broadcast proof, nonce gating, and admission logic.
test/py/test_sweep_engine.py	Updates tests for contract-derived gas funding sizing and fallback behavior.
test/py/test_same_chain_e2e.py	Adds E2E coverage for same-chain deposit→sweep→credit and same-chain withdrawals under verified RPC gating.
test/py/test_rpc_identity.py	Adds unit tests for RPC identity verification, fail-closed behavior, and re-verification loop behavior.
test/py/test_main_lifespan.py	Adds lifespan-ordering tests ensuring RPC identity runs before any chain-touching bootstrap and that drifted/mis-filed chains are excluded.
test/py/test_chain_config.py	Adds Sapphire chain config tests, localnet gating tests, and gas-funding sanity checks.
test/py/test_accounting_routes.py	Updates /deposits/address behavior to advertise minimums only for verified chains with registered asset types; adds tests.
test/py/test_accounting_contract_service.py	Adds tests for identity-gated chain reads and TTL-cached contract gas limit getters.
test/conftest.py	Resets global RPC identity state between tests and enables pre-check fallback for unit tests.
src/services/withdrawal_processor.py	Implements nonce readiness gate, duplicate broadcast proof via receipts, “remembered hash” logic, and stuck-nonce alarming; uses verified RPC clients.
src/services/sweep_engine.py	Switches to verified RPC clients and sizes gas-funding from contract gas-limit constants with headroom; keeps sweep signing price aligned with funding.
src/services/rpc_identity.py	Introduces the RPC chain-id verification gate, commit/narrowing behavior, and periodic re-verification loop.
src/services/deposit_verifier.py	Switches source-chain Web3 construction to the RPC identity gate (verified_web3).
src/services/deposit_discovery.py	Switches discovery Web3 construction to the RPC identity gate and updates error semantics.
src/services/accounting_contract.py	Switches chain Web3 resolution to verified_web3; adds TTL-cached gas-limit getters; improves withdrawal gas admission sizing.
src/README.md	Updates documentation wording for DepositAccountingProtocol mocking guidance.
src/models/accounting.py	Improves OpenAPI schema description for min_deposit.
src/main.py	Runs RPC identity verification first in lifespan; starts/stops re-verification loop; adds accounting VERSION gate.
src/config/chain_config.py	Adds Sapphire testnet config and conditional Sapphire localnet config based on SAPPHIRE_CHAIN_ID.
src/config/init.py	Seeds Sapphire RPC URL independently of Alchemy; returns Sapphire mapping even when Alchemy key is unset.
src/api/routes.py	Adjusts /deposits/address response to only include verified+registered asset minimums and finality depths for served chains.
solidity/test/EVMSignerAndVerifier.ts	Adds tests asserting native sweep gas limit is 25k and encoded into generated txs on Sapphire-like networks.
solidity/test/Accounting.E2E.ts	Extends upgrade tests to assert VERSION==2 and preserve state across upgrade flows.
solidity/tasks/localnetToken.ts	Adds Hardhat task to deploy deterministic localnet ERC-20 (LHONOR) for same-chain dev harness.
solidity/tasks/index.ts	Registers the new deploy-localnet-token task.
solidity/tasks/deploy.ts	Hooks localnet token deployment into deploy flow when on Sapphire localnet.
solidity/scripts/validate-upgrade.ts	Clarifies upgrade validation logging and what is/isn’t being validated.
solidity/contracts/test/LocalnetERC20.sol	Adds localnet-only ERC-20 contract used by same-chain localnet harness.
solidity/contracts/EVMSignerAndVerifier.sol	Bumps gasLimitNativeSweep from 21,000 to 25,000 and updates sweep semantics comment.
solidity/contracts/Accounting.sol	Bumps contract VERSION from 1 to 2.
rofl.yaml	Adds a rubetest deployment profile and associated configuration.
docs/openapi.json	Updates OpenAPI to include min_deposit field description.
compose.rubetest.yaml	Adds a compose file for the rubetest shadow-deployment harness.
.gitleaksignore	Adds allowlist entries for known false positives (addresses/test key) introduced by new files.
.env.testnet	Adds chain 23295 gas price and HONOR token registration entry.
.env.rubetest	Adds a full rubetest environment configuration including Sapphire chain and HONOR token info.
.env.localnet	Adds Sapphire localnet gas price and deterministic LHONOR token registration entry.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

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

Suppressed comments (2)

src/services/rpc_identity.py:236

• _reverification_loop() catches Exception, which also catches asyncio.CancelledError on modern Python. That can cause the background loop to ignore cancellation (e.g., during shutdown), log a stack trace, and continue running.

Re-raise asyncio.CancelledError explicitly before the generic handler so stop_reverification_loop() can reliably cancel and await the task.

async def _reverification_loop(settings, interval_seconds: float, timeout: float) -> None:
    while True:
        await asyncio.sleep(interval_seconds)
        try:
            await reverify_chain_rpc_urls(settings, timeout=timeout)
        except Exception:
            # Keep the loop alive: the current verified set stays as it is, and the
            # next pass gets another chance to drop or readmit.
            logger.exception("RPC identity re-verification pass failed; verified set unchanged")

src/services/withdrawal_processor.py:443

• In the catch-up rebroadcast path, _find_broadcast_tx() returns None both when there is no mined receipt and when the expected tx is merely pending (it logs an info line and returns None). The error log here then asserts the nonce "may have been spent by a different transaction" / "leaving this withdrawal unpayable", which is misleading in the common case where the tx is still in flight.

Consider softening the message (or explicitly handling the pending-tx case) so operators don't get a false 'unpayable' signal.

                    logger.error(
                        f"Withdrawal #{index}: broadcast failed and no successful transaction "
                        f"matching the signed payload exists on {chain_name} - nonce {nonce} may "
                        f"have been spent by a different transaction, leaving this withdrawal "
                        f"unpayable: "

[Copilot]

Pull request overview

Copilot reviewed 37 out of 37 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/services/withdrawal_processor.py:308

• _find_broadcast_tx() only checks the mempool for expected_hash. When resolveWithdrawal re-signs (e.g., after setGasPrice) and the previously broadcast tx is still pending under the remembered hash, this path won't detect it as in-flight, and callers will log a scary failure and pause processing even though the withdrawal may simply be awaiting mining. Consider checking eth_getTransactionByHash for all candidate hashes (remembered + expected).

        # Nothing mined. A mempool entry proves nothing either way, so this lookup only
        # reports, and today's hash is the one a retry would put back on the wire.
        dest_web3 = self._get_destination_web3(chain_id)

        async def fetch_transaction():
            try:
                return await dest_web3.eth.get_transaction(expected_hash)
            except TransactionNotFound:

src/services/withdrawal_processor.py:443

• This error log claims the withdrawal may be “unpayable” due to a foreign-spent nonce, but in this code path _find_broadcast_tx() intentionally treats pending/mempool entries as "not yet proven" (no status-1 receipt). That means this message can be emitted even when our transaction is simply in flight, which is misleading and can cause unnecessary operator escalation. Suggest rewording to avoid implying irrecoverability when the state is just unproven.

                    logger.error(
                        f"Withdrawal #{index}: broadcast failed and no successful transaction "
                        f"matching the signed payload exists on {chain_name} - nonce {nonce} may "
                        f"have been spent by a different transaction, leaving this withdrawal "
                        f"unpayable: "
                        f"{exc}"
                    )

src/main.py:137

• start_reverification_loop(settings) is started before several startup steps that can raise (e.g., key initialization, get_accounting_version() gate, token registration). If startup aborts before reaching yield, the shutdown path (which calls stop_reverification_loop()) never runs, potentially leaving a background task running in a partially-initialized process (notably in test harnesses or supervisor-managed processes that don't immediately exit). Consider starting the loop only after successful startup, or wrapping the startup sequence in a try/finally that stops the loop on exceptions before yield.

    # Endpoints drift while the service runs; re-probe on a timer so a drifted one
    # loses its chain and a recovered one gets it back without a restart.
    start_reverification_loop(settings)