Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
202 commits
Select commit Hold shift + click to select a range
002bc32
feat(drive)!: separate retained document history from primary storage
shumkov Sep 10, 2026
3eb0156
feat(drive)!: prove composite document history and lifecycle counts
shumkov Sep 10, 2026
e901558
feat(drive-abci)!: migrate retained histories at protocol activation
shumkov Sep 10, 2026
26d5f78
feat(sdk)!: expose authenticated document history v1
shumkov Sep 10, 2026
108a501
fix(drive): charge provable counts when propagating history roots
shumkov Sep 10, 2026
145f653
fix(drive): dispatch history versions and authenticate revision offsets
shumkov Sep 10, 2026
bded9a6
fix(drive): validate the complete history migration inventory
shumkov Sep 10, 2026
9a2e8e1
test(drive): cover migrated indexes and signed history updates
shumkov Sep 10, 2026
4288249
docs(version): document the keep-history activation boundary
shumkov Sep 10, 2026
7a11092
fix(sdk): retain both proofs in document history proof info
shumkov Sep 10, 2026
e49b7e5
test(drive): pin sum-only primary trees across history activation
shumkov Sep 10, 2026
fb52284
docs(drive-abci): explain activation migration halt semantics
shumkov Sep 10, 2026
40daacc
fix(drive): require GroveDB v1 envelopes for history v1
shumkov Sep 10, 2026
631f28b
fix(drive): account for and verify history migration operations
shumkov Sep 10, 2026
52f4522
test(drive): preserve legacy history replay and cover protocol 14
shumkov Sep 10, 2026
ed8ac42
fix(sdk): classify oversized history limits as input errors
shumkov Sep 10, 2026
8dcb080
fix(drive): expose history verification in server builds
shumkov Sep 10, 2026
66dd94f
test(drive): compare migration revision counts before zipping
shumkov Sep 10, 2026
39b6126
fix(drive): verify history lifecycle metadata with absence proofs
shumkov Sep 12, 2026
44f807b
fix(sdk): reject proof-disabled document history queries before sending
shumkov Sep 12, 2026
53d1fa4
docs(dapi-grpc): say what the history v1 messages describe and why
shumkov Sep 13, 2026
73b66f7
feat(dapi)!: serve document history as one v1 query with one proof
shumkov Sep 13, 2026
083f165
style(macros): order imports the way rustfmt 1.98 expects
shumkov Sep 13, 2026
3a5f53b
feat(dapi)!: replace the v0 document history query in place
shumkov Sep 13, 2026
afef5ee
fix(drive): name the envelope requirement without a wire version
shumkov Sep 13, 2026
be6cb2e
test(js-evo-sdk): stub the history proof result with its single proof…
shumkov Sep 13, 2026
d568257
fix(sdk): pass the platform version to the history tenderdash check
shumkov Sep 13, 2026
09b3e7c
feat(dapi)!: answer document history with the usual result oneof
shumkov Sep 13, 2026
a95600c
fix(drive): report an unexpected index leaf as corruption during migr…
shumkov Sep 13, 2026
a3df992
refactor(drive)!: select the keep-history storage layout through a st…
shumkov Sep 15, 2026
a803159
refactor(dapi)!: call the history query's selection a filter
shumkov Sep 15, 2026
75bc2bd
test(drive): re-pin the history fixture roots after the contract vers…
shumkov Sep 15, 2026
18cb24a
chore(drive): drop the migration benchmark example and its cost counters
shumkov Sep 15, 2026
8b44ca3
refactor(drive)!: keep the history layout out of shipped generations
shumkov Sep 15, 2026
2c25b31
fix(drive-abci): answer refused history reads as invalid arguments
shumkov Sep 15, 2026
20fceab
refactor(drive): split the history module by concern
shumkov Sep 16, 2026
b00d2e5
docs(drive): say what the protocol 14 storage generations change
shumkov Sep 16, 2026
db16d2c
refactor(drive)!: verify proved cursors through a protocol 14 generation
shumkov Sep 16, 2026
43f0069
fix(wasm-sdk): return the common proof response for document history
shumkov Sep 16, 2026
40a28bb
feat(drive): keep the legacy history readers beside the history query
shumkov Sep 16, 2026
b46ba7b
refactor(drive): version the document history readers like the writers
shumkov Sep 16, 2026
252d6ab
refactor(drive): organize the document history query like the other q…
shumkov Sep 16, 2026
bbade06
fix(drive-abci): guard history migration activation
shumkov Sep 16, 2026
1a3cdd6
fix(drive): keep history query builder available
shumkov Sep 16, 2026
f4b84eb
refactor(drive): route history layout by method version
shumkov Sep 16, 2026
f7ad6b8
refactor(drive): version primary key history queries
shumkov Sep 16, 2026
f5f36d1
style(drive): group document path imports
shumkov Sep 16, 2026
cca128a
test(drive): cover writes across history migration
shumkov Sep 16, 2026
fdc902d
refactor(wasm-sdk): type document history results
shumkov Sep 16, 2026
2a8bdd2
fix(history): address review compatibility gaps
shumkov Sep 16, 2026
b51c712
fix(history): retain revisionless legacy documents
shumkov Sep 16, 2026
ad35d69
fix(drive): account for summable index references
shumkov Sep 17, 2026
d7d682b
feat(platform)!: activate keep-history storage at protocol version 15
shumkov Sep 18, 2026
7615290
fix(drive): keep the history time bound inclusive on the legacy layout
shumkov Sep 18, 2026
7c5c485
chore(dapi-grpc): regenerate the checked-in clients
shumkov Sep 18, 2026
b1442a7
refactor(drive): derive the reference bucket tree type in one place
shumkov Sep 19, 2026
8eeca0c
feat(platform): add version slots for the document lifecycle
shumkov Sep 10, 2026
2c5f2d7
feat(dpp)!: admit deletable keep-history types and add canBeErased
shumkov Sep 10, 2026
0d70596
feat(dpp)!: add the document erase transition kind
shumkov Sep 10, 2026
d145eec
feat(drive): give keep-history documents a delete and an erase
shumkov Sep 10, 2026
713df6a
feat(drive): route the erase transition through to its storage operation
shumkov Sep 10, 2026
0b156bb
feat(drive-abci): validate the document lifecycle before deleting or …
shumkov Sep 10, 2026
da53e46
feat(sdk): report the deleted and erasing states through the history …
shumkov Sep 10, 2026
0fb3095
fix(drive): write the lifecycle record from a fully known element
shumkov Sep 10, 2026
519df97
feat(sdk): expose the document erase across the client surfaces
shumkov Sep 10, 2026
1465ea1
test(drive): pin the storage behaviour of the document lifecycle
shumkov Sep 10, 2026
4b8d08d
test: pin the lifecycle through signed transitions and version slots
shumkov Sep 10, 2026
7fa1b61
fix(drive): read the erasing sentinel off the revision, not the time
shumkov Sep 10, 2026
b50990d
test: exercise the lifecycle over migrated state and end to end
shumkov Sep 10, 2026
aee2225
test(wasm-sdk): pin the erasing state and its times as exact BigInts
shumkov Sep 10, 2026
a481940
test(drive): pin the aggregates and index entries a delete releases
shumkov Sep 10, 2026
4728416
fix(sdk): wait for an erase's affected state, not for proved execution
shumkov Sep 10, 2026
e277027
fix(dpp): make the lifecycle contract refusals paid consensus errors
shumkov Sep 10, 2026
b92e4f7
fix(drive): unflag the lifecycle container and dispatch its erase est…
shumkov Sep 10, 2026
a9f886d
feat(drive-abci): charge an erase for the refunds it hands out
shumkov Sep 10, 2026
6576027
test: close the lifecycle's accounting and proof evidence gaps
shumkov Sep 10, 2026
b273c0e
test(platform-test-suite): read the network from the environment
shumkov Sep 11, 2026
fce5192
test(platform-test-suite): refetch the note before every keep-history…
shumkov Sep 11, 2026
8db8a6b
test(platform-test-suite): sign the keep-history erase with the HIGH key
shumkov Sep 11, 2026
f58df76
test(platform-test-suite): wait for the refused delete to propagate b…
shumkov Sep 11, 2026
98e99e3
fix(wasm-sdk): let an erase name the identity that submits it
shumkov Sep 12, 2026
fc9fb5d
fix(dpp): keep loading legacy contested keep-history contracts at pro…
shumkov Sep 12, 2026
007044d
fix(drive): keep refusing by-revision reads of a gapped history after…
shumkov Sep 12, 2026
f0edec2
fix(sdk): keep every lifecycle state and time in mocked document hist…
shumkov Sep 12, 2026
e953db4
test(drive-abci): reject tampered lifecycle claims for deleted and er…
shumkov Sep 12, 2026
f08dee3
fix(wasm-sdk): refuse JavaScript numbers past the safe range in histo…
shumkov Sep 12, 2026
a7660a7
test(sdk): drop needless borrows in the history mock round-trip test
shumkov Sep 12, 2026
ea6dcf8
fix(sdk): sign an erase with its settings and refuse unsupported vers…
shumkov Sep 13, 2026
3cb369c
refactor(platform)!: land the document lifecycle as protocol 14 gener…
shumkov Sep 18, 2026
e52b0c2
refactor(platform)!: move the document lifecycle to protocol 15 gener…
shumkov Sep 18, 2026
a537d25
fix(drive): refuse a keep-history delete through every entry point th…
shumkov Sep 18, 2026
f88edc5
fix(drive): never write a new document over a deleted one's retained …
shumkov Sep 19, 2026
a5a3d20
refactor(platform)!: carry the erase kind on the shipped batch transi…
shumkov Sep 19, 2026
e04c014
test(platform): pin the erase kind's wire byte and its refusal at pro…
shumkov Sep 19, 2026
1e8c9d3
fix(drive): bill the contract fetch of a lifecycle delete and version…
shumkov Sep 20, 2026
9c8532d
fix(drive): refuse to erase a document that is not deleted
shumkov Sep 21, 2026
e659eb1
refactor(dpp): have document type update validation v2 delegate to v1
shumkov Sep 21, 2026
8faa6c1
refactor(drive-abci): report the lifecycle states from the one histor…
shumkov Sep 21, 2026
21b0369
refactor(drive): let every delete entry point record a keep-history d…
shumkov Sep 21, 2026
fc67863
refactor(drive)!: give the delete entry points the block and deleter …
shumkov Sep 21, 2026
c599ee2
docs(book): a new input changes a method's signature, not the method …
shumkov Sep 21, 2026
aa43260
refactor(wasm-sdk): drop the exact-integer selector type the deserial…
shumkov Sep 21, 2026
6cdd76f
refactor(drive)!: keep the lifecycle record in dpp and serialize it w…
shumkov Sep 21, 2026
b3e8fe2
docs(book): describe the keep-history document lifecycle and history …
shumkov Sep 22, 2026
f24b021
chore(drive): merge v5.1-dev into composite history
shumkov Oct 21, 2026
cb08ff9
fix(sdk): seed unpinned devnets at protocol 14
shumkov Oct 21, 2026
5c91ebf
fix(drive): reject unknown document history writer layouts
shumkov Oct 21, 2026
bd181a3
docs(grpc): describe document history requests without release narration
shumkov Oct 21, 2026
cd4b47a
test(drive): cover upstream index kinds in history migration
shumkov Oct 21, 2026
f1b8726
fix(drive): size history pointer read estimates like writes
shumkov Oct 21, 2026
4a3b50e
fix(drive): assert the history proof envelope floor
shumkov Oct 21, 2026
87c1fb6
test(drive): exercise contract writers at protocol 14 and 15
shumkov Oct 21, 2026
ea00051
style(history): keep protocol assertions and comments precise
shumkov Oct 21, 2026
fd4825c
fix(wasm-sdk): expose retained document history layout types
shumkov Oct 21, 2026
18aadd9
refactor(drive): version the document history layout independently
shumkov Oct 21, 2026
37e16c3
fix(sdk): send history filters before protocol discovery
shumkov Oct 21, 2026
90594f0
fix(drive): accept revision 65536 in history revision filters
shumkov Oct 22, 2026
d3a1182
fix(wasm-sdk): accept returned history entries as cursors
shumkov Oct 22, 2026
8ee4167
fix(dapi): preserve document history wire version zero
shumkov Oct 22, 2026
452dd1c
fix: gate versioned document history queries at activation
shumkov Oct 22, 2026
6beb493
fix(sdk): use version one for retained document history
shumkov Oct 22, 2026
93e90fd
style(drive-abci): drop a same-type conversion in the history offset …
shumkov Oct 22, 2026
342eced
chore: merge v5.1-dev into retained document history
shumkov Oct 27, 2026
b40e744
build: pin GroveDB branch-local count offsets
shumkov Oct 27, 2026
3effb5f
feat(version): select GroveDB V5 for protocol 15
shumkov Oct 27, 2026
5a80fbe
fix(proofs): select document layouts from the signed producer version
shumkov Oct 27, 2026
b6757c4
feat(history): serve revision pages in one GroveDB proof
shumkov Oct 27, 2026
38a4041
test(version): preserve query and activation behavior with GroveDB V5
shumkov Oct 27, 2026
01ff656
fix(sdk): verify history using the signed producer version
shumkov Oct 27, 2026
a251681
test(drive): preserve released execution-proof query layouts
shumkov Oct 28, 2026
20dd12c
test(drive): bound keep-history contract update fees
shumkov Oct 28, 2026
2c859b0
fix(wasm-sdk): return errors for missing history proof metadata
shumkov Oct 28, 2026
3c73a98
chore(history): merge current v5.1-dev and merged GroveDB history sup…
shumkov Nov 9, 2026
3b7053e
docs(history): clarify PV15 estimates and producer proof layout
shumkov Nov 9, 2026
d124bcc
test(history): verify legacy proofs with current Grove rules
shumkov Nov 9, 2026
64963c0
style(history): format Grove activation assertions
shumkov Nov 9, 2026
aa01294
fix(dapi-client): declare that document history v1 needs protocol 15
shumkov Nov 9, 2026
d9ea5f8
test(drive-abci): account for retained-history trees in genesis roots
shumkov Nov 9, 2026
4ce0707
chore(history): merge current v5.1-dev and storing-epoch refund pricing
shumkov Nov 9, 2026
604d9cc
test(drive): record storing epochs in the history index fixture
shumkov Nov 9, 2026
5ecec6d
test(drive-abci): refresh activation root for upstream private stores
shumkov Nov 9, 2026
4ba004d
refactor(drive)!: name timestamp history APIs after their exclusive b…
shumkov Nov 9, 2026
41bca10
refactor(drive): require composite method versions for history queries
shumkov Nov 9, 2026
e2b30e1
test(drive): bound storage and processing estimates independently
shumkov Nov 9, 2026
c067914
refactor(drive): finish history query boundary cleanup
shumkov Nov 9, 2026
438a730
chore: merge v5.1-dev into retained history storage
shumkov Nov 10, 2026
a666534
merge(platform): merge v5.1-dev through f603f988ae
shumkov Nov 10, 2026
a375f69
test(drive): cover unchanged history array entries after owner handover
shumkov Nov 10, 2026
40ba348
style(platform): remove formatting churn from the merge resolutions
shumkov Nov 10, 2026
7ceca85
test(drive-abci): name sponsored history coverage after pointer handover
shumkov Nov 10, 2026
bc11ed0
test(drive): strengthen temporal proof verification controls
shumkov Nov 10, 2026
f39c665
docs(drive): clarify history query caps and signed proof tables
shumkov Nov 10, 2026
000b0b6
chore: merge v5.1-dev activation updates into retained history
shumkov Nov 10, 2026
d5ece21
test(drive): strengthen the temporal bound proof control
shumkov Nov 10, 2026
05b5811
chore: merge v5.1-dev into keep-history-storage-v2
shumkov Nov 11, 2026
cb336dd
test(drive-abci): cover references to retained history targets
shumkov Nov 11, 2026
74a67d2
chore: merge current history storage into lifecycle
shumkov Nov 11, 2026
43c16a8
fix(dapi): regenerate lifecycle response clients
shumkov Nov 11, 2026
0063da3
chore: merge history storage upstream catch-up
shumkov Nov 11, 2026
656edc4
test(drive-abci): cover references across history lifecycle
shumkov Nov 11, 2026
90a2775
chore(version): remove redundant verifier table update
shumkov Nov 11, 2026
7d80b97
docs: describe protocol fifteen history lifecycle and proofs
shumkov Nov 11, 2026
68f9c96
refactor(sdk): express erase base versions as a range
shumkov Nov 11, 2026
aab74ec
fix(dpp): retain parser generation in direct test callers
shumkov Nov 11, 2026
c921499
refactor(dpp): place parser grammars before test modules
shumkov Nov 11, 2026
565db7a
chore: merge v5.1-dev into keep-history-storage-v2
shumkov Nov 12, 2026
50a02ab
docs(dpp): explain erase conversion admission bounds
shumkov Nov 12, 2026
1a46ca9
fix(drive-abci): import erase action validation traits
shumkov Nov 12, 2026
2ff04a5
test(drive): cover flagged summable reference refresh estimates
shumkov Nov 12, 2026
5cd749f
chore: merge history storage fee estimate catch-up
shumkov Nov 12, 2026
282b78f
chore: merge v5.1-dev into keep-history-storage-v2
shumkov Nov 12, 2026
a9d8f2d
chore: merge history storage reference catch-up
shumkov Nov 12, 2026
c5bc974
fix(drive): supply deleter in summable estimate fixture
shumkov Nov 12, 2026
3f37941
fix(drive): preserve empty history absence without a lifecycle record
shumkov Nov 12, 2026
5b3a02c
test(drive): exercise migrated contested history from its legacy prot…
shumkov Nov 12, 2026
729524a
test(drive): verify lifecycle rollback and persisted continuation
shumkov Nov 12, 2026
d6945af
fix(drive): admit lifecycle inserts in the client create-cost mirror
shumkov Nov 12, 2026
4e98e2f
fix(drive): exclude retained history from lifecycle delete refunds
shumkov Nov 12, 2026
4aa9304
test(drive-abci): align lifecycle fixtures with current transition APIs
shumkov Nov 12, 2026
16eb9f8
test(drive-abci): pin lifecycle reference outcomes for either-kind ta…
shumkov Nov 12, 2026
339509f
fix(platform-wallet): summarize erase transitions without a transfer
shumkov Nov 12, 2026
3f55e7d
docs(versioning): describe lifecycle selectors in protocol 15
shumkov Nov 12, 2026
a375a28
chore: merge v5.1-dev after history storage integration
shumkov Nov 12, 2026
862e0bf
docs: align lifecycle and native validation version notes
shumkov Nov 12, 2026
0550f5a
docs: clarify lifecycle record ownership and create refusal
shumkov Nov 12, 2026
bccbf2c
docs(rs-sdk): correct lifecycle query timing example
shumkov Nov 12, 2026
2be8381
fix(drive): preserve pending operations in force deletion
shumkov Nov 12, 2026
5246476
fix(drive): include owner flags in lifecycle delete estimates
shumkov Nov 12, 2026
afe3969
test(drive): pin lifecycle metadata refusal diagnostics
shumkov Nov 12, 2026
86950f0
test(rs-sdk): pin the erase affected-state observation
shumkov Nov 12, 2026
4ada95a
chore: merge v5.1-dev into keep-history lifecycle
shumkov Nov 12, 2026
2198564
docs: clarify lifecycle delete estimation and consume rules
shumkov Nov 12, 2026
d71dfb2
test(drive): compare total lifecycle delete estimates with applied fees
shumkov Nov 12, 2026
a9c0e1a
merge: integrate document-keyed decision contests from v5.1-dev
shumkov Nov 12, 2026
5de4131
fix(dpp): freeze document erasure schema compatibility
shumkov Nov 12, 2026
d634769
fix(drive): describe lifecycle records in the storage schema
shumkov Nov 12, 2026
70dd059
merge: integrate proposal references and schema validation updates
shumkov Nov 12, 2026
7e59618
merge: integrate proposal fees and shielded contact updates
shumkov Nov 12, 2026
5872857
fix(drive): version erase refund recipient pricing
shumkov Nov 13, 2026
d88b055
fix(drive): preserve sibling history deletes in raw conversion
shumkov Nov 13, 2026
6edc4c0
test(drive-abci): normalize inactive erasure flags in shielded parity
shumkov Nov 13, 2026
84ac1e7
docs(platform-version): document lifecycle batch conversion
shumkov Nov 13, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions book/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,7 @@
- [Ranked Index Examples](drive/ranked-index-examples.md)
- [Time-Range Index TTL](drive/time-range-ttl.md)
- [Index-Only Document Types](drive/index-only-document-types.md)
- [Keep-History Documents](drive/keep-history-documents.md)

# Testing

Expand Down
32 changes: 25 additions & 7 deletions book/src/contract-keywords/deletion.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ Whether a document's owner may delete it. Set it to `false` for records that oth
| **Value** | boolean, or `"onlyWhenConsumed"` |
| **Default** | the contract config's `documentsCanBeDeletedContractDefault`, which is `true` unless the contract says otherwise |
| **Since** | protocol version 1; `"onlyWhenConsumed"` protocol version 14 |
| **On update** | Fixed (`DocumentTypeUpdateError`, 40212), except that a type which keeps history before and after the update may change it from `true` to `false`. Adding or removing the key without changing its value is refused too, as a schema change (`IncompatibleDocumentTypeSchemaError`, 10246). |
| **Errors** | `InvalidDocumentTransitionActionError` (10404) for a delete of a type set to `false` or `"onlyWhenConsumed"`, or, from protocol version 14, of a type that keeps history; `DocumentOwnerIdMismatchError` (40102) for a delete by anyone but the owner |
| **On update** | Fixed (`DocumentTypeUpdateError`, 40212), except that a type which keeps history before and after the update may change it from `true` to `false` when it does not allow erasure. Adding or removing the key without changing its value is refused too, as a schema change (`IncompatibleDocumentTypeSchemaError`, 10246). |
| **Errors** | `InvalidDocumentTransitionActionError` (10404) for a delete of a type set to `false` or `"onlyWhenConsumed"`, or, at protocol version 14, of a type that keeps history; `DocumentOwnerIdMismatchError` (40102) for a delete by anyone but the owner |

### Example

Expand All @@ -40,14 +40,14 @@ A commenter may take a comment down at any time. Since `true` is the usual defau
- An identity that is banned or suspended on a moderated contract may still delete its own documents. See [Contract Moderation](../data-model/contract-moderation.md#the-model). On a type set to `false` it can retract them instead, when the type declares [`retractedWhen`](#retractedwhen).
- `false` binds only the owner. The contract's moderators, when the type allows them, and the platform, when the type has a `ttl`, still delete such documents.
- `"onlyWhenConsumed"` binds the owner as `false` does, and lets a create consume the document (see [below](#deleted-only-when-consumed)).
- Drive never deletes a document whose type keeps history (`documentsKeepHistory`). From protocol version 14 a delete of such a document is refused with 10404 whatever `canBeDeleted` says; before it, the delete failed inside Drive as an internal error.
- Through protocol version 14, Drive refuses to delete a document whose type keeps history (`documentsKeepHistory`): 10404 at version 14, and an internal error before it. From version 15, an allowed owner delete removes the current pointer and indexes while retaining its revisions and a lifecycle record. Retained revision storage is refunded only when an allowed erase removes it. See [`canBeErased`](#canbeerased).
- Documents of an `indexOnly` type are deleted with an index-only delete transition that carries their values, since there is no stored row to name by id. A delete by id of such a document is refused (10404). See [Index-Only Types](index-only.md).

### Rules at registration

- From protocol version 14, a type with `documentsKeepHistory: true` must set `canBeDeleted: false` (`InvalidContractStructure`, 10231). The default is `true`, so it has to be written out. A contract registered earlier with both flags on stays readable, but its next update is checked like a new contract, so that update must turn `canBeDeleted` off on the type. That is the one change to `canBeDeleted` an update may make.
- At protocol version 14, a type with `documentsKeepHistory: true` must set `canBeDeleted: false` (`InvalidContractStructure`, 10231); older types stay readable but must withdraw deletion on their next update. From version 15, deletable history is admitted, including legacy types whose flag is already true. A history type may withdraw deletion on update only when it does not allow erasure.
- For references, a type whose owner may delete its documents is deletable: a `permanentDocument` reference, `inList` included, may not point at it (`ReferencedDocumentTypeDeletableError`, 40122), and a `deletableDocument` reference may. See [References](refers-to.md).
- `"onlyWhenConsumed"` is refused on a type that keeps history or is `indexOnly` (`InvalidContractStructure`, 10231): the storage layer never deletes a document that keeps history, and an `indexOnly` type has no stored row a reference finds, so nothing could consume either.
- `"onlyWhenConsumed"` is refused on a type that keeps history or is `indexOnly` (`InvalidContractStructure`, 10231): history types cannot be consumed, and an `indexOnly` type has no stored row a reference finds.

### Deleted only when consumed

Expand Down Expand Up @@ -77,6 +77,23 @@ A preorder stays until the name registration that reveals it consumes it (the `p
- Fixed on update: an update may neither set nor remove it (`DocumentTypeUpdateError`, 40212). Setting it would let documents leave state under the `permanentDocument` references made to a type that promised they never would; removing it would leave the references that consume its documents nothing to delete.
- Before protocol version 14 the meta-schemas accept only a boolean, so a contract carrying the string is refused (`JsonSchemaError`, 10101).

## `canBeErased`

Whether the retained history of a deleted document may be removed, from protocol version 15.

| | |
|---|---|
| **Where** | document type |
| **Value** | boolean |
| **Default** | `false` |
| **Since** | protocol version 15 |
| **On update** | Fixed in both directions (`DocumentTypeUpdateError`, 40212) |
| **Requires** | `documentsKeepHistory: true` and `canBeDeleted: true` |

Delete and erase are separate operations. Delete removes the current pointer and indexes, retaining the revisions. The document's current owner authorizes erasure with the first erase transition. Once erasure starts, any identity may pay to continue it in bounded chunks; the final chunk removes the lifecycle record and history without leaving a receipt. Each removed revision refunds its recorded storage payer. An erase carries no token payment or action fee.

A type that allows erasure cannot withdraw deletion on update. A history type cannot carry a contested index, moderator deletion or a `ttl`. See [Keep-History Documents](../drive/keep-history-documents.md) for the complete lifecycle, temporal reads and proof behavior.

## `retractedWhen`

The replace that retracts a document: what a banned or suspended author may still do on a type whose documents it can not delete. A barred identity can write nothing new, but deleting what it wrote is never refused. On a type set to `canBeDeleted: false` there is no delete, and the author's only way to take a document back is a replace that blanks it, which a bar refuses like any other write. `retractedWhen` names that replace, and lets it through.
Expand Down Expand Up @@ -242,7 +259,7 @@ Authors cannot retract a post, but the contract's moderators can remove one for
All refusals below are `InvalidContractStructure` (10231).

- The contract's config must declare `moderation`. Moderation cannot be added by a later update, so without it nobody could ever delete anything. In return the `moderation` block may keep no banlist, suspension list or warning list at all when a document type gives its moderators an ability.
- Refused on a type that keeps history (Drive never deletes those documents), on an `indexOnly` type (there is no stored row to name), on a type with `creationRestrictionMode` 1 or 2 (its documents are the contract owner's or the platform's), and on a type with a contested index (a restore could not go through the vote the index requires).
- Refused on a type that keeps history (history lifecycle deletion is owner-only), on an `indexOnly` type (there is no stored row to name), on a type with `creationRestrictionMode` 1 or 2 (its documents are the contract owner's or the platform's), and on a type with a contested index (a restore could not go through the vote the index requires).
- For references, the type is no longer permanent even with `canBeDeleted: false`: a `permanentDocument` reference, `inList` included, may not point at it (40122). With `canBeDeleted: false`, no `ttl` and removal records kept (the default), its documents leave state only on a moderator's record, and a [`moderatedDocument`](refers-to.md#moderateddocument) reference is the one that points at it, resolving to the document or to its removal record; a `deletableDocument` reference is refused (40144). Otherwise a `deletableDocument` reference points at it.

## `moderatorAbilities.deleteWithin`
Expand Down Expand Up @@ -455,6 +472,7 @@ Whether the owner of a document a moderator deletes is refunded its storage. By
| Who deletes | Allowed by | Refund to the owner |
|---|---|---|
| The document's owner | `canBeDeleted: true`, on a type that does not keep history, when the stored document meets every `deleteConstraints` rule | Yes, except on a type with a `ttl` |
| The document's owner, retaining history from protocol version 15 | `canBeDeleted: true`, when the stored document meets every `deleteConstraints` rule | Removed pointer/index storage only; retained revisions are refunded to their payers on erase |
| The contract's moderators | `moderatorAbilities.delete: true`, within `moderatorAbilities.deleteWithin` when set | Only with `moderatorAbilities.deleteRefundsOwner: true`, except on a type with a `ttl` |
| The seated moderation team, together | `moderatorAbilities.deleteSettled`, once `moderatorAbilities.deleteWithin` has passed | As for the moderators |
| The platform | `ttl`, once it has passed | No |
Expand All @@ -466,7 +484,7 @@ Which reference may point at a type follows from which of the three it allows. A
- [Deleting Documents](../data-model/contract-moderation.md#deleting-documents), [Deleting Settled Documents](../data-model/contract-moderation.md#deleting-settled-documents) and [Restoring Documents](../data-model/contract-moderation.md#restoring-documents), for the moderation transition, the approvals and the removal record
- [Moderator Abilities](moderator-abilities.md), for the `moderatorAbilities` object and the fields only moderators write
- [Time To Live](ttl.md), the third way a document leaves the state
- [History](history.md), for why a type that keeps history can never delete
- [History](history.md) and [Keep-History Documents](../drive/keep-history-documents.md), for retained revisions, lifecycle states and proofs
- [Mutability](mutability.md), for `immutable` and the conditions `retractedWhen` shares with it, and [Creation, Transfers and Trading](ownership-and-trading.md)
- [propertyConstraints](property-constraints.md), for the grammar of `deleteConstraints` and the totals its rules read
- [References](refers-to.md), for `permanentDocument`, `moderatedDocument` and `deletableDocument`
Expand Down
14 changes: 8 additions & 6 deletions book/src/contract-keywords/history.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Keeps every version of every document of the type, not only the latest.
| **Default** | the contract config's `documentsKeepHistoryContractDefault`, which is `false` unless the contract says otherwise |
| **Since** | protocol version 1 |
| **On update** | Fixed (`DocumentTypeUpdateError`, 40212). Adding or removing the key without changing its value is refused too, as a schema change (`IncompatibleDocumentTypeSchemaError`, 10246). |
| **Errors** | `InvalidDocumentTransitionActionError` (10404) for a delete of a document of the type, from protocol version 14 |
| **Errors** | `InvalidDocumentTransitionActionError` (10404) for a delete at protocol version 14, or when `canBeDeleted` refuses it |

### Example

Expand All @@ -31,15 +31,15 @@ Keeps every version of every document of the type, not only the latest.
}
```

Every edit of a profile adds a version, and every earlier version stays readable. `canBeDeleted: false` has to be written out, since a type that keeps history can never delete and the default is `true`.
Every edit of a profile adds a version. This example explicitly prevents owner deletion; the usual default is `true`. Protocol version 14 requires `canBeDeleted: false` on a history type. From version 15, a deletable history type may remove the current document while retaining its revisions, and may separately allow their erasure with [`canBeErased`](deletion.md#canbeerased).

### How it works

- Through protocol version 14, each document is stored as a small tree of its own, with versions keyed by block time and a pointer to the current one. From protocol version 15, versions live in a separate history tree for the document type and retain both time and revision, including edits sharing a block time. A query by id or through an index sees the current version.
- Every write that changes the document adds a version: a replace, and also a transfer, a price update or a purchase.
- Nothing is ever removed. Drive refuses to delete a document whose type keeps history, so its owner's delete is refused (10404 from protocol version 14; before it, the delete failed inside Drive as an internal error), and the type can have neither moderator deletion nor a `ttl`.
- Through protocol version 14, Drive refuses to delete a document whose type keeps history (10404 at version 14; before it, the delete failed inside Drive as an internal error). From version 15, an allowed owner delete removes the current pointer and indexes but retains every revision. Erase transitions may then remove retained revisions if the type declares `canBeErased: true`. History types still allow neither moderator deletion nor a `ttl`.
- The `getDocumentHistory` query returns a document's versions from a given time on, each with the block time it was written at, at most 10 per request, and with a proof when asked.
- Every version stays stored, paid for by the write that added it.
- Each retained version is paid for by the write that added it. Erasure refunds removed storage to its recorded payer.
- A doctype-level sum or average (`documentsSummable`, `documentsAverageable`) counts only each document's current version. See [Counts, Sums and Averages](aggregates.md).

`getDocumentHistory` uses request and response version 0 through protocol version
Expand All @@ -61,8 +61,9 @@ unsupported-query-version error; the SDK does not fall back to version 0.

All refusals below are `InvalidContractStructure` (10231).

- From protocol version 14, the type must set `canBeDeleted: false`. A contract registered earlier with both flags on stays readable, and its next update must turn `canBeDeleted` off on that type. See [Deletion](deletion.md).
- At protocol version 14, the type must set `canBeDeleted: false`; an older contract with both flags on stays readable but must turn deletion off on its next update. From version 15, deletable history is admitted. Older types whose deletion flag is true become soft-deletable at activation without an update. See [Deletion](deletion.md).
- Refused together with `ttl`, with `moderatorAbilities.delete` and with `indexOnly`.
- From protocol version 15, refused together with a contested index.

## `keepsTransferHistory`

Expand Down Expand Up @@ -153,6 +154,7 @@ The document history contract is a system contract registered at protocol versio
## See also

- [Creation, Transfers and Trading](ownership-and-trading.md), for the actions the three flags record
- [Deletion](deletion.md) and [Time To Live](ttl.md), for why a type that keeps history can never lose a document
- [Deletion](deletion.md) and [Time To Live](ttl.md), for owner deletion, erasure and the expiry restriction
- [Keep-History Documents](../drive/keep-history-documents.md), for lifecycle states, temporal reads and proofs
- [Counts, Sums and Averages](aggregates.md), for the aggregates of the history records
- [Contract-Level Keys and config](contract-config.md), for `documentsKeepHistoryContractDefault` and the contract's own `keepsHistory`
69 changes: 69 additions & 0 deletions book/src/contributing/coding-conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,75 @@ section that lists each edited generation, the protocol versions that select
it, and the reason consensus cannot change there. Reviewers read that section
first.

### A new input changes the signature, not the method count

When the new generation of a method needs something its callers do not pass
yet (the block, the signer, a mode), add the parameter to the method and
update the callers. Do not add a second method beside it (`*_with_lifecycle`,
`*_with_block`), a second operation variant beside the existing one
(`DeleteDocumentWithLifecycle` next to `DeleteDocument`), or a wrapper that
fabricates the missing value on the way in. One method per directory means
one signature, the one the current generation needs.

The shipped generation keeps its own signature. The dispatcher hands it the
part of the new input it always had and drops the rest:

```rust
pub fn delete_document_for_contract_operations(
&self,
document_id: Identifier,
contract: &DataContract,
document_type: DocumentTypeRef,
block_info: &BlockInfo, // was `block_time_ms: u64`
deleter_id: Option<Identifier>, // new: whom the lifecycle record credits
previous_batch_operations: Option<&mut Vec<LowLevelDriveOperation>>,
estimated_costs_only_with_layer_info: &mut Option<EstimatedLayers>,
transaction: TransactionArg,
platform_version: &PlatformVersion,
) -> Result<Vec<LowLevelDriveOperation>, Error> {
match platform_version.drive.methods.document.delete.delete_document_for_contract_operations {
// The shipped generation never knew a deleter; it reads the time off
// the block exactly as it read `block_time_ms` before.
0 => self.delete_document_for_contract_operations_v0(
document_id,
contract,
document_type,
previous_batch_operations,
estimated_costs_only_with_layer_info,
block_info.time_ms,
transaction,
platform_version,
),
1 => self.delete_document_for_contract_operations_v1(
document_id,
contract,
document_type,
block_info,
deleter_id,
previous_batch_operations,
estimated_costs_only_with_layer_info,
transaction,
platform_version,
),
version => Err(Error::Drive(DriveError::UnknownVersionMismatch { .. })),
}
}
```

Why: a twin method is a second name for the same behaviour with the version
decision split across two dispatchers, and callers that reach the old name
silently get the old capability at the new protocol version, or a value
somebody made up to satisfy the old signature. Changing the signature makes
the compiler find every caller, and each one then states what it passes.

How: change the dispatcher's signature, re-point the callers, and let
generation 0 keep receiving what it received before. If a wrapper's new
generation would only forward the new parameter to the method that has the
behaviour, it is not a new generation: forward it from the wrapper's existing
body and leave the wrapper's version slot alone. The one exception is a
public client-facing API that must stay source-compatible across a release;
there, the SDK's builder pattern absorbs the new input.

### Table versions follow protocol-version boundaries, not PRs

Version-table constants (`DRIVE_ABCI_VALIDATION_VERSIONS_V10`,
Expand Down
Loading
Loading