PUBLICATION, DEPRECATION, and TOMBSTONE are statement Edges that record the publication, deprecation advisory, and deletion of a document version, and this page also sets the specification of the version-list document written with those Edges (Codec 0x0B8L~0x0BAL).
| Item | Value |
|---|---|
| Name | DEPRECATION (specification document BIND DEPRECATION) |
| TAG ID | 0x0B9L |
| Codec ID | 0x00000B90 |
| Specification document | 0x00000000/codecs/0x00000B90/ (DECLARE target 0B90) |
| Section | 5 0101 (Edge statement), offset within section C = 25 |
| Kind | Edge · family: statement, group: other |
| TAG WORD | 0000 1011 1001 LLLL (000K KKKC CCCC LLLL) |
| Index description | Deprecation of a published version. DOC-POINTER |
| Hugo side | edge/publication.md (that page also covers PUBLICATION and TOMBSTONE) |
Fields (specification document)
The order of FIELDs in the document is the order of the Payload fields (Codec specification document). The Edge Id of an Edge is not declared as a FIELD.
| Order | Field (BIND) | FIELD | Width | Accepted form (CODEC) | ENUM |
|---|---|---|---|---|---|
| 1 | doc | #2 | record | 0410 DOC-POINTER, 0420 CODEC-POINTER |
These are the statement Edges that record the publication, deprecation, and deletion of a document, and the specification of the version-list document written with those Edges. They set the version-list form of publication addresses and version list.
Codes
| Codec | Name | Payload |
|---|---|---|
0x0B8L | PUBLICATION | Edge Id, DOC-POINTER, content hash |
0x0B9L | DEPRECATION | Edge Id, DOC-POINTER |
0x0BAL | TOMBSTONE | Edge Id, DOC-POINTER, reason category |
- The three codes are built into the decoder (layer 0). A version list is interpreted without consulting a codebook.
- No subform (Codec-specific TAG) is used. The Edge rule that the first element of the Payload is the Edge Id is kept as is.
Layout
TAG WORD Edge, Codec 0x0B8L / 0x0B9L / 0x0BAL
[Length extension TAG]
Edge Id LOCAL Reference record
Document DOC-POINTER Reference record (Issuer, document ID, version ID). For a codec version list, CODEC-POINTER
Content hash 16 WORD (PUBLICATION)
Reason category 1 WORD (TOMBSTONE)
| Field | Width | Description |
|---|---|---|
| Edge Id | LOCAL Reference record | Sequence number in the list. Numbered from 1 and appended in sequence |
| Document | DOC-POINTER record | One version of the published document (DOC-POINTER). The Issuer and document ID are the same as the document the list covers. This lets the list document say what it is a list of even without a path. The version ID is the sequence number within that document (Document version), and 0 (latest) is not used. The version list of a codec uses CODEC-POINTER (Issuer, codec ID, version ID) |
| Content hash | 16 WORD | The content hash of that version (SHA-256, Document content hash) |
| Reason category | 1 WORD | Category code of the deletion reason. The code table is an open problem |
- The length after the DOC-POINTER is fixed per code (16, 0, 1 WORD). Otherwise, reject.
- No time is placed in a record. The
RECORDED-ATof the list document in which the record first appeared is the time of publication, deprecation, or deletion.
Version-list document
The publisher keeps appending one version-list document per document: /<Issuer>/docs/<document ID>/versions.geul (for a codec, /<Issuer>/codecs/<codec ID>/versions.geul; for the Issuer list, see below). Every version of that document published at that publisher goes into one list.
DOC-1WORD/2WORD/4WORD total length
SPEC-VERSION 0x0001 (v1)
PARENT SHA-256-DIGEST Value. Content hash of the previous list document (none for the first list)
RECORDED-AT POSIX-TIMESTAMP-SECONDS Value. Time this list was issued
NEXT-LOCAL-ID Next LOCAL ID to assign (if there are versions)
SIGNATURE The publisher's signature. Its subject is the content hash of this list document
BODY
PUBLICATION · DEPRECATION · TOMBSTONE …
END
- HEAD Meta: SPEC-VERSION, PARENT, RECORDED-AT, NEXT-LOCAL-ID, SIGNATURE.
- A version-list document holds no
DOC-ID(an exception for list documents, DOC-ID). A list is not a published document but a record attached to that document. Which document a list belongs to is stated by the DOC-POINTER (document ID) of the records. So even when received without a path (hashes/, a dump), it is known what the list is of. - The document IDs of the records must all be the document the list covers. Reject a record of another document.
- A version-list document holds no IMPORT and uses only layer-0 Codecs. BODY holds only PUBLICATION, DEPRECATION, and TOMBSTONE. It holds no document-name BIND (publication addresses and version list).
- A new list document keeps the BODY of the previous list document as is at the front and appends records. It does not edit, delete, or reorder.
- The publisher signs the list. For geul.org publication, geul.org (the GEUL Issuer) signs; for private publication, that Issuer signs.
- Document ID
0x0000000000000000is the Issuer’s term-definition index document (Issuer and publication). The Issuer itself is pointed to by ISSUER-POINTER.
Version list of the list document
The list document is the single Issuer list issuers/ (publication addresses and version list). The Issuer list also starts at version 1 and has a version list issuers/versions.geul. Its records point to list versions by a DOC-POINTER with the reserved document ID (0x00000000, 0xFFFFFFFFFFFFFFFF, version ID).
- The record form is as above. So even when received through
hashes/, it is known what the list is of. - The list document itself (
<version ID>.geul) also holds noDOC-ID. - Document ID
0xFFFFFFFFFFFFFFFFis not served at an<Issuer>/docs/<document ID>/address at any Issuer (404). - The
latest.geulof the list is an alias that is not stored. It finds the most recent version in this version list and serves those bytes.
Rules
- The version IDs of PUBLICATION are ascending from 1 without gaps. The version ID is assigned by the publisher.
- The same content hash is not published again. If it already exists, return that version ID.
- DEPRECATION and TOMBSTONE point only to the version ID of a PUBLICATION that appeared earlier. Reject one that points to a nonexistent version.
- The state of a version is computed by applying the records in order. Published → deprecated → deleted. A deleted version is not published again and is not served.
- The latest version is the highest version ID that is neither deprecated nor deleted.
- When a version ID reaches the end of 2 WORDs, that document is published no further and a new document ID is used.
Addresses
/.well-known/geul/<Issuer>/docs/<document ID>/versions.geul latest list document (mutable)
/.well-known/geul/<Issuer>/codecs/<codec ID>/versions.geul latest list document of a codec (mutable)
/.well-known/geul/issuers/versions.geul latest version list of the Issuer list (mutable)
/.well-known/geul/<Issuer>/hashes/<content hash>.geul past list document (immutable)
- What is mutable is the latest-list address. A received list is verified by its signature,
RECORDED-AT, and thePARENTchain. - All past list documents remain in
<Issuer>/hashes/. Following thePARENTchain, the list at any point in time can be traced back.
Verification
- The list document must carry a
SIGNATUREby the key designated for the publisher. - The document ID of the records must equal the requested document ID.
- The content hash of the previous list kept in the lock record must be in the
PARENTchain of the new list. The BODY of that list must equal the leading part of the new list’s BODY. - The content hash of a received document must equal the value written by the PUBLICATION of that version ID, and the document’s
DOC-IDmust equal the requested Issuer and document ID. A list document has noDOC-ID.
Open problems
- The reason-category code table.
- The default signature algorithm and the
SIGNATUREPayload layout. - When and in what form to move to a Merkle log (inclusion and consistency proofs) as lists grow.
- Issuer-level rollback protection. Because a list forms its own chain per document, an attack presenting an old list for only one document is blocked only by that document’s chain.
Related pages
Specification document source
This is the specification document 0x00000000/codecs/0x00000B90/latest.geul as read with geul show (hexadecimal in uppercase).
SPEC-VERSION 0x0001
DOC-ID 0x04260000000000000B9000000000
BODY
#1 DECLARE 0x0B90
#2 FIELD #1 record
#6 CODEC #2 0x0410
#4 BIND #1 "DEPRECATION"
#5 BIND #2 "doc"
#7 CODEC #2 0x0420