@forevermoney/sdk 0.2.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## 0.5.0 — 2026-09-16
+
+- Staked bridges from Subtensor can pull from several validators. Pass
+  `stakePulls: [{ hotkey, amountRao }]` (1–16 entries, unique hotkeys, summing
+  to the bridged amount) and the plan calls the V5.1 gateway's
+  `bridgeOutFromValidators` (or `…WithFee`), which re-delegates every pull to
+  the token's canonical validator before depositing. Without `stakePulls` the
+  plan keeps the single-validator `bridgeOut` call. With a partner fee the cut
+  is charged on top and spread across the pulls in proportion to their
+  amounts, so each position needs headroom for its share. Added `StakePull`, `MAX_STAKE_PULLS`, and the
+  `bridgeOutFromValidators*`, `minStakeRequired`, `MAX_STAKE_SOURCES` and
+  `GATEWAY_COLDKEY` ABI entries.
+- Moved the Subtensor gateway to the V5.1 deployment at
+  `0xd5Fa238aa4177f6c1341491969d9cBeec94EEd69`. `contracts.legacyGateway` is
+  now `contracts.legacyGateways`, a list of retired hubs (oldest first) used for
+  receipt and delivery tracking; the V5 hub stays listed because the spoke
+  gateways still deliver through it. Deployment metadata version is 1.3.0.
+
+## 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,

package/README.md

@@ -11,6 +11,14 @@ 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 current gateways in `contracts.gateway`. Retired gateways
+remain under `contracts.legacyGateways` only so receipts and deliveries of
+bridges sent through them can still be tracked. A spoke gateway's Subtensor
+hub pointer is immutable, so after a hub-only redeploy EVM-to-Subtensor
+deliveries still arrive through the previous hub; the SDK watches every known
+hub, so tracking and recovery detection are unaffected. Plans call the zero-fee V5
+entrypoints unless a `partnerFee` is passed (see "Charge a partner fee").
+
 ## Install
 
 ```bash
@@ -113,11 +121,122 @@ 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.
+
+## Bridge stake held with several validators
+
+Staked alpha on Finney is keyed by validator hotkey, and a bridge can only pull
+from the positions you name. Pass `stakePulls` to draw from more than one
+validator; the gateway re-delegates each pull to the token's canonical
+validator and deposits the total, so stake with any validator can be bridged.
+
+```ts
+const prepared = await foreverMoney.bridge.prepareSubtensorToBase({
+    sender: '0x...',
+    recipient: '0x...',
+    amountWei: 140n * 10n ** 18n,
+    source: 'staked',
+    netuid: 0n,
+    stakePulls: [
+        { hotkey: '0x…validatorA', amountRao: 100_000_000_000n },
+        { hotkey: '0x…validatorB', amountRao: 40_000_000_000n },
+    ],
+})
+```
+
+Rules the SDK checks before building a plan: 1 to `MAX_STAKE_PULLS` (16)
+entries, unique non-zero hotkeys, positive amounts, and a sum equal to the
+bridged amount in RAO. One staking approval on the netuid covers every pull.
+Nothing on-chain enforces the runtime's minimum stake on what you leave behind
+(`minStakeRequired()`, 0.02 TAO-equivalent), so size each pull to either drain
+the position or leave at least that much. With a partner fee the cut is charged
+on top and spread across the pulls in proportion to their amounts, so each
+position needs headroom for its share.
+
+## 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