Cyrix is a Bitcoin-backed P2P credit network on Stacks for borrowing, lending, and on-chain debt clearing.

Inspired by Cycles Protocol: A Peer-to-Peer Electronic Clearing System, Cyrix turns direct obligations and cycle clearing into a live testnet product.

Cyrix applies the Cycles Protocol model to a Bitcoin-backed credit system. Lenders supply USDCx, borrowers lock sBTC, approved lines create direct credit relationships, and each draw creates an on-chain obligation. When obligations overlap, x402 agents can clear valid cycles and reduce settlement pressure across the network.

This repo includes the full stack: Clarity contracts, tests, deployment scripts, and a shipped Stacks testnet web app for borrowing, lending, repayment, liquidation, and agent-driven clearing.

The Cyrix MVP focuses on direct wallet-to-wallet credit relationships:

1. A wallet sets a username.
2. A lender deposits USDCx into protocol-controlled liquidity.
3. A borrower locks sBTC as trust backing.
4. The borrower requests a credit line from a lender.
5. The lender approves a limit and borrower fee.
6. The borrower draws a USDCx obligation.
7. x402 agents clear cycles across obligations and earn rewards.
8. Lenders earn from borrower fees and clearing fees.
9. Unsafe debt can be liquidated against the borrower’s sBTC trust.

The Cyrix roles are:

• sBTC: trust backing and liquidation buffer
• USDCx: credit asset and lender liquidity
• x402 agents: graph clearers who earn reserve-funded rewards

• contracts/: Clarity contracts for the P2P credit MVP.
• tests/: Vitest + Clarinet simnet coverage.
• docs/: architecture and design notes.
• web/: Next.js app for faucet, admin, and protocol flows.
• scripts/: deployment, wallet, admin, and agent CLI utilities.

• mock-sbtc.clar: local sBTC-compatible mock token.
• mock-sbtc-registry.clar: local registry that authorizes protocol callers for the sBTC mock.
• mock-usdcx.clar: local USDCx-compatible mock token.
• cyrix-vault.clar: lender USDCx balances, outstanding credit, and agent reserve.
• cyrix-core.clar: usernames, sBTC trust, credit requests, approved lines, obligations, clearing, repayments, and liquidations.

npm install
npm run check
npm test

• npm run check runs clarinet check.
• npm test runs the Clarinet simnet suite through @stacks/clarinet-sdk.

Mnemonic deploy path:

pnpm run deploy:testnet

Private-key deploy path:

pnpm run deploy:testnet:pk

Notes:

• The mnemonic path reads .env.testnet and writes settings/Testnet.toml.
• The private-key path signs sequential contract publishes and waits for confirmation after each tx.
• Stacks will reject a redeploy if the same deployer tries to publish the same contract names again. Use a fresh deployer or versioned names for upgrades.
• Both flows write live contract IDs into deployments/testnet-addresses.json.

pnpm run wallet:testnet:new

This prints and writes:

• PRIVATE_KEY
• TESTNET_ADDRESS

to:

• generated/testnet-wallet.json

generated/ is gitignored.

Grant backend mint roles on the mock tokens:

pnpm run grant:backend:mint-roles

The signer used by this CLI must already have governance/owner permission on:

• mock-sbtc-registry
• mock-usdcx

Clear a three-obligation cycle from the terminal:

pnpm run agent:clear-cycle -- <obligation-a> <obligation-b> <obligation-c>

The agent signer key is resolved from:

• X402_AGENT_PRIVATE_KEY
• else TESTNET_PRIVATE_KEY
• else STACKS_SERVER_PRIVATE_KEY

To use a Hiro API key without exposing it to the browser, set in web/.env.local:

HIRO_API_BASE=https://api.testnet.hiro.so
HIRO_API_KEY=your_hiro_api_key

The web app now proxies Hiro reads through Next API routes and sends the key server-side as the x-api-key header for:

• read-only contract calls
• FT balance lookups
• tx status polling

The app exposes:

• /faucet: backend-signed minting for mock sBTC and mock USDCx.
• /protocol: usernames, trust deposits, lender liquidity, credit requests, approvals, draws, repayments, x402 clearing, and liquidation.

The protocol page also exposes live read-only views for:

• vault metrics
• lender balance
• current user summary
• profile
• credit request inspection
• credit line inspection
• obligation inspection
• debtor/creditor edge inspection

The strongest live demo uses four wallets:

1. W1 deposits USDCx as a lender.
2. W2 and W3 lock sBTC as trust backing.
3. W2, W3, and W1 approve lines to form a credit loop.
4. Each wallet draws USDCx against an approved lender.
5. W4 runs clear-cycle-3.
6. The graph shrinks, the agent earns a reward, and lender fee balances improve.
7. Borrowers repay obligations or get liquidated if unsafe.

The mock tokens still mirror the contract surfaces the app needs:

• mock-sbtc exposes protocol-mint, protocol-lock, protocol-unlock, transfer-many, and available / locked balance read-only functions.
• mock-usdcx exposes role-gated protocol-mint, protocol-burn, protocol-transfer, pausing, and governance-controlled caller management.
• mock-sbtc-registry uses the same (buff 1) role-flag pattern as the real sBTC contracts.

Apache 2.0