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 from the General Protocols oracle every ~10 minutes, or sooner if the BCH/USD price has moved by 0.5% since the last update. 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.

Security audit#

The CashScript smart contracts were audited by an independent third party prior to launch. See the audit report and summary for the full scope, findings, and remediations.

Based on the Liquity V2 protocol#

ParyonUSD is based on the Liquity V2 protocol. The core mechanics are the same: user-set interest rates, a stability pool absorbing liquidations, and redemptions enforcing the peg.

The two protocols differ in scope and in chain. ParyonUSD is single-collateral (BCH only) and has no governance token. Bitcoin Cash uses a UTXO model: it enables high scalability and concurrent contract execution, but each contract only sees local state. That shapes the two-step redemption mechanism and the epoch-based lockups and payouts on the stability pool.

Lastly, ParyonUSD chose a different funding model and a correspondingly simpler fee structure: a 70/30 protocol fee on staker yield, a fixed redemption fee, a flat upfront borrowing fee, and no rate-adjustment fee.

See the Liquity V2 Comparison for details.