Data formats
Certichain keeps no application database. What a person holds instead is a set of small, self-checking files and codes: a credential package, an encrypted document on IPFS, a shared document file, a disclosure file, a verifiable credential, a QR code. This section describes each one field by field, says where it is produced and consumed, and shows how a reader checks it.
Three rules hold for all of them:
- Untrusted on input. Every reader validates the whole structure before using any field, and most refuse unknown fields. A file of the wrong kind is named ("This is a key update file, not a credential package.").
- Signed facts are checked against the chain. A file can prove what an issuer signed, but only the chain says whether the credential exists, who the issuer is now, and whether it is still active.
- Secrets are marked. Files that carry a document key (the credential package, the capability link, the key update file, the package archive) are labelled as secret in the UI and on these pages.
Pages in this section
| Page | What it describes |
|---|---|
| Credential package | The JSON file the issuer gives the holder: signed fields, signature, salts, document key |
| Encrypted document container | The binary format of an encrypted document on IPFS: canonical header, padded plaintext, wrapped keys |
| Sharing files and codes | Share code, shared document file (grant), capability link, key update file |
| Invitation file | The EIP-712 invitation that lets one wallet link to one student's enrolment |
| Bulk import files | The records file and its adapters, the result file and the package archive |
| Disclosure file | The holder's challenge-bound file that shows chosen fields to one verifier |
| Verifiable credential file | The W3C VC 2.0 and Open Badges 3.0 exports of a credential |
| Compact codes | The short v1., c1. and d1. codes the phone wallet shows as QR codes |
| Deployment manifest | The JSON file that lists the contract sets on each network |
| API envelope | The response shape and signed answers of the verification API |
How the formats relate
Common building blocks
| Building block | Used by | Defined in |
|---|---|---|
EIP-712 domain { name: "Certichain", version: "1", chainId, verifyingContract } | Package, grant, invitation, VC proof | src/lib/eip712.ts |
Signed credential fields (domain, credential, signature, credentialId) | Package, grant | readSignedFields in src/lib/credential-package.ts |
| Strict field readers (addresses, 32-byte hex, decimals, signatures) | All JSON formats | src/lib/file-fields.ts |
| Base64url without padding | Container, grant, link, key update, share code | src/lib/doc-crypto/encoding.ts |
| RFC 8785 canonical JSON | Container header, metadata hash | canonicalize |
| Wrong-file detection | Package, grant, key update | src/lib/doc-crypto/file-kind.ts |
Source files
src/lib/credential-package.ts,src/lib/eip712.ts,src/lib/file-fields.tssrc/lib/doc-crypto/src/lib/invitation-file.tssrc/lib/import/