@forevermoney/sdk 0.1.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 0.4.0 — 2026-09-16
+
+- Added `asset: 'sn80'` to the bridge builders and preparation methods for Base
+  SN80 ↔ Finney subnet-80 stake. Existing calls continue to default to TAO.
+- Added the verified Base and Finney SN80 token addresses and `SN80_NETUID`.
+- SN80 staking approvals use netuid 80 and alpha RAO; ERC-20 approvals use the
+  Base SN80 token. The partner fee remains 0% and the full principal crosses.
+- Rejects unsupported SN80 liquid TAO conversion, other subnets, and other
+  EVM lanes before requesting a quote.
+- Added an optional `partnerFee: { recipient, bps }` to every bridge builder and
+  `prepare*` method. The fee is charged on top of the bridged amount via the V5
+  `*WithFee` entrypoints and paid to the recipient on the source chain; the full
+  amount still crosses. `prepare*` enforces the gateway's `maxIntegratorFeeBps`.
+  Added `partnerFeeWei` to `BridgePreparation`, `MAX_PARTNER_FEE_BPS`,
+  `partnerFeeCut`, `partnerFeeTaoTopUp`, and the `INVALID_PARTNER_FEE` error
+  code. Omitting the fee keeps the zero-fee calls and byte-identical plans.
+  The hub quote uses the deployed `quoteBridgeOutWithFee(…, taoAmount,
+stakedAlphaRao, fee)` signature and cross-checks its top-ups against the SDK.
+- SN80 plans keep `minTaoOut` equal to the bridged amount, like TAO.
+- Updated deployment metadata version to 1.2.0.
+
+## 0.3.0 — 2026-09-16
+
+- Moved bridging to the V5 gateways. `contracts.gateway` is now
+  `0x1da2415229b614C787e145D1D7346eb496319C52` on Base,
+  `0xf27fdA637131E25B2A1b4865ED9597d881980c7E` on Robinhood, and
+  `0xcd0C6d98D0A126B1c113d15b4c28F38321437787` on Subtensor. Existing approvals
+  for the old gateways do not carry over.
+- Added `contracts.legacyGateway` with the previous gateway addresses. Receipt
+  parsing and CCIP delivery tracking accept both, so bridges sent through the old
+  gateways can still be tracked.
+- Added the V5 `*WithFee` bridge entrypoints, `maxIntegratorFeeBps`,
+  `bridgeFeeBps`, `integratorTaoTopUp`, and the `NotDelivered` event to the ABIs.
+  Plans still use the zero-fee entrypoints; the partner fee is 0%.
+- Fixed the `claimableToken` ABI argument names to `(token, account)`, the
+  order the gateway has always used. The selector is unchanged.
+- `getCcipDeliveryStatus` reports `recovery` when the Subtensor gateway emits
+  `NotDelivered`, not only `Claimable`.
+- Added `MIN_LIQUID_SUBTENSOR_TO_EVM_WEI`: bridging liquid TAO from Subtensor
+  requires at least 0.002 TAO.
+- Plan regression fixtures now check the V5 plans, which differ from the
+  originals only in the gateway address.
+
+## 0.2.0 — 2026-09-10
+
+- Replaced ethers with viem 2.56.3 for RPC clients, ABI encoding, gas estimation,
+  event decoding, and transaction tracking.
+- Replaced `@polkadot/util` and `@polkadot/util-crypto` with PAPI's
+  `@polkadot-api/substrate-bindings` 0.21.1 for SS58 validation and mirror addresses.
+- Added `toViemTransaction()` and a typed example that reuses existing viem clients.
+  Retained the dependency-free `toEthersTransaction()` compatibility adapter.
+- Lower-level tracking functions accept viem public clients and retain support
+  for ethers-style JSON-RPC providers through a dependency-free adapter. The
+  high-level transport interface, human-readable ABIs, and plan format are unchanged.
+- Enforced the plan's canonical chain in `toViemTransaction()` and rejected
+  unsupported chain IDs before signing.
+- Preserved uppercase EVM address normalization and mixed-case checksum validation.
+- Added regression tests for wrong-chain signing, legacy provider tracking, and
+  address normalization.
+- Added original-implementation plan and address regression fixtures; migrated
+  offline tests, fork tests, and the guarded live canary to the new libraries.
+- Fixed the Base canary to request staked delivery: its 0.001 TAO maximum is below
+  the 0.01 TAO liquid-delivery minimum. Broadcast guards and funding caps remain.
+
 ## 0.1.0
 
 - Added canonical Base and Subtensor production deployment metadata.

package/README.md

@@ -11,6 +11,11 @@ is transferred 1:1 and the network fee is charged separately, so the SDK fixes
 the contract's minimum destination output to the bridged principal instead of
 exposing configurable slippage.
 
+Bridge plans use the V5 gateways in `contracts.gateway`. The previous gateways
+remain under `contracts.legacyGateway` only so receipts and deliveries of
+bridges sent through them can still be tracked. Plans call the zero-fee V5
+entrypoints unless a `partnerFee` is passed (see "Charge a partner fee").
+
 ## Install
 
 ```bash
@@ -19,6 +24,12 @@ npm install @forevermoney/sdk
 
 Node.js 22 or newer is required. Both ESM and CommonJS builds are published.
 
+The SDK uses viem for EVM reads, ABI encoding, and receipt decoding, and
+PAPI's `@polkadot-api/substrate-bindings` for SS58 and EVM mirror addresses.
+It does not require ethers or the legacy `@polkadot/*` packages. The full PAPI
+RPC client is unnecessary because the bridge executes on Subtensor EVM;
+this SDK does not sign native Substrate extrinsics.
+
 ## Create a client
 
 ```ts
@@ -54,8 +65,10 @@ const foreverMoney = createForeverMoneyClient({
 })
 ```
 
-See [`examples/talisman.ts`](./examples/talisman.ts) for account and transaction
-handling.
+Existing viem public clients can supply their `.transport` directly. See
+[`examples/viem.ts`](./examples/viem.ts) for transport reuse and execution with a
+viem wallet client, or [`examples/talisman.ts`](./examples/talisman.ts) for
+raw EIP-1193 account and transaction handling.
 
 ## Prepare a bridge
 
@@ -105,11 +118,92 @@ method.
 
 For a staked source, pass the stake `netuid`. The SDK reads the staking
 precompile allowance and expresses the approval in RAO.
+For a liquid Subtensor source, the SDK requires at least 0.002 TAO because the
+gateway stakes it before bridging. This minimum does not apply to an existing
+staked source.
 
 The bridge does not deduct its fee from the destination amount. For both
 directions, the SDK encodes the bridge amount itself as the contract's minimum
 output; callers cannot weaken that invariant.
 
+## Bridge SN80 on Base
+
+Pass `asset: 'sn80'` to bridge Base SN80 to a Finney subnet-80 staked position,
+or bridge existing subnet-80 stake back to Base SN80. The default asset is `tao`,
+so existing TAO integrations keep their behavior. SN80 is supported on the Base
+lane with staked input/delivery; liquid TAO conversion and the Robinhood SN80
+lane are not supported by these methods.
+
+```ts
+const toFinney = await foreverMoney.bridge.prepareBaseToSubtensor({
+    asset: 'sn80',
+    sender: '0x...',
+    amountWei: 100n * 10n ** 18n, // 100 SN80
+    destination: '5...',
+    delivery: 'staked',
+})
+
+const toBase = await foreverMoney.bridge.prepareSubtensorToBase({
+    asset: 'sn80',
+    sender: '0x...',
+    recipient: '0x...',
+    amountWei: 100n * 10n ** 18n, // 100 staked SN80
+    source: 'staked',
+})
+```
+
+SN80 uses 18-decimal token units, restricted to whole alpha RAO (multiples of
+`10^9` token wei). The Finney approval uses the staking precompile and netuid
+`80` automatically; an explicitly different `netuid` is rejected. Base approves
+the SN80 ERC-20 to the V5 gateway. Both directions bridge the full SN80 amount
+with a 0% partner fee and charge network fees separately. The liquid TAO
+minimums do not apply to SN80 stake. SN80 delivery is always staked
+(`wantLiquid: false`), so the gateway never converts the stake into TAO.
+
+Bridging staked SN80 from Finney pulls the caller's alpha from the vault's own
+validator hotkey on netuid 80 (`AlphaVault.positionOf(SN80)`). Stake held with
+any other SN80 validator cannot be bridged until it is moved to that hotkey.
+
+Canonical SN80 token addresses are exported as `contracts.wrappedSn80`:
+
+- Base: `0x6F63d869011f95274498023b4ABFC00b30c34378`
+- Finney: `0xfD628dE75EF96f0A5C59659159C6cA81E0DC2222`
+
+The Base address `0x2292233d308188fcb3775f63a20f31dff6db02d9` is the SN80/TAO
+liquidity pool; bridge calls use the token addresses above.
+
+## Charge a partner fee
+
+Integrators can take a fee on each bridge by passing `partnerFee` to any bridge
+builder or preparation method. The fee is charged **on top** of `amountWei` and
+paid to `recipient` on the source chain in the same transaction; the full
+`amountWei` always crosses, and `minTaoOut` / `minTokenOut` still bound it.
+
+```ts
+const prepared = await foreverMoney.bridge.prepareBaseToSubtensor({
+    sender: '0x...',
+    amountWei: 100n * 10n ** 18n,
+    destination: '5...',
+    delivery: 'staked',
+    partnerFee: { recipient: '0xYourTreasury', bps: 100 }, // 1%
+})
+prepared.partnerFeeWei // 1 TAO: what the sender pays on top
+```
+
+What the sender supplies extra, per direction:
+
+| Direction                    | Extra input                                       | Plan effect                                             |
+| ---------------------------- | ------------------------------------------------- | ------------------------------------------------------- |
+| Base / Robinhood → Subtensor | `amount × bps / 10 000` of the token              | approval covers `amount + cut`; `bridgeToFinneyWithFee` |
+| Subtensor → EVM, liquid      | `partnerFeeTaoTopUp(amount, bps)` TAO (whole RAO) | added to the transaction value; `bridgeOutWithFee`      |
+| Subtensor → EVM, staked      | `alphaRao × bps / 10 000` of the caller's alpha   | staking approval covers it; `bridgeOutWithFee`          |
+
+`bps` must be an integer from 0 to 10 000; `0` or omitting `partnerFee` uses the
+original zero-fee entrypoints, so existing plans are unchanged. Each gateway caps
+the fee at `maxIntegratorFeeBps` (1% at deployment, governance can raise it to
+10%); `prepare*` reads the cap and throws `INVALID_PARTNER_FEE` when `bps`
+exceeds it. The recipient must not be the zero address or the gateway.
+
 ## Track bridge delivery
 
 Capture the destination block immediately before broadcasting the source bridge
@@ -163,9 +257,23 @@ for (const step of prepared.plan.steps) {
 }
 ```
 
-Ethers consumers can pass `toEthersTransaction(step.transaction)` directly to
-`Signer.sendTransaction()`. Both adapters validate the plan's decimal
-quantities before conversion.
+Viem consumers can pass `toViemTransaction(step.transaction)` to
+`walletClient.sendTransaction()`. The adapter supplies the canonical `chain`
+for the plan, so viem rejects a wallet connected to another network. Do not
+override that chain or disable viem's chain assertion. The adapter maps
+`from` to `account`, `gasLimit` to `gas`, and decimal quantities to `bigint`.
+Confirm the signing account and chain before every signature. Local-account
+signers must pass their account object explicitly, after checking that its
+address matches the plan's sender.
+
+`toEthersTransaction()` remains as a dependency-free compatibility adapter for
+existing consumers. All adapters validate decimal quantities before conversion.
+The exported lower-level tracking functions accept either a viem `PublicClient`
+or an existing ethers-style provider with `send(method, params)`. Legacy
+providers are adapted through their own transport without an ethers dependency.
+The `createForeverMoneyClient()` transport interface is unchanged. Exported
+`foreverMoneyAbis` remain human-readable; use viem's `parseAbi()` when calling
+contracts directly.
 
 If a plan contains an approval, its later transaction intentionally has no gas
 limit: that transaction cannot be simulated against pre-approval state. The