# Saturn DEX — Developer Documentation

> Saturn is a modular, fully on-chain decentralized exchange (DEX) and lending protocol built on the Phantasma blockchain. This documents every public smart-contract method that developers and AI agents can call to build on Saturn. Two products: v4 (30 modular contracts across core DEX, advanced pools & capital, financial products, agent automation, and lending) and v3 (the legacy monolithic SATRN contract). Read methods are free to call; write methods require the caller's wallet signature (witness). Address each contract by its lowercase symbol (e.g. saturnrouter, saturnswap, saturnmarket) or SATRN for v3.

## Launch the app
- [Saturn DEX v4 — Phantasma mainnet](https://m4.saturnx.cc/)
- [Saturn DEX v3 — Phantasma mainnet](https://m3.saturnx.cc/)
- [Saturn DEX v4 — devnet](https://d4.saturnx.cc/)
- [Saturn DEX v3 — devnet](https://d3.saturnx.cc/)

## Documentation
- [Interactive docs](https://devops.saturnx.cc/): searchable v3/v4 reference
- [Full single-page reference (HTML)](https://devops.saturnx.cc/reference.html): every contract and method
- [Full reference for LLMs (Markdown)](https://devops.saturnx.cc/llms-full.txt): complete method-by-method API
- [Example scripts (GitHub)](https://github.com/Infinite-Star-Studios/SaturnDex4ExampleScripts): ready-to-run scripts for every contract

## How to call Saturn contracts
> Use phantasma-sdk-ts (or the Poltergeist / Ecto wallets). To READ: build a script with ScriptBuilder.callContract(contractId, method, [args]) and call api.invokeRawScript('main', script), then decode the result. To WRITE: build a transaction that calls the method with its args; the user signs and their wallet becomes the on-chain witness. Gas is paid in KCAL on Phantasma.

## Saturn DEX v4 contracts (30)

### Core DEX
- [SaturnAdmin (`saturnadmin`)](https://devops.saturnx.cc/reference.html#saturnadmin) — Protocol Configuration: Central configuration hub.
- [SaturnPools (`saturnpools`)](https://devops.saturnx.cc/reference.html#saturnpools) — Pool Registry & Scaling: Canonical source of every pool in the protocol.
- [SaturnLiquidity (`saturnliquidity`)](https://devops.saturnx.cc/reference.html#saturnliquidity) — Pool Creation & Liquidity: The single entry point for creating a new pool, adding liquidity to your own pool, and removing a pool entirely.
- [SaturnSwap (`saturnswap`)](https://devops.saturnx.cc/reference.html#saturnswap) — AMM Swap Engine: The hot path of the DEX.
- [SaturnFees (`saturnfees`)](https://devops.saturnx.cc/reference.html#saturnfees) — Provider Fee Vault: Holds the provider's share of every swap fee until it is claimed.
- [SATURN (`SATURN`)](https://devops.saturnx.cc/reference.html#SATURN) — Pool Ownership NFT: The SATURN token is a non-fungible certificate representing ownership of a pool.
- [SaturnRewards (`saturnrewards`)](https://devops.saturnx.cc/reference.html#saturnrewards) — Liquidity Mining Campaigns: Anyone can fund a reward campaign for a specific token pair.
- [SaturnRouter (`saturnrouter`)](https://devops.saturnx.cc/reference.html#saturnrouter) — Router & Aggregated Views: The recommended entry point for any frontend or SDK.

### Advanced Pools & Capital
- [SaturnCLPools (`saturnclpools`)](https://devops.saturnx.cc/reference.html#saturnclpools) — Concentrated Liquidity Pools: Range-bound AMM that allows liquidity providers to concentrate capital within a chosen price band (priceMin–priceMax), dramatically increasing capita…
- [SaturnTWAMM (`saturntwamm`)](https://devops.saturnx.cc/reference.html#saturntwamm) — Time-Weighted Average Market Maker: Sandwich-resistant streaming swap engine.
- [SaturnFlash (`saturnflash`)](https://devops.saturnx.cc/reference.html#saturnflash) — Flash Loans & Flash Arbitrage: Executes atomic two-pool flash arbitrage using idle liquidity borrowed from saturnliquidity.
- [SaturnHolders (`saturnholders`)](https://devops.saturnx.cc/reference.html#saturnholders) — Holder Rewards (Stake-to-Earn): MasterChef-style stake-to-earn vault that distributes a slice of every swap's fee to token holders pro-rata by stake.

### Financial Products
- [SaturnBonds (`saturnbonds`)](https://devops.saturnx.cc/reference.html#saturnbonds) — Securitized Fee Streams: Providers can sell the future provider-fee stream of a pool as a fixed-yield bond.
- [SaturnRental (`saturnrental`)](https://devops.saturnx.cc/reference.html#saturnrental) — Pool Rental Market: Franchise model for pools.
- [SaturnFeeOptions (`saturnfeeopts`)](https://devops.saturnx.cc/reference.html#saturnfeeopts) — Fee Rate Options: Derivatives on pool fee rates.
- [SaturnSyndicate (`saturnsyndicate`)](https://devops.saturnx.cc/reference.html#saturnsyndicate) — Liquidity Syndicate: Pool crowdfunding.
- [SaturnLaunchpad (`saturnlaunchpad`)](https://devops.saturnx.cc/reference.html#saturnlaunchpad) — Fixed-Price Token Launches: SaturnLaunchpad lets any developer or project creator run a fixed-price token sale (launchpad) that, on success, bootstraps a Saturn DEX liquidity po…

### Agent Automation
- [SaturnArbitrage (`saturnarb`)](https://devops.saturnx.cc/reference.html#saturnarb) — Flash Arbitrage Engine: Atomic cross-pool arbitrage for agents.
- [SaturnLimit (`saturnlimit`)](https://devops.saturnx.cc/reference.html#saturnlimit) — On-Chain Limit Orders: Set-and-forget limit orders.
- [SaturnPredict (`saturnpredict`)](https://devops.saturnx.cc/reference.html#saturnpredict) — Pool Performance Prediction Market: Bet on whether a pool's on-chain metric will exceed a threshold by a set deadline.
- [SaturnVaults (`saturnvaults`)](https://devops.saturnx.cc/reference.html#saturnvaults) — Agent Strategy Vaults: Robo-advisor vaults for DeFi.
- [SaturnStakeArb (`saturnstakearb`)](https://devops.saturnx.cc/reference.html#saturnstakearb) — Permissionless Stake-Arbitrage: Permissionless arbitrage engine that lets any bot atomically borrow idle capital from saturnholders' staked pool, round-trip it across two Saturn poo…

### Lending Protocol
- [SaturnLendCfg (`saturnlendcfg`)](https://devops.saturnx.cc/reference.html#saturnlendcfg) — Lending Protocol Configuration: The single source-of-truth for every tunable parameter in the Saturn Lending protocol, which is built on top of Saturn DEX v3 and v4.
- [SaturnCredit (`saturncredit`)](https://devops.saturnx.cc/reference.html#saturncredit) — Borrower Credit Score (0–1000): Tracks every borrower's on-chain credit profile — a composite score from 0 to 1000 built from time in the system, on-time repayments, late payments,…
- [SaturnVault (`saturnvault`)](https://devops.saturnx.cc/reference.html#saturnvault) — Collateral Vault (LP-backed): Custodian for all loan collateral on the Saturn lending protocol.
- [SaturnLoans (`saturnloans`)](https://devops.saturnx.cc/reference.html#saturnloans) — Loan Ledger & Lifecycle: Central on-chain ledger for every loan in the Saturn lending protocol.
- [SaturnAuto (`saturnauto`)](https://devops.saturnx.cc/reference.html#saturnauto) — Automatic Lending (Disabled in v1.0): Protocol-managed lending reserve with algorithmic loan origination.
- [SaturnMarket (`saturnmarket`)](https://devops.saturnx.cc/reference.html#saturnmarket) — P2P Lending Marketplace: The primary developer entry-point for Saturn Lending v1.0.
- [SaturnDexAdapt (`saturndexadapt`)](https://devops.saturnx.cc/reference.html#saturndexadapt) — Dual-DEX Pricing Adapter (v3 + v4): Unified pricing and pool-validation bridge between the Saturn Lending protocol and both DEX generations: Saturn DEX v3 (SATRN string-keyed pools, LP…
- [SaturnTaz (`saturntaz`)](https://devops.saturnx.cc/reference.html#saturntaz) — TAZ Rewards & RA Pledging: Awards TAZ governance tokens on every fully-repaid loan, split 30% to the borrower, 30% to the lender, and 40% to the lender's active RA pledgers (v1…

## Saturn DEX v3 contracts (1)
- [Saturn DEX v3 (SATRN) (`SATRN`)](https://devops.saturnx.cc/reference.html#SATRN) — Monolithic v3 AMM — pools, swaps, liquidity NFTs, rewards: The legacy Saturn DEX, still live on Phantasma mainnet as a single self-contained contract (SATRN).

## Community
- [Telegram](https://t.me/saturnxdex)
- [Example scripts on GitHub](https://github.com/Infinite-Star-Studios/SaturnDex4ExampleScripts)