Saturn DEX — Full Contract Reference

getAdmin(): address

Returns the current protocol admin address. Use this to verify whether a wallet has privileged control or simply to display protocol ownership in your UI.

// Phantasma SDK — invokeRawScript to read
const script = ScriptBuilder
  .begin()
  .callContract("saturnadmin", "getAdmin", [])
  .endScript();

const res = await api.invokeRawScript("main", script);
const adminAddress = res.decoded[0]; // address

getFeeSplitRatios(): string

Returns all three fee split ratios packed into a single string of the form "reinvest:X_provider:Y_admin:Z". Convenient for single-call rendering of the complete fee split.

const script = ScriptBuilder
  .begin()
  .callContract("saturnadmin", "getFeeSplitRatios", [])
  .endScript();

const { decoded } = await api.invokeRawScript("main", script);
// "reinvest:60_provider:10_admin:30"

getReinvestPct(): number

Percentage of each swap fee that is reinvested back into the pool's reserves. This grows the pool's depth over time.

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 routed directly to the protocol admin treasury at swap time.

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

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 — all tokens are scaled up to this many decimals inside the protocol to keep math precise regardless of each token's native decimals.

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

The SOUL-denominated storage fee a provider must pay (on top of their token pair) when calling createPool(). The fee is staked by the protocol for on-chain storage rent.

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

getSOULfeeAddLiquidity(): number

SOUL-denominated storage fee required when calling addLiquidity() on an existing pool.

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

getStorageFee(): number

Current balance of SOUL fees the protocol has accrued but not yet staked. Purely informational — useful for protocol dashboards.

const pending = 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);

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. A scale factor of 0 means the token has not yet been registered in any pool.

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" 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");
}

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

Returns 1 if the pool is currently pawned (provider has locked it against transfer / removal), 0 otherwise.

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 active bond, rental, option, or syndicate positions are holding this pool. While > 0, the pool cannot be removed.

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

Total number of unique token symbols that have ever been added to any pool.

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 on-chain token balance held by the SaturnPools contract itself — the custodial balance backing every pool's reserves.

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

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", []);

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 (30–3000 basis points by default) and the pool must not be locked in any reward campaign.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, Address.Null, 100000, 1500)
  .callContract("saturnpools", "updatePoolFee", [from, poolId, 250]) // 2.5%
  .spendGas(from)
  .endScript();
// sign with wallet, broadcast

pawnPool(from: address, poolId: number)

Marks the pool as pawned. A pawned pool continues to earn and swap normally, but the provider cannot transfer or remove it — useful as collateral or a commitment signal for external products.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, Address.Null, 100000, 1500)
  .callContract("saturnpools", "pawnPool", [from, poolId])
  .spendGas(from)
  .endScript();

unpawnPool(from: address, poolId: number)

Clears the pawned flag on a pool. Either the pool provider or the protocol admin can call this.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, Address.Null, 100000, 1500)
  .callContract("saturnpools", "unpawnPool", [from, poolId])
  .spendGas(from)
  .endScript();

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 basis points — 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 plus a SOUL storage fee are transferred into protocol custody.

// Create a 0.3% fee SOUL/KCAL pool
const soulFee = await readContract("saturnadmin", "getSOULfeeCreatePool", []);
// User must hold: amount0 + amount1 + soulFee + gas buffer

const tx = ScriptBuilder
  .begin()
  .allowGas(from, Address.Null, 100000, 3000)
  .callContract("saturnliquidity", "createPool",
    [from, 10000000000, 10000000000, "SOUL", "KCAL", 30])
  .spendGas(from)
  .endScript();
// sign & broadcast; read resulting poolId from events / getNextPoolId()

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. Only the pool provider can add liquidity to their own pool.

// Read reserves to project the required B amount
const resA = await readContract("saturnpools", "getPoolReserveA", [poolId]);
const resB = await readContract("saturnpools", "getPoolReserveB", [poolId]);
const tokenA = await readContract("saturnpools", "getPoolTokenA", [poolId]);
const tokenB = await readContract("saturnpools", "getPoolTokenB", [poolId]);

const scaledAddA = await readContract("saturnpools", "scaleUp", [amountA, tokenA]);
const requiredBraw = await readContract("saturnpools", "scaleDown",
  [(scaledAddA * resB) / resA, tokenB]);
const maxB = Math.floor(requiredBraw * 1.01); // 1% slippage

const tx = ScriptBuilder
  .begin()
  .allowGas(from, Address.Null, 100000, 2000)
  .callContract("saturnliquidity", "addLiquidity", [from, poolId, amountA, maxB])
  .spendGas(from)
  .endScript();

removePool(from: address, poolId: number)

Removes a pool entirely. All scaled reserves are paid out to the provider (converted back to raw units), any pending provider fees are auto-claimed, the pool is deactivated, and the SATURN NFT certificate is burned. The pool cannot be removed while it is pawned, locked in a reward campaign, or held by any active bond / rental / option / syndicate.

// Pre-flight checks
const pawned = await readContract("saturnpools", "getPoolPawned", [poolId]);
const campLocks = await readContract("saturnpools", "getPoolCampaignLockCount", [poolId]);
const finLocks = await readContract("saturnpools", "getPoolFinancialLockCount", [poolId]);
if (pawned || campLocks || finLocks) throw new Error("Pool not removable");

const tx = ScriptBuilder
  .begin()
  .allowGas(from, Address.Null, 100000, 3000)
  .callContract("saturnliquidity", "removePool", [from, poolId])
  .spendGas(from)
  .endScript();

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 engine runs the constant-product formula (after the pool fee, provider split, and admin split are taken), then transfers tokenOut to the caller. 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
const best = await readContract("saturnrouter", "getBestPoolForSwap", ["SOUL", "KCAL", amountIn]);
// best is an object or string containing the poolId and expected output

// 2) Compute a slippage-protected minimum
const minOut = Math.floor(expectedOut * 0.99); // 1% slippage

// 3) Submit the swap
const tx = ScriptBuilder
  .begin()
  .allowGas(from, Address.Null, 100000, 2500)
  .callContract("saturnswap", "swap", [from, poolId, amountIn, "SOUL", "KCAL", minOut])
  .spendGas(from)
  .endScript();

getContractAddress(): address

Returns the on-chain address of the SaturnSwap contract. Useful if your frontend needs to display token balances held by the swap engine (for example to debug settled-but-unclaimed fees), or if you're integrating another contract that must transfer tokens here before calling swapFromContract().

const swapAddr = await readContract("saturnswap", "getContractAddress", []);
const balance = await fetchTokenBalance(swapAddr, "SOUL");

claimProviderFees(from: address, poolId: number)

The pool provider calls this to sweep all accumulated provider fees for their pool — both tokens at once. The amounts are scaled down to raw units before being transferred out. The call reverts if the pool currently has an active fee redirect (meaning a bond or rental owns the fee stream right now).

// 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 (pA > 0 || pB > 0) {
  const tx = ScriptBuilder
    .begin()
    .allowGas(from, Address.Null, 100000, 1500)
    .callContract("saturnfees", "claimProviderFees", [from, poolId])
    .spendGas(from)
    .endScript();
}

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

Returns the scaled amount of a specific token currently claimable by the pool's provider. Call this once for tokenA and once for tokenB to show a complete balance. 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"
}

getTotalNftMinted(): number

Total number of SATURN pool NFTs currently in circulation. Equivalent to the total number of active pools (burned NFTs are not counted).

const activePools = 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 a specific pool — read the ROM metadata of each NFT (via Phantasma's NFT API) to get the associated poolId, token pair, and display name.

const script = ScriptBuilder
  .begin()
  .callContract("SATURN", "getUserPools", [userAddress])
  .endScript();
const { decoded } = await api.invokeRawScript("main", script);
// For each returned nftId, fetch the NFT metadata to get poolId:
for (const nftId of decoded) {
  const nft = await api.getNFT("SATURN", nftId);
  console.log("Pool #" + nft.properties.poolId, nft.properties.name);
}

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, Address.Null, 100000, 2500)
  .callContract("saturnrewards", "createCampaign",
    [from, "SOUL", "KCAL", "GHOST", 1000000000, 7 * 86400]) // 7-day GHOST campaign
  .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 added to the campaign's total locked liquidity — the provider's final reward is proportional to this snapshot, not to the pool's future depth. Enrollment locks the pool (cannot change fee, cannot remove) until the reward is claimed or withdrawn.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, Address.Null, 100000, 2000)
  .callContract("saturnrewards", "enrollInCampaign", [from, poolId, campaignId])
  .spendGas(from)
  .endScript();

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

Called after the campaign's end time. Transfers the provider's proportional share of the reward pot (snapshotLiquidity / totalLockedLiquidity × totalReward) and removes the campaign lock from the pool. Can only be called once per enrollment.

const expected = await readContract("saturnrewards", "getExpectedReward", [poolId, campaignId]);
if (expected > 0) {
  const tx = ScriptBuilder
    .begin()
    .allowGas(from, Address.Null, 100000, 2000)
    .callContract("saturnrewards", "claimCampaignReward", [from, poolId, campaignId])
    .spendGas(from)
    .endScript();
}

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

Early exit for a provider who wants out before the campaign ends. Forfeits the pool's reward share — the forfeited amount is absorbed by the remaining participants — and unlocks the pool immediately.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, Address.Null, 100000, 2000)
  .callContract("saturnrewards", "withdrawFromCampaign", [from, poolId, campaignId])
  .spendGas(from)
  .endScript();

endCampaign(from: address, campaignId: number)

Called by the campaign creator at least 30 days after the end time. Marks the campaign inactive and returns any unclaimed reward tokens to the creator. The grace period gives providers plenty of time to claim before the creator can reclaim anything.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, Address.Null, 100000, 2000)
  .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. Parse client-side by splitting on underscores.

const info = await readContract("saturnrewards", "getCampaignInfo", [campaignId]);
// e.g. "pair:KCAL_SOUL_reward:GHOST_total:1000000000_claimed:0_start:1700000000_end:1700604800_active:1_locked:0"

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 snapshot liquidity of every pool currently enrolled in the campaign.

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 every campaignId ever created, including ended ones.

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

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 snapshot liquidity this pool had at the moment it enrolled. 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 the raw reward amount the provider will receive if they claim right now, given the current totalLocked. The number will drift if other pools enroll or withdraw before the campaign ends — always requery just before submitting a claim.

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

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

Iterates every active pool for the token pair and returns the poolId that would give the highest net output after that pool's fee. This is the first call your swap flow should make — pass the result into SaturnSwap.swap().

const poolId = await readContract("saturnrouter", "getBestPoolForSwap",
  ["SOUL", "KCAL", 10000000000]);
if (poolId === 0) throw new Error("No liquidity available");

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, pawned flag, and campaign lock count, packed into a single underscore-delimited string.

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]);

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 — the multiplier used to go from raw units to scaled units.

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 breakdown in one string.

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. Only the creator (from) can later add or remove liquidity.

const tx = sb.begin()
  .allowGas(from)
  .callContract("saturnclpools", "createClPool", [
    from, "SOUL", "KCAL",
    1000000000,   // amountA: 10 SOUL (8-decimal example)
    5000000000,   // amountB: 50 KCAL
    40000000,     // priceMin: 0.4 KCAL/SOUL (× 1e8)
    60000000,     // priceMax: 0.6 KCAL/SOUL (× 1e8)
    30            // feePer10k: 0.3%
  ])
  .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 = sb.begin()
  .allowGas(from)
  .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.

// Read the current price first to estimate required tokenB
const resA = await readContract("saturnclpools", "getClPoolReserveA", [poolId]);
const resB = await readContract("saturnclpools", "getClPoolReserveB", [poolId]);
const addA = 500000000n;
const estimatedB = (addA * BigInt(resB)) / BigInt(resA);
const maxB = estimatedB + (estimatedB / 100n); // +1% slippage

const tx = sb.begin()
  .allowGas(from)
  .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 (feePer10k basis points) is deducted from amountIn before the AMM math runs, and is accumulated in the pool for the provider to claim later. 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.

// Preview the current price, then swap
const price = await readContract("saturnclpools", "getClPoolPrice", [poolId]);
console.log("Current price (scaled 1e8):", price);

const tx = sb.begin()
  .allowGas(from)
  .callContract("saturnclpools", "swapClPool", [
    from, poolId, 100000000, "SOUL", "KCAL", 0
  ])
  .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 = sb.begin()
  .allowGas(from)
  .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:1000000000_resB:5000000000_priceMin:40000000_priceMax:60000000_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 scaled reserve of tokenA. Divide by the token's scale factor to get the user-facing amount.

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". 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|S1abc...|SOUL|KCAL|1000000000|5000000000|40000000|60000000|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 per-chunk slippage guard — if the market moves severely during the stream the chunk executor's call will revert rather than deliver bad fills.

// 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
const minOut     = 0;            // no per-chunk floor
const bounty     = 100;          // 1% bounty to executors

const tx = sb.begin()
  .allowGas(from)
  .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 = sb.begin()
  .allowGas(from)
  .callContract("saturntwamm", "cancelStream", [from, streamId])
  .spendGas(from)
  .endScript();

executeStreamingChunk(from: address, streamId: number)

Executes the next time-proportional chunk of an active stream. Permissionless — any address can call this, not just the stream owner. The chunk size is computed from (totalAmountIn × elapsedSinceStart / duration) minus what has already been streamed, so cumulative integer-rounding error stays at zero; the final chunk settles any residue. The chunk is routed through saturnswap.swapFromContract against the stream's target pool. The executor receives bountyPer10k basis-points of the chunk's gross output, paid immediately; the remainder accumulates for the stream owner to claim. When the last chunk is executed the stream status transitions to 1 (completed) automatically.

// 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) {
  const tx = sb.begin()
    .allowGas(executor)
    .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. The stream does not need to be completed; active, completed, and cancelled streams all allow claims as long as accumulated > 0.

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

getContractVersion(): string

Returns the current TWAMM contract version string.

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. Decremented to zero each time claimStreamingOutput is called.

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 expires. Chunks can still execute after this time to settle residue.

getStreamLastExecutionTime(streamId: number): number

Returns the Unix timestamp of the most recent chunk execution. 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 the per-chunk minimum output slippage guard set when the stream was placed. Zero means no floor.

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.

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. 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), repays the borrowed principal plus the flash fee, and transfers the net profit to from. The transaction reverts atomically if the round-trip yields no profit, the profit is too small to cover the flash fee, or netProfit falls below minNetProfit — so the caller's reserves are never at risk, only their gas. The tokenMid is resolved automatically from poolIdBuy's pair. poolIdBuy and poolIdSell must be different pools and both must contain tokenStart.

const from = "S3...myBotAddress";
const tx = sb.begin()
  .allowGas(from)
  .callContract("saturnflash", "executeFlashArb",
    [from, poolIdBuy, poolIdSell, "SOUL", amountIn, minNetProfit])
  .spendGas(from)
  .endScript();
// returns netProfit (number) — raw units of tokenStart

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 the current raw-unit balance of tokenSymbol held by saturnliquidity — the maximum amount that can be borrowed in a single executeFlashArb call. Always query this before sizing amountIn to avoid an insufficient-liquidity revert.

const max = await readContract("saturnflash", "getMaxBorrowable", ["SOUL"]);
const amountIn = Math.floor(max * 0.5); // use a fraction for safety

getFlashFeePer10k(): number

Returns the current flash fee rate in basis points out of 10,000 (e.g. 5 = 0.05%). This rate is applied to amountIn to determine the fee the executor pays on top of loan repayment.

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. Useful for constructing token-transfer pre-approvals or inspecting on-chain balances.

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 (in raw token units) collected by the protocol admin across all successful arb executions.

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 (in raw token units of tokenStart) paid out to a specific executor across all successful arb executions.

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

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 tx = sb.begin()
  .allowGas(from)
  .callContract("saturnholders", "stake", [from, "SOUL", stakeAmount])
  .spendGas(from)
  .endScript();

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. In v4.5.0, any portion of the stake locked via a saturntaz pledge cannot be unstaked until saturntaz calls unlockPledge.

const from = "S3...userAddress";
const tx = sb.begin()
  .allowGas(from)
  .callContract("saturnholders", "unstake", [from, "SOUL", unstakeAmount])
  .spendGas(from)
  .endScript();

claim(from: address, tokenSymbol: string)

Pays out all pending rewards for from's tokenSymbol stake without altering the stake balance. Reward tokens 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 tx = sb.begin()
  .allowGas(from)
  .callContract("saturnholders", "claim", [from, "SOUL"])
  .spendGas(from)
  .endScript();

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;

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. 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 used in the MasterChef accumulator and also the maximum flash-borrowable amount for saturnstakearb.

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. Use this to enumerate all active staking markets without needing to know the token list in advance.

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 tx = sb.begin()
  .allowGas(from)
  .callContract("saturnholders", "registerStakedToken", ["LEGACY"])
  .spendGas(from)
  .endScript();

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. Useful for token-transfer approvals or direct balance lookups.

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

listBond(from: address, poolId: number, faceValue: number, purchasePrice: number, feeToken: string, durationSeconds: number, mode: number, collateralAmount: number)

Pool provider lists a new bond against one of their pools. faceValue is the max payout to the buyer; purchasePrice is what the buyer pays up front (must be strictly less than faceValue). In HYBRID mode (mode = 2) the provider deposits collateralAmount of feeToken now — this is held as a buffer to guarantee the buyer's payout.

// Hybrid mode bond for pool 42, 1M SOUL face, 900k purchase, 90 day term, 100k collateral
const tx = ScriptBuilder
  .begin()
  .allowGas(from, Address.Null, 100000, 2500)
  .callContract("saturnbonds", "listBond",
    [from, 42, 1000000, 900000, "SOUL", 90 * 86400, 2, 100000])
  .spendGas(from)
  .endScript();

cancelListing(from: address, bondId: number)

Cancel a bond listing before any buyer has purchased it. Returns any deposited collateral back to the issuer.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, Address.Null, 100000, 1500)
  .callContract("saturnbonds", "cancelListing", [from, bondId])
  .spendGas(from)
  .endScript();

purchaseBond(from: address, bondId: number)

Buyer pays the listing's purchasePrice directly to the issuer, becomes the bond holder, starts the term clock, and triggers fee redirection — all swap fees in feeToken now flow to this contract on behalf of the buyer. The pool becomes financially locked until settlement.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, Address.Null, 100000, 2000)
  .callContract("saturnbonds", "purchaseBond", [from, bondId])
  .spendGas(from)
  .endScript();

settleBond(from: address, bondId: number)

Called any time after the bond's maturity. Claims the accumulated fees (plus collateral in hybrid mode), pays up to faceValue to the bond holder, returns any excess to the original issuer, clears the fee redirect, and unlocks the pool. Anyone can call this — in practice the holder does because they want their payout.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, Address.Null, 100000, 2500)
  .callContract("saturnbonds", "settleBond", [from, bondId])
  .spendGas(from)
  .endScript();

transferBond(from: address, to: address, bondId: number)

Secondary-market transfer. The current holder assigns the bond to a different address. Bond must be active; recipient cannot be the current holder. Off-chain payment is up to the two parties.

const tx = ScriptBuilder
  .begin()
  .allowGas(from, Address.Null, 100000, 1500)
  .callContract("saturnbonds", "transferBond", [from, recipientAddress, bondId])
  .spendGas(from)
  .endScript();

getBondInfo(bondId: number): string

Packed string with every top-level bond field — pool, face value, purchase price, fee token, mode, maturity timestamp, status, and collateral. Parse with String.split on underscores.

const info = await readContract("saturnbonds", "getBondInfo", [bondId]);

getBondPoolId(bondId: number): number

Pool the bond is issued against.

const pid = await readContract("saturnbonds", "getBondPoolId", [bondId]);

getBondIssuer(bondId: number): address

Address of the wallet that created the bond listing.

const issuer = await readContract("saturnbonds", "getBondIssuer", [bondId]);

getBondBuyer(bondId: number): address

Current holder of the bond. Null for listings that have not been purchased yet. Updated on transferBond().

const holder = await readContract("saturnbonds", "getBondBuyer", [bondId]);

getBondFaceValue(bondId: number): number

Maximum raw payout the buyer can receive at maturity.

const face = await readContract("saturnbonds", "getBondFaceValue", [bondId]);

getBondPurchasePrice(bondId: number): number

Up-front raw amount the buyer paid (or pays) for the bond.

const price = await readContract("saturnbonds", "getBondPurchasePrice", [bondId]);

getBondFeeToken(bondId: number): string

Symbol of the token the bond is denominated in — purchase price, face value, and collateral are all in this token, and only swap fees accrued in this token are counted toward the payout.

const token = await readContract("saturnbonds", "getBondFeeToken", [bondId]);

getBondCollateral(bondId: number): number

Raw collateral amount posted by the issuer (always 0 in partial mode).

const col = await readContract("saturnbonds", "getBondCollateral", [bondId]);

getBondMode(bondId: number): number

Returns 1 for PARTIAL (no collateral) or 2 for HYBRID (collateral-backed).

const mode = await readContract("saturnbonds", "getBondMode", [bondId]);

getBondStatus(bondId: number): number

Lifecycle state of the bond.

const s = await readContract("saturnbonds", "getBondStatus", [bondId]);

getBondMaturityTime(bondId: number): number

Unix timestamp at which the bond can be settled. While the bond is listed (status 0), this field stores the term duration in seconds — it only becomes an absolute timestamp after purchase.

const maturity = await readContract("saturnbonds", "getBondMaturityTime", [bondId]);

getNextBondId(): number

ID that will be assigned to the next bond listed.

const next = await readContract("saturnbonds", "getNextBondId", []);

getAllBondIds(): number*

Generator yielding every bondId ever created.

const script = ScriptBuilder
  .begin()
  .callContract("saturnbonds", "getAllBondIds", [])
  .endScript();

listForRent(from: address, poolId: number, dailyRate: number, depositRequired: number, minFeePer10k: number, maxFeePer10k: number, minTermDays: number)

Pool provider lists their pool for rent. Saves the current fee rate so it can be restored at end, and defines the renter's operating envelope.

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnrental", "listForRent", [
    from,
    poolId,
    dailyRateSoul,      // raw SOUL per day
    depositSoul,        // raw SOUL deposit
    25,                 // 0.25% min fee
    300,                // 3.00% max fee
    7                   // minimum 7-day term
  ])
  .spendGas(from)
  .endScript();

cancelListing(from: address, rentalId: number)

Pool provider cancels a listing that has not yet been rented. Only works while status = 0 (listed).

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnrental", "cancelListing", [from, rentalId])
  .spendGas(from)
  .endScript();

rentPool(from: address, rentalId: number)

Renter takes the listing. Pays deposit + (dailyRate * minTermDays) in SOUL, gains fee control, and the pool's fee stream is redirected to the rental escrow.

// Always preflight: read dailyRate + deposit + minTermDays first
const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnrental", "rentPool", [from, rentalId])
  .spendGas(from)
  .endScript();

extendRental(from: address, rentalId: number, additionalDays: number)

Renter prepays additional days before the current paid-through time. Avoids losing fee control when the term expires.

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnrental", "extendRental", [from, rentalId, 30]) // +30 days
  .spendGas(from)
  .endScript();

adjustFee(from: address, rentalId: number, newFeePer10k: number)

Renter changes the pool's fee rate, within the [minFee, maxFee] window set at list time. This is the core lever of the franchise model — raise fees to earn more per swap, lower them to attract volume.

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnrental", "adjustFee", [from, rentalId, 150]) // 1.50%
  .spendGas(from)
  .endScript();

claimRentalFees(from: address, rentalId: number)

Renter harvests the swap fees accumulated on both sides of the pool while the rental has been active.

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnrental", "claimRentalFees", [from, rentalId])
  .spendGas(from)
  .endScript();

collectRent(from: address, rentalId: number)

Pool provider withdraws rent that the renter has already prepaid. Can be called at any time while the rental is active.

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnrental", "collectRent", [from, rentalId])
  .spendGas(from)
  .endScript();

endRental(from: address, rentalId: number)

Either party settles the rental once the paid-through time has passed. Finalizes fees to the renter, pays remaining rent to the owner, refunds the deposit, restores the original fee rate, and unlocks the pool.

// Check readiness first
const pt = await readContract("saturnrental", "getRentalPaidThroughTime", [rentalId]);
if (Date.now() / 1000 < pt) throw new Error("Not expired yet");

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnrental", "endRental", [from, rentalId])
  .spendGas(from)
  .endScript();

getRentalInfo(rentalId: number): string

One-shot status snapshot used by marketplace UIs. Returns an underscore-delimited string with the key fields.

const raw = await readContract("saturnrental", "getRentalInfo", [rentalId]);
const parts = Object.fromEntries(
  raw.split("_").map(kv => kv.split(":"))
);
// parts.pool, parts.rate, parts.deposit, parts.minFee, parts.maxFee, parts.status, parts.paidThrough

getRentalPoolId(rentalId: number): number

Returns the poolId this rental is attached to.

const poolId = await readContract("saturnrental", "getRentalPoolId", [rentalId]);

getRentalOwner(rentalId: number): address

Returns the pool provider who listed this rental.

const owner = await readContract("saturnrental", "getRentalOwner", [rentalId]);

getRentalOperator(rentalId: number): address

Returns the address currently renting the pool, or @null if the listing has not been rented yet.

const renter = await readContract("saturnrental", "getRentalOperator", [rentalId]);

getRentalDailyRate(rentalId: number): number

Returns the daily rent, in raw SOUL.

const perDay = await readContract("saturnrental", "getRentalDailyRate", [rentalId]);

getRentalStatus(rentalId: number): number

Returns the lifecycle status code.

const status = await readContract("saturnrental", "getRentalStatus", [rentalId]);

getRentalPaidThroughTime(rentalId: number): number

Unix timestamp up to which rent has been prepaid. endRental cannot be called before this time.

const pt = await readContract("saturnrental", "getRentalPaidThroughTime", [rentalId]);
const secondsLeft = pt - Math.floor(Date.now() / 1000);

getNextRentalId(): number

Returns the rentalId that will be assigned to the next listing.

const next = await readContract("saturnrental", "getNextRentalId", []);

getAllRentalIds(): number*

Generator yielding every rentalId ever created.

const script = ScriptBuilder
  .begin()
  .callContract("saturnrental", "getAllRentalIds", [])
  .endScript();

writeOption(from: address, poolId: number, targetFeePer10k: number, premium: number, premiumToken: string, durationSeconds: number)

Pool provider creates and lists a new option. Captures the pool's current fee rate so it can be restored when the option unwinds.

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnfeeopts", "writeOption", [
    from,
    poolId,
    50,              // target 0.50% fee
    premiumRaw,      // e.g. 100 SOUL raw
    "SOUL",
    604800           // 7 day window
  ])
  .spendGas(from)
  .endScript();

cancelListing(from: address, optionId: number)

Option writer cancels a listing that has not yet been bought. Only works while status = 0 (listed).

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnfeeopts", "cancelListing", [from, optionId])
  .spendGas(from)
  .endScript();

buyOption(from: address, optionId: number)

Buyer pays the premium to the writer and activates the option. The duration window starts now and the pool gets a financial lock.

// Always preflight to show the buyer total cost
const premium = await readContract("saturnfeeopts", "getOptionPremium", [optionId]);

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnfeeopts", "buyOption", [from, optionId])
  .spendGas(from)
  .endScript();

exerciseOption(from: address, optionId: number)

Buyer snaps the pool's fee rate to the option's target. Can be called any time before the option expires, even multiple times (each call just re-applies the same rate).

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnfeeopts", "exerciseOption", [from, optionId])
  .spendGas(from)
  .endScript();

releaseOption(from: address, optionId: number)

Buyer voluntarily gives up fee control before expiry. Useful if the buyer is done with the position and wants to unlock the pool so the writer can list again.

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnfeeopts", "releaseOption", [from, optionId])
  .spendGas(from)
  .endScript();

expireOption(from: address, optionId: number)

Anyone can trigger expiry after the option's endTime has passed. Typically called by the writer to reclaim full fee control and unlock the pool.

const endTime = await readContract("saturnfeeopts", "getOptionEndTime", [optionId]);
if (Date.now() / 1000 < endTime) throw new Error("Not expired yet");

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnfeeopts", "expireOption", [from, optionId])
  .spendGas(from)
  .endScript();

getOptionInfo(optionId: number): string

One-shot status snapshot used by options marketplace UIs. Returns an underscore-delimited string with the key fields.

const raw = await readContract("saturnfeeopts", "getOptionInfo", [optionId]);
const parts = Object.fromEntries(raw.split("_").map(kv => kv.split(":")));
// parts.pool, parts.targetFee, parts.premium, parts.token, parts.end, parts.exercised, parts.status

getOptionPoolId(optionId: number): number

Returns the poolId the option is written on.

const poolId = await readContract("saturnfeeopts", "getOptionPoolId", [optionId]);

getOptionWriter(optionId: number): address

Returns the pool provider who wrote (sold) the option.

const writer = await readContract("saturnfeeopts", "getOptionWriter", [optionId]);

getOptionBuyer(optionId: number): address

Returns the address holding the option, or @null while still in listed state.

const buyer = await readContract("saturnfeeopts", "getOptionBuyer", [optionId]);

getOptionTargetFee(optionId: number): number

Returns the fee rate (per 10,000) that exerciseOption will set on the pool.

const target = await readContract("saturnfeeopts", "getOptionTargetFee", [optionId]);
const pct = (target / 100).toFixed(2) + "%";

getOptionPremium(optionId: number): number

Returns the premium price, in raw units of premiumToken.

const premium = await readContract("saturnfeeopts", "getOptionPremium", [optionId]);

getOptionStatus(optionId: number): number

Returns the lifecycle status code.

const status = await readContract("saturnfeeopts", "getOptionStatus", [optionId]);

getOptionEndTime(optionId: number): number

Returns the Unix timestamp when the option expires. Before buy, this field holds the duration in seconds — only meaningful once status = 1.

const end = await readContract("saturnfeeopts", "getOptionEndTime", [optionId]);
const secondsLeft = end - Math.floor(Date.now() / 1000);

getNextOptionId(): number

Returns the optionId that will be assigned to the next writeOption call.

const next = await readContract("saturnfeeopts", "getNextOptionId", []);

getAllOptionIds(): number*

Generator yielding every optionId ever created.

const script = ScriptBuilder
  .begin()
  .callContract("saturnfeeopts", "getAllOptionIds", [])
  .endScript();

createSyndicate(from: address, tokenA: string, tokenB: string, targetA: number, targetB: number, feePer10k: number)

Anyone can open a new syndicate funding round for a given token pair. Sets the fundraising targets and the eventual pool's fee rate.

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnsyndicate", "createSyndicate", [
    from,
    "SOUL",
    "KCAL",
    100000_00000000,   // target 100000 SOUL raw
    500000_00000000,   // target 500000 KCAL raw
    30                 // 0.30% pool fee
  ])
  .spendGas(from)
  .endScript();

cancelSyndicate(from: address, syndicateId: number)

Creator cancels a syndicate before it has been activated. Contributors must then call withdrawContribution to pull their tokens back.

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnsyndicate", "cancelSyndicate", [from, syndicateId])
  .spendGas(from)
  .endScript();

contribute(from: address, syndicateId: number, amountA: number, amountB: number)

Investor deposits both tokens into an open syndicate. Each contribution may not exceed the remaining distance to its target; repeated contributions from the same address are aggregated.

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnsyndicate", "contribute", [
    from,
    syndicateId,
    amountARaw,
    amountBRaw
  ])
  .spendGas(from)
  .endScript();

withdrawContribution(from: address, syndicateId: number)

Contributor reclaims their deposit. Works while the syndicate is still in funding (status 0) or after it has been cancelled (status 3). Withdraws the entire outstanding contribution in one call.

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnsyndicate", "withdrawContribution", [from, syndicateId])
  .spendGas(from)
  .endScript();

activateSyndicate(from: address, syndicateId: number)

Creator converts the pooled capital into a real pool. The syndicate contract itself becomes the pool provider, and the pool is immediately financial-locked so nobody can accidentally remove it.

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnsyndicate", "activateSyndicate", [from, syndicateId])
  .spendGas(from)
  .endScript();

claimSyndicateReward(from: address, syndicateId: number)

Member harvests their proportional share of fees accrued on the syndicate pool. Share is (contribA * 10000) / totalRaisedA basis points.

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnsyndicate", "claimSyndicateReward", [from, syndicateId])
  .spendGas(from)
  .endScript();

dissolveSyndicate(from: address, syndicateId: number)

Creator winds the syndicate down. Pool's financial lock is released, any pending fees are swept into the syndicate contract, and the pool reserves are cleared. Members then call claimDissolution to get their share of what remains.

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnsyndicate", "dissolveSyndicate", [from, syndicateId])
  .spendGas(from)
  .endScript();

claimDissolution(from: address, syndicateId: number)

After a syndicate has been dissolved, each member claims their proportional share of the remaining reserves in both tokens. Single-claim only — the member entry is zeroed on success.

const script = ScriptBuilder
  .begin()
  .allowGas(from, null, gasPrice, gasLimit)
  .callContract("saturnsyndicate", "claimDissolution", [from, syndicateId])
  .spendGas(from)
  .endScript();

getSyndicateInfo(syndicateId: number): string

One-shot status snapshot for marketplace UIs. Returns an underscore-delimited string with the key fields.

const raw = await readContract("saturnsyndicate", "getSyndicateInfo", [syndicateId]);
const parts = Object.fromEntries(raw.split("_").map(kv => kv.split(":")));

getSyndicateTokenA(syndicateId: number): string

Returns tokenA symbol for this syndicate.

const tA = await readContract("saturnsyndicate", "getSyndicateTokenA", [syndicateId]);

getSyndicateTokenB(syndicateId: number): string

Returns tokenB symbol for this syndicate.

const tB = await readContract("saturnsyndicate", "getSyndicateTokenB", [syndicateId]);

getSyndicatePoolId(syndicateId: number): number

Returns the poolId created by activateSyndicate, or 0 if not yet active.

const poolId = await readContract("saturnsyndicate", "getSyndicatePoolId", [syndicateId]);

getSyndicateStatus(syndicateId: number): number

Returns the lifecycle status code.

const status = await readContract("saturnsyndicate", "getSyndicateStatus", [syndicateId]);

getSyndicateRaisedA(syndicateId: number): number

Returns total raw tokenA raised so far.

const raisedA = await readContract("saturnsyndicate", "getSyndicateRaisedA", [syndicateId]);

getSyndicateRaisedB(syndicateId: number): number

Returns total raw tokenB raised so far.

const raisedB = await readContract("saturnsyndicate", "getSyndicateRaisedB", [syndicateId]);

getSyndicateMemberCount(syndicateId: number): number

Returns the number of distinct contributors with currently non-zero recorded contributions.

const members = await readContract("saturnsyndicate", "getSyndicateMemberCount", [syndicateId]);

getNextSyndicateId(): number

Returns the syndicateId that will be assigned to the next createSyndicate call.

const next = await readContract("saturnsyndicate", "getNextSyndicateId", []);

getMemberContribution(syndicateId: number, member: address): string

Returns a single member's outstanding recorded contribution in both tokens. Used by the 'My contribution' panel.

const raw = await readContract("saturnsyndicate", "getMemberContribution", [syndicateId, member]);
const [a, b] = raw.split("_").map(p => p.split(":")[1]);

getAllSyndicateIds(): number*

Generator yielding every syndicateId ever created.

const script = ScriptBuilder
  .begin()
  .callContract("saturnsyndicate", "getAllSyndicateIds", [])
  .endScript();

createLaunchpad(from: address, tokenA: string, tokenQuote: string, tokensForSale: number, quotePerA: number, poolFeePer10k: number, minFillPer10k: number, minCommitQuote: number, endTime: number)

Creates a new fixed-price launchpad. The creator deposits the full `tokensForSale` amount of `tokenA` into escrow at creation time. The sale runs until `endTime` (max 14 days from now) or until the allocation sells out. On activation the sale proceeds and unsold token A seed a Saturn pool at the fee tier set by `poolFeePer10k`. Call `saturnadmin.getMinPoolFeePer10k()` and `getMaxPoolFeePer10k()` to clamp the fee input before submitting. `minFillPer10k` controls the minimum fill required to activate (1000 = 10%, 10000 = 100% sellout required). `minCommitQuote` is the smallest individual commitment accepted.

const from = "S3myAddress...";
const tx = sb.begin()
  .allowGas(from)
  .callContract("saturnlaunchpad", "createLaunchpad", [
    from,
    "MYTOKEN",     // tokenA
    "SOUL",        // tokenQuote
    1000000,       // 1,000,000 MYTOKEN for sale
    100,           // 100 SOUL per 1 MYTOKEN
    30,            // 0.3% pool fee
    5000,          // 50% minimum fill to activate
    1000,          // min 1,000 SOUL per commit
    Math.floor(Date.now() / 1000) + 86400 * 7  // 7-day window
  ])
  .spendGas(from)
  .endScript();

cancelLaunchpad(from: address, launchpadId: number)

Allows the creator to abort their launchpad before any buyers have committed. Immediately returns all escrowed tokenA to the creator and sets the launchpad status to Cancelled (3). Buyers can still call `withdrawCommit` after cancellation, but because no one can commit once the sale ends this is primarily a pre-buyer cleanup path. If buyers have already committed use `proposeDissolve` / `executeDissolve` instead.

const tx = sb.begin()
  .allowGas(from)
  .callContract("saturnlaunchpad", "cancelLaunchpad", [from, launchpadId])
  .spendGas(from)
  .endScript();

commit(from: address, launchpadId: number, amountQuote: number)

Commits quote tokens to a live launchpad, reserving the equivalent tokenA allocation at the fixed price. `amountQuote` must be a multiple of `quotePerA` so the allocation is exact. Multiple calls from the same address accumulate; the buyer's total commitment determines their pool share weight if the launch activates. Buyers cannot commit after `endTime` even if the launchpad status is still 0.

const from = "S3buyerAddress...";
const tx = sb.begin()
  .allowGas(from)
  .callContract("saturnlaunchpad", "commit", [from, 3, 5000])
  .spendGas(from)
  .endScript();

withdrawCommit(from: address, launchpadId: number)

Withdraws the caller's entire committed quote amount and re-opens their reserved tokenA allocation for other buyers. Can be called while the launchpad is in funding state (status 0) — allowing buyers to back out before activation — or after cancellation (status 3). Clears vote state and reward debt so the address is fully reset. If the launchpad is already active (status 1) use `proposeDissolve` instead.

const tx = sb.begin()
  .allowGas(from)
  .callContract("saturnlaunchpad", "withdrawCommit", [from, launchpadId])
  .spendGas(from)
  .endScript();

activateLaunchpad(from: address, launchpadId: number)

Called by the creator to finalize a successful launch. Transfers the raised quote tokens and the sold tokenA into a new Saturn pool, registers the pool, and locks it under the launchpad's financial lock. The creator's share weight is set to equal the total raised quote (matching buyers 1:1 so the creator holds ~50% of pool fees). Any unsold tokenA is returned to the creator immediately. After activation all participants earn trading fees proportional to their share weight.

const tx = sb.begin()
  .allowGas(creatorAddress)
  .callContract("saturnlaunchpad", "activateLaunchpad", [creatorAddress, launchpadId])
  .spendGas(creatorAddress)
  .endScript();

dissolveViaTimeout(from: address, launchpadId: number)

Anyone can call this once `endTime` has passed and the launchpad is still in funding state (status 0) without having been activated. Marks the launchpad as dissolved (status 2) and triggers the refund path. Useful when the creator is absent or a buyer wants to recover their funds immediately after the window expires. Does not require a proposal or vote since the timeout is the objective trigger.

const tx = sb.begin()
  .allowGas(from)
  .callContract("saturnlaunchpad", "dissolveViaTimeout", [from, launchpadId])
  .spendGas(from)
  .endScript();

proposeDissolve(from: address, launchpadId: number)

Opens a dissolution proposal for an active or funding launchpad. The proposer must be a buyer (committed quote > 0); the creator cannot propose. The proposer's committed quote is automatically counted as the first vote. A 72-hour timelock (259,200 seconds) starts from proposal time before `executeDissolve` can be called. Only one proposal can be open at a time.

const tx = sb.begin()
  .allowGas(buyerAddress)
  .callContract("saturnlaunchpad", "proposeDissolve", [buyerAddress, launchpadId])
  .spendGas(buyerAddress)
  .endScript();

voteDissolve(from: address, launchpadId: number)

Adds the caller's committed quote weight to the open dissolution vote. Each buyer can vote once. Votes are weighted by the buyer's committed quote amount so larger positions carry more weight. A strict majority of total buyer stake (> 50%) is needed for `executeDissolve` to succeed.

const tx = sb.begin()
  .allowGas(buyerAddress)
  .callContract("saturnlaunchpad", "voteDissolve", [buyerAddress, launchpadId])
  .spendGas(buyerAddress)
  .endScript();

executeDissolve(from: address, launchpadId: number)

Executes an approved dissolution proposal once the 72-hour timelock has elapsed and a strict majority of buyer stake has voted yes. For an active launchpad (status 1) this harvests any pending fees, removes pool reserves, and makes the funds claimable via `claimDissolution`. For a funding-state launchpad it simply marks it dissolved, and buyers use `claimFundingRefund`.

// Check readiness first
const earliestExec = await readContract("saturnlaunchpad", "getDissolveEarliestExecute", [launchpadId]);
const votes = await readContract("saturnlaunchpad", "getDissolveVotes", [launchpadId]);
const raised = await readContract("saturnlaunchpad", "getLaunchpadRaisedQuote", [launchpadId]);
// votes * 2 > raised => majority confirmed

const tx = sb.begin()
  .allowGas(buyerAddress)
  .callContract("saturnlaunchpad", "executeDissolve", [buyerAddress, launchpadId])
  .spendGas(buyerAddress)
  .endScript();

claimLaunchpadReward(from: address, launchpadId: number)

Harvests accumulated trading-fee rewards for a participant in an active launchpad (status 1). Both the creator and buyers earn fees proportional to their share weight (buyers: their committed quote; creator: an equal weight to the total raised quote, set at activation). Triggers a fee harvest from the underlying pool before computing pending amounts, so the payout reflects fees earned up to this block. Can be called as often as desired.

const tx = sb.begin()
  .allowGas(from)
  .callContract("saturnlaunchpad", "claimLaunchpadReward", [from, launchpadId])
  .spendGas(from)
  .endScript();

claimDissolution(from: address, launchpadId: number)

Claims a participant's share of the pool reserves after a post-activation dissolution (status 2 with creatorShareWeight > 0). Each participant receives their proportional share of dissolved tokenA and tokenQuote reserves plus any uncollected fee rewards. The creator and each buyer call this independently. This path is only valid for launchpads that were activated before being dissolved; use `claimFundingRefund` for pre-activation dissolutions.

const tx = sb.begin()
  .allowGas(from)
  .callContract("saturnlaunchpad", "claimDissolution", [from, launchpadId])
  .spendGas(from)
  .endScript();

claimFundingRefund(from: address, launchpadId: number)

Refunds participants after a pre-activation dissolution (status 2, creatorShareWeight == 0) — i.e. the launchpad was dissolved by timeout or vote before `activateLaunchpad` was ever called. The creator reclaims their full escrowed tokenA; each buyer reclaims their full committed tokenQuote. The original `tokensForSale` value is preserved for indexers (v4.1.1 audit fix) via a dedicated reclaim flag rather than zeroing the field.

// Creator reclaims their tokenA:
const creatorTx = sb.begin()
  .allowGas(creatorAddress)
  .callContract("saturnlaunchpad", "claimFundingRefund", [creatorAddress, launchpadId])
  .spendGas(creatorAddress)
  .endScript();

// Buyer reclaims their tokenQuote:
const buyerTx = sb.begin()
  .allowGas(buyerAddress)
  .callContract("saturnlaunchpad", "claimFundingRefund", [buyerAddress, launchpadId])
  .spendGas(buyerAddress)
  .endScript();

getContractVersion(): string

Returns the contract version string. Use to verify which deployment you are talking to.

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

getLaunchpadInfo(launchpadId: number): string

Returns a packed string summary of a launchpad's key parameters in one call, avoiding N individual round-trips. Format: `tokenA:<sym>_tokenQuote:<sym>_forSale:<n>_price:<n>_sold:<n>_raised:<n>_status:<n>_pool:<n>_buyers:<n>`. Status codes: 0 = Funding, 1 = Active, 2 = Dissolved, 3 = Cancelled.

const info = await readContract("saturnlaunchpad", "getLaunchpadInfo", [3]);
// "tokenA:MYTOKEN_tokenQuote:SOUL_forSale:1000000_price:100_sold:600000_raised:60000000_status:0_pool:0_buyers:4"

getLaunchpadCreator(launchpadId: number): address

Returns the address that created the launchpad.

getLaunchpadTokenA(launchpadId: number): string

Returns the symbol of the token being sold.

getLaunchpadTokenQuote(launchpadId: number): string

Returns the symbol of the quote token buyers pay with.

getLaunchpadTokensForSale(launchpadId: number): number

Returns the original total tokenA amount offered. This field retains its original value even after dissolution (v4.1.1 audit fix).

getLaunchpadQuotePerA(launchpadId: number): number

Returns the fixed price: how many raw units of tokenQuote purchase one raw unit of tokenA.

getLaunchpadPoolFeePer10k(launchpadId: number): number

Returns the trading fee rate (basis points per 10,000) configured for the post-launch pool.

getLaunchpadMinFillPer10k(launchpadId: number): number

Returns the minimum fill threshold per 10,000 of tokensForSale required to activate.

getLaunchpadMinCommitQuote(launchpadId: number): number

Returns the minimum quote amount accepted per individual commit call.

getLaunchpadEndTime(launchpadId: number): number

Returns the Unix timestamp at which the funding window closes. Commits are rejected at or after this time.

getLaunchpadSoldA(launchpadId: number): number

Returns how many raw units of tokenA have been reserved by buyers so far.

getLaunchpadRaisedQuote(launchpadId: number): number

Returns the total raw units of tokenQuote committed by all buyers. This doubles as the total buyer share weight.