Merge pull request #54 from mpcp-protocol/docs/remove-nft-references

docs: replace NFT references with XLS-70 credentials

Author: naory

README.md

@@ -118,7 +118,7 @@ Import from `mpcp-service/sdk`.
 ```
 mpcp-reference
  ├── src
- │   ├── anchor/          # On-chain adapters: did:xrpl, HCS, XRPL NFT revocation
+ │   ├── anchor/          # On-chain adapters: did:xrpl, HCS, XRPL NFT policy anchoring, XLS-70 credential revocation
  │   ├── hash/            # Canonical JSON serialization and SHA-256 hashing
  │   ├── policy-core/     # Policy evaluation engine and types
  │   ├── protocol/        # Artifact types, schemas, SBA/PolicyGrant signing, Trust Bundles

docs/animation/MPCP_ANIMATION_PACK.md

@@ -113,7 +113,7 @@ Autonomous parking example
 Vehicle enters → policy → budget → Trust Gateway → XRPL settlement
 
 Scene 5
-Policy document anchored to ledger (Hedera HCS / XRPL NFT)
+Policy document anchored to ledger (Hedera HCS or XRPL NFT)
 
 Scene 6
 Verification replay animation

docs/implementation/dispute-verification.md

@@ -18,7 +18,7 @@ const result = verifyDisputedSettlement({
   context: settlementVerificationContext,
   // Optional: ledger anchor result from policy document anchoring
   ledgerAnchor: {
-    anchorRef: grant.anchorRef,  // "hcs:0.0.12345:42" or "xrpl:nft:ABC123..."
+    anchorRef: grant.anchorRef,  // e.g. "hcs:0.0.12345:42" or "xrpl:nft:ABC123..."
     rail: "hedera-hcs",
     sequenceNumber: "42",
     topicId: "0.0.12345",

docs/implementation/intent-anchoring.md

@@ -2,7 +2,9 @@
 
 Optional support for publishing MPCP policy documents to distributed ledgers. Provides public auditability, dispute protection, and tamper-evident policy history.
 
-**Hedera HCS** adapter is implemented (publish policy document to a topic). **XRPL NFT** adapter is implemented (mint an NFT representing the policy document). Both return an `anchorRef` that is stored on the PolicyGrant.
+**Hedera HCS** and **XRPL NFT** adapters support **policy document** anchoring: HCS publishes to a topic; the XRPL path encrypts (optional), stores ciphertext on IPFS, and records the policy via an NFToken whose URI points at that content (`anchorRef` = `xrpl:nft:{tokenId}` with the policy hash in the anchoring flow). Store the returned reference on the PolicyGrant for auditability and dispute resolution.
+
+> **Grant liveness** (revoking or invalidating a grant) is a **separate** mechanism: XRPL **XLS-70** credentials (`CredentialCreate` / `CredentialDelete`). That replaces the older **NFT mint-on-issue / burn-on-revoke** pattern for **grants**. Do not conflate XLS-70 grant credentials with **policy** `anchorRef` on HCS or XRPL NFT.
 
 ## Purpose
 
@@ -17,36 +19,48 @@ The `anchorRef` field on a PolicyGrant identifies the on-chain location of the a
 | Format | Rail | Example |
 |--------|------|---------|
 | `hcs:{topicId}:{seq}` | Hedera HCS | `hcs:0.0.12345:42` |
-| `xrpl:nft:{tokenId}` | XRPL NFT | `xrpl:nft:ABC123...` |
+| `xrpl:nft:{tokenId}` | XRPL NFT (policy document URI) | `xrpl:nft:00080000...` |
 
 ## Usage
 
 ```typescript
-import { hederaHcsAnchorPolicyDocument, checkXrplNftRevocation } from "mpcp-service/anchor";
+import {
+  hederaHcsAnchorPolicyDocument,
+  xrplEncryptAndStorePolicyDocument,
+  checkXrplNftRevocation,
+} from "mpcp-service/anchor";
 
 const policyDoc = { version: "1.0", policyHash: "a1b2c3...", issuedAt: "2026-01-01T00:00:00Z" };
 
 // Hedera HCS (requires MPCP_HCS_POLICY_TOPIC_ID, MPCP_HCS_OPERATOR_ID, MPCP_HCS_OPERATOR_KEY)
 const result = await hederaHcsAnchorPolicyDocument(policyDoc);
-// { anchorRef: "hcs:0.0.12345:42", rail: "hedera-hcs", anchoredAt: "..." }
+// { reference: "hcs:0.0.12345:42", rail: "hedera-hcs", anchoredAt: "..." }
+
+// XRPL NFT path: encrypt + IPFS → CID for NFToken URI (`ipfs://{cid}`); mint off-chain / policy authority, then anchorRef = `xrpl:nft:{tokenId}`
+// const prep = await xrplEncryptAndStorePolicyDocument(policyDoc, { encryption: {...}, ipfsStore: myStore });
 
-// Store the anchorRef on the PolicyGrant
+// Optional: verify the policy-anchor NFT still exists on XRPL (policy audit / tamper check).
+// This is not grant liveness — use XLS-70 credentials for that (see PolicyGrant).
+const nftStatus = await checkXrplNftRevocation("00080000ABCD...");
+// { revoked: false } if the anchor NFT still exists; { revoked: true } if burned
+
+// Store the anchor reference on the PolicyGrant (maps to anchorRef on the grant)
 const grant = createPolicyGrant({
   policyHash: "a1b2c3",
   allowedRails: ["xrpl"],
   allowedAssets: [...],
   expiresAt: "2030-12-31T23:59:59Z",
-  anchorRef: result.anchorRef,
+  anchorRef: result.reference,
 });
 ```
 
 ## PolicyAnchorResult
 
 ```typescript
 interface PolicyAnchorResult {
-  anchorRef: string;         // "hcs:{topicId}:{seq}" | "xrpl:nft:{tokenId}"
+  anchorRef: string;         // "hcs:{topicId}:{seq}" | "xrpl:nft:{tokenId}" (SDK field: `reference`)
   rail: AnchorRail;
-  txHash?: string;           // XRPL transaction hash
+  txHash?: string;           // Optional ledger record id (implementation-specific)
   topicId?: string;          // Hedera HCS topic ID
   sequenceNumber?: string;   // Hedera HCS sequence number
   anchoredAt?: string;       // ISO 8601
@@ -72,20 +86,16 @@ The Hedera HCS adapter publishes policy documents to a Hedera Consensus Service
 - `MPCP_HCS_POLICY_TOPIC_ID` — HCS topic ID for policy anchoring
 - `HEDERA_NETWORK` (optional) — `testnet` or `mainnet`, default `testnet`
 
-## XRPL NFT Adapter
-
-The XRPL NFT adapter mints an NFT on the XRP Ledger representing the policy document. The NFT token ID becomes the `anchorRef`.
+## XRPL NFT Adapter (policy document anchoring)
 
-**Revocation check:** Use `checkXrplNftRevocation(tokenId)` to verify whether the NFT has been burned (which signals policy revocation).
+> **Scope:** This path is for **policy document anchoring** only (tamper-evident policy history on XRPL). **Grant liveness** (revocation) uses **XLS-70 Credentials** — see PolicyGrant and the XRPL profile; do not use NFToken burn as the grant revocation mechanism.
 
-```typescript
-import { checkXrplNftRevocation } from "mpcp-service/anchor";
+The reference SDK provides `xrplEncryptAndStorePolicyDocument` (in `mpcp-service/anchor`): it encrypts the policy document, uploads the ciphertext via an injected IPFS client, and returns a **CID** intended as the NFToken URI (`ipfs://{cid}`). **NFTokenMint** (and setting `anchorRef` to `xrpl:nft:{tokenId}`) is typically performed by the policy authority service, not inside the lightweight SDK.
 
-const revoked = await checkXrplNftRevocation("ABC123...");
-if (revoked) {
-  // Policy has been revoked on-chain
-}
-```
+**Requirements:**
+- Caller-supplied **IPFS store** (`PolicyDocumentIpfsStore`) — no bundled IPFS client
+- Encryption options when using encrypted submit mode (`PolicyAnchorEncryptionOptions`)
+- XRPL account with NFToken issuance rights for minting the policy anchor NFT
 
 ## XRPL Payment Memos
 

docs/implementation/l1-ecosystem-evaluation.md

@@ -39,7 +39,7 @@ Adding a second rail is a protocol-level decision. It requires:
 | Identity | `did:xrpl` | On-ledger DID method; XLS-70 Credentials for grant liveness |
 | Offline friendliness | Strong | Trust Bundle + signature verification; no chain client needed |
 | Tooling | Good | `xrpl.js`, testnet faucet, well-documented |
-| MPCP integration | Deep | Anchor adapters, DID resolver, NFT revocation, stablecoin profile, golden vectors |
+| MPCP integration | Deep | Anchor adapters, DID resolver, NFT policy anchoring, XLS-70 credential revocation, stablecoin profile, golden vectors |
 
 **Assessment:** Production-ready for MPCP v1.0. No gaps.
 

docs/reference/service-api.md

@@ -67,17 +67,19 @@ Publish a policy document to a ledger and return an `anchorRef` for use in Polic
 
 ```typescript
 // Hedera HCS (requires MPCP_HCS_POLICY_TOPIC_ID, MPCP_HCS_OPERATOR_ID, MPCP_HCS_OPERATOR_KEY)
-const result = await anchorPolicyDocument(policyDoc, { rail: "hedera-hcs" });
-// result.anchorRef: "hcs:{topicId}:{sequenceNumber}"
+const hcs = await anchorPolicyDocument(policyDoc, { rail: "hedera-hcs" });
+// hcs.anchorRef: "hcs:{topicId}:{sequenceNumber}"
 
-// XRPL NFT
-const result = await anchorPolicyDocument(policyDoc, { rail: "xrpl-nft" });
-// result.anchorRef: "xrpl:nft:{tokenId}"
+// XRPL NFT — policy document anchoring (encrypted doc → IPFS URI on NFToken; mint completed by policy authority)
+const nft = await anchorPolicyDocument(policyDoc, { rail: "xrpl-nft" /* + encryption / ipfs options */ });
+// nft.anchorRef: "xrpl:nft:{tokenId}"
 ```
 
-Supported rails: `hedera-hcs`, `xrpl-nft`.
+Supported rails for **policy document** anchoring: **`hedera-hcs`**, **`xrpl-nft`**.
 
-The returned `anchorRef` can be stored on the PolicyGrant (`grant.anchorRef`) to provide on-chain auditability.
+> **Grant liveness** (whether a grant is still valid) is **not** defined by burning the policy anchor NFT. Use **XLS-70** `CredentialCreate` / `CredentialDelete` on XRPL for credential-based grant revocation. Policy `anchorRef` (HCS or XRPL NFT) remains the tamper-evident **policy document** anchor only.
+
+The returned `anchorRef` can be stored on the PolicyGrant (`grant.anchorRef`) to provide on-chain auditability of the **policy document**.
 
 ---