Metadata-Version: 2.4
Name: ward-protocol
Version: 0.2.11
Summary: Deterministic default resolution for XLS-66 lending vaults on the XRP Ledger
Author-email: Ward Protocol <team@wardprotocol.org>
License: MIT
Project-URL: Homepage, https://wardprotocol.org
Project-URL: Repository, https://wardprotocol.org
Project-URL: Documentation, https://api.wardprotocol.org/docs
Project-URL: Bug Tracker, https://github.com/wflores9/ward-protocol/issues
Keywords: xrpl,default-protection,defi,blockchain,escrow,nft,xls-66
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: xrpl-py<6.0.0,>=4.5.0
Requires-Dist: httpx<1.0.0,>=0.25.0
Requires-Dist: pydantic<3.0.0,>=2.5.0
Requires-Dist: redis<9.0.0,>=5.0.0
Provides-Extra: dev
Requires-Dist: anyio[trio]>=4.0; extra == "dev"
Requires-Dist: hypothesis<7.0.0,>=6.0.0; extra == "dev"
Requires-Dist: jsonschema<5.0.0,>=4.19.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: pytest>=7.4; extra == "dev"
Dynamic: license-file

# Ward Protocol

> `ward_signed = False — always.`
> Ward constructs unsigned transactions. Institutions sign. The chain settles.
> Ward is never a counterparty, never a custodian, never a signatory.

[![CI](https://github.com/wflores9/ward-protocol/actions/workflows/test.yml/badge.svg)](https://github.com/wflores9/ward-protocol/actions)
[![PyPI](https://img.shields.io/pypi/v/ward-protocol)](https://pypi.org/project/ward-protocol/)
[![npm](https://img.shields.io/npm/v/@wardprotocol/sdk)](https://www.npmjs.com/package/@wardprotocol/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## Overview

Ward Protocol defines deterministic default resolution
for institutional lending vaults on the XRP Ledger (XLS-66 amendment in
validator voting). The validator specifies nine checks sourced from authoritative
ledger state — no discretionary Ward approval and no Ward signature. The hosted
Altnet surface currently proves policy checks F01-F03. Full XLS-66 lifecycle
validation is the next XRPL Devnet integration milestone.

wardprotocol.org | wardprotocol.org/assurance | wardprotocol.org/demo

## Live Status

| Metric | Value |
|--------|-------|
| SDK Version | PyPI/npm badges above |
| Hosted API | api.wardprotocol.org — live |
| Test Counts | Latest CI + `src/lib/wardMetrics.ts` |
| Critical Path Coverage | `src/lib/wardMetrics.ts` |
| Documented Invariants | 32 |
| TLA+ Model Checks | INV-007 and INV-016 in CI |
| Dependency Security | CI audit and secret-scanning gates |
| XRPLF Standard | Discussion #474 — active |

## The Nine Checks

| Step | Check |
|------|-------|
| 1 | NFT existence + taxon 281 (XLS-20) |
| 2 | Policy validity — ledger close_time + on-chain premium payment |
| 3 | Vault address binding — NFT metadata vault == defaulted vault |
| 4 | LSF_LOAN_DEFAULT flag on LedgerEntry(index=loan_id) |
| 5 | Vault loss > 0 drops |
| 6 | Pool usable balance >= vault loss (balance - XRPL reserve) |
| 7 | Replay protection — NFT still live (burn-on-settlement) |
| 8 | Claimant holds NFT — AccountNFTs(account=claimant) |
| 9 | Pool solvency + rate limit (<=3/NFT/300s, ratio >=1.5x) |

## Install

```bash
pip install ward-protocol          # Python SDK
npm install @wardprotocol/sdk      # TypeScript SDK
```

Hosted API: https://api.wardprotocol.org

## Quick Start

```python
import asyncio
from ward import WardClient, ClaimValidator

# Validate against the configured XRPL endpoint
validator = ClaimValidator(url="https://s.altnet.rippletest.net:51234/")
claim = await validator.validate_claim(
    claimant_address="rClaimantXXX...",
    nft_token_id="A" * 64,
    defaulted_vault="rVaultXXX...",
    loan_id="B" * 64,
    pool_address="rPoolXXX...",
)
print(claim.approved)           # True
print(claim.steps_passed)       # 9
print(claim.ward_signed)        # False — always
```

## Integration Status

| Surface | Status | Evidence |
|---------|--------|----------|
| XRPL Altnet | Hosted verification | F01-F03 policy evidence |
| XRPL Devnet XLS-65/66 | Next integration milestone | Full vault, loan, default, and checks 4-9 lifecycle |
| Non-XRPL modules | Source scaffolds only | Seven modules contain unimplemented lifecycle methods |

Ward's resolution model is intended to be rail-agnostic, but no non-XRPL module
is presented as a deployable integration. See `docs/multichain-gaps.md`.

## Running Tests

```bash
# Python
pip install -r requirements.txt
python3 -m pytest tests/ -v

# Rust
cd ward && cargo test

# TypeScript
cd sdk/typescript && npm install && npm test
```

## Assurance

Internal pre-mainnet security report, TLA+ models, and continuous
scanning results: wardprotocol.org/assurance

- Automated test and coverage totals are maintained in `src/lib/wardMetrics.ts`
- 32 invariants are documented in `INVARIANTS.md`
- TLA+ CI model checks cover INV-007 and INV-016; this is not a proof of all 32 invariants
- Dependency audit, secret scanning, and signer-boundary checks run in CI
- Git history scrubbed and verified clean
- ward_signed = False enforced at 4 independent layers

## Community

- Discord: discord.gg/j45hnRP3HW
- XRPLF Discussion #474: github.com/XRPLF/XRPL-Standards/discussions/474
- Website: wardprotocol.org
- X: x.com/wardprotocol

## Commercial

Published SDK packages and included specifications are MIT licensed.
Mainnet API, Ward-conformant certification, and enterprise support
require a commercial license. See COMMERCIAL.md.

Contact: team@wardprotocol.org

## License

MIT — see LICENSE file.

ward_signed = False — always.
