Custos docs

Getting started

Quickstart

Scaffold the template and run its test suite in a few minutes with no account. Then deploy your own market to Hedera testnet and watch the network keep it.

Before you start#

1. Scaffold and test locally#

No account and nothing spent. The tests emulate Hedera's Token Service and mock the Schedule Service.

  1. Create your project

    bash
    npm create scaffold-hbar@latest -- --template victorjayeoba/scaffold-hbar-custos

    The CLI asks for a project name and installs everything.

  2. Compile and test the contracts

    bash
    cd <your-project>
    yarn foundry:compile
    yarn foundry:test

    This runs every unit, fuzz and invariant test, including the solvency invariants (no bad debt, the pool always covers the largest possible gains, the keeper reserve always covers the next run).

2. Deploy your own market to testnet#

  1. Create or import a deployer account

    bash
    yarn foundry:account:generate      # or: yarn foundry:account:import

    Fund it from the faucet. The deploy sends HBAR, as the table below shows.

  2. bash
    yarn custos:deploy:testnet

    Deploys PriceGuard, LiquidityPool and PerpMarket, links them, creates the cUSDC-LP share token on the Token Service and funds the keeper. It writes packages/foundry/deployments/296.json and regenerates packages/nextjs/contracts/deployedContracts.ts, so the app points at your market.

  3. Book the first tick

    bash
    yarn custos:start:testnet

    Associates the pool and market with USDC and books the keeper's first tick. From here on the network runs it: every tick books the next.

  4. Seed it (optional)

    bash
    yarn custos:demo:testnet

    Swaps HBAR to USDC on SaucerSwap, deposits it in the pool, and opens a 50x long with 1 HBAR.

What the scripts sendDefaultSet with
The keeper's HBAR reserve40 ℏKEEPER_FUND
Creating the share token (about 12 ℏ is used, the rest comes back)30 ℏSHARE_TOKEN_FEE
Demo: HBAR swapped to pool USDC120 ℏDEMO_POOL_HBAR
Demo: HBAR per trade1 ℏDEMO_TRADE_HBAR

3. Run the app#

bash
yarn next:dev

Open localhost:3000/keeper. The first network run arrives one interval (30 minutes by default) after custos:start:testnet. Connect HashPack, Kabila, MetaMask or any WalletConnect wallet; see Trade for what each page does.

The keeper page: the next scheduled check, the HBAR held up front per run, and the reserve
/keeper on the live testnet deployment

Next steps#