Architecture

This page provides a high-level technical overview of ParyonUSD for those who want to understand how the protocol works under the hood. For user-facing guides, see the User Guides.

Overview#

ParyonUSD is built entirely on Bitcoin Cash using CashScript smart contracts. The protocol is non-custodial — all operations are executed by on-chain contracts without any intermediary holding funds.

The system consists of 26 smart contracts organized into modular subsystems, a TypeScript library for building transactions, and autonomous services that maintain the protocol.

Smart contracts#

The contracts are organized into six subsystems:

Borrowing (Parity) — The entry point for creating loans. Holds the PUSD minting NFT and creates loans with the correct initial state. Multiple instances exist for transaction parallelism.

Loans — Each loan is a mutable NFT with 27 bytes of on-chain state (debt amount, interest rate, redemption status, and more). A main Loan contract delegates all logic to 8 modular function contracts (manage, repay, liquidate, redeem, change interest, etc.).

Stability Pool — Holds staked PUSD and manages liquidations. Distributes yield to stakers via epoch-based Payout contracts. A Collector contract gathers interest payments each period.

Redemptions — Handles the multi-step redemption process. Locks the price at redemption start, enforces a 12-block finalization window, and allows target swapping to ensure the lowest-rate loan is always redeemed first.

Price Oracle — Stores the BCH/USD price on-chain. Updated every ~10 minutes from the General Protocols oracle. This is the only upgradable component — the oracle source can be migrated if needed. All other contracts are immutable.

Loan Key Factory — Pre-creates loan key NFTs with unique token IDs for BCMR metadata compatibility.

Design patterns#

Modular function contracts — Rather than large monolithic contracts, ParyonUSD uses small single-function contracts that compose via mutual authentication. This keeps individual contracts simple and saves transaction size.

Parallelism via duplication — Key contracts are deployed as multiple UTXOs (e.g., 10 borrowing instances, 5 price contract instances) to allow concurrent operations without contention.

Sidecar UTXOs — Since a single BCH output can only hold one token category, contracts that need both an NFT and fungible tokens use a companion “sidecar” output.

NFT-based state — Loans, staking receipts, and redemptions are all represented as mutable NFTs. This means positions are self-contained on-chain objects that can be queried and verified independently.

Autonomous services#

Two server-side services maintain protocol health:

Transaction service — Monitors the blockchain and executes maintenance transactions: price updates, interest collection, liquidations, redemption finalizations, and period/epoch transitions. Runs autonomously without user interaction.

API service — Manages delegated interest rates for loans using managed rates, takes periodic snapshots of protocol statistics, and hosts BCMR metadata files for wallet display.

Data flow#

The user-facing app connects directly to the Bitcoin Cash network via Electrum servers. It uses the ParyonUSD TypeScript library to query contract state, build transactions, and submit them for signing via WalletConnect. No data passes through ParyonUSD servers for core operations — the app is a direct interface to the blockchain.

Historical data (transaction history, closed loans) is optionally fetched from ChainGraph, a GraphQL indexer for Bitcoin Cash.

Open source#

The smart contracts are open source and can be independently verified. The contracts are written in CashScript and compiled to Bitcoin Cash Script for on-chain execution.