@forevermoney/sdk 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.5.1 — 2026-09-16
+
+- Added optional `minAmountOutWei` to Subtensor-to-EVM bridge requests. Callers can explicitly bound output slippage, including staking rounding dust. Defaults to the input amount; rejects zero, negative, non-bigint, and above-input minima before RPC calls. The same minimum is used for gas estimation and final calldata, for single- and multi-validator routes with or without partner fees.
+
+## 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

package/README.md

@@ -11,9 +11,12 @@ 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
+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
@@ -172,6 +175,36 @@ Canonical SN80 token addresses are exported as `contracts.wrappedSn80`:
 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
@@ -405,3 +438,7 @@ testing are documented in [`docs/testing.md`](./docs/testing.md).
 
 Security reports should follow [`SECURITY.md`](./SECURITY.md). Maintainer release
 steps are in [`docs/releasing.md`](./docs/releasing.md).
+
+### Minimum bridge output
+
+Subtensor-to-EVM builders and preparation methods accept optional `minAmountOutWei` (destination token units, 18 decimals, after partner fees). It must be positive and no greater than `amountWei`; omission preserves the exact-output default. Choose the minimum explicitly to cover your acceptable slippage or native staking rounding dust. The SDK uses the same value for gas estimation and final transaction calldata. For example, `minAmountOutWei: amountWei - 4n * EVM_WEI_PER_RAO` allows four native RAO of dust when the amount exceeds that budget. This does not change the input amount or approval amount.

package/dist/index.cjs

@@ -28,6 +28,7 @@ __export(index_exports, {
   ForeverMoneyError: () => ForeverMoneyError,
   GAS_LIMIT_BUFFER_BPS: () => GAS_LIMIT_BUFFER_BPS,
   MAX_PARTNER_FEE_BPS: () => MAX_PARTNER_FEE_BPS,
+  MAX_STAKE_PULLS: () => MAX_STAKE_PULLS,
   MIN_LIQUID_BASE_TO_SUBTENSOR_WEI: () => MIN_LIQUID_BASE_TO_SUBTENSOR_WEI,
   MIN_LIQUID_EVM_TO_SUBTENSOR_WEI: () => MIN_LIQUID_EVM_TO_SUBTENSOR_WEI,
   MIN_LIQUID_SUBTENSOR_TO_EVM_WEI: () => MIN_LIQUID_SUBTENSOR_TO_EVM_WEI,
@@ -162,7 +163,7 @@ var SUBTENSOR_CCIP_SELECTOR = 2135107236357186872n;
 var RAO_PER_TAO = 1000000000n;
 var EVM_WEI_PER_RAO = 1000000000n;
 var SN80_NETUID = 80n;
-var FOREVERMONEY_DEPLOYMENT_VERSION = "1.2.0";
+var FOREVERMONEY_DEPLOYMENT_VERSION = "1.3.0";
 var foreverMoneyDeployment = Object.freeze({
   version: FOREVERMONEY_DEPLOYMENT_VERSION,
   base: Object.freeze({
@@ -172,9 +173,11 @@ var foreverMoneyDeployment = Object.freeze({
     ccipSelector: BASE_CCIP_SELECTOR,
     contracts: Object.freeze({
       gateway: (0, import_viem2.getAddress)("0x1da2415229b614C787e145D1D7346eb496319C52"),
-      legacyGateway: (0, import_viem2.getAddress)(
-        "0x5EF3d7D19e4b233a1A169DA0d5CB02ec6b160a2C"
-      ),
+      // Retired gateways, oldest first; kept only to track transfers sent
+      // through them.
+      legacyGateways: [
+        (0, import_viem2.getAddress)("0x5EF3d7D19e4b233a1A169DA0d5CB02ec6b160a2C")
+      ],
       wrappedTao: (0, import_viem2.getAddress)(
         "0xf3081494b87e8d5fb7960f066e931d1d0e6e3d67"
       ),
@@ -207,9 +210,9 @@ var foreverMoneyDeployment = Object.freeze({
     ccipSelector: ROBINHOOD_CCIP_SELECTOR,
     contracts: Object.freeze({
       gateway: (0, import_viem2.getAddress)("0xf27fdA637131E25B2A1b4865ED9597d881980c7E"),
-      legacyGateway: (0, import_viem2.getAddress)(
-        "0x53Dcc4FE04193e489BE537F722F65317DB1E65d8"
-      ),
+      legacyGateways: [
+        (0, import_viem2.getAddress)("0x53Dcc4FE04193e489BE537F722F65317DB1E65d8")
+      ],
       wrappedTao: (0, import_viem2.getAddress)(
         "0xf3081494B87e8D5fb7960f066E931D1D0e6E3d67"
       ),
@@ -225,10 +228,14 @@ var foreverMoneyDeployment = Object.freeze({
     chainId: SUBTENSOR_CHAIN_ID,
     ccipSelector: SUBTENSOR_CCIP_SELECTOR,
     contracts: Object.freeze({
-      gateway: (0, import_viem2.getAddress)("0xcd0C6d98D0A126B1c113d15b4c28F38321437787"),
-      legacyGateway: (0, import_viem2.getAddress)(
-        "0x998f20Fea90bF7792774dECc7f994716442B1705"
-      ),
+      // V5.1 AlphaGateway: multi-validator staked input (tao-bridge 485c898).
+      gateway: (0, import_viem2.getAddress)("0xd5Fa238aa4177f6c1341491969d9cBeec94EEd69"),
+      // V4 and V5 hubs. The spokes still deliver to the V5 hub (their hub
+      // pointer is immutable), so it stays here for delivery tracking.
+      legacyGateways: [
+        (0, import_viem2.getAddress)("0x998f20Fea90bF7792774dECc7f994716442B1705"),
+        (0, import_viem2.getAddress)("0xcd0C6d98D0A126B1c113d15b4c28F38321437787")
+      ],
       alphaVault: (0, import_viem2.getAddress)(
         "0x11837459896D96F821a8D88eC93a3C8D152033D4"
       ),
@@ -437,6 +444,11 @@ var ALPHA_GATEWAY_ABI = Object.freeze([
   "function integratorCut(uint256 amount,uint16 bps) pure returns (uint256)",
   "function quoteBridgeOutWithFee(uint64 destSelector,address token,address recipient,uint256 mintedAmount,uint256 taoAmount,uint256 stakedAlphaRao,(address recipient,uint16 bps) integrator) view returns (uint256 fee,uint256 nativeTopUp,uint256 alphaTopUp,uint256 amountCrossing)",
   "function bridgeOutWithFee(uint64 destSelector,address token,address recipient,uint256 taoAmount,uint256 stakedAlphaRao,uint256 minTokenOut,(address recipient,uint16 bps) integrator) payable returns (bytes32 messageId)",
+  "function bridgeOutFromValidators(uint64 destSelector,address token,address recipient,uint256 taoAmount,(bytes32 validator,uint256 alphaRao)[] sources,uint256 minTokenOut) payable returns (bytes32 messageId)",
+  "function bridgeOutFromValidatorsWithFee(uint64 destSelector,address token,address recipient,uint256 taoAmount,(bytes32 validator,uint256 alphaRao)[] sources,uint256 minTokenOut,(address recipient,uint16 bps) integrator) payable returns (bytes32 messageId)",
+  "function minStakeRequired() view returns (uint256)",
+  "function MAX_STAKE_SOURCES() view returns (uint256)",
+  "function GATEWAY_COLDKEY() view returns (bytes32)",
   "function claimLiquid(address token,uint256 minTaoOut,address to)",
   "function claimNative(address to)",
   "function claimStaked(address token,bytes32 destColdkey,address to)",
@@ -605,6 +617,7 @@ var MIN_LIQUID_EVM_TO_SUBTENSOR_WEI = 10000000000000000n;
 var MIN_LIQUID_BASE_TO_SUBTENSOR_WEI = MIN_LIQUID_EVM_TO_SUBTENSOR_WEI;
 var MIN_LIQUID_SUBTENSOR_TO_EVM_WEI = 2000000n * EVM_WEI_PER_RAO;
 var MAX_PARTNER_FEE_BPS = 1e4;
+var MAX_STAKE_PULLS = 16;
 var NO_PARTNER_FEE = {
   recipient: "0x0000000000000000000000000000000000000000",
   bps: 0
@@ -698,6 +711,27 @@ function sourceNetuid(input) {
   }
   return netuid;
 }
+function stakePullsFor(input, amountRao) {
+  if (input.stakePulls === void 0) return void 0;
+  if (input.source !== "staked") {
+    throw new ForeverMoneyError(
+      "INVALID_TRANSACTION_PLAN",
+      "Stake pulls are only valid for a staked source."
+    );
+  }
+  return resolveStakePulls(input.stakePulls, amountRao);
+}
+function minimumSubtensorOutput(input) {
+  const minimum = input.minAmountOutWei ?? input.amountWei;
+  assertNonNegativeAmount(minimum, "Minimum output");
+  if (minimum === 0n || minimum > input.amountWei) {
+    throw new ForeverMoneyError(
+      "INVALID_TRANSACTION_PLAN",
+      "Minimum output must be positive and no greater than the input amount."
+    );
+  }
+  return minimum;
+}
 function assertDelivery(value) {
   if (value !== "liquid" && value !== "staked") {
     throw new ForeverMoneyError(
@@ -769,7 +803,72 @@ function encodeSpokeBridge(token, amountWei, exit, fee) {
     args: [token, amountWei, exit, 0n, fee]
   });
 }
-function encodeHubBridge(destSelector, token, recipient, taoAmount, stakedAlphaRao, minTokenOut, fee) {
+function resolveStakePulls(pulls, amountRao) {
+  if (pulls.length === 0 || pulls.length > MAX_STAKE_PULLS) {
+    throw new ForeverMoneyError(
+      "INVALID_TRANSACTION_PLAN",
+      `Between 1 and ${MAX_STAKE_PULLS} stake pulls are required.`,
+      { count: pulls.length }
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  let total = 0n;
+  const resolved = pulls.map((pull) => {
+    const validator = normalizeBytes32(pull.hotkey, "Stake pull hotkey");
+    if (validator === `0x${"0".repeat(64)}`) {
+      throw new ForeverMoneyError(
+        "INVALID_TRANSACTION_PLAN",
+        "Stake pull hotkey must not be zero."
+      );
+    }
+    const key = validator.toLowerCase();
+    if (seen.has(key)) {
+      throw new ForeverMoneyError(
+        "INVALID_TRANSACTION_PLAN",
+        "Stake pulls must not repeat a hotkey.",
+        { hotkey: validator }
+      );
+    }
+    seen.add(key);
+    if (typeof pull.amountRao !== "bigint" || pull.amountRao <= 0n) {
+      throw new ForeverMoneyError(
+        "INVALID_TRANSACTION_PLAN",
+        "Each stake pull must take a positive amount of RAO.",
+        { hotkey: validator }
+      );
+    }
+    total += pull.amountRao;
+    return { validator, alphaRao: pull.amountRao };
+  });
+  if (total !== amountRao) {
+    throw new ForeverMoneyError(
+      "INVALID_TRANSACTION_PLAN",
+      "Stake pulls must sum to the bridged amount.",
+      { pulledRao: total.toString(), amountRao: amountRao.toString() }
+    );
+  }
+  return resolved;
+}
+function encodeHubBridge(destSelector, token, recipient, taoAmount, stakedAlphaRao, minTokenOut, fee, pulls) {
+  if (pulls !== void 0) {
+    const args2 = [
+      destSelector,
+      token,
+      recipient,
+      taoAmount,
+      pulls,
+      minTokenOut
+    ];
+    return fee.bps === 0 ? (0, import_viem6.encodeFunctionData)({
+      abi: alphaAbi,
+      functionName: "bridgeOutFromValidators",
+      args: args2
+    }) : (0, import_viem6.encodeFunctionData)({
+      abi: alphaAbi,
+      functionName: "bridgeOutFromValidatorsWithFee",
+      args: [...args2, fee]
+    });
+  }
   const args = [
     destSelector,
     token,
@@ -911,6 +1010,7 @@ function buildSubtensorToEvmPlan(input) {
   assertAssetMode(input.asset, input.source);
   const netuid = sourceNetuid(input);
   assertSubtensorToEvmAmount(input.amountWei, input.source);
+  const minAmountOutWei = minimumSubtensorOutput(input);
   assertNonNegativeAmount(input.exactNetworkFeeWei, "Network fee");
   const { subtensor } = foreverMoneyDeployment;
   const evm = getForeverMoneyEvmDeployment(input.evmChain);
@@ -959,6 +1059,7 @@ function buildSubtensorToEvmPlan(input) {
   }
   const taoAmount = input.source === "liquid" ? input.amountWei : 0n;
   const stakedAlphaRao = input.source === "staked" ? amountRao : 0n;
+  const pulls = stakePullsFor(input, amountRao);
   const value = taoAmount + taoTopUp + feeWithBuffer(input.exactNetworkFeeWei);
   assertNonNegativeAmount(value, "Transaction value");
   steps.push(
@@ -974,8 +1075,9 @@ function buildSubtensorToEvmPlan(input) {
         recipient,
         taoAmount,
         stakedAlphaRao,
-        input.amountWei,
-        partnerFee
+        minAmountOutWei,
+        partnerFee,
+        pulls
       ),
       value,
       input.estimatedBridgeGas === void 0 ? void 0 : gasLimitWithBuffer(input.estimatedBridgeGas)
@@ -1073,6 +1175,7 @@ async function prepareSubtensorToEvm(provider, input) {
   assertAssetMode(input.asset, input.source);
   const netuid = sourceNetuid(input);
   assertSubtensorToEvmAmount(input.amountWei, input.source);
+  const minAmountOutWei = minimumSubtensorOutput(input);
   const { subtensor } = foreverMoneyDeployment;
   const evm = getForeverMoneyEvmDeployment(input.evmChain);
   const partnerFee = resolvePartnerFee(
@@ -1126,8 +1229,9 @@ async function prepareSubtensorToEvm(provider, input) {
         recipient,
         taoAmount,
         stakedAlphaRao,
-        input.amountWei,
-        partnerFee
+        minAmountOutWei,
+        partnerFee,
+        stakePullsFor(input, stakedAlphaRao)
       ),
       value
     });
@@ -1730,12 +1834,12 @@ function bridgeMessageIdFromReceipt(direction, receipt) {
   );
   const evmToSubtensor = isEvmToSubtensorDirection(direction);
   const [addresses, contractAbi, eventName] = evmToSubtensor ? [
-    [evm.contracts.legacyGateway, evm.contracts.gateway],
+    [...evm.contracts.legacyGateways, evm.contracts.gateway],
     spokeGatewayAbi,
     "BridgedToFinney"
   ] : [
     [
-      foreverMoneyDeployment.subtensor.contracts.legacyGateway,
+      ...foreverMoneyDeployment.subtensor.contracts.legacyGateways,
       foreverMoneyDeployment.subtensor.contracts.gateway
     ],
     alphaGatewayAbi,
@@ -1897,7 +2001,7 @@ async function getCcipDeliveryStatus(provider, input) {
     );
   }
   const subtensorGateways = [
-    foreverMoneyDeployment.subtensor.contracts.legacyGateway,
+    ...foreverMoneyDeployment.subtensor.contracts.legacyGateways,
     foreverMoneyDeployment.subtensor.contracts.gateway
   ];
   for (const log of receipt.logs) {