> ## Documentation Index > Fetch the complete documentation index at: https://docs.writz.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Architecture Diagrams > Visual reference for Writz Protocol v1 - from Bitcoin locking to SPV verification and lending on Soroban. ## System Architecture End-to-end view of how Bitcoin, the relayer, the Writz v1 contracts (`bitcoin-spv`, `writz-lend`) and the browser interact. The privacy edition's contracts are drawn as a separate group: `writz-lend` never calls them. ![Writz System Architecture](https://mintcdn.com/writz-protocol/H_sPi9-nz-OQpN2-/diagrams/output/01-system-architecture.png?fit=max\&auto=format\&n=H_sPi9-nz-OQpN2-\&q=85\&s=90a746955763cafd483252d008de5afe) **Key layers:** * **Bitcoin** - P2WSH locks collateral; two spending paths (cooperative co-sign or CLTV timelock) * **Relayer** - submits Bitcoin headers to `bitcoin-spv`, serves SPV proofs, and co-signs the release PSBT after a full repayment * **Soroban contracts** - `bitcoin-spv` verifies Bitcoin transactions; `writz-lend` holds plaintext positions, the USDC pool and liquidation, priced by the Reflector oracle * **Browser** - the Bitcoin wallet signs the key-control proof and the release; the Stellar wallet signs Soroban transactions *** ## Deposit Flow Step-by-step path from connecting a Bitcoin wallet to having an active position on Stellar. ![Deposit Flow](https://mintcdn.com/writz-protocol/H_sPi9-nz-OQpN2-/diagrams/output/02-deposit-flow.png?fit=max\&auto=format\&n=H_sPi9-nz-OQpN2-\&q=85\&s=9070ae6e89a95ec763061e305168152b) 1. Connect Bitcoin wallet (Xverse) and Stellar wallet (Freighter) 2. Derive unique P2WSH address from protocol key + user key + timelock height 3. Send BTC to that address on-chain 4. Relayer serves the SPV proof (block hash + Merkle path + raw transaction) 5. The Bitcoin wallet signs the key-control message (BIP-137) for this contract, depositor and txid 6. `writz-lend.deposit()` rebuilds the P2WSH, calls `bitcoin-spv.verify_transaction`, checks the timelock window and the signature, consumes the txid and creates the position *** ## Borrow & Repay Flow How `writz-lend` handles a borrow or a repayment. ![Borrow and Repay Flow](https://mintcdn.com/writz-protocol/H_sPi9-nz-OQpN2-/diagrams/output/03-borrow-repay-flow.png?fit=max\&auto=format\&n=H_sPi9-nz-OQpN2-\&q=85\&s=474ec33dd921ecbc57cfbf699c5d0987) * **Borrow:** only the depositor; interest accrues first; the post-borrow ratio at the Reflector price must stay at or above 150%, within pool liquidity and the 50,000 USDC total cap * **Repay:** partial or full; a full repayment closes the position and emits `repay_full` *** ## BTC Release Flow (Path A) Cooperative co-signed release after full repayment. ![BTC Release Flow](https://mintcdn.com/writz-protocol/nYtWJyg5bCBf8TvX/diagrams/output/04-btc-release-flow.png?fit=max\&auto=format\&n=nYtWJyg5bCBf8TvX\&q=85\&s=0fa74e0c0e3b8d4d7382e253a90e9c4a) * The relayer's repay watcher reacts to `repay_full`, builds the PSBT and co-signs it with the protocol key * The half-signed PSBT is published on `writz-lend` (`publish_release_psbt`) and can be read with `get_release_psbt` even if Writz is down * Final witness: `[user_sig, protocol_sig, 0x01, redeemScript]` *** ## Soroban Contract Interactions How the Writz v1 testnet contracts call each other. ![Contract Interactions](https://mintcdn.com/writz-protocol/ob-rXdGsZ5IiQwOx/diagrams/output/07-contract-interactions.png?fit=max\&auto=format\&n=ob-rXdGsZ5IiQwOx\&q=85\&s=544fdc9c126f2a544d00dfe1432140e3) | Contract | Role | | - | - | | `bitcoin-spv` | Verifies Bitcoin transactions against its stored header chain; shared deposit txid registry | | `writz-lend` | Deposits, USDC pool, interest, keeper liquidation, release PSBT storage | | `commitment-tree`, `zk-verifier` | Privacy edition (in progress), testnet only; not part of v1 and never called by `writz-lend` | *** ## Privacy edition (in progress): ZK Circuits > These circuits belong to the separate, opt-in privacy edition, in progress and on testnet only. They are not part of Writz v1 and are not used by `writz-lend`. See [Privacy edition (in progress)](https://docs.writz.xyz/how-it-works/privacy-edition.md). The main Groth16 circuits (Circom / BN254), their private inputs, public inputs, and public outputs. ![ZK Circuits](https://mintcdn.com/writz-protocol/5nk-qtD5SjakN9Bx/diagrams/output/05-zk-circuits.png?fit=max\&auto=format\&n=5nk-qtD5SjakN9Bx\&q=85\&s=20f8953bd7bfc25c6fabfff9d32779d4) | Circuit | Purpose | | - | - | | `deposit.circom` | Binds a Poseidon commitment to a Bitcoin txid | | `borrow_repay.circom` | Proves Merkle inclusion + valid collateral ratio after state change | | `liquidation.circom` | Proves position is under-collateralized | *** ## Privacy edition (in progress): Commitment State Machine > Privacy edition only. Writz Lend positions on `writz-lend` have no commitments: they are plaintext, keyed by the Bitcoin txid, with the statuses Active, Closed and Liquidated. Complete lifecycle of a privacy edition position from pending to BTC release (or liquidation). ![Commitment State Machine](https://mintcdn.com/writz-protocol/H_sPi9-nz-OQpN2-/diagrams/output/06-commitment-state-machine.png?fit=max\&auto=format\&n=H_sPi9-nz-OQpN2-\&q=85\&s=9ca0614c08ba6e95c712b3bed90209e8) | State | Description | | - | - | | **Pending** | `deposit()` verified, waiting for `insert_commitment()` | | **Active · debt=0** | Commitment in Merkle tree, no outstanding debt | | **Active · debt>0** | USDC borrowed; nonce rotates on every partial repay | | **Closed** | Full repayment done; old nullifier spent | | **Released** | Path A PSBT finalized; BTC returned on Bitcoin | | **Liquidated** | Ratio below 120%; keeper repaid debt | *** ## Regenerating Diagrams ```bash theme={null} pip3 install graphviz python3 scripts/diagrams/render-all.py ``` Output: `docs/diagrams/output/*.svg` and `*.png` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.