Skip to main content

​
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 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
  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
  • 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
  • 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

​
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).
The main Groth16 circuits (Circom / BN254), their private inputs, public inputs, and public outputs. ZK Circuits

​
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

​
Regenerating Diagrams

Output: docs/diagrams/output/*.svg and *.png