@forevermoney/sdk 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.5.3 — 2026-09-19
+
+- Increased EVM-to-Subtensor CCIP destination execution gas from the spoke
+  gateways' 300,000 default to an explicit 3,500,000. A 900,000 manual
+  execution reached the gateway but still fell back to a claimable booking;
+  the same live liquid claim path estimates near 2,560,000 gas. Quotes and
+  transaction calldata now use the same exported
+  `EVM_TO_SUBTENSOR_DESTINATION_GAS_LIMIT` for zero-fee and partner-fee
+  bridges. Callers can override it per transaction with the optional
+  `destinationGasLimit` request field, without changing or republishing the
+  SDK.
+- Added the explicit-gas `quoteBridgeToFinney` and `bridgeToFinney` overloads
+  to the public SpokeGateway ABI.
+
+## 0.5.2 — 2026-09-16
+
+- Added opt-in stake rounding adjustment to Subtensor bridge preparation, with an explicit disable option and adjusted amount/plan metadata. Searches only on `StrandedStake`, preserves minimum output, requotes candidates and checks source balances, minimum remainders and partner-fee allocations. Approval-required plans are explicitly marked as not yet simulated.
+- Exported the same provider-neutral search (`estimateRoundedStake`), nested revert decoder and dust minimum helper so integrations do not need their own rounding implementation.
+
 ## 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.

package/README.md

@@ -6,10 +6,10 @@ vault contracts.
 The SDK owns the canonical production deployment: chain IDs, CCIP selectors,
 contract addresses, ABIs, and protocol-specific amount conversion. An
 integrator supplies only RPC transports and user input. The SDK never accepts a
-private key, signs a transaction, or broadcasts a transaction. Bridge principal
-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.
+private key, signs a transaction, or broadcasts a transaction. Network fees are
+charged separately. Subtensor-to-EVM requests accept an explicit minimum output
+to account for native staking rounding; exact output remains the default.
+SDK 0.5.2 also provides opt-in stake rounding preparation (see below).
 
 Bridge plans use the current gateways in `contracts.gateway`. Retired gateways
 remain under `contracts.legacyGateways` only so receipts and deliveries of
@@ -101,6 +101,11 @@ Liquid Base-to-Subtensor delivery requires at least `0.01 TAO` because the
 destination vault must unstake the bridged position. The SDK rejects smaller
 liquid deliveries with `AMOUNT_BELOW_MINIMUM` before quoting or planning them;
 staked delivery does not use this liquid-unstaking minimum.
+EVM-to-Subtensor plans quote and encode an explicit 3,500,000 destination gas
+limit so the variable-cost Subtensor exit path can auto-execute through CCIP.
+The policy is exported as `EVM_TO_SUBTENSOR_DESTINATION_GAS_LIMIT`. Pass a
+positive bigint as `destinationGasLimit` to override it for one preparation or
+plan; the SDK uses that value for both the fee quote and transaction calldata.
 The network-fee buffer is 2% and the estimated-gas buffer is 50%; both policies
 are exported as bigint basis-point constants and covered by property tests.
 
@@ -442,3 +447,59 @@ 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.
+
+### Optional stake rounding adjustment
+
+`client.bridge.prepareSubtensorToEvm` (and `prepareSubtensorToBase`) accepts
+`stakeRounding: { enabled: true, positions, minStakeRao }`. Omit it, pass `false`,
+or set `enabled: false` to preserve the exact requested input with no search.
+Synchronous `build*Plan` methods never simulate or adjust amounts.
+
+```ts
+import { stakedMinimumOutput } from '@forevermoney/sdk'
+
+const prepared = await client.bridge.prepareSubtensorToEvm({
+    evmChain: 'base',
+    asset: 'sn80',
+    source: 'staked',
+    sender,
+    recipient,
+    amountWei,
+    stakePulls,
+    minAmountOutWei: stakedMinimumOutput(amountWei, stakePulls.length),
+    stakeRounding: {
+        enabled: true,
+        positions, // [{ hotkey, stakeRao }], freshly read source balances
+        minStakeRao: 0n, // caller's minimum positive remainder per validator
+    },
+})
+```
+
+Only `StrandedStake(bytes32,uint256)` triggers adjustment. The SDK reduces the
+named validator's pull by one alpha base unit per attempt, for at most eight
+reductions, re-quotes fees and simulates the exact candidate. It keeps the
+**original absolute minimum output**, checks balances and remaining stake,
+including the partner fee apportioned on top, and propagates unrelated errors.
+The search stops if no valid candidate fits that budget. `stakedMinimumOutput`
+provides an explicit dust tolerance of two base units per source plus two for
+the deposit; tiny inputs retain an exact minimum. It is not a guarantee of
+successful execution.
+
+When enabled, `prepared.stakeRounding` reports `requestedAmountWei`, the actual
+`amountWei`, `minAmountOutWei`, `pulls`, and `simulationComplete`. Display the
+returned amount and use **the returned plan**, rather than rebuilding from the
+original request. If approval is required, `simulationComplete` is false:
+confirm approval, refresh balances, and prepare again before sending the bridge.
+Revalidate before signing; if the amount changes again, show it for review.
+Keep the original `minAmountOutWei` when re-preparing an adjusted amount so
+successive attempts cannot gradually lower output protection. Never automatically
+retry a broadcast transaction.
+
+For custom ethers/wallet quote flows, the SDK also exports
+`estimateRoundedStake({ amountWei, minAmountOutWei, pulls, positions,
+minStakeRao, adjustRounding, partnerFeeBps, quoteAndEstimate, isActive })`.
+`adjustRounding` defaults to true **for this explicitly invoked helper**; false
+performs one exact estimate. Its callback must quote and estimate the supplied
+candidate and minimum, and must never sign or broadcast. An optional `isActive`
+callback stops obsolete work between requests. `strandedStakeSource(error)`
+decodes nested RPC/ethers/viem errors for UI error messages.