Skip to main content

Run locally

The repository has three self-contained folders, each with its own toolchain: contracts/ (Rust), backend/ (TypeScript on Node.js), and frontend/ (Next.js). There is no workspace spanning them. This page shows how to run each one and the checks CI runs on every pull request.

To run the whole system without funds or mainnet, see Simulation instead.

Requirements​

ToolVersionNeeded for
rustupanyInstalls the pinned Rust toolchain from contracts/rust-toolchain.toml: Rust 1.99.1 with rustfmt, clippy, and the wasm32-unknown-unknown target
cargo-near0.22Building the contract wasm; the sandbox tests call it to build the contract they deploy
Node.js24 or laterBackend and frontend. The backend runs its .ts files directly with Node's type stripping, so it has no build step
DockeranyOnly for the reproducible contract build (see Verify the contract)

Install cargo-near 0.22 with its installer, the same way CI does:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/cargo-near/releases/download/cargo-near-v0.22.0/cargo-near-installer.sh | sh

Then clone the repository:

git clone https://github.com/TarasBrilian/setllend.git
cd setllend
cp .env.example .env # every value is optional for local runs

Contract​

The contract and its test helpers form one Cargo workspace in contracts/:

CrateFolderWhat it is
setllendcontracts/setllend/The contract. Unit tests live in src/tests/
mock-intentscontracts/mocks/intents/A mock intents.near: balances, transfer with mt_on_transfer and refunds, auth_call, mt_transfer
mock-oraclecontracts/mocks/oracle/A mock aggregate-oracle.near with the same list_prices_no_older_than method and JSON, and setters for prices and publish times
setllend-testscontracts/tests/Sandbox tests with near-workspaces

Run every test:

cd contracts
cargo test

This runs the unit tests first, then the sandbox tests, which build the wasm with cargo near, start a local NEAR sandbox node, deploy the contract with the two mocks, and drive it only through the mock intents.near, as real users would: orders and refunds of invalid ones, cancels, note sales, borrow fills priced through the oracle and skipped on a stale price, collateral withdrawal against debt, multi-token loans, failed payouts and their recovery, liquidation, bad debt, owner management of collateral tokens, and the gas of full batches. Every loan in them is opened by a real fill. NEAR Intents and the oracle have no testnet, which is why the mocks exist.

The tests also check contracts/setllend/fixtures/golden.json, which holds the exact JSON the contract parses and produces (msg strings, match_orders arguments, views, events) and test vectors for its math. The backend's TypeScript encoders and math are tested against the same file, so the two can't drift apart.

To build the wasm alone:

cd contracts/setllend
cargo near build non-reproducible-wasm # quick local build
cargo near build reproducible-wasm # the pinned Docker build used for mainnet; needs a clean git tree

Backend​

cd backend
npm install
npm run dev

This starts the API on http://localhost:8080 against the deployed setllend.near on mainnet. Without keys it is read-only: it loads the books and loans from the contract's views, follows the contract's events from the FastNear explorer, serves the REST API and WebSocket, and reads oracle prices, but it submits nothing. POST /api/intents answers not_ready, the matcher doesn't send batches, and the keeper doesn't run.

Check it:

curl -s localhost:8080/health

"contract": "ready" means it has loaded the books. History (trades and account events) starts from the moment it first runs, unless SETLLEND_START_BLOCK is set to the contract's deploy block, in which case a fresh database reads history from there. The database is a SQLite file, setllend.db in the backend/ folder by default.

npm run dev restarts on file changes; npm start runs without watching. Both load the root .env if it exists.

Backend checks:

npm run typecheck
npm test # unit tests, plus the end-to-end scenario on the simulated chain

Frontend​

cd frontend
npm install
npm run dev

Open http://localhost:3000 and connect an EVM wallet or a NEAR wallet. npm run dev first copies the shared types from backend/src/shared/ into frontend/src/shared/ (npm run sync-types), so the JSON the app signs is byte-identical to what the backend and contract expect.

The app reads the backend at NEXT_PUBLIC_API_URL:

ValueBackend
empty (default)The deployed API, https://setllend-production.up.railway.app
http://localhost:8080Your local read-only backend from above
http://localhost:8787The simulation

Until the backend reports the contract as ready, the app shows sample data marked Demo data.

:::warning A local app still uses real wallets Pointed at the deployed API or a local backend that reads mainnet, the app signs real intents and sends real deposits, exactly like https://www.setllend.xyz. Only the simulation keeps everything off chain, and even there Deposit and NEAR wallet actions are real. :::

Environment variables​

All variables live in one .env.example at the repository root. Copy it to .env (which git ignores) and fill in what you need; an empty value counts as unset. Secrets never go in the repository, and only NEXT_PUBLIC_* variables reach the browser.

VariableUsed byMeaning
PORTBackendHTTP port. Default 8080
DATABASE_PATHBackendSQLite file. Default setllend.db in the working directory
NEAR_RPC_URLBackendNEAR JSON-RPC endpoint for views, prices, and transactions. Default https://free.rpc.fastnear.com
FASTNEAR_TX_URLBackendFastNear explorer API the event follower reads. Default https://tx.main.fastnear.com
SETLLEND_CONTRACTBackendThe contract to follow. Default setllend.near
SETLLEND_START_BLOCKBackendBlock height a fresh database reads history from; usually the deploy block. Unset: from the current block
NEAR_ACCOUNT_IDBackendThe NEAR account that pays gas and holds the keeper's funds. Required when any key below is set; without it the keeper doesn't run
NEAR_INTENTS_PRIVATE_KEYBackend (relayer)Function-call key of that account for execute_intents on intents.near. Secret
NEAR_MATCHER_PRIVATE_KEYBackend (matcher)Function-call key of that account for match_orders on the contract. Secret
NEAR_KEEPER_SIGNING_KEYBackend (keeper)ed25519 key registered on intents.near that signs the keeper's liquidate intents. Secret. Without it the keeper only scans
ONE_CLICK_JWTBackend (1Click wrapper)1Click partner API key, sent as X-API-Key. Secret. Without it the 1Click endpoints answer 503
NEXT_PUBLIC_API_URLFrontendBackend URL, see above. Empty means the deployed API

.env.example also lists variables for the contract deploy and setup scripts, which only the contract owner uses.

Any key you set must belong to the account in NEAR_ACCOUNT_ID. Without a key, the component that needs it runs read-only and the rest keeps working.

CI checks​

.github/workflows/ci.yml runs on every pull request and every push to main. To reproduce it locally:

# contracts/
cd contracts
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test

# backend/
cd ../backend
npm ci
npm run typecheck
npm test

# frontend/
cd ../frontend
npm ci
npm run check-types-sync # fails if frontend/src/shared/ differs from backend/src/shared/
npm run typecheck
npm run lint
npm run build