Saturn DEX — Full Contract Reference

getAdmin(): address

Returns the current protocol admin address. The admin slice of every swap fee (getAdminPct()) is paid to it, and the admin-only methods of saturnadmin and most other v4 contracts check its signature (SATURN keeps its own owner, SATURN.getOwner()). Use it to show protocol ownership or to check whether a wallet has admin rights.

const admin = await readContract("saturnadmin", "getAdmin", []);
// "P2KBPHBKq1xuoSajuKxQCd7RfCfGFyoczoHQdVxacEUc9As" on mainnet and devnet today

getContractVersion(): string

Returns the deployed build tag of this contract. The mainnet and devnet deployments documented here report "saturnadmin-4.4.0". Compare it against the value you developed against before trusting method semantics after an upgrade.

const v = await readContract("saturnadmin", "getContractVersion", []);
// "saturnadmin-4.4.0"

getFeeSplitRatios(): string

Returns all four fee split percentages packed into a single string of the form "reinvest:X_provider:Y_admin:Z_holder:H". Convenient for single-call rendering of the complete fee split. The holder slice is credited to the saturnholders stakers of the swap's input token; since saturnswap-4.4.3 it stays in the pool as reinvest when nobody stakes that token.

const split = await readContract("saturnadmin", "getFeeSplitRatios", []);
// "reinvest:60_provider:10_admin:20_holder:10" on mainnet and devnet
const parts = Object.fromEntries(split.split("_").map((kv) => kv.split(":")));

getReinvestPct(): number

Percentage of each swap fee that stays in the pool's reserves, growing its depth. saturnswap does not read this value: the reinvest part is whatever is left of the fee after the provider, admin and holder slices, so when nobody stakes the input token the holder slice is added to it (70% instead of 60% on mainnet today).

const reinvest = await readContract("saturnadmin", "getReinvestPct", []);

getProviderPct(): number

Percentage of each swap fee paid to the pool provider, accrued in the FeeVault and claimable via SaturnFees.claimProviderFees().

const provider = await readContract("saturnadmin", "getProviderPct", []);

getAdminPct(): number

Percentage of each swap fee sent straight to the protocol admin wallet (saturnadmin.getAdmin()) at swap time.

const admin = await readContract("saturnadmin", "getAdminPct", []);

getHolderPct(): number

Percentage of each swap fee credited to the stakers of the swap's input token in saturnholders (saturnholders.accrueHolderFee), pro-rata by stake; 10 on mainnet and devnet today. Since saturnswap-4.4.3 the slice is taken only when saturnholders.getTotalStaked(tokenIn) > 0; when nobody stakes the input token it stays in the pool as reinvest. Together with getReinvestPct(), getProviderPct() and getAdminPct() it sums to 100. Zero means no holder rewards are being paid from swap fees (the value on a fresh deployment).

const holderPct = await readContract("saturnadmin", "getHolderPct", []);

getPoolFeeRange(): string

Returns both min and max per-pool fee rate as a single packed string. Use when creating a pool so the UI can clamp the user's fee slider to the valid range.

const range = await readContract("saturnadmin", "getPoolFeeRange", []);
// "min:30_max:3000"

getMinPoolFeePer10k(): number

Minimum fee rate (in basis points out of 10,000) a provider may set when creating a pool. 30 means 0.3%.

const minFee = await readContract("saturnadmin", "getMinPoolFeePer10k", []);

getMaxPoolFeePer10k(): number

Maximum allowed pool fee rate (in basis points out of 10,000). 3000 means 30%.

const maxFee = await readContract("saturnadmin", "getMaxPoolFeePer10k", []);

getTargetDecimals(): number

The internal scaling target: every token amount is converted to this many decimals inside the protocol (multiplied up for tokens with fewer decimals, divided down for tokens with more, such as KCAL's 10), so pool reserves and fee balances are 8-decimal numbers.

const dec = await readContract("saturnadmin", "getTargetDecimals", []);

getMinScaledPoolUnits(): number

Minimum amount (in scaled units) required when creating a pool. Combined with each token's scale factor, this becomes the raw-unit minimum returned by SaturnRouter.getMinRawForPoolCreation().

const minPool = await readContract("saturnadmin", "getMinScaledPoolUnits", []);

getMinScaledSwapUnits(): number

Minimum amount (in scaled units) required per swap. Enforced by the Swap Engine and used by Router views to show users the minimum swap they can submit.

const minSwap = await readContract("saturnadmin", "getMinScaledSwapUnits", []);

getMinScaledAddLiqUnits(): number

Minimum amount (in scaled units) when adding liquidity to an existing pool.

const minAdd = await readContract("saturnadmin", "getMinScaledAddLiqUnits", []);

getAbsoluteMinRaw(): number

The absolute floor for any computed raw-unit minimum. Even if scaling math would give a smaller number, raw minimums never drop below this value.

const floor = await readContract("saturnadmin", "getAbsoluteMinRaw", []);

getMaxTruncationPercent(): number

Maximum allowable truncation loss (in %) when removing a pool. If scale-down rounding would lose more than this percentage of either token's reserve, removePool() reverts.

const maxTrunc = await readContract("saturnadmin", "getMaxTruncationPercent", []);

getSOULfeeCreatePool(): number

Always returns 0. The SOUL storage fee that createPool() used to charge was removed; the method is kept so older integrations keep working. Do not budget SOUL for pool creation because of this value — the one notable extra cost of createPool() is the gas burned to mint the SATURN certificate NFT (about 2,500 KCAL).

const fee = await readContract("saturnadmin", "getSOULfeeCreatePool", []);
// fee === 0

getSOULfeeAddLiquidity(): number

Always returns 0. addLiquidity() no longer charges a SOUL fee; the getter remains for ABI compatibility only.

const fee = await readContract("saturnadmin", "getSOULfeeAddLiquidity", []);

getStorageFee(): number

Always returns 0. The protocol no longer collects SOUL for storage. On Phantasma the transaction itself escrows a small amount of SOUL per new storage key it creates (about 0.002 SOUL, refunded when the key is later deleted), which is why wallets that create pools, orders, bonds or loans should hold a little SOUL besides KCAL for gas.

const accrued = await readContract("saturnadmin", "getStorageFee", []);

getGuardLocked(user: address): number

Returns 1 if the given user currently holds a reentrancy guard slot (meaning they are mid-transaction somewhere in the protocol), 0 otherwise. Normally this should be 0 between transactions.

const locked = await readContract("saturnadmin", "getGuardLocked", [userAddress]);
if (locked === 1) console.warn("guard stuck for", userAddress);

getGuardOwner(user: address): string

Returns the name of the Saturn contract that currently holds the per-user reentrancy lock for `user` (for example "saturnswap" or "saturnbonds"), or an empty string when the user is not locked. Pair it with getGuardLocked() when diagnosing a transaction that was refused with a reentrancy error.

const owner = await readContract("saturnadmin", "getGuardOwner", [userAddress]);

updateAdmin(newAdmin: address)

Admin only. Only the saturnadmin owner (the wallet getAdmin() returns) can call this. Hands the protocol admin role to newAdmin at once. Everything that reads saturnadmin.getAdmin() follows: the admin slice of each swap fee goes to the new wallet, and most admin checks and upgrades in the other v4 contracts accept its signature. SATURN keeps its own owner (SATURN.getOwner()), which this does not change.

updateFeeSplitRatios(newReinvest: number, newProvider: number, newAdmin: number)

Admin only. Only the saturnadmin owner can call this. Legacy 3-way setter: sets the reinvest / provider / admin percentages of every swap fee and forces the holder slice (getHolderPct) to 0, which switches holder rewards off. Mainnet and devnet run 60 / 10 / 20 / 10 today; use updateFeeSplitRatiosV2 to keep a holder slice.

updateFeeSplitRatiosV2(newReinvest: number, newProvider: number, newAdmin: number, newHolder: number)

Admin only. Only the saturnadmin owner can call this. Sets the 4-way swap-fee split in whole percent: reinvest (left in the pool), provider (credited in saturnfees), admin (sent to getAdmin()) and holder (credited to saturnholders stakers of the swap's input token; since saturnswap-4.4.3 it stays in the pool when nobody stakes that token). Mainnet and devnet run 60 / 10 / 20 / 10.

updatePoolFeeRange(newMin: number, newMax: number)

Admin only. Only the saturnadmin owner can call this. Sets the allowed range of per-swap pool fees (per 10,000). New pools (createPool, syndicate, launchpad, saturnclpools) and fee changes (saturnpools.updatePoolFee, rentals, fee options) must stay inside it. Existing pools keep their fee. Mainnet and devnet: 30 to 3000.

updateMinScaledAmounts(newPoolMin: number, newSwapMin: number, newAddLiqMin: number)

Admin only. Only the saturnadmin owner can call this. Sets the three minimums, in 8-decimal scaled units: per side of createPool, per swap input, and per addLiquidity token A. saturnpools.getMinRawForToken turns each into a raw minimum per token (never below getAbsoluteMinRaw(), 100).

updateMaxTruncationPercent(newPercent: number)

Admin only. Only the saturnadmin owner can call this. Sets how much of a reserve (whole percent) scale-down rounding may lose when a pool is removed; removePool and saturnpools.clearPoolReserves revert with "Truncation N% on TOKEN" above it.

updateSOULfees(newCreatePool: number, newAddLiquidity: number)

Admin only. DEPRECATED — the saturnadmin owner's call always reverts with "SOUL entry fees removed: createPool/addLiquidity no longer charge SOUL"; any other caller gets "Only admin". Kept in the ABI for upgrade compatibility; getSOULfeeCreatePool() and getSOULfeeAddLiquidity() always return 0.

accrueStorageFee(feesFromSoul: number)

Internal: only saturnliquidity can call this. DEPRECATED no-op: it records nothing and moves no tokens, and getStorageFee() always returns 0. Kept in the ABI for upgrade compatibility; saturnliquidity 4.3.3 no longer calls it.

increaseStorage(from: address, stakeAmount: number, soultoken: string)

DEPRECATED — always reverts with "Storage staking removed: Gen3 storage is funded by tx data escrow, not by staking or SOUL charged here", for every caller. Kept in the ABI for upgrade compatibility. Storage is paid by each transaction's SOUL data escrow instead (about 0.002 SOUL per new storage key).

acquireGuard(user: address)

Internal: only saturnswap, saturnliquidity, saturnfees, saturnrewards, saturnclpools, saturnflash, saturnholders, saturnbonds, saturnrental, saturnfeeopts, saturnsyndicate, saturnlaunchpad, saturnarb, saturnlimit, saturnpredict, saturnvaults, saturntwamm and saturnstakearb can call this. Takes the per-user reentrancy lock at the start of a user action: marks user as locked and records the calling contract as the lock owner (see getGuardLocked / getGuardOwner).

releaseGuard(user: address)

Internal: only the Saturn DEX contracts listed under acquireGuard can call this, and only the one that took the lock. Clears the per-user reentrancy lock at the end of a user action.

clearReentrancy(user: address)

Admin only. Only the saturnadmin owner can call this. Force-clears a user's reentrancy lock (getGuardLocked becomes 0, getGuardOwner becomes ""). Meant for a lock left behind by a bug; a failed transaction rolls its own lock back.

getCanonicalPairKey(symbolA: string, symbolB: string): string

Returns the protocol's canonical key for a token pair. Symbols are sorted alphabetically so that "SOUL+KCAL" and "KCAL+SOUL" both map to the same key "KCAL_SOUL". Use this whenever you need to look up how many pools exist for a pair.

const key = await readContract("saturnpools", "getCanonicalPairKey", ["SOUL", "KCAL"]);
// "KCAL_SOUL"
const count = await readContract("saturnpools", "getPairPoolCount", [key]);

getPoolPairKey(poolId: number): string

Returns the canonical pair key for a specific pool. Equivalent to calling getCanonicalPairKey() with that pool's two token symbols.

const pairKey = await readContract("saturnpools", "getPoolPairKey", [poolId]);

scaleUp(amount: number, symbol: string): number

Converts a raw (on-chain decimal) amount into the protocol's internal scaled units, using the stored scale factor for that token. Use this before passing amounts to any method that expects scaled units.

const scaled = await readContract("saturnpools", "scaleUp", [1000000, "KCAL"]);

scaleDown(amount: number, symbol: string): number

Inverse of scaleUp — converts a scaled internal amount back into raw token units for display. Use this when reading reserves, payouts, or any number returned by a protocol view.

const scaledReserve = await readContract("saturnpools", "getPoolReserveA", [poolId]);
const tokenA = await readContract("saturnpools", "getPoolTokenA", [poolId]);
const raw = await readContract("saturnpools", "scaleDown", [scaledReserve, tokenA]);

getScaleFactor(tokenSymbol: string): number

Returns the stored scale factor for a token: 10^(8 − decimals) for a token with 8 decimals or fewer, 1 for a token with more (the division is in getScaleDivisor). scaled = raw × factor / divisor. Live values: SOUL factor 1 / divisor 1, RA and TAZ 1 / 10, KCAL 1 / 100. 0 means the scale was never computed.

const factor = await readContract("saturnpools", "getScaleFactor", ["SOUL"]);

getMinRawForToken(symbol: string, minScaledUnits: number): number

Given a token and a scaled-unit minimum from SaturnAdmin (e.g. getMinScaledSwapUnits), returns the equivalent raw-unit minimum that a user must provide. The result is floored by getAbsoluteMinRaw so tiny scale factors can't produce zero minimums.

const minScaled = await readContract("saturnadmin", "getMinScaledSwapUnits", []);
const minRaw = await readContract("saturnpools", "getMinRawForToken", ["KCAL", minScaled]);

validateTokenSymbol(symbol: string)

Reverts with "Token does not exist: <symbol>" if the given symbol isn't registered as a Phantasma token. Useful as a cheap preflight before submitting a transaction that would otherwise fail mid-execution.

try {
  await readContract("saturnpools", "validateTokenSymbol", ["MYTOKEN"]);
  // token exists
} catch (e) {
  console.error("Unknown token");
}

getScaleDivisor(tokenSymbol: string): number

Returns the cached divisor that scaleDown() applies to a token whose decimals exceed the protocol target (8). It is 1 for tokens at or below the target and 0 when the token's scale has never been computed (cold cache). With a cold cache scaleUp() and scaleDown() return the amount unchanged and getMinRawForToken() returns saturnadmin.getAbsoluteMinRaw(), while saturnrouter.getBestPoolForSwapV2() and the router's getMinRawFor*() fail as reads because they try to write the cache. A factor cached with divisor 0 (before the divisor existed) is treated as divisor 1.

const divisor = await readContract("saturnpools", "getScaleDivisor", ["KCAL"]);

computeAndStoreScaleFactor(symbol: string)

Warms the scale cache for a token: reads Token.getDecimals(symbol) and stores the factor / divisor pair that converts raw amounts to the protocol's 8-decimal internal units. Idempotent — it does nothing when the factor is already stored. No witness is required, so any wallet (or your indexer) can call it, and every path that needs a scale (createPool, router scoring, the lending adapter's warmScale) calls it internally. Use it before the first read against a brand-new token, because getScaleFactor() / getScaleDivisor() return 0 while the cache is cold.

// Warm the scale cache once for a newly listed token
const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnpools", "computeAndStoreScaleFactor", ["NEWTOKEN"])
  .spendGas(from)
  .endScript();
// sign with the caller's wallet and send

getPoolProvider(poolId: number): address

Returns the address of the wallet that created (and currently owns) the given pool.

const provider = await readContract("saturnpools", "getPoolProvider", [poolId]);

getPoolTokenA(poolId: number): string

Returns the symbol of the pool's first token (slot A). Note: A/B slot order is provider-chosen at creation and is NOT canonical.

const tokenA = await readContract("saturnpools", "getPoolTokenA", [poolId]);

getPoolTokenB(poolId: number): string

Returns the symbol of the pool's second token (slot B).

const tokenB = await readContract("saturnpools", "getPoolTokenB", [poolId]);

getPoolReserveA(poolId: number): number

Returns the scaled reserve of token A in the pool. Pass the result through scaleDown() to get the raw amount for display.

const resA = await readContract("saturnpools", "getPoolReserveA", [poolId]);
const symA = await readContract("saturnpools", "getPoolTokenA", [poolId]);
const displayA = await readContract("saturnpools", "scaleDown", [resA, symA]);

getPoolReserveB(poolId: number): number

Returns the scaled reserve of token B in the pool.

const resB = await readContract("saturnpools", "getPoolReserveB", [poolId]);

getPoolActive(poolId: number): number

Returns 1 if the pool is active (can be swapped, can accept liquidity), 0 if it has been removed.

const isActive = (await readContract("saturnpools", "getPoolActive", [poolId])) === 1;

getPoolPawned(poolId: number): number

1 while the pool is pledged as collateral for a saturnmarket loan (since 4.1.8), 0 otherwise. A pledged pool holds a financial lock of exactly 1 and its SATURN certificate sits in saturnvault; swaps, provider fees and addLiquidity continue, but it cannot be removed, re-priced by the provider, burned, time-locked, enrolled in a campaign or put under another product until the loan is repaid (pledge released, certificate back to the borrower) or liquidated / defaulted (the lender becomes the provider). pawnPool / unpawnPool are unrelated deprecated stubs.

const pawned = await readContract("saturnpools", "getPoolPawned", [poolId]);

getPoolNftId(poolId: number): number

Returns the token ID of the SATURN NFT certificate that represents ownership of this pool. Transferring this NFT transfers pool ownership.

const nftId = await readContract("saturnpools", "getPoolNftId", [poolId]);

getPoolFee(poolId: number): number

Returns the pool's per-swap fee rate in basis points out of 10,000. 300 = 3%. Range: 30–3000 (0.3%–30%).

const feeBp = await readContract("saturnpools", "getPoolFee", [poolId]);
const pct = feeBp / 100; // e.g. 300 → 3%

getPoolScaledLiquidity(poolId: number): number

Returns the smaller of the pool's two scaled reserves — a cheap "depth" metric for ranking pools.

const depth = await readContract("saturnpools", "getPoolScaledLiquidity", [poolId]);

getPoolCampaignLockCount(poolId: number): number

How many active reward campaigns currently reference this pool. When > 0, the provider can't change the pool fee or remove the pool.

const locks = await readContract("saturnpools", "getPoolCampaignLockCount", [poolId]);

getPoolFinancialLockCount(poolId: number): number

How many financial products hold this pool: bonds, rentals, fee options, syndicate and launchpad pools, or a loan pledge (exactly 1 while getPoolPawned() = 1). While > 0 the pool cannot be removed and the provider cannot change its fee; swaps and addLiquidity continue.

const finLocks = await readContract("saturnpools", "getPoolFinancialLockCount", [poolId]);

getPairPoolCount(pairKey: string): number

Returns how many pools exist for a given canonical pair key. Use it to iterate pools for a pair with getPairPoolAtIndex().

const key = await readContract("saturnpools", "getCanonicalPairKey", ["SOUL", "KCAL"]);
const n = await readContract("saturnpools", "getPairPoolCount", [key]);

getPairPoolAtIndex(lookupKey: string): number

Returns the poolId stored at a given index within a pair's pool list. The lookupKey is the canonical pair key concatenated with "_INDEX".

const key = "KCAL_SOUL";
const count = await readContract("saturnpools", "getPairPoolCount", [key]);
for (let i = 0; i < count; i++) {
  const poolId = await readContract("saturnpools", "getPairPoolAtIndex", [`${key}_${i}`]);
}

getReserveValue(tokenSymbol: string): number

Total scaled reserve of a token across every pool in the DEX. Useful for protocol-level stats.

const scaledTotal = await readContract("saturnpools", "getReserveValue", ["SOUL"]);

getCountOfTokensOnList(): number

Length of the token list behind getTokensInDEXList(). A symbol is appended whenever a pool is created while the DEX holds none of that token (its global reserve is 0), so a token whose pools were all removed and later re-created is listed again: this counts entries, not unique tokens (mainnet lists ANGEL three times).

const n = await readContract("saturnpools", "getCountOfTokensOnList", []);

getCountOfPairsOnList(): number

Total number of unique token pairs that have ever had at least one pool.

const n = await readContract("saturnpools", "getCountOfPairsOnList", []);

getTokensInDEXList(): string*

Generator-style method that yields every token symbol registered in the DEX. Phantasma exposes this as an enumerable script call.

// Phantasma invokeRawScript returns all yielded values in a single list
const script = ScriptBuilder
  .begin()
  .callContract("saturnpools", "getTokensInDEXList", [])
  .endScript();
const { decoded } = await api.invokeRawScript("main", script);

getPairsInDEXList(): string*

Generator yielding every canonical pair key currently indexed.

const script = ScriptBuilder
  .begin()
  .callContract("saturnpools", "getPairsInDEXList", [])
  .endScript();

getAllPoolIds(): number*

Generator yielding every poolId that has ever been created, including removed ones. Filter with getPoolActive() if you only want live pools.

const script = ScriptBuilder
  .begin()
  .callContract("saturnpools", "getAllPoolIds", [])
  .endScript();

getContractTokenBalanceEach(tokenSymbol: string): number

Raw token balance at the saturnpools contract address. saturnpools holds no tokens: reserves, unclaimed provider fees and holder rewards all sit at saturnliquidity.getLiquidityAddress(), so this normally returns 0 (mainnet SOUL reads 0).

const balance = await readContract("saturnpools", "getContractTokenBalanceEach", ["SOUL"]);

getAllPoolsData(): string*

Yields one pipe-delimited row per registered pool (active or removed), in registration order: poolId|tokenA|tokenB|reserveA|reserveB|feePer10k|active. Reserves are in the protocol's 8-decimal scaled units — use scaleDown() to display them. One call replaces seven per-pool reads when building a pool table.

const rows = await readContract("saturnpools", "getAllPoolsData", []);
// rows[0] => "1|KCAL|SOUL|100000000000|250000000000|30|1"
const pools = rows.map((r) => { const [id, a, b, ra, rb, fee, active] = r.split("|"); return { id: +id, a, b, ra, rb, fee: +fee, active: active === "1" }; });

getActivePoolsData(): string*

Same rows as getAllPoolsData() but only for pools whose active flag is 1. The natural feed for a swap UI's pool list.

const rows = await readContract("saturnpools", "getActivePoolsData", []);

getNextPoolId(): number

The poolId that will be assigned to the next pool created.

const next = await readContract("saturnpools", "getNextPoolId", []);

getTotalPoolCount(): number

Total number of pools ever created in the protocol, including removed ones.

const total = await readContract("saturnpools", "getTotalPoolCount", []);

getContractVersion(): string

Returns the deployed build tag of this contract. The mainnet and devnet deployments documented here report "saturnpools-4.1.10". Compare it against the value you developed against before trusting method semantics after an upgrade.

const v = await readContract("saturnpools", "getContractVersion", []);
// "saturnpools-4.1.10"

getTwapTracked(poolId: number): number

1 when the admin keeps a time-weighted average price for this pool (setTwapTracked), 0 otherwise. The RA/TAZ reference pool the lending protocol prices with is tracked (pool 33 on mainnet, saturndexadapt.getReferencePool()).

const tracked = await readContract("saturnpools", "getTwapTracked", [33]); // 1 on mainnet

getTwapCumulativeA(poolId: number): number

Accumulated price of token A in token B, Uniswap-v2 style: the sum of (reserveB × getTwapScale() / reserveA) × the seconds each price held, up to now (the interval since the last reserve write is added at the current reserves, so no write is needed to read it). Two readings c1 at t1 and c2 at t2 give the average price (c2 − c1) / (t2 − t1), scaled by 10^18. Several reserve writes in one block add zero weight, so a swap in and back inside one transaction does not move the average.

const c1 = BigInt(await readContract("saturnpools", "getTwapCumulativeA", [poolId]));
const t1 = Math.floor(Date.now() / 1000);
// ... at least a few minutes later
const c2 = BigInt(await readContract("saturnpools", "getTwapCumulativeA", [poolId]));
const t2 = Math.floor(Date.now() / 1000);
const avgBperA = Number((c2 - c1) / BigInt(t2 - t1)) / 1e18; // wall-clock seconds approximate chain time

getTwapCumulativeB(poolId: number): number

The same accumulator for the price of token B in token A (reserveA × 10^18 / reserveB, times seconds).

const cB = await readContract("saturnpools", "getTwapCumulativeB", [poolId]);

getTwapSince(poolId: number): number

Unix time the current unbroken price series started: when tracking started, or the last reserve write that found a side empty (a hole). While a side is empty it reports the current time. 0 while the pool is not tracked. If it is later than your first reading, discard that reading: the average would span a stop or a hole.

const since = await readContract("saturnpools", "getTwapSince", [poolId]);

getTwapLastUpdate(poolId: number): number

Unix time the pool's accumulators were last written (its last reserve write while tracked, or when tracking started).

const last = await readContract("saturnpools", "getTwapLastUpdate", [poolId]);

getTwapScale(): number

The scale of every TWAP price: 10^18.

const scale = await readContract("saturnpools", "getTwapScale", []);

getPoolWithdrawable(poolId: number): number

1 when the provider could withdraw the pool today (liquidity not burned and no live time lock: now ≥ getPoolLockUntil), 0 otherwise. Burns and time locks are made through saturnlplock (burnPool, lockPool). A pool reading 0 cannot be pledged as loan collateral; the lending reference pool must read 0.

const canPull = (await readContract("saturnpools", "getPoolWithdrawable", [poolId])) === 1;

getPoolBurned(poolId: number): number

1 when the pool's liquidity was burned through saturnlplock.burnPool: removePool refuses it forever ("Pool liquidity is burned - it can never be withdrawn"), the provider can only lower its fee, and the SATURN certificate becomes the pool's fee key (saturnfees pays the provider fees to its holder, and it cannot be destroyed). Swaps continue. 0 otherwise. A burn cannot be undone.

const burned = await readContract("saturnpools", "getPoolBurned", [poolId]);

getPoolLockUntil(poolId: number): number

Unix time until which the pool's liquidity is time-locked through saturnlplock.lockPool (0 = never locked). removePool refuses the pool until then with "Pool liquidity is time-locked until <unix>". A live lock can only be extended, never shortened.

const until = await readContract("saturnpools", "getPoolLockUntil", [poolId]);

getNftPoolId(nftId: number): number

Reverse of getPoolNftId: the pool a SATURN certificate id belongs to. 0 when unknown (certificates minted before the reverse map existed are filled in by claimPoolProvider or a burn).

const poolId = await readContract("saturnpools", "getNftPoolId", [nftId]);

claimPoolProvider(from: address, poolId: number)

The holder of a pool's SATURN certificate takes the provider role. Needed for pools whose certificate moved before 4.1.10 (when the provider did not follow the certificate); since 4.1.10 every certificate transfer does this automatically. Also records the certificate id to pool id map. Refused while the pool is pledged to a loan, under a bond, rental or fee option, or enrolled in a reward campaign.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnpools", "claimPoolProvider", [from, poolId])
  .spendGas(from)
  .endScript();
// sign with the certificate holder's wallet and send

skim(to: address, tokentoskim: string)

DISABLED — always reverts with "skim disabled (F-08): shared-custody reconciliation removed - cannot distinguish stranded tokens from module-owned funds". Kept in the ABI for compatibility.

updatePoolFee(from: address, poolId: number, newFeePer10k: number)

Lets the pool provider change their pool's per-swap fee. The new fee must lie inside the protocol range (getMinPoolFeePer10k .. getMaxPoolFeePer10k, 30–3000 per 10k by default) and the pool must be free of locks: no active reward-campaign enrollment and no financial product (bond, rental, option, syndicate, launchpad or loan collateral). While a rental or fee option is live the fee is driven by saturnrental / saturnfeeopts, which call this method on the operator's behalf — a direct call from the provider, even one who owns the rental listing, is refused until the product ends.

// Move the pool fee to 0.5%
const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnpools", "updatePoolFee", [from, poolId, 50])
  .spendGas(from)
  .endScript();
// sign with the caller's wallet and send

pawnPool(from: address, poolId: number)

DEPRECATED — always reverts with "Deprecated in 4.1.0: pawn functionality moved to a dedicated contract". Kept in the ABI for compatibility; there is nothing to call here. A pool is pledged to a loan through saturnmarket.acceptQuote, after which getPoolPawned() reads 1.

unpawnPool(from: address, poolId: number)

DEPRECATED — always reverts with "Deprecated in 4.1.0: pawn functionality moved to a dedicated contract". Kept in the ABI for compatibility; there is nothing to call here. A loan pledge is released by the full repayment (saturnloans.makePayment) or handed to the lender on liquidation / default.

clearScaleFactor(symbol: string)

Admin only. The saturnpools _owner (the owner address set when the contract was deployed, not the saturnadmin getAdmin() check) must sign. Sets the cached scale factor and divisor of symbol back to 0. Until computeAndStoreScaleFactor runs again (every swap, pool creation and liquidity add calls it), scaleUp and scaleDown return amounts unchanged and getMinRawForToken returns saturnadmin.getAbsoluteMinRaw. Token decimals never change, so a recompute normally stores the same pair. The exception is a legacy entry (factor set, divisor 0) for a token with more than 8 decimals: it is recomputed with a divisor of 10^(decimals - 8) instead of the identity it used before. Its stored reserves are not rewritten, so they, and any open saturnloans loan in that token, are then read off by that factor. Use it only when no loan is open in the symbol and the reserves are migrated in the same transaction.

setTwapTracked(poolId: number, tracked: number)

Admin only. The saturnadmin owner (saturnadmin.getAdmin()) must sign. tracked = 1 starts the time-weighted price of an active pool: getTwapLastUpdate and getTwapSince are set to now and the accumulators keep their values. Starting a pool that is already tracked changes nothing. tracked = 0 first brings the accumulators up to now at the current reserves, then freezes them and sets getTwapSince to 0. Stopping a pool that is not tracked changes nothing. Each change emits PoolLockChanged(poolId, tracked, "twap").

registerPool(from: address, token0Symbol: string, token1Symbol: string, scaledAmount0: number, scaledAmount1: number, customFeePer10k: number): number

Internal: only saturnliquidity (createPool), saturnsyndicate or saturnlaunchpad can call this. Creates the pool record: takes the next pool id, records from as provider, stores the pair and the opening reserves (8-decimal scaled), marks the pool active and sets its fee per 10,000. It also adds the pool to the pair index (getPairPoolCount / getPairPoolAtIndex) and to getAllPoolIds, adds the reserves to the global per-token totals (getReserveValue), appends a token to getTokensInDEXList when its global total was 0 and a pair to getPairsInDEXList when it had no pool yet, and emits PoolRegistered. The caller moves the tokens; this method moves none.

addReserves(poolId: number, scaledAddA: number, scaledAddB: number)

Internal: only saturnliquidity (addLiquidity) can call this. Adds scaledAddA and scaledAddB (8-decimal scaled) to the pool's reserves and to the global per-token totals, brings the TWAP up to date first if the pool is tracked, and emits PoolReservesChanged with reason "addLiquidity". The caller checks the pool and the provider and moves the tokens.

setReservesAfterSwap(poolId: number, newResA: number, newResB: number, tokenIn: string, tokenOut: string, scaledInDelta: number, scaledOutDelta: number)

Internal: only saturnswap can call this. Writes the pool's new reserves after a swap (8-decimal scaled), adds scaledInDelta to the global total of tokenIn and takes scaledOutDelta from the total of tokenOut, brings the TWAP up to date first if the pool is tracked, and emits PoolReservesChanged with reason "swap". tokenIn and tokenOut must be the pool's own pair, in either order.

clearPoolReserves(poolId: number)

Internal: only saturnliquidity (removePool), saturnsyndicate or saturnlaunchpad can call this. It is the one gate every pool withdrawal passes. It refuses a pledged, burned or still time-locked pool, and a pool with any financial or campaign lock. It checks that converting each reserve back to raw units loses no more than saturnadmin.getMaxTruncationPercent, subtracts the reserves from the global per-token totals, sets both reserves to 0 and the pool inactive, and emits PoolCleared. The caller sends the tokens out.

incrementCampaignLock(poolId: number)

Internal: only saturnrewards can call this, from enrollInCampaign. Adds 1 to the pool's campaign lock count (getPoolCampaignLockCount) and emits PoolLockChanged(poolId, newCount, "campaign"). While the count is above 0 the provider cannot change the fee, remove the pool or move its certificate.

decrementCampaignLock(poolId: number)

Internal: only saturnrewards can call this, from claimCampaignReward and withdrawFromCampaign. Takes 1 off the pool's campaign lock count and emits PoolLockChanged(poolId, newCount, "campaign"). At 0 it does nothing and does not revert.

incrementFinancialLock(poolId: number)

Internal: only saturnbonds, saturnrental, saturnfeeopts, saturnsyndicate or saturnlaunchpad can call this, when a financial product takes the pool. Adds 1 to the pool's financial lock count (getPoolFinancialLockCount) and emits PoolLockChanged(poolId, newCount, "financial"). While the count is above 0 the provider cannot change the fee, remove the pool or move its certificate. saturndexadapt is not on this list since 4.1.8: lending locks a pool only through pledgePool.

decrementFinancialLock(poolId: number)

Internal: only saturnbonds, saturnrental, saturnfeeopts, saturnsyndicate or saturnlaunchpad can call this, when their product ends. Takes 1 off the pool's financial lock count and emits PoolLockChanged(poolId, newCount, "financial"). At 0 it does nothing. On a pledged pool it will not take the count below 1: that lock belongs to the pledge, and only releasePledge or handOverPledgedPool clears it.

setPoolNftId(poolId: number, nftId: number)

Internal: only the SATURN certificate contract can call this, from mintPoolCertificate when a pool is created. Records the certificate id on the pool (getPoolNftId) and the reverse map from certificate to pool (getNftPoolId). No event.

adminReduceReservesForMigration(poolId: number, scaledSubA: number, scaledSubB: number)

Internal: only saturnfees can call this, from its admin-only adminZeroAccumulatorForMigration (the saturnadmin owner signs there). That method zeroes a pool's legacy provider-fee claimable balances and passes the same amounts here, which takes scaledSubA and scaledSubB (8-decimal scaled) off the pool's reserves and the global per-token totals. A side passed as 0 is left alone. Brings the TWAP up to date first if the pool is tracked and emits PoolReservesChanged with reason "migration".

setPoolBurned(poolId: number)

Internal: only saturnlplock can call this, from burnPool. Marks the pool's liquidity burned for good (getPoolBurned = 1): clearPoolReserves refuses it forever, the provider can only lower the fee, and SATURN refuses to burn its certificate, which stays the fee key. Also records the certificate-to-pool map (getNftPoolId) and emits PoolLockChanged(poolId, 1, "burned"). The financial lock count is untouched, so bonds, rentals and fee options still work on a burned pool.

setPoolLockUntil(poolId: number, lockUntil: number)

Internal: only saturnlplock can call this, from lockPool. Sets the unix time (seconds) until which the pool's liquidity cannot be withdrawn (getPoolLockUntil); clearPoolReserves refuses the pool before then. saturnlplock only ever moves it later. Emits PoolLockChanged(poolId, lockUntil, "timelock").

pledgePool(poolId: number, owner: address)

Internal: only saturndexadapt can call this, from v4LockPool when saturnvault takes a borrower's v4 pool as loan collateral. owner must sign and be the pool's provider. The pool must be active, have a certificate and carry nothing: no pledge, no financial or campaign lock, not burned, no live time lock. Sets the financial lock count to exactly 1 and getPoolPawned to 1, and emits PoolLockChanged with lockType "financial", then "pledge". While pledged, the pool takes no other lock, burn, time lock or campaign and cannot be removed.

releasePledge(poolId: number)

Internal: only saturndexadapt can call this, from v4UnlockPool when saturnvault releases the collateral after full repayment. Clears the pledge (getPoolPawned = 0) and takes the financial lock count down by 1. It is lenient on the count, so a repayment is never blocked here. Emits PoolLockChanged with lockType "financial", then "unpledge".

handOverPledgedPool(poolId: number, newProvider: address)

Internal: only saturndexadapt can call this, from v4HandOverPool on a liquidation or default. Strict: the pool must be pledged, active and hold a financial lock count of exactly 1, so the lender never receives a pool another product still holds. Clears the pledge and the lock and makes newProvider (the lender) the provider; saturnvault sends the certificate in the same call. Emits PoolLockChanged with lockType "financial", then "handover".

followCertificate(poolId: number, holder: address)

Internal: only the SATURN certificate contract can call this. SATURN's onSend trigger calls it on every certificate transfer that neither starts nor ends at the lending vault, when getNftPoolId knows the certificate's pool (for an older certificate it does not, and the new holder runs claimPoolProvider instead). The new holder becomes the pool's provider (fee claims, fee changes, liquidity, removal). It refuses while the pool is pledged, under a bond, rental or fee option, or enrolled in a reward campaign, so the whole certificate transfer reverts with the strings below and an obligation never changes hands half way. A removed (inactive) pool is skipped, so its certificate moves freely. A change of provider emits PoolLockChanged(poolId, 0, "provider").

createPool(from: address, amountToken0: number, amountToken1: number, token0Symbol: string, token1Symbol: string, customFeePer10k: number)

Creates a brand new pool for a token pair. The caller sets the starting reserves and chooses the per-swap fee rate (in units of 1/10,000 — it must fall inside the protocol range). On success the pool is registered, the SATURN NFT certificate for this pool is minted to the caller, and the caller's tokens are transferred into protocol custody. Several pools can exist for the same pair, each with its own fee, which is why the router scores pools instead of assuming one per pair.

// Create a 0.3% fee SOUL/KCAL pool seeded with 100 SOUL and 100 KCAL
const minSoul = await readContract("saturnrouter", "getMinRawForPoolCreation", ["SOUL"]); // 10000000000
const minKcal = await readContract("saturnrouter", "getMinRawForPoolCreation", ["KCAL"]); // 1000000000000
const poolId = await readContract("saturnpools", "getNextPoolId", []); // expected id; confirm it in the PoolCreated event

const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit) // gasPrice × gasLimit must cover ~2,500 KCAL (certificate mint)
  .callContract("saturnliquidity", "createPool", [from,
    10000000000,     // amountToken0: 100 SOUL (8 decimals)
    1000000000000,   // amountToken1: 100 KCAL (10 decimals)
    "SOUL", "KCAL",
    30])             // customFeePer10k: 30 = 0.3%
  .spendGas(from)
  .endScript();
// sign with the caller's wallet and send; the wallet needs the two amounts plus ~2,500 KCAL gas

addLiquidity(from: address, poolId: number, amountTokenA: number, maxAmountTokenB: number)

Adds proportional liquidity to an existing pool. You specify exactly how much of token A you want to add; the contract calculates the matching amount of token B based on the current reserve ratio and deposits both. maxAmountTokenB is your slippage cap — the call reverts if the required B amount exceeds it. Token A is the pool's tokenA (saturnpools.getPoolTokenA), not whichever token you pick. Only the pool provider can add liquidity; since saturnpools 4.1.10 the provider follows the SATURN certificate. A burned or time-locked pool (saturnlplock) still accepts liquidity, and the added tokens fall under the same terms: on a burned pool they can never be withdrawn, and on a time-locked pool not before the lock ends.

// Project the token B amount from the live reserves (8-decimal scaled; use BigInt)
const tokenA = await readContract("saturnpools", "getPoolTokenA", [poolId]);
const tokenB = await readContract("saturnpools", "getPoolTokenB", [poolId]);
const resA = BigInt(await readContract("saturnpools", "getPoolReserveA", [poolId]));
const resB = BigInt(await readContract("saturnpools", "getPoolReserveB", [poolId]));
const amountA = 1000000000n; // raw tokenA, e.g. 10 SOUL (8 decimals)
const scaledA = BigInt(await readContract("saturnpools", "scaleUp", [amountA, tokenA]));
const needB = BigInt(await readContract("saturnpools", "scaleDown", [scaledA * resB / resA, tokenB]));
const maxB = needB * 101n / 100n; // accept 1% price movement

const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnliquidity", "addLiquidity", [from, poolId,
    amountA,   // amountTokenA: raw units of the pool's tokenA
    maxB])     // maxAmountTokenB: raw tokenB cap, reverts "Exceeds max: N" above it
  .spendGas(from)
  .endScript();
// sign with the caller's wallet and send

removePool(from: address, poolId: number)

Removes a pool entirely. Both reserves are paid out in raw units together with the pool's pending provider fees, the pool is deactivated, and its SATURN certificate is burned if the caller holds it (otherwise the certificate is left alone). The caller must hold the pool's SATURN certificate or be its provider (saturnpools.getPoolProvider). Since saturnpools 4.1.10 a certificate transfer also makes the new holder the provider, so a seller loses the right to remove the pool; the provider route remains so a pool whose certificate was destroyed can still be withdrawn. The pool cannot be removed while it is enrolled in a reward campaign, held by any financial product (bond, rental, fee option, syndicate, launchpad or loan pledge), or burned or time-locked through saturnlplock.

// Pre-flight: removePool reverts while any of these blocks it
const withdrawable = await readContract("saturnpools", "getPoolWithdrawable", [poolId]); // 0 = burned or time-locked
const campLocks = await readContract("saturnpools", "getPoolCampaignLockCount", [poolId]);
const finLocks = await readContract("saturnpools", "getPoolFinancialLockCount", [poolId]); // bond, rental, option, syndicate, launchpad, loan pledge
if (Number(withdrawable) !== 1 || Number(campLocks) > 0 || Number(finLocks) > 0) throw new Error("Pool not removable yet");

const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnliquidity", "removePool", [from, poolId])
  .spendGas(from)
  .endScript();
// sign with the caller's wallet and send; reserves plus pending provider fees come back in raw units

getLiquidityAddress(): address

Returns the custody address that holds every pool's reserves, the unclaimed provider fees and the holder-reward slices; saturnflash borrows from this same balance (saturnflash.getMaxBorrowable reads it). Other contracts transfer tokens here before calling swapFromContract(); a frontend can use it to show total value locked per token.

const custody = await readContract("saturnliquidity", "getLiquidityAddress", []);

getContractTokenBalanceEach(tokenSymbol: string): number

Raw on-chain balance of one token held in custody by this contract: every v4 pool's reserve in that token (including syndicate, launchpad and saturnclpools positions), plus provider fees and holder rewards not yet claimed. Compare it with the sum of getPoolReserveA/B (scaled down) plus pending fees to reconcile an indexer.

const tvlSoul = await readContract("saturnliquidity", "getContractTokenBalanceEach", ["SOUL"]);

getContractVersion(): string

Returns the deployed build tag of this contract. The mainnet and devnet deployments documented here report "saturnliquidity-4.3.3". Compare it against the value you developed against before trusting method semantics after an upgrade.

const v = await readContract("saturnliquidity", "getContractVersion", []);
// "saturnliquidity-4.3.3"

sendTokensOut(to: address, tokenSymbol: string, amount: number)

Internal: only saturnswap, saturnfees, saturnpools, saturnsyndicate, saturnlaunchpad, saturnclpools, saturnflash and saturnholders can call this. Pays amount raw units of tokenSymbol out of custody (the shared balance behind every pool) to `to`. The calling contract does the accounting: swap output and admin fees, fee claims, holder rewards, flash loans, concentrated-pool, syndicate and launchpad withdrawals.

receiveSwapInputV3(from: address, tokenIn: string, reinvestAmount: number, providerFeeAmount: number, holderFeeAmount: number, adminFeeAmount: number)

Internal: only saturnswap can call this. Collects the input of a user-signed swap: moves reinvestAmount + providerFeeAmount + holderFeeAmount of tokenIn (raw) from `from` into custody, and adminFeeAmount straight to the saturnadmin.getAdmin() wallet.

receiveSwapInputV2(from: address, tokenIn: string, reinvestAmount: number, providerFeeAmount: number, adminFeeAmount: number)

Internal: only saturnswap can call this. Legacy 3-amount form of receiveSwapInputV3 (no holder slice): moves reinvestAmount + providerFeeAmount of tokenIn (raw) from `from` into custody and adminFeeAmount to the saturnadmin.getAdmin() wallet. saturnswap-4.4.3 always calls receiveSwapInputV3.

receiveSwapInput(from: address, tokenIn: string, poolAmount: number, adminFeeAmount: number)

DEPRECATED — always reverts with "Deprecated in 4.1.0: swap engine must call receiveSwapInputV2 or V3", for every caller. Kept in the ABI for upgrade compatibility.

swap(from: address, poolId: number, amountIn: number, tokenIn: string, tokenOut: string, minAmountOut: number): number

Executes a swap against a specific pool. The caller sends amountIn of tokenIn; the output is the constant-product amount for amountIn minus the whole pool fee, computed in 8-decimal scaled units with integer division, and tokenOut is sent to the caller. The fee is then split: provider 10% (claimable in saturnfees), admin 20% (sent to the admin wallet), holders 10% (only when tokenIn has stakers in saturnholders) and the rest added to the pool's reserve (saturnadmin.getFeeSplitRatios). Set minAmountOut to protect against slippage (pass 0 to disable the check). Always query SaturnRouter first to find the best pool for a pair — passing a sub-optimal poolId here won't revert but will give you a worse rate.

// 1) Find the best pool for SOUL→KCAL (scan up to 20 pools of the pair)
const poolId = await readContract("saturnrouter", "getBestPoolForSwapV2", ["SOUL", "KCAL", amountIn, 20]);
if (poolId === 0) throw new Error("No liquidity available");

// 2) Quote exactly like the engine: 8-decimal scaled units, integer division
const info = await readContract("saturnrouter", "getPoolFullInfo", [poolId]);
const f = Object.fromEntries(info.split("_").map((p) => p.split(":")));
const inIsA = f.tokenA === "SOUL";
const rIn = BigInt(inIsA ? f.resA : f.resB), rOut = BigInt(inIsA ? f.resB : f.resA);
const sIn = BigInt(await readContract("saturnpools", "scaleUp", [amountIn, "SOUL"]));
const afterFee = sIn - (sIn * BigInt(f.fee)) / 10000n;
const sOut = (afterFee * rOut) / (rIn + afterFee);
const expectedOut = BigInt(await readContract("saturnpools", "scaleDown", [Number(sOut), "KCAL"]));
const minOut = Number((expectedOut * 99n) / 100n); // 1% slippage, raw KCAL

// 3) Submit the swap
const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit) // up to 0.2 KCAL; one swap burns about 0.05 KCAL and the rest is refunded
  .callContract("saturnswap", "swap", [from, poolId, amountIn, "SOUL", "KCAL", minOut])
  .spendGas(from)
  .endScript();

getContractAddress(): address

Returns the on-chain address of the SaturnSwap contract. The swap engine never holds tokens: swap inputs, reserves and unclaimed fees all sit at saturnliquidity.getLiquidityAddress(), and the contracts allowed to call swapFromContract() transfer their input there, not here. Useful mainly to identify saturnswap in transaction traces.

const swapAddr = await readContract("saturnswap", "getContractAddress", []);
// token balances live at saturnliquidity.getLiquidityAddress(), not here

getContractVersion(): string

Returns the deployed build tag of this contract. The mainnet and devnet deployments documented here report "saturnswap-4.4.3". Compare it against the value you developed against before trusting method semantics after an upgrade.

const v = await readContract("saturnswap", "getContractVersion", []);
// "saturnswap-4.4.3"

swapFromContract(poolId: number, amountIn: number, tokenIn: string, tokenOut: string, minAmountOut: number, recipient: address): number

Internal: only saturnlimit, saturnarb, saturnflash, saturnstakearb, saturnvaults or saturntwamm can call this. The contract path of swap(): the same exact-pair check, minimum swap size, fee split and constant-product math, but no signer. The calling contract must first transfer amountIn of tokenIn to saturnliquidity.getLiquidityAddress(); this method pulls nothing and does not check that the input arrived. From that input the admin fee is sent to the admin wallet, the provider fee is accrued in saturnfees, the holder slice is accrued in saturnholders (only when tokenIn has stakers; otherwise it stays in the pool), the rest is added to the reserve, and tokenOut is sent to recipient. The reentrancy guard is held on recipient for the call. Emits ContractSwapExecuted.

claimProviderFees(from: address, poolId: number)

Sweeps all pending provider fees of a pool, both tokens at once, to the caller. Pending balances are scaled down to raw units and paid out of saturnliquidity custody. Who may claim: for a normal pool, its provider (saturnpools.getPoolProvider, which follows the SATURN certificate since saturnpools 4.1.10); since saturnfees-4.1.3, for a burned pool (saturnlplock), only the current holder of its SATURN certificate, the pool's fee key. The call reverts while a fee redirect is active (a bond or rental owns the fee stream).

// Check claimable on both sides before claiming
const tokenA = await readContract("saturnpools", "getPoolTokenA", [poolId]);
const tokenB = await readContract("saturnpools", "getPoolTokenB", [poolId]);
const pA = await readContract("saturnfees", "getProviderClaimable", [poolId, tokenA]);
const pB = await readContract("saturnfees", "getProviderClaimable", [poolId, tokenB]);

if (BigInt(pA) > 0n || BigInt(pB) > 0n) {
  const tx = ScriptBuilder
    .begin()
    .allowGas(from, null, gasPrice, gasLimit)
    .callContract("saturnfees", "claimProviderFees", [from, poolId])
    .spendGas(from)
    .endScript();
  // sign with the caller's wallet and send
}

getProviderClaimable(poolId: number, tokenSymbol: string): number

Returns the pending provider fee of one token of a pool, in 8-decimal scaled units. It is claimable by the pool's provider, by the certificate holder of a burned pool, or by the bond/rental contract while a redirect is active. Call this once for tokenA and once for tokenB (or use getProviderClaimablePair()). Apply saturnpools.scaleDown() before showing the number to users.

const scaled = await readContract("saturnfees", "getProviderClaimable", [poolId, "SOUL"]);
const raw = await readContract("saturnpools", "scaleDown", [scaled, "SOUL"]);

getFeeRedirectActive(poolId: number): number

Returns 1 if the pool currently has a fee redirect active (the fee stream is owned by a bond or rental), 0 otherwise. Use this to disable the "Claim Fees" button in your UI and show the right explanation to the provider.

const redirected = await readContract("saturnfees", "getFeeRedirectActive", [poolId]);
if (redirected === 1) {
  // UI: "Fees are currently being earned by a bond/rental holder"
}

getProviderClaimablePair(poolId: number): string

Both pending provider balances of a pool in one call, packed as "tokenA:<sym>_pendingA:<n>_tokenB:<sym>_pendingB:<n>". Amounts are in scaled (8-decimal) units — pass them through saturnpools.scaleDown() to display raw token amounts.

const s = await readContract("saturnfees", "getProviderClaimablePair", [poolId]);
const f = Object.fromEntries(s.split("_").map((kv) => kv.split(":")));
// f.tokenA, f.pendingA, f.tokenB, f.pendingB

getProviderLifetimeFees(poolId: number, tokenSymbol: string): number

Cumulative provider fees accrued to a pool in one token since saturnfees-4.1.2 added the counter (fees from before that build are not counted), in 8-decimal scaled units. Unlike getProviderClaimable() it is never reduced by claims or redirects, so it is the right number for "fees earned to date" statistics and for the lifetime-fee metric that saturnpredict markets settle on.

const lifetime = await readContract("saturnfees", "getProviderLifetimeFees", [poolId, "SOUL"]);

getFeeRedirectContract(poolId: number): string

Name of the contract that owns (or last owned) the pool's provider-fee redirect: "saturnbonds" or "saturnrental", the only callers setFeeRedirect accepts. Empty string if no redirect was ever set. Syndicate and launchpad pools are not redirects: those contracts are the pool's provider. Read it together with getFeeRedirectActive() to explain to a provider why claimProviderFees() is refused.

const owner = await readContract("saturnfees", "getFeeRedirectContract", [poolId]);

getContractVersion(): string

Returns the deployed build tag of this contract. The mainnet and devnet deployments documented here report "saturnfees-4.1.3". Compare it against the value you developed against before trusting method semantics after an upgrade.

const v = await readContract("saturnfees", "getContractVersion", []);
// "saturnfees-4.1.3"

accrueProviderFee(poolId: number, tokenIn: string, scaledProviderFee: number)

Internal: only saturnswap can call this. Credits a swap's provider fee (8-decimal scaled) to the pool's pending balance for tokenIn (getProviderClaimable) and to its lifetime counter (getProviderLifetimeFees).

setFeeRedirect(poolId: number, active: number)

Internal: only saturnbonds or saturnrental can call this. active = 1 hands the pool's provider-fee stream to the calling contract (bond purchase, rental start); any other value turns it off again (bond settlement, rental end). While it is on, claimProviderFees reverts.

claimRedirectedFees(poolId: number, tokenSymbol: string, recipient: address): number

Internal: only the contract that owns the pool's active fee redirect (saturnbonds or saturnrental) can call this. Pays the pool's pending provider fee in tokenSymbol to recipient: scales it down to raw units, zeroes it, and sends it out of saturnliquidity custody.

claimProviderFeesForContract(providerContract: address, poolId: number)

Internal: only saturnsyndicate or saturnlaunchpad can call this. Claims both sides of a pool whose provider is that contract (a contract cannot sign as a wallet witness): zeroes the pending balances and sends the raw amounts to providerContract.

claimAndReturnFees(poolId: number, tokenSymbol: string): number

Internal: only saturnliquidity can call this (removePool). Zeroes the pool's pending provider fee in tokenSymbol and returns it in raw units without moving tokens; removePool adds it to the payout.

adminZeroAccumulatorForMigration(poolId: number)

Admin only. Only the protocol admin (saturnadmin.getAdmin()) can call this. Migration tool for legacy pools whose pending provider fees were also counted in their reserves: zeroes both pending balances of the pool and subtracts the same scaled amounts from its reserves (saturnpools.adminReduceReservesForMigration). The lifetime counter is not touched.

getTotalNftMinted(): number

Certificates minted by createPool() minus those burned by removePool(). It matches the number of active certificate-bearing pools (20 on mainnet today) unless a pool was removed while its certificate was held elsewhere or had already been burned by its holder; those removals are not subtracted. Syndicate and launchpad pools have no certificate and are not counted.

const certificates = await readContract("SATURN", "getTotalNftMinted", []);

getUserPools(from: address): number*

Generator yielding every SATURN NFT token ID currently owned by the given address. Each token ID maps to one pool: saturnpools.getNftPoolId(nftId) gives the poolId, or read the NFT's properties (poolId, tokenA, tokenB, name) through the RPC getNFT call. Token IDs are 256-bit numbers (up to 78 digits); keep them as strings or BigInt, since a JavaScript Number loses precision (getUserPoolsData() returns them as strings). While a pool backs a loan, its certificate sits in the lending vault (saturnvault) and is not listed for the borrower.

const nftIds = await readContract("SATURN", "getUserPools", [userAddress]); // decode as BigInt, not Number
for (const nftId of nftIds) {
  const poolId = await readContract("saturnpools", "getNftPoolId", [nftId]); // 0 = unknown
  const nft = await api.getNFT("SATURN", String(nftId), true);
  const props = Object.fromEntries(nft.properties.map((p) => [p.key, p.value]));
  console.log("Pool #" + poolId, props.tokenA + "/" + props.tokenB, props.name);
}

holdsPoolCertificate(from: address, poolId: number): number

Returns 1 if `from` currently owns the SATURN NFT that certifies pool `poolId`, 0 otherwise, including when the pool never had a certificate (unknown poolId, or a syndicate / launchpad pool). A removed pool keeps its certificate id, so if that certificate was not burned its holder still gets 1: check saturnpools.getPoolActive too. removePool(), saturnfees (burned pools), saturnlplock and the lending adapter use this check. Since saturnpools 4.1.10 the provider normally equals the holder. The exceptions are a pledged pool, whose certificate the lending vault holds while the borrower stays provider, and a certificate with no getNftPoolId entry that moved without claimPoolProvider.

const isOwner = await readContract("SATURN", "holdsPoolCertificate", [userAddress, poolId]);

getUserPoolsData(from: address): string*

Generator variant of getUserPools() that yields each owned SATURN NFT id as a decimal string row (one id per row), so the 256-bit ids arrive without precision loss. Handy for clients that already consume the pipe-delimited *Data feeds elsewhere. Resolve each id to its pool via the NFT's ROM (poolId, tokenA, tokenB fields) exactly as with getUserPools().

const nftIds = await readContract("SATURN", "getUserPoolsData", [userAddress]);

getContractVersion(): string

Returns the deployed build tag of this contract. The mainnet and devnet deployments documented here report "saturnnft-4.1.5". Compare it against the value you developed against before trusting method semantics after an upgrade.

const v = await readContract("SATURN", "getContractVersion", []);
// "saturnnft-4.1.5"

getName(): string

Token name property of the SATURN certificate contract.

const v = await readContract("SATURN", "getName", []);
// "Saturn Pool NFT"

getSymbol(): string

Token symbol property. Use it ("SATURN") with the RPC getNFT / getTokenBalance calls.

const v = await readContract("SATURN", "getSymbol", []);
// "SATURN"

isTransferable(): bool

true: certificates can be sent with the standard Phantasma NFT transfer. Since saturnnft-4.1.5 a transfer also moves the pool's provider role to the receiver, and it reverts while the pool carries a bond, rental, fee option or reward campaign (see the contract description).

const v = await readContract("SATURN", "isTransferable", []);
// true

isFungible(): bool

false: every certificate is a unique NFT tied to one pool.

const v = await readContract("SATURN", "isFungible", []);
// false

isBurnable(): bool

true: a holder can burn a certificate directly, except the certificate of a burned pool (saturnlplock), whose burn reverts with "This certificate is the fee key of a burned pool and cannot be destroyed". Burning a live pool's certificate does not remove the pool: its provider keeps it, and removePool still works through the provider.

const v = await readContract("SATURN", "isBurnable", []);
// true

getMaxSupply(): number

Token-wide supply cap: 0, meaning no cap. Each certificate is minted in its own series with a max supply of 1.

const v = await readContract("SATURN", "getMaxSupply", []);
// 0

getOwner(): address

Owner of the SATURN token contract: the wallet allowed to upgrade it (onUpgrade) and to infuse certificates (onInfuse). Today it is the same wallet as saturnadmin.getAdmin() on mainnet and devnet, but it is stored separately: saturnadmin.updateAdmin does not change it.

const owner = await readContract("SATURN", "getOwner", []);

mintPoolCertificate(from: address, poolId: number, tokenA: string, tokenB: string)

Internal: only saturnliquidity can call this (createPool). Creates a new series with max supply 1 and mints one certificate to `from`. ROM: name "Saturn v4.1 - Pool #<poolId> <tokenA>/<tokenB> - <rarity>", the ownership description, poolId, tokenA, tokenB, imageURL, infoURL, royalties 0. Records the id both ways in saturnpools (setPoolNftId: getPoolNftId / getNftPoolId) and adds 1 to getTotalNftMinted().

burnPoolCertificate(from: address, poolId: number)

Internal: only saturnliquidity can call this (removePool). Burns the pool's certificate if `from` holds it and subtracts 1 from getTotalNftMinted(); if the certificate is elsewhere or already gone it does nothing, so removal never gets stuck on it.

createCampaign(from: address, tokenA: string, tokenB: string, rewardToken: string, rewardAmount: number, durationSeconds: number)

Creates a new reward campaign targeting a specific token pair. The full rewardAmount of rewardToken is transferred up front from the creator's wallet into the contract, and will be distributed proportionally to pools that enroll during the campaign window.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnrewards", "createCampaign",
    [from, "SOUL", "KCAL", "SOUL",
      1000000000,   // rewardAmount: 10 SOUL (8 decimals)
      7 * 86400])   // durationSeconds: 7 days
  .spendGas(from)
  .endScript();

enrollInCampaign(from: address, poolId: number, campaignId: number)

Called by a pool provider to enroll their pool in an active campaign. The pool's current scaled liquidity is snapshot and multiplied by the seconds remaining until the campaign's end time; that liquidity-seconds weight is added to the campaign's total and fixes the provider's share — later changes to the pool's depth do not matter, but enrolling earlier earns more. Enrollment locks the pool (cannot change fee, cannot remove) until the reward is claimed or the pool withdraws. A pool that is under a financial product (bond, rental, option, syndicate, launchpad or loan collateral) cannot enroll.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnrewards", "enrollInCampaign", [from, poolId, campaignId])
  .spendGas(from)
  .endScript();

claimCampaignReward(from: address, poolId: number, campaignId: number)

Called after the campaign's end time. Pays the provider's share of the reward pot: share = poolWeight × totalReward / totalLocked, in raw reward units, rounded down. poolWeight and totalLocked are the liquidity-seconds from getPoolCampaignLiquidity() and getCampaignTotalLocked(). The share is capped at what is still unclaimed (totalReward − getCampaignRewardClaimed()). The claim then removes this campaign's lock from the pool. Each enrollment settles once (4.1.5): the claim is recorded even when the capped share is 0, so it cannot be repeated. After endCampaign() nothing is left, so a late claim pays 0 (it still removes the lock); withdrawFromCampaign() is the cleaner way to unlock the pool.

const expected = await readContract("saturnrewards", "getExpectedReward", [poolId, campaignId]);
const active = await readContract("saturnrewards", "getCampaignActive", [campaignId]);
const paid = await readContract("saturnrewards", "getPoolCampaignClaimed", [poolId, campaignId]);
// active 0 = endCampaign() ran and the pot is empty: call withdrawFromCampaign() instead
if (expected > 0 && active == 1 && paid == 0) {
  const tx = ScriptBuilder
    .begin()
    .allowGas(from, null, gasPrice, gasLimit)
    .callContract("saturnrewards", "claimCampaignReward", [from, poolId, campaignId])
    .spendGas(from)
    .endScript();
}

withdrawFromCampaign(from: address, poolId: number, campaignId: number)

Unenrolls the pool and removes this campaign's lock at once. It forfeits the pool's share: its weight is subtracted from getCampaignTotalLocked(), so the pools that remain split the pot. There is no time check: it works before or after the end time, and after endCampaign() it is the clean way to unlock a pool that never claimed (a late claim pays 0). Not allowed once the pool has claimed. While the campaign is still running the pool may enroll again, with a new weight based on its liquidity and the time left.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnrewards", "withdrawFromCampaign", [from, poolId, campaignId])
  .spendGas(from)
  .endScript();

endCampaign(from: address, campaignId: number)

Called by the campaign creator at least 30 days (2,592,000 s) after the end time. Marks the campaign inactive, sets getCampaignRewardClaimed() to the full reward total, removes the id from getAllCampaignIds() / getActiveCampaignIds(), and sends the unclaimed remainder (totalReward − claimed, raw units) to the creator. Pools that never claimed keep their campaign lock until the provider calls withdrawFromCampaign() or claims (the claim pays 0).

const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnrewards", "endCampaign", [from, campaignId])
  .spendGas(from)
  .endScript();

getCampaignInfo(campaignId: number): string

Returns a single packed string with every top-level field of a campaign. Cheap to render — one round-trip instead of eight. Do not split on every underscore: the pair key contains one ("KCAL_SOUL"). Split on the "_<label>:" markers instead. locked is in liquidity-seconds.

const info = await readContract("saturnrewards", "getCampaignInfo", [campaignId]);
// "pair:KCAL_SOUL_reward:KCAL_total:10000000000000000_claimed:0_start:1790008570_end:1797784570_active:1_locked:53450098582043255861"
const f = Object.fromEntries(info.split(/_(?=[a-z]+:)/).map((kv) => {
  const i = kv.indexOf(":");
  return [kv.slice(0, i), kv.slice(i + 1)];
}));
// f.pair = "KCAL_SOUL", f.total = "10000000000000000"

getCampaignActive(campaignId: number): number

Returns 1 if the campaign is still active, 0 if it has been ended by the creator.

const active = await readContract("saturnrewards", "getCampaignActive", [campaignId]);

getCampaignRewardToken(campaignId: number): string

Symbol of the token being distributed as the campaign reward.

const token = await readContract("saturnrewards", "getCampaignRewardToken", [campaignId]);

getCampaignRewardTotal(campaignId: number): number

Total reward amount that was escrowed at creation (raw units).

const total = await readContract("saturnrewards", "getCampaignRewardTotal", [campaignId]);

getCampaignTotalLocked(campaignId: number): number

Sum of the enrollment weights (liquidity-seconds) of every pool currently enrolled in the campaign. Divide a pool's getPoolCampaignLiquidity() by this to get its share.

const totalLiq = await readContract("saturnrewards", "getCampaignTotalLocked", [campaignId]);

getCampaignEndTime(campaignId: number): number

Unix timestamp (seconds) at which the campaign ends and providers can begin claiming.

const endTs = await readContract("saturnrewards", "getCampaignEndTime", [campaignId]);
const msLeft = Math.max(0, endTs * 1000 - Date.now());

getNextCampaignId(): number

The ID that will be assigned to the next campaign created.

const nextId = await readContract("saturnrewards", "getNextCampaignId", []);

getAllCampaignIds(): number*

Generator yielding the ids of campaigns that have not been ended. endCampaign() removes the id, so in practice it matches getActiveCampaignIds(). Walk 1 .. getNextCampaignId() − 1 to reach ended campaigns.

const script = ScriptBuilder
  .begin()
  .callContract("saturnrewards", "getAllCampaignIds", [])
  .endScript();

getCampaignCreator(campaignId: number): address

Wallet that funded the campaign — the only address allowed to call endCampaign().

const creator = await readContract("saturnrewards", "getCampaignCreator", [campaignId]);

getCampaignRewardClaimed(campaignId: number): number

Raw amount of the reward token paid out to providers so far. When the creator ends the campaign the value is set to the full reward total (the unclaimed remainder went back to the creator).

const claimed = await readContract("saturnrewards", "getCampaignRewardClaimed", [campaignId]);

getCampaignStartTime(campaignId: number): number

Unix timestamp at which the campaign was created; enrollment weights are measured against the window between now and getCampaignEndTime().

const start = await readContract("saturnrewards", "getCampaignStartTime", [campaignId]);

getCampaignPairKey(campaignId: number): string

Canonical pair key ("A_B", tokens sorted) the campaign rewards. Pools whose saturnpools.getPoolPairKey() equals it are eligible to enroll.

const pairKey = await readContract("saturnrewards", "getCampaignPairKey", [campaignId]);

getActiveCampaignIds(): number*

Yields the ids of campaigns whose active flag is still 1 (not yet ended by the creator). Note that a campaign past its end time stays active until endCampaign() is called, so check getCampaignEndTime() to separate "enrollable" from "claimable".

const ids = await readContract("saturnrewards", "getActiveCampaignIds", []);

getActiveCampaignsData(): string*

One pipe-delimited row per active campaign: campaignId|pairKey|rewardToken|rewardTotal|rewardClaimed|startTime|endTime|active|totalLocked. totalLocked is the liquidity-seconds sum. Builds a campaigns table in one round-trip.

const rows = await readContract("saturnrewards", "getActiveCampaignsData", []);
// "2|KCAL_SOUL|SOUL|100000000000|0|1757700000|1760292000|1|0"

getContractVersion(): string

Returns the deployed build tag of this contract. The mainnet and devnet deployments documented here report "saturnrewards-4.1.5". Compare it against the value you developed against before trusting method semantics after an upgrade.

const v = await readContract("saturnrewards", "getContractVersion", []);
// "saturnrewards-4.1.5"

getPoolEnrolledInCampaign(poolId: number, campaignId: number): number

Returns 1 if the pool is currently enrolled in the given campaign, 0 otherwise.

const enrolled = await readContract("saturnrewards", "getPoolEnrolledInCampaign", [poolId, campaignId]);

getPoolCampaignLiquidity(poolId: number, campaignId: number): number

Returns the enrollment weight of this pool: its scaled liquidity at enrollment multiplied by the seconds that remained in the campaign (liquidity-seconds). This is the weight used in the proportional reward calculation — it does NOT update as the pool's reserves change later.

const snap = await readContract("saturnrewards", "getPoolCampaignLiquidity", [poolId, campaignId]);

getPoolCampaignClaimed(poolId: number, campaignId: number): number

Returns the raw reward amount already claimed for this (pool, campaign) pair. Zero until the provider calls claimCampaignReward().

const claimed = await readContract("saturnrewards", "getPoolCampaignClaimed", [poolId, campaignId]);

getExpectedReward(poolId: number, campaignId: number): number

Computes poolWeight × totalReward / totalLocked in raw reward units, using the current totalLocked. The number will drift if other pools enroll or withdraw — always requery just before submitting a claim. It does not apply the claim's cap: it keeps returning the share after the pool has claimed, and after endCampaign(), when the real payout is 0.

const projected = await readContract("saturnrewards", "getExpectedReward", [poolId, campaignId]);

getBestPoolForSwapV2(tokenIn: string, tokenOut: string, amountIn: number, maxPools: number): number

Scans up to maxPools pools registered for the pair (in registration order) and returns the poolId that would give the highest net output for amountIn after that pool's fee. Inactive pools and pools with empty reserves score 0 and are skipped. This is the first call your swap flow should make — pass the result into SaturnSwap.swap(). It returns the pool id only, not the output: scoring uses the swap engine's math in 8-decimal scaled units, out = (in − in × fee / 10000) × reserveOut / (reserveIn + in − in × fee / 10000), so compute the amount yourself the same way. maxPools bounds the gas of the scan; pass getPoolCountForPair() to consider every pool (hard cap 100).

const count = await readContract("saturnrouter", "getPoolCountForPair", ["SOUL", "KCAL"]);
const poolId = await readContract("saturnrouter", "getBestPoolForSwapV2",
  ["SOUL", "KCAL", 10000000000, Math.max(1, Math.min(count, 100))]); // maxPools 0 reverts
if (poolId === 0) throw new Error("No liquidity available");

getBestPoolForSwap(tokenIn: string, tokenOut: string, amountIn: number): number

DEPRECATED — always reverts with "Deprecated in 4.1.0: use getBestPoolForSwapV2(tokenIn, tokenOut, amountIn, maxPools)". Kept in the ABI for compatibility only.

getPoolPrice(poolId: number, tokenIn: string): number

Returns the current spot price of tokenIn expressed in the other token of the pool. The result is scaled by 1e8 so you can divide by 100_000_000 on the client to get a floating-point ratio.

const scaled = await readContract("saturnrouter", "getPoolPrice", [poolId, "SOUL"]);
const price = scaled / 1e8; // display price of SOUL in the other token

getPoolCountForPair(tokenA: string, tokenB: string): number

Shortcut for getCanonicalPairKey → getPairPoolCount. Returns the number of pools (active or removed) that exist for a pair.

const n = await readContract("saturnrouter", "getPoolCountForPair", ["SOUL", "KCAL"]);

getPoolIdForPairAtIndex(tokenA: string, tokenB: string, index: number): number

Returns the poolId at a given index in the pair's pool list. Use together with getPoolCountForPair() to iterate every pool for a pair without building a canonical key yourself.

const count = await readContract("saturnrouter", "getPoolCountForPair", ["SOUL", "KCAL"]);
for (let i = 0; i < count; i++) {
  const pid = await readContract("saturnrouter", "getPoolIdForPairAtIndex", ["SOUL", "KCAL", i]);
}

getPoolFullInfo(poolId: number): string

One-call view that returns every field a frontend typically needs to render a pool row: tokens, scaled reserves, fee rate, active flag, campaign lock count and financial lock count, packed into a single underscore-delimited string. The obsolete pawned field was dropped in 4.1.1; read saturnpools.getPoolPawned() to see whether a pool backs a loan.

const info = await readContract("saturnrouter", "getPoolFullInfo", [poolId]);
const parts = Object.fromEntries(
  info.split("_").map(p => { const [k, ...v] = p.split(":"); return [k, v.join(":")]; })
);

getProviderClaimable(poolId: number, tokenSymbol: string): number

Convenience re-export of SaturnFees.getProviderClaimable() so your app can hit a single contract.

const pending = await readContract("saturnrouter", "getProviderClaimable", [poolId, "SOUL"]);

getPoolScaledLiquidity(poolId: number): number

Re-export of SaturnPools.getPoolScaledLiquidity — cheap "depth" metric for ranking pools.

const depth = await readContract("saturnrouter", "getPoolScaledLiquidity", [poolId]);

getProviderClaimablePair(poolId: number): string

Passthrough to saturnfees.getProviderClaimablePair(): both pending provider balances of a pool packed as "tokenA:<sym>_pendingA:<n>_tokenB:<sym>_pendingB:<n>" (scaled units).

const pending = await readContract("saturnrouter", "getProviderClaimablePair", [poolId]);

getPoolProvider(poolId: number): address

Passthrough to saturnpools.getPoolProvider(): the wallet (or contract, for syndicate and launchpad pools) recorded as the pool's provider. For ownership checks prefer SATURN.holdsPoolCertificate(), which follows the NFT.

const provider = await readContract("saturnrouter", "getPoolProvider", [poolId]);

getContractVersion(): string

Returns the deployed build tag of this contract. The mainnet and devnet deployments documented here report "saturnrouter-4.1.1". Compare it against the value you developed against before trusting method semantics after an upgrade.

const v = await readContract("saturnrouter", "getContractVersion", []);
// "saturnrouter-4.1.1"

getMinRawForPoolCreation(tokenSymbol: string): number

Returns the minimum raw amount of a token a provider must supply when calling createPool(). Already applies the token's scale factor and the absolute floor from SaturnAdmin.

const minA = await readContract("saturnrouter", "getMinRawForPoolCreation", ["SOUL"]);
const minB = await readContract("saturnrouter", "getMinRawForPoolCreation", ["KCAL"]);

getMinRawForSwap(tokenSymbol: string): number

Returns the minimum raw amount a user must send as the input of a swap. Enforces both the scaled-units minimum and the absolute floor.

const minSwap = await readContract("saturnrouter", "getMinRawForSwap", ["SOUL"]);

getMinRawForAddLiquidity(tokenSymbol: string): number

Returns the minimum raw amount of token A a user must add in a single addLiquidity() call.

const minAdd = await readContract("saturnrouter", "getMinRawForAddLiquidity", ["SOUL"]);

getScaleFactor(tokenSymbol: string): number

Re-export of SaturnPools.getScaleFactor. scaled = raw × factor / divisor: the factor is 10^(8 − decimals) for tokens with 8 decimals or fewer and 1 above 8, where saturnpools.getScaleDivisor() holds 10^(decimals − 8) (KCAL: factor 1, divisor 100). This router has no divisor passthrough, so read saturnpools.getScaleDivisor or use saturnpools.scaleUp / scaleDown.

const f = await readContract("saturnrouter", "getScaleFactor", ["SOUL"]);

getTargetDecimals(): number

Re-export of SaturnAdmin.getTargetDecimals (8 by default).

const dec = await readContract("saturnrouter", "getTargetDecimals", []);

getMaxTruncationPercent(): number

Re-export of SaturnAdmin.getMaxTruncationPercent (default 10).

const maxTrunc = await readContract("saturnrouter", "getMaxTruncationPercent", []);

getFeeSplitRatios(): string

Re-export of SaturnAdmin.getFeeSplitRatios. Returns the full reinvest / provider / admin / holder breakdown in one string. The holder slice is taken only when the swap's input token has stakers in saturnholders; otherwise it stays in the pool as reinvest.

const split = await readContract("saturnrouter", "getFeeSplitRatios", []);

getPoolFeeRange(): string

Re-export of SaturnAdmin.getPoolFeeRange. Returns both min and max per-pool fee rates packed into one string.

const range = await readContract("saturnrouter", "getPoolFeeRange", []);

createClPool(from: address, tokenA: string, tokenB: string, amountA: number, amountB: number, priceMin: number, priceMax: number, feePer10k: number)

Creates a new concentrated liquidity pool seeded with the caller's initial liquidity. The initial price (scaledB / scaledA × 1e8) must fall inside [priceMin, priceMax]; the call reverts otherwise. The pool is immediately active, assigned a monotonically increasing poolId, and indexed under the canonical pair key so router views can discover it. Both tokens must pass the saturnpools symbol validator, and since 4.2.6 each side must meet the v4 minimum pool size (saturnadmin.getMinScaledPoolUnits: 100 whole tokens per side live). Also since 4.2.6 only the amount the 8-decimal scaled reserve represents is taken; for a token with more than 8 decimals the sub-unit remainder stays in your wallet. Only the creator (from) can later add or remove liquidity.

// 100 SOUL + 500 KCAL: price 5 KCAL per SOUL, range 4..6
const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnclpools", "createClPool", [
    from, "SOUL", "KCAL",
    10000000000,     // amountA: 100 SOUL (8 decimals); live minimum is 100 whole tokens per side
    5000000000000,   // amountB: 500 KCAL (10 decimals)
    400000000,       // priceMin: 4 KCAL per SOUL (× 1e8)
    600000000,       // priceMax: 6 KCAL per SOUL (× 1e8)
    30               // feePer10k: 0.3% (live range 30..3000)
  ])
  .spendGas(from)
  .endScript();

removeClPool(from: address, poolId: number)

Permanently deactivates a CL pool and returns all reserves plus any unclaimed fees to the pool provider. Only the original creator of the pool may call this. After removal the pool cannot be reactivated; poolId remains in storage with active=0. Any accumulated fees are bundled into the refund — a separate claimClFees call is not required.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnclpools", "removeClPool", [from, poolId])
  .spendGas(from)
  .endScript();

addClLiquidity(from: address, poolId: number, amountA: number, maxAmountB: number)

Adds liquidity to an existing active CL pool at the current ratio. The amount of tokenB actually deposited is calculated from the pool's current reserves and the supplied amountA; if that computed amount exceeds maxAmountB the call reverts, giving the caller a slippage guard. Only the pool provider (the original creator) can add liquidity. Both token amounts are transferred from the caller to the liquidity vault. Since 4.2.6 only the tokenA the 8-decimal scaled reserve can represent is taken; for a token with more than 8 decimals the sub-unit remainder stays in your wallet.

// SOUL/KCAL pool. Reserves are 8-decimal scaled, so convert with each token's decimals.
const resA = BigInt(await readContract("saturnclpools", "getClPoolReserveA", [poolId]));
const resB = BigInt(await readContract("saturnclpools", "getClPoolReserveB", [poolId]));
const addA = 500000000n;                  // 5 SOUL (8 decimals: raw = scaled)
const scaledB = (addA * resB) / resA;     // tokenB needed, scaled
const rawB = scaledB * 100n;              // KCAL has 10 decimals: raw = scaled × 10^(10-8)
const maxB = rawB + rawB / 100n;          // +1% headroom

const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnclpools", "addClLiquidity", [from, poolId, addA, maxB])
  .spendGas(from)
  .endScript();

swapClPool(from: address, poolId: number, amountIn: number, tokenIn: string, tokenOut: string, minAmountOut: number): number

Executes a swap against a specific CL pool using the xy=k formula. The fee (amountIn * feePer10k / 10000, raw) is deducted from amountIn before the AMM math runs, and is accumulated in the pool for the provider to claim later. Since 4.2.6 a swap whose fee rounds to zero is refused, and the sub-unit remainder of the input that the 8-decimal scaled reserve cannot hold goes to the provider with the fee. The swap reverts if the resulting price would fall outside the pool's declared [priceMin, priceMax] range — this is the core CL invariant. Returns the actual raw output amount delivered to the caller. Use minAmountOut to guard against slippage.

// Sell 1 SOUL for KCAL on a SOUL/KCAL pool with 1% slippage.
// Reserves are 8-decimal scaled; KCAL has 10 decimals (raw = scaled × 100).
const resA = BigInt(await readContract("saturnclpools", "getClPoolReserveA", [poolId]));
const resB = BigInt(await readContract("saturnclpools", "getClPoolReserveB", [poolId]));
const fee  = BigInt(await readContract("saturnclpools", "getClPoolFeePer10k", [poolId]));
const amountIn = 100000000n;                              // 1 SOUL (8 decimals)
const afterFee = amountIn - (amountIn * fee) / 10000n;
const scaledOut = (afterFee * resB) / (resA + afterFee);  // xy=k output, scaled
const minOut = (scaledOut * 100n * 99n) / 100n;           // raw KCAL, less 1%

const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnclpools", "swapClPool", [
    from, poolId, amountIn, "SOUL", "KCAL", minOut
  ])
  .spendGas(from)
  .endScript();

claimClFees(from: address, poolId: number)

Withdraws all accumulated swap fees from both sides of a CL pool to the pool provider. Fees are denominated in the raw token amounts that were charged at swap time. After claiming, the fee accumulators reset to zero. The pool does not need to be active — fees can be claimed even on an inactive pool (though removeClPool bundles fees into the refund anyway, so a separate claim before removal is optional).

const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnclpools", "claimClFees", [from, poolId])
  .spendGas(from)
  .endScript();

getContractVersion(): string

Returns the current contract version string, useful for verifying on-chain deployment matches your SDK expectations.

const version = await readContract("saturnclpools", "getContractVersion", []);

getClPoolInfo(poolId: number): string

Returns all core pool fields packed into a single underscore-delimited string: "tokenA:X_tokenB:Y_resA:N_resB:N_priceMin:N_priceMax:N_fee:N_active:N". Reserves are in scaled (internal) units. Use this for a single-round-trip refresh of a known pool.

const info = await readContract("saturnclpools", "getClPoolInfo", [poolId]);
// "tokenA:SOUL_tokenB:KCAL_resA:10000000000_resB:50000000000_priceMin:400000000_priceMax:600000000_fee:30_active:1"
const fields = Object.fromEntries(info.split("_").map(f => f.split(":")));

getClPoolProvider(poolId: number): address

Returns the address of the wallet that created and owns the specified CL pool.

getClPoolTokenA(poolId: number): string

Returns the symbol of the first token in the pool's pair.

getClPoolTokenB(poolId: number): string

Returns the symbol of the second token in the pool's pair.

getClPoolReserveA(poolId: number): number

Returns the current reserve of tokenA in 8-decimal scaled units: divide by 1e8 for whole tokens, or use saturnpools.scaleDown(value, tokenA) for raw units.

getClPoolReserveB(poolId: number): number

Returns the current scaled reserve of tokenB.

getClPoolPriceMin(poolId: number): number

Returns the lower bound of the pool's active price range. Price is stored as (reserveB / reserveA) × 1e8.

getClPoolPriceMax(poolId: number): number

Returns the upper bound of the pool's active price range.

getClPoolFeePer10k(poolId: number): number

Returns the pool's swap fee in basis points out of 10,000. For example, 30 means 0.3%.

getClPoolActive(poolId: number): number

Returns 1 if the pool is active and accepting swaps/liquidity, 0 if it has been removed.

getClPoolFeesARaw(poolId: number): number

Returns the current unclaimed fee accumulator for tokenA, in raw (unscaled) units.

getClPoolFeesBRaw(poolId: number): number

Returns the current unclaimed fee accumulator for tokenB, in raw (unscaled) units.

getClPoolPrice(poolId: number): number

Computes and returns the current spot price of the pool as (reserveB × 1e8) / reserveA. Returns 0 if reserveA is zero (pool drained or not yet funded). Use this to display a live price quote or to estimate slippage before swapping.

const price = await readContract("saturnclpools", "getClPoolPrice", [poolId]);
const humanPrice = Number(price) / 1e8; // e.g. 0.5 KCAL/SOUL

getNextClPoolId(): number

Returns the ID that will be assigned to the next CL pool created. Pool IDs are sequential starting from 1.

getClPairPoolCount(pairKey: string): number

Returns the number of CL pools that exist for a given canonical pair key (as produced by saturnpools.getCanonicalPairKey). Use this to paginate pair pools before fetching them with getClPairPoolAtIndex.

const count = await readContract("saturnclpools", "getClPairPoolCount", [pairKey]);
for (let i = 0; i < count; i++) {
  const pid = await readContract("saturnclpools", "getClPairPoolAtIndex", [pairKey + "_" + i]);
}

getClPairPoolAtIndex(lookupKey: string): number

Returns the poolId stored at a specific index under a pair key. The lookupKey format is "<pairKey>_<index>", e.g. "KCAL_SOUL_0" (saturnpools.getCanonicalPairKey("SOUL", "KCAL") returns "KCAL_SOUL"). Iterate from 0 to getClPairPoolCount(pairKey)-1 to enumerate all pools for a pair.

getAllClPoolIds(): number*

Streams all ever-created CL pool IDs (including inactive ones) as a sequence. Use getActiveClPoolIds() if you only want live pools.

const allIds = await readContract("saturnclpools", "getAllClPoolIds", []);

getActiveClPoolIds(): number*

Streams the IDs of all currently active (non-removed) CL pools. More efficient for UI discovery than getAllClPoolIds() when removed pools should be hidden.

const activeIds = await readContract("saturnclpools", "getActiveClPoolIds", []);

getActiveClPoolsData(): string*

Batch view that streams one encoded row per active CL pool — eliminates N round-trips when building a pool-list UI. Each row is pipe-delimited: "poolId|provider|tokenA|tokenB|reserveA|reserveB|priceMin|priceMax|fee|active". Reserves are in scaled internal units.

const rows = await readContract("saturnclpools", "getActiveClPoolsData", []);
// rows is an array of strings, e.g.:
// ["1|P2K...|SOUL|KCAL|10000000000|50000000000|400000000|600000000|30|1", ...]
const pools = rows.map(row => {
  const [poolId, provider, tokenA, tokenB, resA, resB, priceMin, priceMax, fee, active] = row.split("|");
  return { poolId, provider, tokenA, tokenB, resA, resB, priceMin, priceMax, fee, active };
});

placeStreamingOrder(from: address, poolId: number, amountIn: number, durationSeconds: number, tokenIn: string, tokenOut: string, minChunkSeconds: number, minOutputPerChunk: number, bountyPer10k: number)

Opens a new streaming order. The full amountIn is transferred from the caller into the TWAMM contract's escrow immediately. The stream runs for durationSeconds, executing chunks no faster than one per minChunkSeconds. Each chunk executor receives bountyPer10k basis-points of that chunk's output as a bounty; set to 0 to disable executor incentives (only recommended for self-operated bots). minOutputPerChunk is a mandatory price floor (it must be greater than 0): the minimum raw output of one on-time chunk (amountIn × minChunkSeconds / durationSeconds). Every chunk must pay the same per unit of input, so a late chunk twice that size needs twice the output and a smaller last chunk proportionally less: floor = minOutputPerChunk × chunkIn × durationSeconds / (amountIn × minChunkSeconds), at least 1. Size it from the pool's quote for one on-time chunk minus the slippage you accept. The floor applies to the chunk's output before the executor's bounty is taken. Placement also refuses a stream whose on-time chunk is below the swap minimum (saturnrouter.getMinRawForSwap(tokenIn)).

// Stream 100 SOUL into KCAL over 1 hour, one chunk per minute, 1% bounty
const amountIn   = 10000000000n; // 100 SOUL (8 decimals)
const duration   = 3600;         // 1 hour
const minChunk   = 60;           // chunks every 60 s minimum
// Floor: the pool's quote for one on-time chunk (100 × 60 / 3600 = 1.66666666 SOUL) minus the slippage you accept
const minOut     = 350000000000n; // 35 KCAL (10 decimals) per on-time chunk, scaled to each chunk's size. Mainnet pool 12 quoted 36.16 KCAL on 2026-09-28; other SOUL/KCAL pools pay less, so quote your own pool
const bounty     = 100;          // 1% of each chunk's output to whoever fires it

const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturntwamm", "placeStreamingOrder", [
    from, poolId, amountIn, duration, "SOUL", "KCAL", minChunk, minOut, bounty
  ])
  .spendGas(from)
  .endScript();

cancelStream(from: address, streamId: number)

Cancels an active stream early. Returns all remaining unstreamed input AND any accumulated output that has not yet been claimed — both in a single call. Status is set to 2 (cancelled) and the stream is removed from the active list. Only the stream owner may cancel. Once cancelled a stream cannot be resumed.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturntwamm", "cancelStream", [from, streamId])
  .spendGas(from)
  .endScript();

executeStreamingChunk(from: address, streamId: number)

Executes the next chunk of an active stream. Permissionless: any signer can call it once minChunkSeconds have passed since the last chunk (the first chunk is due minChunkSeconds after placement), and the caller earns the bounty. The chunk is everything owed since the last one, floor(amountInTotal × (now − startTime) / durationSeconds) − streamedSoFar, and from endTime on the whole remainder. If what would be left afterwards is below the swap minimum (saturnrouter.getMinRawForSwap(tokenIn)), it is swept into this chunk, so no stream ends with stuck dust. The chunk goes from escrow to saturnliquidity and through saturnswap.swapFromContract on the stream's pool with the chunk's floor as minAmountOut (floorMode 1: minOutputPerChunk × chunkIn × durationSeconds / (amountInTotal × minChunkSeconds), at least 1; floorMode 0, streams placed before 4.2.4: minOutputPerChunk). The executor receives bountyPer10k / 10,000 of the chunk's output in tokenOut, paid immediately; the rest accumulates for the owner. The chunk that empties the stream sets status 1 (completed), removes it from the active list and pays the owner all accumulated output in the same transaction (emits StreamClaimed).

// Bot / agent loop: execute whenever a chunk is ready
const lastExec    = await readContract("saturntwamm", "getStreamLastExecutionTime", [streamId]);
const minInterval = await readContract("saturntwamm", "getStreamMinChunkSeconds", [streamId]);
const nextWindow  = Number(lastExec) + Number(minInterval);

if (Date.now() / 1000 >= nextWindow + 3) { // block time trails the clock: keep a few seconds of margin
  // quote the chunk first: it must clear the swap minimum and its floor
  const tx = ScriptBuilder
    .begin()
    .allowGas(executor, null, gasPrice, gasLimit)
    .callContract("saturntwamm", "executeStreamingChunk", [executor, streamId])
    .spendGas(executor)
    .endScript();
}

claimStreamingOutput(from: address, streamId: number)

Transfers all accumulated tokenOut from completed chunk swaps to the stream owner. Can be called at any point during or after the stream — mid-stream partial claims are fully supported. Resets the accumulator to zero after payout. Since 4.2.4 the chunk that completes a stream pays the owner automatically and cancelStream pays out the accumulated output, so claims matter while a stream runs; a stream completed under 4.2.3 may still hold output to claim.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturntwamm", "claimStreamingOutput", [from, streamId])
  .spendGas(from)
  .endScript();

getContractVersion(): string

Returns the current TWAMM contract version string. Mainnet and devnet report saturntwamm-4.2.4; the floor and dust rules on this page need 4.2.4.

const version = await readContract("saturntwamm", "getContractVersion", []);

getStreamInfo(streamId: number): string

Returns all key stream fields as a single underscore-delimited string for a one-round-trip refresh. Format: "pool:N_in:TOKEN_out:TOKEN_total:N_streamed:N_remaining:N_accOut:N_start:N_end:N_status:N". All amounts in raw units; times are Unix timestamps.

const info = await readContract("saturntwamm", "getStreamInfo", [streamId]);
const fields = Object.fromEntries(info.split("_").map(f => f.split(":")));
// fields.status === "0"  → still running

getStreamOwner(streamId: number): address

Returns the address of the wallet that placed the streaming order.

getStreamPoolId(streamId: number): number

Returns the target pool ID that chunks are swapped through.

getStreamTokenIn(streamId: number): string

Returns the symbol of the input token being streamed.

getStreamTokenOut(streamId: number): string

Returns the symbol of the output token being accumulated.

getStreamAmountInTotal(streamId: number): number

Returns the total input amount placed when the stream was created.

getStreamAmountInRemaining(streamId: number): number

Returns how much of the input has not yet been streamed. Use this to compute percentage completion.

const total     = await readContract("saturntwamm", "getStreamAmountInTotal",     [streamId]);
const remaining = await readContract("saturntwamm", "getStreamAmountInRemaining", [streamId]);
const pctDone   = ((Number(total) - Number(remaining)) / Number(total) * 100).toFixed(1);

getStreamAmountStreamedSoFar(streamId: number): number

Returns the cumulative raw input amount that has been swapped across all executed chunks.

getStreamAmountOutAccumulated(streamId: number): number

Returns the current unclaimed output balance sitting in the TWAMM contract for this stream. Set to zero when claimStreamingOutput is called, and when the completing chunk or cancelStream pays the owner.

getStreamStartTime(streamId: number): number

Returns the Unix timestamp when the stream was placed.

getStreamEndTime(streamId: number): number

Returns the Unix timestamp at which the stream's duration ends (startTime + durationSeconds; there is no separate duration getter). From then on the next chunk is the whole remainder, still subject to pacing, the swap minimum and the floor.

getStreamLastExecutionTime(streamId: number): number

Returns the Unix timestamp of the most recent chunk execution (the placement time until the first chunk). Add getStreamMinChunkSeconds() to determine when the next chunk becomes executable.

const last    = await readContract("saturntwamm", "getStreamLastExecutionTime", [streamId]);
const minSecs = await readContract("saturntwamm", "getStreamMinChunkSeconds",    [streamId]);
const ready   = Date.now() / 1000 >= Number(last) + Number(minSecs);

getStreamMinChunkSeconds(streamId: number): number

Returns the minimum pacing interval (in seconds) between consecutive chunk executions for this stream.

getStreamMinOutputPerChunk(streamId: number): number

Returns minOutputPerChunk as placed: the minimum raw tokenOut for one on-time chunk. For floorMode 1 streams (placed on 4.2.4) it is a price, scaled to each chunk's size; for floorMode 0 streams it is a fixed amount per chunk. Placement requires it to be > 0.

getStreamBountyPer10k(streamId: number): number

Returns the executor bounty rate in basis points out of 10,000. Multiply by chunk output and divide by 10,000 to estimate what an executor earns per call.

getStreamStatus(streamId: number): number

Returns the lifecycle status of a stream: 0 = active, 1 = completed (fully streamed), 2 = cancelled. An id never assigned (including 0) also reads 0, so check 0 < streamId < getNextStreamId() or use the active-stream views.

getStreamFloorMode(streamId: number): number

How the stream's floor works. 1 = minOutputPerChunk is a price (streams placed on 4.2.4): a chunk of chunkIn raw must pay at least minOutputPerChunk × chunkIn × durationSeconds / (amountInTotal × minChunkSeconds), at least 1. 0 = a fixed minOutputPerChunk per chunk (streams placed before the 4.2.4 upgrade). A keeper needs it to compute the floor a chunk must clear; durationSeconds = getStreamEndTime − getStreamStartTime.

const mode = await readContract("saturntwamm", "getStreamFloorMode", [streamId]);

getNextStreamId(): number

Returns the ID that will be assigned to the next stream. Stream IDs are sequential starting from 1.

getTotalStreamsPlaced(): number

Returns the cumulative count of all streams ever placed, including completed and cancelled ones.

getTotalStreamsCompleted(): number

Returns the number of streams that have been fully executed to completion (all input streamed).

getActiveStreamCount(): number

Returns the current number of active (status = 0) streams. Useful for a live dashboard counter.

const active = await readContract("saturntwamm", "getActiveStreamCount", []);

getAllActiveStreamIds(): number*

Streams the IDs of all currently active (status = 0) streams. Pair with getStreamInfo() or getActiveStreamsData() to build a live order-book view.

const ids = await readContract("saturntwamm", "getAllActiveStreamIds", []);

getActiveStreamIdsByOwner(owner: address): number*

Returns only the active stream IDs that belong to a specific owner address. Useful for a personal dashboard showing all of a user's live streams.

const myStreams = await readContract("saturntwamm", "getActiveStreamIdsByOwner", [userAddress]);

getActiveStreamIdsByPool(poolId: number): number*

Returns only the active stream IDs targeting a specific pool. Useful for pool analytics pages that want to show pending TWAMM flow alongside live reserves.

const poolStreams = await readContract("saturntwamm", "getActiveStreamIdsByPool", [poolId]);

getActiveStreamsData(): string*

Batch view that streams one encoded row per active stream, eliminating N round-trips for list UIs. A keeper still needs per-stream reads the rows do not carry: getStreamStartTime, getStreamLastExecutionTime, getStreamMinChunkSeconds, getStreamAmountStreamedSoFar, getStreamMinOutputPerChunk, getStreamBountyPer10k and getStreamFloorMode (several calls fit in one invokeRawScript). Each row is pipe-delimited: "streamId|poolId|owner|tokenIn|tokenOut|amountInTotal|amountInRemaining|amountOutAccumulated|endTime|status".

const rows = await readContract("saturntwamm", "getActiveStreamsData", []);
const streams = rows.map(row => {
  const [streamId, poolId, owner, tokenIn, tokenOut,
         amtTotal, amtRemaining, amtOut, endTime, status] = row.split("|");
  return { streamId, poolId, owner, tokenIn, tokenOut,
           amtTotal, amtRemaining, amtOut, endTime, status };
});

getActiveStreamsDataByOwner(owner: address): string*

Same pipe-delimited batch format as getActiveStreamsData() but filtered to a single owner. Use this on a wallet portfolio page to load all of a user's live streams in one call.

const myRows = await readContract("saturntwamm", "getActiveStreamsDataByOwner", [userAddress]);

executeFlashArb(from: address, poolIdBuy: number, poolIdSell: number, tokenStart: string, amountIn: number, minNetProfit: number): number

Core flash-arbitrage entrypoint. Borrows amountIn of tokenStart from saturnliquidity, executes leg 1 (tokenStart → tokenMid via poolIdBuy) and leg 2 (tokenMid → tokenStart via poolIdSell), returns amountIn to saturnliquidity, pays flashFee = amountIn × flashFeePer10k / 10000 to the protocol admin wallet (saturnadmin.getAdmin()) and transfers netProfit = finalAmount − amountIn − flashFee to from. The executor puts up no capital: the transaction reverts atomically if finalAmount ≤ amountIn, if the gross profit does not exceed the flash fee, or if netProfit < minNetProfit, so a failed attempt costs only gas. tokenMid is the other token of poolIdBuy; poolIdSell must be a different active pool holding the same two tokens (in either order). Both legs are ordinary saturnswap contract swaps, so each pays its pool's full swap fee (currently provider 10%, admin 20%, holders 10% when the input token has stakers, the rest reinvested into that pool) before the profit check. Only saturnpools (v4) pools can be used, not saturnclpools ranges or v3 SATRN pools.

// Pre-flight reads (free): paused? enough to borrow? fee?
const enabled = await readContract("saturnflash", "getFlashEnabled", []);
const max = await readContract("saturnflash", "getMaxBorrowable", ["SOUL"]);
const amountIn = 10000000000; // 100 SOUL (8 decimals), sized by simulating both pools
const fee = await readContract("saturnflash", "quoteFlashFee", [amountIn]); // 5000000 = 0.05 SOUL at 5/10k
if (enabled !== 1 || amountIn > max) throw new Error("cannot flash-borrow now");

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnflash", "executeFlashArb", [
    from,
    poolIdBuy,     // leg 1: SOUL -> tokenMid here (tokenMid is cheap in SOUL)
    poolIdSell,    // leg 2: tokenMid -> SOUL here (same pair, tokenMid dearer)
    "SOUL",        // tokenStart: borrowed, repaid and paid out in SOUL
    amountIn,      // 100 SOUL borrowed from saturnliquidity
    1000000        // minNetProfit: 0.01 SOUL after the flash fee, else revert
  ])
  .spendGas(from)
  .endScript();
// returns netProfit in raw SOUL; also emitted in FlashArbExecuted

quoteFlashFee(amount: number): number

Returns the flash fee that would be charged on a given borrow amount at the current flashFeePer10k rate. Use this before calling executeFlashArb to calculate whether the expected arb spread exceeds the total cost (2× swap fees + flash fee + gas).

const fee = await readContract("saturnflash", "quoteFlashFee", [amountIn]);
// fee must be < expected spread for the arb to be profitable

getMaxBorrowable(tokenSymbol: string): number

Returns saturnliquidity's whole raw balance of tokenSymbol (every pool's reserves plus unclaimed provider fees and holder rewards), which is the ceiling executeFlashArb checks amountIn against. It is not a per-pool limit and not a trade size: the profitable amountIn is set by the reserves of the two pools you route through and is usually far smaller. Check amountIn against it to rule out "Insufficient liquidity for flash arb".

const max = await readContract("saturnflash", "getMaxBorrowable", ["SOUL"]);
if (amountIn > max) throw new Error("not enough SOUL in saturnliquidity"); // size amountIn from the two pools' reserves, not from max

getFlashFeePer10k(): number

Returns the current flash fee rate in basis points out of 10,000 (e.g. 5 = 0.05%). The fee is amountIn × rate / 10000, taken out of the round trip's gross profit and paid to the protocol admin wallet; the admin can set the rate between 1 and 100.

const feePer10k = await readContract("saturnflash", "getFlashFeePer10k", []);

getFlashEnabled(): number

Returns 1 if flash arbitrage is currently active, 0 if the admin has paused it. Check this before attempting executeFlashArb to surface a clear status in your bot or UI.

const enabled = await readContract("saturnflash", "getFlashEnabled", []);
if (enabled !== 1) throw new Error("Flash arb is currently paused");

getContractVersion(): string

Returns the deployed version string for this contract.

const ver = await readContract("saturnflash", "getContractVersion", []);

getContractAddress(): address

Returns the on-chain address of this contract. saturnflash holds tokens only inside an executeFlashArb call, so its balance is normally 0; you never send it tokens and there is nothing to approve.

const addr = await readContract("saturnflash", "getContractAddress", []);

getTotalFlashArbs(): number

Returns the cumulative count of successful flash arbitrage executions since deployment.

const total = await readContract("saturnflash", "getTotalFlashArbs", []);

getTotalFlashFeesCollected(): number

Returns the lifetime total of flash fees paid to the protocol admin wallet across all successful executeFlashArb calls. Raw amounts of different tokenStart symbols are added together, so this is an activity counter, not a value in one token.

const fees = await readContract("saturnflash", "getTotalFlashFeesCollected", []);

getExecutorArbCount(executor: address): number

Returns the number of successful flash arb executions performed by a specific executor address. Use this on leaderboards or to track your own bot's activity.

const count = await readContract("saturnflash", "getExecutorArbCount", [botAddress]);

getExecutorTotalProfit(executor: address): number

Returns the lifetime net profit (after the flash fee, before gas) paid to an executor across all successful executeFlashArb calls. Raw amounts of different tokenStart symbols are added together, so keep per-token profit from your own FlashArbExecuted events.

const profit = await readContract("saturnflash", "getExecutorTotalProfit", [botAddress]);

updateFlashFee(newFeePer10k: number)

Admin only. The saturnadmin owner (saturnadmin.getAdmin()) must sign. Sets the flash fee that executeFlashArb charges on amountIn, per 10,000: from 1 (0.01%) to 100 (1%). The constructor default is 5 (0.05%). The fee goes to the admin wallet. Emits FlashFeeUpdated. Read the current value with getFlashFeePer10k.

setFlashEnabled(enabled: number)

Admin only. The saturnadmin owner (saturnadmin.getAdmin()) must sign. Emergency switch: 0 pauses executeFlashArb (it then reverts with "Flash arb is paused"), 1 turns it back on. Views keep working. Emits FlashEnabledChanged. Read the current value with getFlashEnabled.

stake(from: address, tokenSymbol: string, amount: number)

Deposits amount raw units of tokenSymbol into the rewards vault on behalf of from. If the user already has an open position, any pending rewards are settled first so they aren't lost. The user's bookmark is set to the current accumulator value, ensuring they only earn from future accruals. Tokens are transferred from the caller's wallet into this contract's custody and cannot be traded while staked — this custody model prevents the wash-claim attack that pure hold-to-earn is vulnerable to.

const from = "S3...userAddress";
const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnholders", "stake", [
    from,
    "SOUL",
    10000000000    // amount: 100 SOUL (8 decimals)
  ])
  .spendGas(from)
  .endScript();
// about 0.025 KCAL of gas measured on devnet

unstake(from: address, tokenSymbol: string, amount: number)

Withdraws amount raw units of tokenSymbol from the vault back to from. Pending rewards are settled automatically before the stake is decremented, so the user receives everything they've earned. Partial unstakes are supported — only the requested amount is returned and the remainder continues earning. If amount would reduce the stake to zero, the distinct-stakers count is decremented. Any part of the stake locked by a saturntaz pledge (getPledgeLocked) cannot be unstaked until saturntaz calls unlockPledge. A saturnstakearb loan never blocks an unstake: it opens and closes inside one transaction and the principal is re-checked before that transaction commits.

const from = "S3...userAddress";
const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnholders", "unstake", [
    from,
    "SOUL",
    5000000000     // amount: 50 SOUL (8 decimals), <= getStakedAmount - getPledgeLocked
  ])
  .spendGas(from)
  .endScript();
// pending rewards are paid in the same transaction

claim(from: address, tokenSymbol: string)

Pays out all pending rewards for from's tokenSymbol stake without altering the stake balance. Rewards (the swap-fee slice and the saturnstakearb profit share, both in tokenSymbol) are transferred from saturnliquidity (the central custodian) directly to from. The user's bookmark is bumped to the current accumulator so subsequent calls report zero pending until new swaps accrue more fees. Can be called at any time after stake().

const from = "S3...userAddress";
const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnholders", "claim", [from, "SOUL"])
  .spendGas(from)
  .endScript();
// check getPendingRewards(from, "SOUL") first; 0 pending still succeeds

accrueHolderFee(tokenSymbol: string, scaledFee: number)

Contract-only hook: accepts calls only from saturnswap, which calls it on every swap, passing the input token and the holder slice of that swap's fee (in saturnpools' 8-decimal scaled units). It converts the fee to raw units (saturnpools.scaleDown) and raises the token's accumulator by realFee × 1e12 / getTotalStaked(tokenSymbol), so every staker of tokenSymbol earns pro-rata; it moves no tokens (the fee itself stays at saturnliquidity). saturnswap only takes a holder slice when getTotalStaked(tokenIn) > 0, at saturnadmin.getHolderPct() percent of the pool fee (10% today). Documented so bots and indexers can read the HolderAccrued event; a wallet or another contract cannot call it.

getPledgeLocked(user: address, tokenSymbol: string): number

Returns the raw-unit amount of tokenSymbol currently locked against unstaking for user by a Saturn Lending pledge (via saturntaz). The available-for-unstake amount is stakedAmount − pledgeLocked. Query this alongside getStakedAmount to surface the correct withdrawable balance in your UI.

const locked = await readContract("saturnholders", "getPledgeLocked", [userAddr, "SOUL"]);
const staked  = await readContract("saturnholders", "getStakedAmount", [userAddr, "SOUL"]);
const available = staked - locked;

lockForPledge(user: address, tokenSymbol: string, amount: number)

Contract-only hook: accepts calls only from saturntaz (Saturn Lending's non-custodial RA pledge). Locks amount of user's staked tokenSymbol against unstaking. The tokens stay staked and keep earning; only unstake() is limited to stake − pledgeLocked. Wallets pledge through saturntaz, not here.

unlockPledge(user: address, tokenSymbol: string, amount: number)

Contract-only hook: accepts calls only from saturntaz, which calls it when a pledge is withdrawn after its window. Reduces user's pledge-locked amount so it can be unstaked again.

flashLendStake(borrower: address, tokenSymbol: string, amount: number)

Contract-only hook: accepts calls only from saturnstakearb, as step 1 of executeArb. Marks a loan open for tokenSymbol (getLoanOpen = 1) and transfers amount of the staked tokens to borrower (saturnstakearb passes its own address). Staker balances and getTotalStaked do not change. A bot never calls this directly; it calls saturnstakearb.executeArb, which must end with settleArbLoan in the same transaction.

settleArbLoan(tokenSymbol: string, holderShare: number)

Contract-only hook: accepts calls only from saturnstakearb, as the last step of executeArb. Solvency check: requires this contract's tokenSymbol balance to be ≥ getTotalStaked(tokenSymbol) again, so the borrowed principal must be back in full or the whole transaction reverts. Then credits holderShare (the stakers' half of the arbitrage profit, already sent to saturnliquidity by saturnstakearb) to every staker pro-rata through the same accumulator as swap fees (holderShare × 1e12 / totalStaked), adds it to getLifetimeAccrued, and closes the loan.

getLoanOpen(tokenSymbol: string): number

Returns 1 while a saturnstakearb flash-borrow of tokenSymbol's staked capital is in progress within a transaction, 0 otherwise. Under normal conditions this will always return 0 from an external query because the borrow opens and closes within a single atomic transaction. Useful for debugging or monitoring.

const open = await readContract("saturnholders", "getLoanOpen", ["SOUL"]);

getStakedAmount(user: address, tokenSymbol: string): number

Returns the raw-unit amount of tokenSymbol currently staked by user. This is the gross staked balance; subtract getPledgeLocked to get the amount available for immediate unstaking.

const staked = await readContract("saturnholders", "getStakedAmount", [userAddr, "SOUL"]);

getPendingRewards(user: address, tokenSymbol: string): number

Computes and returns the unclaimed rewards (in raw token units) accrued to user's tokenSymbol stake since their last claim, stake, or unstake: the swap-fee slice plus the stakers' half of any saturnstakearb profit, as stake × (getAccFeePerToken − getUserRewardDebt) / 1e12. This is the primary view to display in a rewards dashboard — query it before calling claim() to show the user what they'll receive.

const pending = await readContract("saturnholders", "getPendingRewards", [userAddr, "SOUL"]);
console.log(`Claimable: ${pending} raw SOUL units`);

getUserRewardDebt(user: address, tokenSymbol: string): number

Returns the user's reward-debt bookmark — the accFeePerToken value at the time of their last settle (stake, unstake, or claim). The difference between the current accumulator and this bookmark, multiplied by the user's stake, gives the pending rewards. Useful for verifying MasterChef math or building advanced analytics.

const debt = await readContract("saturnholders", "getUserRewardDebt", [userAddr, "SOUL"]);

getStakeInfo(user: address, tokenSymbol: string): string

Returns a packed summary string for a user's position in a single call: "stake:{n}_debt:{n}_pending:{n}". Convenient for a compact dashboard widget or a single-RPC snapshot of a user's full position.

const info = await readContract("saturnholders", "getStakeInfo", [userAddr, "SOUL"]);
// "stake:500000000_debt:1234000000000_pending:12300"

getUserPortfolioData(user: address): string*

Returns one row per token in which user has an active stake (stake > 0). Each row is "symbol|stake|pending|rewardDebt". Use this to render a user's entire staking portfolio in a single call instead of N per-token round-trips.

const rows = await readContract("saturnholders", "getUserPortfolioData", [userAddr]);
// ["SOUL|500000000|12300|1234000000000", "KCAL|200000000|4500|987000000000"]

getTotalStaked(tokenSymbol: string): number

Returns the total raw-unit amount of tokenSymbol currently staked across all holders. This is the denominator of the reward accumulator, the cap on saturnstakearb.executeArb's amountIn, and the balance settleArbLoan requires this contract to hold again after every stake-arb loan. Pledge-locked stake is included (it can be lent, since it always returns in the same transaction). saturnswap takes the holder slice of a swap fee only when this is > 0 for the input token.

const totalStaked = await readContract("saturnholders", "getTotalStaked", ["SOUL"]);

getAccFeePerToken(tokenSymbol: string): number

Returns the current global accumulated-fee-per-unit value for tokenSymbol, scaled by 1e12. This counter only ever increases. Use it alongside getUserRewardDebt to reconstruct the MasterChef pending-reward formula: pending = stake × (accNow − debt) / 1e12.

const acc = await readContract("saturnholders", "getAccFeePerToken", ["SOUL"]);

getTotalStakers(tokenSymbol: string): number

Returns the number of distinct addresses currently holding a non-zero stake of tokenSymbol. Useful for showing participation metrics in your UI.

const stakers = await readContract("saturnholders", "getTotalStakers", ["SOUL"]);

getLifetimeAccrued(tokenSymbol: string): number

Returns the total raw-unit amount of tokenSymbol that has ever been accrued into the reward pool (from both swap fees and arb profits) since deployment. Useful for APR calculation and historical analytics.

const lifetime = await readContract("saturnholders", "getLifetimeAccrued", ["SOUL"]);

getStakedTokenSymbols(): string*

Returns an iterator of every token symbol that has ever been staked. Symbols whose stake has since dropped to zero stay listed, so check totalStaked in getStakedTokensData before treating one as an active market (or a stake-arb source).

const symbols = await readContract("saturnholders", "getStakedTokenSymbols", []);
// ["SOUL", "KCAL", "DYT", ...]

getStakedTokensData(): string*

Returns one packed row per staked token symbol. Each row is "symbol|totalStaked|accFeePerToken|stakers|lifetimeAccrued|loanOpen". Use this for a single-call dashboard load of all token staking metrics.

const rows = await readContract("saturnholders", "getStakedTokensData", []);
// ["SOUL|500000000|1234000000000|42|9870000|0", ...]

registerStakedToken(tokenSymbol: string)

Permissionless, idempotent utility that adds tokenSymbol to the enumeration index (getStakedTokenSymbols / getStakedTokensData) if it has totalStaked > 0 but is not yet listed. Only needed for tokens staked before the v4.4.1 enumeration index was introduced. New stakes self-register automatically inside stake().

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnholders", "registerStakedToken", ["LEGACY"])
  .spendGas(from)
  .endScript();
// no witness check: any wallet can pay the gas

getContractVersion(): string

Returns the deployed version string for this contract.

const ver = await readContract("saturnholders", "getContractVersion", []);

getContractAddress(): address

Returns the on-chain address of this contract. Use it for balance lookups (getAccount). There are no token approvals: stake() moves the tokens with the staker's own signature.

const addr = await readContract("saturnholders", "getContractAddress", []);

lockPool(from: address, poolId: number, durationSeconds: number)

Time-locks the pool's liquidity until now + durationSeconds (unix seconds, block time). Until then saturnliquidity.removePool reverts with "Pool liquidity is time-locked until <unix>" and the pool cannot back a loan. from must sign and be the pool's provider (saturnpools.getPoolProvider) or hold its SATURN certificate. Every call, extensions included, sends getLockFee() raw TAZ from the caller to getFeeWallet() (50 TAZ today). With no live lock, the pool must carry no bond, rental, fee option, syndicate, launchpad or loan (getPoolFinancialLockCount = 0). With a live lock the call is an extension: the new end, counted from now, must be later than the current end, so a lock can never be shortened, and the financial-product check is skipped. The end is stored in saturnpools (getPoolLockUntil). This contract records the caller (getLockedBy) and time (getLockedAt) of the latest call, adds 1 to getLockCount and lists the pool in getLockedPoolIds.

// Lock a pool for 90 days. Costs getLockFee() raw TAZ (50 TAZ today), paid by from.
const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnlplock", "lockPool", [from, poolId,
    7776000])   // durationSeconds: 90 days (86,400 .. 315,360,000)
  .spendGas(from)
  .endScript();
// sign with the provider's or certificate holder's wallet and send

// Extend a live lock by 30 days: the duration counts from now, not from the old end
const until = await readContract("saturnlplock", "getLockUntil", [poolId]);
const now = Math.floor(Date.now() / 1000);
const durationSeconds = (until - now) + 30 * 86400;   // new end must be later than until
// build the same lockPool call with durationSeconds; it pays the full lock fee again

burnPool(from: address, poolId: number)

Burns the pool's liquidity forever. There is no undo. saturnpools.getPoolBurned becomes 1 and saturnliquidity.removePool reverts with "Pool liquidity is burned - it can never be withdrawn" from then on. The reserves stay in the pool and keep trading. The SATURN certificate becomes the pool's fee key: saturnfees.claimProviderFees pays the burned pool's provider fees only to the certificate holder, the certificate cannot be destroyed, and saturnpools.updatePoolFee can only lower the fee. from must sign and be the provider or hold the certificate. Pays getBurnFee() TAZ to getFeeWallet() (0 today, so a burn is free). With no live time lock, the pool must carry no bond, rental, fee option, syndicate, launchpad or loan (getPoolFinancialLockCount = 0); with a live lock that check is skipped. The burn takes the pool off getLockedPoolIds and adds it to getBurnedPoolIds; a lock end already stored stays in getLockUntil.

// Burn a pool's liquidity forever. This cannot be undone.
const info = await readContract("saturnlplock", "getPoolLockInfo", [poolId]);
if (info.startsWith("burned:1")) throw new Error("already burned");
const tx = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnlplock", "burnPool", [from, poolId])
  .spendGas(from)
  .endScript();
// sign with the provider's or certificate holder's wallet and send
// afterwards the SATURN certificate is the pool's fee key: whoever holds it claims the fees

releaseExpiredLock(poolId: number)

Housekeeping that anyone may call; it needs no pool rights, only gas. Takes a pool whose lock has run out off getLockedPoolIds. Withdrawal never needs it: saturnpools compares getPoolLockUntil with the clock, so removePool works as soon as the lock ends. It changes nothing in saturnpools and keeps getLockedBy, getLockedAt and getLockCount. The last pool in the list moves into the freed slot, so the list order changes.

// Tidy expired locks off the list (anyone may; costs only gas)
const ids = await readContract("saturnlplock", "getLockedPoolIds", []);
const now = Math.floor(Date.now() / 1000);
for (const id of ids) {
  if ((await readContract("saturnlplock", "getLockUntil", [id])) > now) continue;
  const tx = ScriptBuilder
    .begin()
    .allowGas(from, null, gasPrice, gasLimit)
    .callContract("saturnlplock", "releaseExpiredLock", [id])
    .spendGas(from)
    .endScript();
  // sign with any wallet and send
}

getPoolLockInfo(poolId: number): string

The pool's burn and lock state in one call: "burned:<0|1>|until:<unix>|locked:<0|1>|locks:<n>". burned is getBurned, until is getLockUntil (0 = never locked), locked is getLocked (1 while until is later than now) and locks is getLockCount.

const info = await readContract("saturnlplock", "getPoolLockInfo", [poolId]);
// "burned:0|until:1798120528|locked:1|locks:1"
const f = Object.fromEntries(info.split("|").map((kv) => kv.split(":")));
const burned = f.burned === "1", locked = f.locked === "1", until = Number(f.until);

getBurned(poolId: number): number

1 when the pool's liquidity is burned, 0 otherwise. Reads saturnpools.getPoolBurned.

const burned = await readContract("saturnlplock", "getBurned", [poolId]);

getLockUntil(poolId: number): number