Build on routr.

Overview

routr is one NEAR contract that holds two registries: platforms (a launchpad, a wallet, any front end that opens markets) and pools, one per token, quote and platform. A pool is a constant-product market with a virtual quote reserve: the token side is seeded once, there are no LP shares and no liquidity withdrawal, and the quote side starts from a virtual reserve that, with the seed, sets the opening price. Swaps are a single ft_transfer_call. Fees are booked per account at swap time and paid out by anyone.

Concepts

Platform

A registered id (for example fastr) with an owner, a fee recipient, a creator_bps and a builder_bps. Registration is open to anyone and costs the record's storage plus a 0.5 NEAR bond that becomes the platform's storage credit. A platform can name up to 8 pool_creators (usually its factory) so nobody else opens pools under its id, and up to 32 approved builders it pays for routing orders.

Pool key

Every pool has a lookup key token|quote|platform_id that is known before the pool exists, so a token contract can embed its own route at creation. Methods that take a pool_id accept the numeric id or the key.

Curve

Price follows x · (y_real + y_virtual) = k. The seed amount and virtual_quote set the opening price (virtual_quote / seed). Sales pay out of the real quote reserve only, never the virtual one. If tokens exist outside the pool that were not bought from it, selling them can take the price below the opening price. A buy that would push the quote reserve past a fixed bound is refused, which bounds the arithmetic on that path.

Frozen terms

At create_pool the pool copies the protocol share, the protocol recipient, the platform recipient, creator_bps and builder_bps; the caller sets fee_bps. Later changes to the platform or the protocol apply to new pools only. The creator can hand its entitlement to another account, and the platform's list of approved builders applies to all its pools at once.

Quickstart

A launchpad's full path with near-api-js: register once, then per launch create the pool, seed it, quote and route a trade, and claim fees. Run it against testnet with ROUTR=routr-dev.testnet.

/**
 * routr quickstart for a launchpad (NEAR, near-api-js v5): register your platform once, then per launch
 * create the pool, seed it with the token supply, quote and route a first trade, and claim fees.
 *
 *   npm i near-api-js tsx
 *   ROUTR=routr-dev.testnet PLATFORM=mypad ACCOUNT=mypad.testnet npx tsx quickstart.ts
 *
 * Every call below is one contract method; the contract's own docs are in contracts/routr/src/lib.rs.
 * Amounts are strings of raw units (yocto for wNEAR). Pools are addressable by their key
 * `${token}|${quote}|${platform}` before they exist, so a token can carry its own route.
 */
import { connect, keyStores, Account, utils } from "near-api-js";

const ROUTR = process.env.ROUTR ?? "routr-dev.testnet";
const PLATFORM = process.env.PLATFORM ?? "mypad";
const ACCOUNT = process.env.ACCOUNT!; // your platform's account (its factory/locker seeds pools)
const WRAP = "wrap.testnet";
const TGAS = (n: number) => BigInt(n) * 10n ** 12n;
const NEAR = (n: string) => utils.format.parseNearAmount(n)!;

async function main() {
  const near = await connect({
    networkId: "testnet",
    nodeUrl: "https://rpc.testnet.fastnear.com",
    keyStore: new keyStores.UnencryptedFileSystemKeyStore(`${process.env.HOME}/.near-credentials`),
  });
  const me = await near.account(ACCOUNT);
  const view = (method: string, args: object) => me.viewFunction({ contractId: ROUTR, methodName: method, args });

  // 1. Register the platform once: 70% of the platform's part to each pool's creator, 5% to approved builders,
  //    only this account may create pools under the id. The 0.5 NEAR bond is the platform's storage credit for
  //    the claim keys its pools' swaps create (top it up any time with `platform_top_up`).
  const existing = await view("get_platform", { platform_id: PLATFORM });
  if (existing && existing.owner !== ACCOUNT) {
    throw new Error(`platform id ${PLATFORM} belongs to ${existing.owner}; pick another id`);
  }
  if (!existing) {
    await me.functionCall({
      contractId: ROUTR, methodName: "register_platform", gas: TGAS(30), attachedDeposit: BigInt(NEAR("0.52")),
      args: { platform_id: PLATFORM, fee_recipient: ACCOUNT, creator_bps: 7000, builder_bps: 500,
              pool_creators: [ACCOUNT], builders: [] },
    });
  }

  // 2. Per launch: check the key, create the pool, seed it. `virtual_quote` sets the starting price:
  //    opening price = virtual_quote / seed; seeding the whole supply with virtual_quote 1,000 NEAR opens the supply's
  //    value at 1,000 NEAR. This is an opening price, not a promise about any later price.
  const token = process.env.TOKEN ?? `mytoken.${ACCOUNT}`; // an NEP-141 whose supply this account holds
  const status = await view("get_launch_status", { token, quote: WRAP, platform_id: PLATFORM });
  console.log("launch status", status.state, "terms", status.terms, "deposit", status.create_pool_deposit);
  if (status.state === "absent") {
    await me.functionCall({
      contractId: ROUTR, methodName: "create_pool", gas: TGAS(30), attachedDeposit: BigInt(status.create_pool_deposit),
      args: { token, quote: WRAP, platform_id: PLATFORM, creator: ACCOUNT, seeder: ACCOUNT, fee_bps: 100,
              virtual_quote: NEAR("1000") },
    });
  }
  if (status.state !== "seeded") {
    // the seed is one ft_transfer_call of the supply; `expect_creator` binds the pool to the fee recipient you expect
    await me.functionCall({
      contractId: token, methodName: "ft_transfer_call", gas: TGAS(60), attachedDeposit: 1n,
      args: { receiver_id: ROUTR, amount: "1000000000000000000000000000",
              msg: JSON.stringify({ Seed: { pool_id: status.key, expect_creator: ACCOUNT } }) },
    });
  }

  // 3. Quote and route a buy: the quote is what you show before the user signs (fee waterfall, impact, executable).
  const amountIn = NEAR("1");
  const q = await view("quote_swap", { pool_id: status.key, token_in: WRAP, amount_in: amountIn, builder: null });
  if (!q) throw new Error(`no pool ${status.key}`);
  console.log("quote", q.amount_out, "impact bps", q.price_impact_bps, "executable", q.executable, q.reason ?? "");
  if (q.executable) {
    const minOut = (BigInt(q.amount_out) * 98n) / 100n; // 2% slippage
    await me.functionCall({
      contractId: WRAP, methodName: "ft_transfer_call", gas: TGAS(100), attachedDeposit: 1n,
      args: { receiver_id: ROUTR, amount: amountIn,
              msg: JSON.stringify({ Swap: { pool_id: status.key, min_out: minOut.toString(), recipient: null, builder: null } }) },
    });
  }

  // 4. Fees: booked per account at swap time; anyone can push them. A contract recipient reconciles with
  //    `get_claim_info` (cumulative creator leg vs cumulative delivered) instead of trusting a single push.
  const info = await view("get_claim_info", { pool_id: status.key, account: ACCOUNT });
  console.log("creator leg", info.fees_creator, "delivered so far", info.delivered);
  await me.functionCall({ contractId: ROUTR, methodName: "push", gas: TGAS(40), args: { account: ACCOUNT, token: WRAP } });

  // 5. Events for your indexer: NEP-297 standard "routr" (pool_created, pool_seeded, swap with every fee leg and
  //    the reserves after, payout). Page your own pools with get_platform_pools(platform_id, from, limit).
  console.log("my pools", await view("get_platform_pools", { platform_id: PLATFORM, from: 0, limit: 20 }));
}

main().catch((e) => { console.error(e); process.exit(1); });

The example registers a platform id only if it is free. If get_platform returns a record, check that its owner, recipient and pool creators are yours before using it.

Messages

Seeding and swapping are NEP-141 transfers to routr with a JSON msg. routr returns the unused amount, so a rejected seed or a swap below min_out costs only gas.

Seed (once, from the pool's seeder, the pool's token)

{"Seed": {"pool_id": "<id or token|quote|platform>", "expect_creator": "<account>"}}

expect_creator binds the seed to the creator the seeder expects; if the pool names someone else, the seed is refused.

Swap (either side of a seeded pool)

{"Swap": {"pool_id": "<id or token|quote|platform>", "min_out": "<raw units>", "recipient": null, "builder": null}}

recipient defaults to the sender. builder earns the platform's builder_bps only if the platform approved it; otherwise that leg stays with the platform.

Methods

Views

Events

NEP-297 logs with standard: "routr", version: "1.0.0". Amounts are strings of raw units.

Errors

Fees and terms

A pool charges fee_bps (1 to 1,000) of the quote leg of each swap. From that fee the protocol takes protocol_fee_bps (2,000 today, capped at 3,000 in the code). The remainder is the platform's: creator_bps of it goes to the pool's creator, builder_bps of it to an approved builder named on the swap, and the rest to the platform's recipient. Every leg is visible in quote_swap before signing and in the swap event after.

Storage and payouts

Output and fee shares are liabilities first: a swap's output is recorded as pending while its transfer is in flight and becomes owed if the transfer fails (for example an unregistered recipient). push pays anything owed, for anyone, at any time. Claim records cost storage that traders do not attach, so each platform's bond is its own credit, charged per new claim record its pools create; a platform whose credit is spent has its pools' swaps refused until someone tops it up. The contract also checks the venue's shared storage room before accepting a swap. The payout callback is written not to panic: it uses saturating arithmetic and emits invariant_broken instead, so monitor get_pending, get_owed and that event.

Deployments

Current reproducible CI build of the routr contract: code hash 8BKXgNYV8Qzr3HJZuNqS2Vee1zP28nax9rFDhW3iSuNC (301,886 bytes, commit f277aba). The reviewed build deployed to mainnet may differ and its hash will be published here; see Security.