Module 1
WardClient
High-level SDK entrypoint for institutions and integrators.
Protocol specification
The technical basis for deterministic default resolution.
Engineering reference for Ward Protocol: architecture, claim validation, signer-boundary guarantees, settlement behavior, and the controls that make conformance reviewable.
9 on-ledger checks8 attack vectors mitigatedward_signed = FalseSDK v0.2.10
Specification snapshot
Core invariant
ward_signed = False
Decision source
Authoritative on-ledger state only
Settlement role
Ward returns unsigned payloads only
Primary assurance surface
Nine-step claim validation
Architecture
Five modules form the conformance and settlement surface.
Module 2
VaultMonitor
WebSocket default detection with authoritative ledger re-verification.
Module 3
ClaimValidator
Nine-step deterministic on-chain claim validation.
Module 4
EscrowSettlement
Unsigned escrow lifecycle for controlled institutional execution.
Module 5
PoolHealthMonitor
Coverage ratio and reserve accounting for pool safety.
Claim validation
Nine deterministic checks govern every claim.
These steps are intentionally explicit. They define the evidence path institutions can inspect and the basis for every conformant result.
Step 1
NFT existence and taxon enforcement (WARD_POLICY_TAXON = 281)
Step 2
Policy validity using XRPL ledger close_time, never server clock
Step 3
Vault address binding: metadata vault must equal defaulted_vault
Step 4
LSF_LOAN_DEFAULT flag on LedgerEntry(index=loan_id)
Step 5
Vault loss must be greater than zero drops
Step 6
Pool usable balance must exceed the validated loss amount
Step 7
Replay protection: policy NFT must still be live
Step 8
Claimant must still hold the policy NFT on ledger
Step 9
Pool solvency and rate limits must still hold at settlement
Protocol details
Reference sections for operators, integrators, and reviewers.
Overview
Ward Protocol is an open specification and SDK for deterministic default protection on institutional lending vaults. Core invariant: ward_signed = False. Ward constructs unsigned transactions. Institutions sign. The chain settles. Ward never holds, touches, or stores private keys.
Vault monitor
VaultMonitor subscribes to XRPL ledger events over TLS, treats incoming transaction messages as hints only, and confirms default through independent LedgerEntry reads. Default status is only promoted after repeated authoritative confirmation.
Escrow settlement
Ward never receives the claimant preimage. Institutions sign EscrowCreate, claimants sign EscrowFinish, and policy NFTs are burned on settlement to prevent replay. ward_signed = False is preserved across the entire settlement path.
Shared implementation surface
Shared primitives live in ward/primitives.py, ward/constants.py, and ward/tx_builder.py so address validation, reserve accounting, payload construction, and signer-boundary guarantees stay consistent across the protocol surface.
Attack-vector mitigations
The spec defines control intent, not just happy-path behavior.
Policy forgery blocked by taxon enforcement at step 1.
Replay and double-spend blocked by burn-on-settlement plus re-checking live NFT status.
Clock manipulation removed by relying on XRPL ledger close_time.
Signal manipulation reduced by independent LedgerEntry reads for every event.
Front-running risk narrowed because Ward never stores or receives preimages.
Pool drainage risk constrained through dual solvency and coverage checks.
Address injection blocked by validate_xrpl_address() at API boundaries.
Silent network failure constrained through heartbeat monitoring and reconnect logic.
Protocol constants
| Constant | Value |
|---|---|
| WARD_POLICY_TAXON | 281 |
| WARD_CREDENTIAL_TAXON | 282 |
| TF_BURNABLE | 0x00000001 |
| LSF_LOAN_DEFAULT | 0x00010000 |
| MIN_COVERAGE_RATIO | 1.5 |
| CLAIM_RATE_LIMIT_MAX | 3 |
| CLAIM_RATE_LIMIT_WINDOW_S | 300 |
| MONITOR_HEARTBEAT_TIMEOUT_S | 60 |
| XRPL_BASE_RESERVE_DROPS | 20_000_000 |
| XRPL_OWNER_RESERVE_DROPS | 2_000_000 |
Signer boundary reminder
No Ward class stores a wallet, no Ward method calls submit_and_wait, and build_unsigned_tx() is the transaction construction path that preserves ward_signed = False.
Navigation flow
Move from the protocol reference into review, sandbox, and integration.
The spec should feed directly into a conformance review, a live sandbox run, or an implementation surface. No dead ends, no broken buttons, and no ambiguity about the next institutional step.