Orblivion starter bot (TypeScript)
==================================

A trading bot you run on your own computer. It trades through Orblivion on Robinhood Chain, and you change one file:
strategy.ts. The full guide: https://orblivion.com/docs/starter-bot.html

Files
  strategy.ts       YOUR LOGIC: decide(market, book, state) returns the orders to place. The only file to edit.
  config.json       the settings (below)
  bot.ts            the loop: prices and balances -> decide -> limits -> trade (or dry run) -> log
  setup-wallet.ts   one-time setup (keys, funding, the session), status, and the off switches (revoke, reset-code)
  package.json      @orblivion/sdk, viem and tsx; the npm scripts below
  tsconfig.json     for your editor, and for npm run typecheck

Needs Node.js 20 or later.

Quick start
  npm install
  npm run setup                   make the keys, fund them, grant the session (anything sent asks for SEND)
  npm run bot                     a dry run: it decides, checks and logs, and sends nothing
  ... read bot-log.jsonl, then set "dry_run": false in config.json ...
  npm run bot                     live

  npm run status                  balances, the session, and what its caps have left
  npm run revoke                  the off switch: ends the session at once
  npm run reset-code              the emergency switch: makes the wallet a plain account again
  npm run setup -- keys | fund | session | setup     one step of the setup

Stop the bot with Ctrl+C, or create a file named STOP in this folder.

The off switches
  npm run revoke                  ends the session: the wallet's own transactions disable the session's delegation
                                  and set its approvals back to 0, then Orblivion stops co-signing. session.json keeps
                                  the session's revocation record (no secret), so revoke builds those transactions here
                                  and sends them straight to Robinhood Chain, even when Orblivion doesn't answer, then
                                  reads them back. That needs an SDK with revocationRecord
                                  (npm install @orblivion/sdk@latest); with an older one revoke takes its on-chain steps
                                  from Orblivion's answer.
  npm run revoke -- --chain-only  the same transactions from session.json alone, with nothing asked of Orblivion, and
                                  the chain's answer read from it alone: for when Orblivion's answer disagrees with
                                  session.json.
  npm run reset-code              the emergency switch: makes the wallet a plain account again (its code removed by its
                                  own transaction, straight to Robinhood Chain). No session can move anything from it
                                  after that. It doesn't revoke the session or reset the approvals: setting the code
                                  again brings the session back until it expires, so revoke as well.

config.json
  bot.tokens          the tokens the bot prices, reads balances of, and may trade (core symbols or 0x addresses);
                      the session is granted for exactly these
  bot.interval_s      seconds between ticks
  bot.dry_run         true (the default): nothing is sent. Each order is checked as a quote (session mode) or a plan
                      (direct mode), and none of the session's limits are used. false: live.
  bot.mode            "session" (the default, safer): the bot holds only an executor key, which can trade nothing but
                      what the session the wallet signed allows. "direct" (simpler): the bot trades with the wallet's key.
  bot.key_dir         where the keys and session.json live, outside this folder (default ~/.orblivion-bot)
  bot.api_url         Orblivion's API; empty: ORBLIVION_API_URL if set, else https://api.orblivion.com
  bot.stop_file       the bot stops when a file with this name appears in this folder
  limits.*            the bot's own limits, checked before every order: max_trade_usd and max_day_usd (rolling 24 h,
                      kept in bot-ledger.json). Orders are cut down to fit; under $1 is skipped.
  session.*           what the wallet signs in session mode, enforced by Orblivion's co-signer and on chain:
                      max_trade_usd (at most 1,000), max_day_usd, max_trades, hours (at most 720, 30 days), and
                      setup_budget_usd, the most of any ERC-20 (USDG, for one) the session may sell in its whole life

How it keeps you safe
  - dry_run is on by default, and a dry run uses none of the session's limits.
  - The bot's own limits cut every order: per trade, per rolling 24 hours, at most what the wallet holds, at least $1.
  - In session mode the wallet's key stays out of the bot. The session's caps are enforced by Orblivion's co-signer and
    by the chain on every trade, whatever the bot does.
  - Every trade is checked by the SDK before anything is signed: the route, the minimum output, the fee, the recipient.

The keys are never printed. Anyone with wallet.json controls the wallet: don't share or commit it, and use a wallet
that holds only what the bot trades. The Python bot uses the same key folder and files.

Session mode sets a plain wallet's code to MetaMask's EIP7702StatelessDeleGator (EIP-7702), which sessions run on.
The key stays the owner, and the wallet works as before; an authorization to address 0 undoes it.

This is example code, not financial advice. You bear the outcome of every trade it makes:
https://orblivion.com/docs/terms.html
MIT License: ../LICENSE.txt