ward-protocol 0.2.4__tar.gz → 0.2.6__tar.gz

ward_protocol-0.2.6/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: ward-protocol
+Version: 0.2.6
+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<5.0.0,>=4.5.0
+Requires-Dist: httpx<1.0.0,>=0.25.0
+Requires-Dist: pydantic<3.0.0,>=2.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: anyio[trio]>=4.0; extra == "dev"
+Dynamic: license-file
+
+# Ward Protocol
+
+[![Version](https://img.shields.io/badge/SDK-v0.2.5-gold)](https://pypi.org/project/ward-protocol/)
+[![Tests](https://img.shields.io/badge/tests-317%20Python%20%C2%B7%2040%20Rust%20%C2%B7%2045%20TypeScript-brightgreen)](#running-tests)
+[![CI](https://github.com/wflores9/ward-protocol/actions/workflows/test.yml/badge.svg)](https://github.com/wflores9/ward-protocol/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/ward-protocol)](https://pypi.org/project/ward-protocol/)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey)](LICENSE)
+
+> **`ward_signed = False — always.`**
+> Ward constructs unsigned transactions. Institutions sign. XRPL settles.
+> Ward is never a counterparty, never a custodian, never a signatory.
+
+---
+
+## Overview
+
+Ward Protocol is the open specification for deterministic default resolution on XLS-66 institutional lending vaults on the XRP Ledger. When a borrower defaults, nine on-chain checks run automatically against live ledger state — no oracle, no human judgment, no Ward signature. The outcome is the same every time, for every institution, regardless of who runs the vault. See real-world scenarios at [wardprotocol.org/use-cases](https://wardprotocol.org/use-cases).
+
+---
+
+## How It Works
+
+Full specification at [wardprotocol.org/spec](https://wardprotocol.org/spec).
+
+Nine deterministic steps — all state from the XRPL ledger:
+
+| Step | Check |
+|------|-------|
+| 1 | NFT existence + taxon 281 (XLS-20) |
+| 2 | Policy validity — ledger `close_time` + matching 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/300 s, ratio ≥ 1.5×) |
+
+---
+
+## Live Status
+
+| Metric | Value |
+|--------|-------|
+| SDK Version | v0.2.5 |
+| Hosted API | api.wardprotocol.org — live |
+| Python Tests | 317/317 passing (3.10 · 3.11 · 3.12) |
+| Rust Tests | 40/40 passing |
+| TypeScript Tests | 45/45 passing |
+| Altnet E2E | F·01–F·04 confirmed on-chain |
+| XRPLF Standard | Discussion #474 — active |
+| Swell 2026 | Application submitted |
+
+---
+
+## Quick Start
+
+```python
+pip install ward-protocol==0.2.5
+```
+
+```python
+import asyncio
+from ward import WardClient, ClaimValidator
+
+# Purchase default-protection coverage
+client = WardClient(url="https://s.altnet.rippletest.net:51234/")
+result = await client.purchase_coverage(
+    wallet=depositor_wallet,        # institution signs — Ward never does
+    vault_address="rVaultXXX...",
+    coverage_drops=500_000_000,     # 500 XRP
+    period_days=90,
+    pool_address="rPoolXXX...",
+)
+assert result["ward_signed"] is False  # invariant
+
+# Validate a claim — 9 steps, all on-chain
+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.claim_payout_drops)  # min(vault_loss, policy_coverage)
+```
+
+---
+
+## SDK & API
+
+```bash
+pip install ward-protocol          # Python SDK
+npm install ward-protocol          # TypeScript SDK
+```
+
+**Hosted API:** `https://api.wardprotocol.org`
+- `GET  /health` — status check
+- `POST /keys/generate` — API key (Developer tier, no auth required)
+- `POST /validate` — 9-step claim validation
+- `POST /purchase` — unsigned coverage transaction
+
+Full docs: [wardprotocol.org/docs](https://wardprotocol.org/docs)  
+Build guide: [wardprotocol.org/build](https://wardprotocol.org/build)  
+Institutional readiness: [docs/institutional-readiness.md](docs/institutional-readiness.md)
+
+---
+
+## XLS Standards
+
+| Standard | Role in Ward |
+|----------|-------------|
+| XLS-66 | Lending vault + loan lifecycle — Ward resolves defaults |
+| XLS-20 | Policy NFT (taxon 281, `TF_BURNABLE`, non-transferable) |
+| XLS-70 | KYC/AML credential NFT (taxon 282) |
+| XLS-80 | Domain verification for vault operators |
+
+---
+
+## Multi-Chain Roadmap
+
+| Chain | Status | Notes |
+|-------|--------|-------|
+| XRPL | **Live** | Altnet E2E confirmed, mainnet at XLS-66 launch |
+| Flare EVM | Phase 1.5 | FDC enables XRPL state verification from Flare |
+| Hedera | Phase 2 | HCS + HTS + Solidity contracts |
+| Solana | Phase 3 | Anchor + Metaplex pNFT (Anodos Finance call June 12) |
+| Stellar | Phase 4 | Soroban + Horizon SSE + SEP-0010 |
+| XDC | Evaluating | XDC Network — XLS-66 compatibility assessment |
+
+Integration plans: [docs/integration/](docs/integration/)
+
+---
+
+## Running Tests
+
+```bash
+# Python (317 unit tests)
+pip install -r requirements.txt
+python -m pytest test_ward.py -m "not integration" -v
+
+# Rust (40 tests)
+cd ward && cargo test
+
+# TypeScript (45 tests)
+cd sdk/typescript && npm install && npm test
+
+# Lint
+ruff check ward/ --select=E,F,W,I --ignore=E501
+```
+
+---
+
+## Community
+
+- **Discord:** [discord.gg/cGm9m5pEGK](https://discord.gg/cGm9m5pEGK)
+- **XRPLF Discussion #474:** [github.com/XRPLF/XRPL-Standards/discussions/474](https://github.com/XRPLF/XRPL-Standards/discussions/474)
+- **Website:** [wardprotocol.org](https://wardprotocol.org)
+- **PyPI:** [pypi.org/project/ward-protocol](https://pypi.org/project/ward-protocol/)
+
+---
+
+## License
+
+The Ward Protocol specification and SDK are MIT licensed.  
+The hosted API at `api.wardprotocol.org` is subject to commercial terms.  
+Ward Protocol is protocol software — not an insurance product, financial instrument, or regulated entity.
+
+See [wardprotocol.org/terms](https://wardprotocol.org/terms)
+
+---
+
+`ward_signed = False — always.`

ward_protocol-0.2.6/README.md

@@ -0,0 +1,176 @@
+# Ward Protocol
+
+[![Version](https://img.shields.io/badge/SDK-v0.2.5-gold)](https://pypi.org/project/ward-protocol/)
+[![Tests](https://img.shields.io/badge/tests-317%20Python%20%C2%B7%2040%20Rust%20%C2%B7%2045%20TypeScript-brightgreen)](#running-tests)
+[![CI](https://github.com/wflores9/ward-protocol/actions/workflows/test.yml/badge.svg)](https://github.com/wflores9/ward-protocol/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/ward-protocol)](https://pypi.org/project/ward-protocol/)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey)](LICENSE)
+
+> **`ward_signed = False — always.`**
+> Ward constructs unsigned transactions. Institutions sign. XRPL settles.
+> Ward is never a counterparty, never a custodian, never a signatory.
+
+---
+
+## Overview
+
+Ward Protocol is the open specification for deterministic default resolution on XLS-66 institutional lending vaults on the XRP Ledger. When a borrower defaults, nine on-chain checks run automatically against live ledger state — no oracle, no human judgment, no Ward signature. The outcome is the same every time, for every institution, regardless of who runs the vault. See real-world scenarios at [wardprotocol.org/use-cases](https://wardprotocol.org/use-cases).
+
+---
+
+## How It Works
+
+Full specification at [wardprotocol.org/spec](https://wardprotocol.org/spec).
+
+Nine deterministic steps — all state from the XRPL ledger:
+
+| Step | Check |
+|------|-------|
+| 1 | NFT existence + taxon 281 (XLS-20) |
+| 2 | Policy validity — ledger `close_time` + matching 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/300 s, ratio ≥ 1.5×) |
+
+---
+
+## Live Status
+
+| Metric | Value |
+|--------|-------|
+| SDK Version | v0.2.5 |
+| Hosted API | api.wardprotocol.org — live |
+| Python Tests | 317/317 passing (3.10 · 3.11 · 3.12) |
+| Rust Tests | 40/40 passing |
+| TypeScript Tests | 45/45 passing |
+| Altnet E2E | F·01–F·04 confirmed on-chain |
+| XRPLF Standard | Discussion #474 — active |
+| Swell 2026 | Application submitted |
+
+---
+
+## Quick Start
+
+```python
+pip install ward-protocol==0.2.5
+```
+
+```python
+import asyncio
+from ward import WardClient, ClaimValidator
+
+# Purchase default-protection coverage
+client = WardClient(url="https://s.altnet.rippletest.net:51234/")
+result = await client.purchase_coverage(
+    wallet=depositor_wallet,        # institution signs — Ward never does
+    vault_address="rVaultXXX...",
+    coverage_drops=500_000_000,     # 500 XRP
+    period_days=90,
+    pool_address="rPoolXXX...",
+)
+assert result["ward_signed"] is False  # invariant
+
+# Validate a claim — 9 steps, all on-chain
+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.claim_payout_drops)  # min(vault_loss, policy_coverage)
+```
+
+---
+
+## SDK & API
+
+```bash
+pip install ward-protocol          # Python SDK
+npm install ward-protocol          # TypeScript SDK
+```
+
+**Hosted API:** `https://api.wardprotocol.org`
+- `GET  /health` — status check
+- `POST /keys/generate` — API key (Developer tier, no auth required)
+- `POST /validate` — 9-step claim validation
+- `POST /purchase` — unsigned coverage transaction
+
+Full docs: [wardprotocol.org/docs](https://wardprotocol.org/docs)  
+Build guide: [wardprotocol.org/build](https://wardprotocol.org/build)  
+Institutional readiness: [docs/institutional-readiness.md](docs/institutional-readiness.md)
+
+---
+
+## XLS Standards
+
+| Standard | Role in Ward |
+|----------|-------------|
+| XLS-66 | Lending vault + loan lifecycle — Ward resolves defaults |
+| XLS-20 | Policy NFT (taxon 281, `TF_BURNABLE`, non-transferable) |
+| XLS-70 | KYC/AML credential NFT (taxon 282) |
+| XLS-80 | Domain verification for vault operators |
+
+---
+
+## Multi-Chain Roadmap
+
+| Chain | Status | Notes |
+|-------|--------|-------|
+| XRPL | **Live** | Altnet E2E confirmed, mainnet at XLS-66 launch |
+| Flare EVM | Phase 1.5 | FDC enables XRPL state verification from Flare |
+| Hedera | Phase 2 | HCS + HTS + Solidity contracts |
+| Solana | Phase 3 | Anchor + Metaplex pNFT (Anodos Finance call June 12) |
+| Stellar | Phase 4 | Soroban + Horizon SSE + SEP-0010 |
+| XDC | Evaluating | XDC Network — XLS-66 compatibility assessment |
+
+Integration plans: [docs/integration/](docs/integration/)
+
+---
+
+## Running Tests
+
+```bash
+# Python (317 unit tests)
+pip install -r requirements.txt
+python -m pytest test_ward.py -m "not integration" -v
+
+# Rust (40 tests)
+cd ward && cargo test
+
+# TypeScript (45 tests)
+cd sdk/typescript && npm install && npm test
+
+# Lint
+ruff check ward/ --select=E,F,W,I --ignore=E501
+```
+
+---
+
+## Community
+
+- **Discord:** [discord.gg/cGm9m5pEGK](https://discord.gg/cGm9m5pEGK)
+- **XRPLF Discussion #474:** [github.com/XRPLF/XRPL-Standards/discussions/474](https://github.com/XRPLF/XRPL-Standards/discussions/474)
+- **Website:** [wardprotocol.org](https://wardprotocol.org)
+- **PyPI:** [pypi.org/project/ward-protocol](https://pypi.org/project/ward-protocol/)
+
+---
+
+## License
+
+The Ward Protocol specification and SDK are MIT licensed.  
+The hosted API at `api.wardprotocol.org` is subject to commercial terms.  
+Ward Protocol is protocol software — not an insurance product, financial instrument, or regulated entity.
+
+See [wardprotocol.org/terms](https://wardprotocol.org/terms)
+
+---
+
+`ward_signed = False — always.`

{ward_protocol-0.2.4 → ward_protocol-0.2.6}/pyproject.toml

@@ -5,8 +5,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ward-protocol"
-version = "0.2.4"
-description = "Open specification for XLS-66 vault default protection on the XRP Ledger"
+version = "0.2.6"
+description = "Deterministic default resolution for XLS-66 lending vaults on the XRP Ledger"
 readme = "README.md"
 requires-python = ">=3.10"
 license = {text = "MIT"}
@@ -25,9 +25,9 @@ classifiers = [
   "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-  "xrpl-py>=4.5.0",
-  "httpx>=0.25.0",
-  "pydantic>=2.5.0",
+  "xrpl-py>=4.5.0,<5.0.0",
+  "httpx>=0.25.0,<1.0.0",
+  "pydantic>=2.5.0,<3.0.0",
 ]
 
 
@@ -42,7 +42,7 @@ dev = [
 
 [project.urls]
 Homepage = "https://wardprotocol.org"
-Repository = "https://github.com/wflores9/ward-protocol"
+Repository = "https://wardprotocol.org"
 Documentation = "https://api.wardprotocol.org/docs"
 "Bug Tracker" = "https://github.com/wflores9/ward-protocol/issues"
 

{ward_protocol-0.2.4 → ward_protocol-0.2.6}/ward/__init__.py

@@ -1,5 +1,5 @@
 """
-Ward Protocol SDK — Public Package API  v0.2.2
+Ward Protocol SDK — Public Package API  v0.2.4
 
     from ward import WardClient, VaultMonitor, ClaimValidator
     from ward import EscrowSettlement, PoolHealthMonitor
@@ -7,20 +7,19 @@ Ward Protocol SDK — Public Package API  v0.2.2
     from ward import PoolHealth, VerifiedDefault, ValidationResult
 
 Changelog:
-    v0.2.2  Add ripple_time_now, get_ledger_close_time exports;
-            full __all__ with all constants; aligned with ward_client.py shim.
+    v0.2.4  README/stats corrected; CI workflows overhauled; ruff.toml added.
+    v0.2.3  On-chain coverage registry; webhook notifications; TypeScript SDK.
+    v0.2.2  Add ripple_time_now, get_ledger_close_time exports; full __all__.
     v0.2.1  Add ClaimValidator, ValidationResult, EscrowSettlement, EscrowRecord.
     v0.2.0  Initial modular split from ward_client monolith.
 """
 
-
-__version__ = "0.2.3"
+__version__ = "0.2.4"
 
 
 from ward.client import WardClient
 from ward.constants import (
     ALLOWED_WS_URLS,
-    VaultRegistration,
     CLAIM_RATE_LIMIT_MAX,
     CLAIM_RATE_LIMIT_WINDOW_S,
     CREDENTIAL_NFT_TAXON,
@@ -43,6 +42,7 @@ from ward.constants import (
     XRPL_BASE_RESERVE_DROPS,
     XRPL_OWNER_RESERVE_DROPS,
     LicenseTier,
+    VaultRegistration,
 )
 from ward.pool import PoolHealth, PoolHealthMonitor
 from ward.primitives import (
@@ -50,16 +50,16 @@ from ward.primitives import (
     SecurityError,
     ValidationError,
     WardError,
+    build_unsigned_tx,
     check_rate_limit,
     generate_claim_preimage,
     get_ledger_close_time,
     make_preimage_condition,
     ripple_time_now,
-    submit_with_retry,
+    validate_condition_hex,
     validate_drops,
     validate_drops_amount,
     validate_nft_id,
-    validate_wallet,
     validate_xrpl_address,
 )
 from ward.registry import (
@@ -74,48 +74,65 @@ from ward.vault_monitor import DefaultSignal, VaultMonitor, VerifiedDefault
 
 __all__ = [
     # Registry
-    "register_vault", "get_vaults", "get_vault", "deregister_vault",
+    "register_vault",
+    "get_vaults",
+    "get_vault",
+    "deregister_vault",
     "VaultRegistration",
-
     # Core SDK classes
     "WardClient",
-    "VaultMonitor", "VerifiedDefault", "DefaultSignal",
-    "ClaimValidator", "ValidationResult",
-    "EscrowSettlement", "EscrowRecord",
-    "PoolHealthMonitor", "PoolHealth",
-
+    "VaultMonitor",
+    "VerifiedDefault",
+    "DefaultSignal",
+    "ClaimValidator",
+    "ValidationResult",
+    "EscrowSettlement",
+    "EscrowRecord",
+    "PoolHealthMonitor",
+    "PoolHealth",
     # Errors
-    "WardError", "ValidationError", "SecurityError", "LedgerError",
-
+    "WardError",
+    "ValidationError",
+    "SecurityError",
+    "LedgerError",
     # Validators / crypto utilities
-    "validate_xrpl_address", "validate_drops_amount", "validate_drops",
-    "validate_nft_id", "validate_wallet",
+    "validate_condition_hex",
+    "validate_xrpl_address",
+    "validate_drops_amount",
+    "validate_drops",
+    "validate_nft_id",
     "check_rate_limit",
-    "make_preimage_condition", "generate_claim_preimage",
-    "get_ledger_close_time", "ripple_time_now",
-    "submit_with_retry",
-
+    "make_preimage_condition",
+    "generate_claim_preimage",
+    "get_ledger_close_time",
+    "ripple_time_now",
+    "build_unsigned_tx",
     # Licensing tier
     "LicenseTier",
-
     # Network endpoints
-    "DEFAULT_TESTNET_URL", "DEFAULT_TESTNET_WS",
-    "DEFAULT_MAINNET_URL", "DEFAULT_MAINNET_WS",
+    "DEFAULT_TESTNET_URL",
+    "DEFAULT_TESTNET_WS",
+    "DEFAULT_MAINNET_URL",
+    "DEFAULT_MAINNET_WS",
     "ALLOWED_WS_URLS",
-
     # NFT / taxon constants
-    "WARD_POLICY_TAXON", "WARD_CREDENTIAL_TAXON", "CREDENTIAL_NFT_TAXON",
-    "TF_BURNABLE", "TF_TRANSFERABLE",
+    "WARD_POLICY_TAXON",
+    "WARD_CREDENTIAL_TAXON",
+    "CREDENTIAL_NFT_TAXON",
+    "TF_BURNABLE",
+    "TF_TRANSFERABLE",
     "VALID_KYC_TYPES",
-
     # Risk / rate constants
     "MIN_COVERAGE_RATIO",
-    "CLAIM_RATE_LIMIT_MAX", "CLAIM_RATE_LIMIT_WINDOW_S",
-    "ESCROW_DISPUTE_HOURS", "ESCROW_CANCEL_HOURS",
+    "CLAIM_RATE_LIMIT_MAX",
+    "CLAIM_RATE_LIMIT_WINDOW_S",
+    "ESCROW_DISPUTE_HOURS",
+    "ESCROW_CANCEL_HOURS",
     "MONITOR_HEARTBEAT_TIMEOUT_S",
-
     # XRPL chain constants
     "LSF_LOAN_DEFAULT",
-    "XRPL_BASE_RESERVE_DROPS", "XRPL_OWNER_RESERVE_DROPS",
-    "XRP_MAX_DROPS", "RIPPLE_EPOCH_OFFSET",
+    "XRPL_BASE_RESERVE_DROPS",
+    "XRPL_OWNER_RESERVE_DROPS",
+    "XRP_MAX_DROPS",
+    "RIPPLE_EPOCH_OFFSET",
 ]

ward_protocol-0.2.6/ward/adapters/__init__.py

@@ -0,0 +1,19 @@
+"""Ward Protocol chain adapters."""
+
+from ward.adapters.axelar import AxelarAdapter
+from ward.adapters.flare import FlareAdapter
+from ward.adapters.hedera import HederaAdapter
+from ward.adapters.solana import SolanaAdapter
+from ward.adapters.stellar import StellarAdapter
+from ward.adapters.wormhole import WormholeNTTAdapter
+from ward.adapters.xdc import XDCAdapter
+
+__all__ = [
+    "WormholeNTTAdapter",
+    "FlareAdapter",
+    "AxelarAdapter",
+    "SolanaAdapter",
+    "HederaAdapter",
+    "StellarAdapter",
+    "XDCAdapter",
+]

ward_protocol-0.2.6/ward/adapters/_config.py

@@ -0,0 +1,17 @@
+"""Shared configuration guards for institutional-grade chain adapters."""
+
+from __future__ import annotations
+
+
+def require_non_placeholder(
+    value: str,
+    *,
+    field_name: str,
+    invalid_values: set[str],
+) -> str:
+    """Reject placeholder configuration that would silently misroute funds."""
+    if value in invalid_values:
+        raise ValueError(
+            f"{field_name} must be explicitly configured; placeholder defaults are blocked"
+        )
+    return value