IPFS & identity storage.

Content is addressed by its hash.

IPFS, the InterPlanetary File System, is a protocol for content-addressed storage. A normal web URL is a location, it names a server and a path, and trusts whoever runs that server to hand back the right bytes. IPFS instead names content by a CID (content identifier), which is derived from a cryptographic hash of the bytes themselves. The identifier comes directly from the content, not from where it is stored.

Why identity objects are stored off-chain.

The XRP Ledger is a settlement and identity layer, not a file store. Its transaction fields are small and metered, the URI fields SciPHR writes are capped at 256 bytes on the path we validate. An identity needs to publish objects that are far larger than that. Content addressing resolves the tension cleanly: put the tiny pointer on-chain where immutability and ordering matter, and put the full object off-chain where size is cheap, with the hash carrying integrity across the boundary.

The envelope and the DID document.

Identity creation publishes two content-addressed objects and writes two on-chain anchors that point at them. They share the same shape, a small reference on-chain, the full object in IPFS, but they live on different ledger objects and use different URI schemes for good reasons.

The DID document is larger than a DID field.

A DID document is not one value, it is a small W3C record. For a SciPHR wallet it carries the wallet verification method (an Ed25519 public key) and the Secure Enclave device key (a P-256 key, plus any other enrolled devices), with the authentication and assertion relations between them. Recovery rules live in the account's on-chain signer list, and the envelope is anchored on the NFT, neither is embedded here. Even so, the document does not fit in the XRPL DID fields, which are capped at 256 bytes per field on the path we validate, so the on-chain DID has to point at it.

// DID document, pinned to IPFS, anchored by DIDSet
{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:xrpl:testnet:rSciPHRwa11et…",
  "controller": "did:xrpl:testnet:rSciPHRwa11et…",
  "verificationMethod": [
    { "id": "#wallet",           // XRPL wallet
      "type": "Ed25519VerificationKey2020",
      "publicKeyHex": "ED…" },
    { "id": "#device-primary",   // Secure Enclave
      "type": "JsonWebKey2020",
      "publicKeyJwk": { "kty":"EC", "crv":"P-256", "x":"…", "y":"…" } }
  ],
  "authentication": ["#device-primary"],
  "assertionMethod": ["#wallet"]
}
// > too large for a 256-byte DID field
// > so: DIDSet URI = ipfs://<did-document-cid>

What this adds, and what it removes.

This pattern is not free. It adds exactly one dependency to onboarding, and in return it removes a structural mismatch in the current model. The cost is worth naming plainly.

IPFS publishing during onboarding.

During onboarding the DID document is assembled from the wallet and device public keys and published to IPFS; only once its CID exists is DIDSet master-signed by the device with the resulting ipfs:// URI. Publishing is a prerequisite: if it fails, onboarding stops before the anchor is written, so there is no half-state where the chain references a CID that was never published.

• Generate keys on deviceThe XRPL Ed25519 master and regular keys are created in the Keychain; the Secure Enclave P-256 device key is created in the chip. Nothing leaves the device.
• Assemble the DID documentA W3C DID document is built from the wallet and device public keys, the Ed25519 wallet method, the P-256 Secure Enclave key, and their authentication and assertion relations. Public by design, no secret material.
• Publish to IPFSThe document is pinned to content-addressed storage, which returns its CID. This write is on the critical path and is retried; a failure halts onboarding here.
• Master-sign DIDSetThe device master-signs DIDSet with URI = ipfs://<did-document-cid>, alongside SetRegularKey, SignerListSet, and NFTokenMint.
• Backend broadcasts, XRPL settlesThe backend relays the signed blob; the ledger validates and settles. The DID now resolves to a complete, verifiable document.

Verifying off-chain content.

The reason this is safe to do off-chain is that integrity travels with the address. Whoever serves the bytes, the SciPHR gateway at ipfs.sciphr.io or any public gateway, the resolved document is bound back to the on-chain DID before it is trusted.

• DID document, resolved by ipfs://<cid>; the CID is derived from the document's bytes, and the backend rejects any resolved document whose id does not equal the DID being resolved.
• Encrypted envelope, fetched by its CID and checked against the explicit #<sha256> in the NFT anchor before any restore, anchor finalization, or metadata display.
• Content-addressed, because the CID is a hash of the bytes, any IPFS client that verifies the address detects substituted content; SciPHR pins and resolves through its own gateway at ipfs.sciphr.io.
• No custody crosses the boundary, the envelope stays sciphrtext only its owner can open, and the DID document is public metadata, so off-chain storage never holds anything that can sign or decrypt.