feat(rebalance): buy cNGN back on HyperFX, and share the KMS signer

[robertleifke]

What

The market maker's flow is one-directional — it sells cNGN for USDC — so without a routine that buys cNGN back, the bid side eventually goes dark. This adds that routine, and moves kms-signer into a shared package rather than copying it.

Proven end to end on Base tonight:

19.9 USDC -> 27,262.280616 cNGN -> sub 15  (448,634 -> 475,896.280616)

Filled at ₦1,369.96 against a rate-picker mid of ~₦1,372, so about 15 bps to rebalance. Same chain, same cNGN the venue settles, no bridge. The whole exercise — including three failed attempts — cost about 9 cents.

Why a shared package for the signer

kms-signer.ts moves from services/execution/src to @numo/kms-signer (as a git mv, so history follows). It is the code that signs; a second copy would drift, and fixing one instance of a thing is this repo's most-repeated mistake. The 6 signer tests move with it — execution goes 75 → 69, the new package has 6.

Things worth knowing before reviewing

Never use the SDK's quote here	@hyperbridge/sdk 2.8.13 (latest) prices this pair off the V1 phantomOrderPriceSnapshots table, which froze 2026-08-08 at 1393.0 — 1,617 identical rows — and validates only that the timestamp parses. The live feed is phantomOrderPriceSnapshotV2s, which the SDK never references. Quoting off V1 asks ~1.8% above market and never fills.
A bundler is required	executeBest submits the winning bid as an ERC-4337 UserOperation. Without a bundler URL it places the order, fails instantly with Bundler URL not configured, and leaves the input escrowed. Alchemy serves its Rundler bundler on the same URL as the RPC.
The gateway rewrites the order	It assigns the nonce (we send 0) and deducts the 5 bps protocol fee from the input. The commitment hashes the canonical struct, so cancel rebuilds from the indexer and verifies the hash before sending.
cancelOrder takes two arguments	A one-argument call reverts with no reason. Same-chain needs no destination proof, and recovery refunds the escrow and the solver fee — only the 5 bps is kept.
Read replicas lag both ways	A read after a receipt can be served pre-block; one pinned to the receipt's block can answer Unknown block. This produced three wrong conclusions in one evening — a 19.92 USDC refund printed as +0, an approve that had succeeded made the next simulate revert insufficient allowance, and a landed deposit reported an error. waitFor() is the fix.
Status updates are circular	Bid -> Swap -> UniswapQuoteEngine -> adapter. JSON.stringify on one killed a process that was holding escrowed funds. brief() cannot throw.

Verification

• ./scripts/verify.sh node → all checks passed
• Tests assert the guards fire, not just the happy path: the staleness limit, the no-bids case, a zero-rounding quote, and gross-vs-net pricing (pinned to the real on-chain fill of 300 USDC → 410,494.65 cNGN)
• All four CLI commands exercised as dry runs against live state
• Both new packages wired into services-execution.yml, a new services-rebalance.yml, and scripts/verify.sh — a check in only one place is what that script exists to prevent

Keys

Signs with KMS alias/numo-exchange-rebalance → 0x1661AA54fA390cd916722F971e4A9Fe4c01889fB. Deliberately not the executor key: a compromise here costs the float, not the venue's settlement authority.

Not done

The withdrawal leg (sub 15 → signer). Sub 15 is owned by the market maker's wallet, so it needs either that key or a signed POST /v1/withdrawals. Until then the loop is manual on that one step.

🤖 Generated with Claude Code