Skip to content
4 changes: 2 additions & 2 deletions book/src/contract-keywords/deletion.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ A commenter may take a comment down at any time. Since `true` is the usual defau
### How it works

- The owner deletes a document with a delete transition that names its id. Anyone else is refused (`DocumentOwnerIdMismatchError`, 40102), and a document that does not exist is `DocumentNotFoundError` (40101).
- The owner is refunded the part of the document's storage fee that has not yet been paid out to past epochs. A document of a type with a `ttl` refunds nothing. See [Refunds](../fees/overview.md#refunds).
- The owner is refunded the part of the document's storage fee that has not yet been paid out to past epochs. Storage the contract owner paid for as the document's [gas sponsor](token-cost.md#who-pays-the-gas-gasfeespaidby) is refunded to them instead. A document of a type with a `ttl` refunds nothing. See [Refunds](../fees/overview.md#refunds).
- A delete may carry a token cost or an action fee, like any document action. See [Token Costs](token-cost.md) and [Action Fees](action-fees.md).
- 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).
- `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.
Expand Down Expand Up @@ -297,7 +297,7 @@ Whether the owner of a document a moderator deletes is refunded its storage. By

### How it works

- With `true`, the owner is refunded as for their own deletion: the part of the storage fee not yet paid out to past epochs. The refund goes to the owner, not to the moderator, who still pays for the transition and the record. A document of a type with a `ttl` refunds nothing either way.
- With `true`, the storage is refunded as for the owner's own deletion: the part of the storage fee not yet paid out to past epochs, to the owner, or to the contract owner for storage they paid for as the document's [gas sponsor](token-cost.md#who-pays-the-gas-gasfeespaidby). The deleting moderator gets none of it as moderator, and still pays for the transition and the record. A document of a type with a `ttl` refunds nothing either way.
- With `false`, the credits stay in the storage pools they were paid into.

### Rules at registration
Expand Down
4 changes: 2 additions & 2 deletions book/src/contract-keywords/moderator-abilities.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ The keys:
| `delete` | The moderators delete documents of the type. By default each deletion leaves a removal record and can be restored within a week; with `deleteKeepsRecord: false` it leaves none and is final. | [Deletion](deletion.md#moderatorabilitiesdelete) |
| `deleteWithin` | Limits `delete` to so many seconds after a document's last change. | [Deletion](deletion.md#moderatorabilitiesdeletewithin) |
| `deleteKeepsRecord` | Whether a deletion leaves a removal record, and so can be restored. Default `true`. | [Deletion](deletion.md#moderatorabilitiesdeletekeepsrecord) |
| `deleteRefundsOwner` | Whether the deleted document's owner is refunded its storage. Default `false`. | [Deletion](deletion.md#moderatorabilitiesdeleterefundsowner) |
| `deleteRefundsOwner` | Whether the deleted document's storage is refunded to whoever it names: its owner, or the contract owner for storage they paid for as its gas sponsor. Default `false`. | [Deletion](deletion.md#moderatorabilitiesdeleterefundsowner) |
| `deleteSettled` | Past `deleteWithin`, the seated team of an elected contract deletes a document together: one member proposes, and so many approve, the leader among them only when the rule says so (`leader: true`). | [Deletion](deletion.md#moderatorabilitiesdeletesettled) |
| `deleteKeepsFields` | The fields of a deleted document whose values stay public in its removal record, such as a post's hashtag. | [Deletion](deletion.md#moderatorabilitiesdeletekeepsfields) |
| `changeFields` | The listed properties are written only by the moderators. | [below](#changefields) |
Expand Down Expand Up @@ -76,7 +76,7 @@ A user files a report and can never edit it. A report starts with no `status`: t
- The document records who wrote the fields last, and when: [`$moderatedAt` and `$moderatedBy`](system-properties.md#moderatedat-and-moderatedby), which an index of the type may name to find what the moderators handled.
- The document is updated in place. Every other property stays as its owner wrote it, `$updatedAt` among them, so a change never opens a [`deleteWithin`](deletion.md#moderatorabilitiesdeletewithin) window again. `$revision` goes up by one, so a replace its owner built on the earlier revision is refused (`InvalidDocumentRevisionError`, 40106) rather than writing over the change.
- References are not checked again: no field a moderator writes holds one or is read by one (see the rules below). A report whose post a moderator has already deleted can still be marked handled.
- The moderator pays for the transition and the bytes it adds. Storage the change frees, or index entries it moves, are refunded to the document's owner, who paid for them. Nothing the type prices is charged: a moderator's change is no action of the owner's.
- The moderator pays for the transition and the bytes it adds. Storage the change frees, or index entries it moves, are refunded to whoever paid for them: the document's owner, or the contract owner for a document whose storage they hold as its [gas sponsor](token-cost.md#who-pays-the-gas-gasfeespaidby). Nothing the type prices is charged: a moderator's change is no action of the owner's.
- A change that changes nothing, every field already holding the value named, is refused (10905): it would bump `$revision` for nothing.
- A change needs a listed reason from a seated team, but does not count toward the team's action share: changes of one document have no bound, as deletions of the content that exists do, so counting them would let a member farm the share.
- The proof of the change is the document as it now stands, holding the values the change set.
Expand Down
5 changes: 4 additions & 1 deletion book/src/contract-keywords/token-cost.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,10 @@ From protocol version 14 the contract owner can pay the gas (the storage and pro
- A batch has one payer. Transitions of one batch that resolve to different payers are refused (`InconsistentGasFeesPaidByInBatchError`, 40130); a token transition in the batch is never sponsored, so it counts as the signer paying.
- When the contract owner's balance does not cover the gas (and any action fees they would owe), a batch that insisted is refused and charged nothing (`GasSponsorInsufficientBalanceError`, 40222), and a batch that only preferred falls back to the signer.
- A transition that fails validation is never sponsored: its signer pays for the work that ran.
- Storage refunds still go to the document's owner, whoever paid for the storage. Each token the contract owner hands out is therefore worth up to the storage fee of the largest document the type allows, so a type that offers to pay should bound its documents' size (`maxLength`, `maxItems`, [maxBytes](max-bytes.md)) and price the action to match.
- Storage refunds go to whoever paid for the storage. A sponsored action records the contract owner as the owner of the storage it writes, a contested document's vote poll entries included, so deleting or shrinking the document later refunds the contract owner, not the document's owner. A document of a type with a `ttl` is stored without storage flags and refunds nobody, sponsored or not.
- The contract owner still pays the storage fee of each document a sponsored action writes, up to the largest the type allows, and gets back only the part not yet paid out to past epochs, only when the document is deleted or shrinks. A type that offers to pay should bound its documents' size (`maxLength`, `maxItems`, [maxBytes](max-bytes.md)) and price the action to match.
- A stored document the contract owner holds stays theirs when its owner replaces or transfers it at their own expense: the refund of what that write adds to it goes to the contract owner too. Otherwise one small replace of their own would hand the owner the whole document, and its refund. New index entries the write adds name whom the write names: its signer, or the new owner on a transfer.
- Each stored part of a document has one owner. A sponsored action that grows a part the document's owner paid for, or shrinks it, takes that part over, with the refund of what the owner paid for it; a part holding the bytes of one epoch only keeps its owner when it shrinks in a later epoch, as does a part rewritten at the same size. A document owner who would rather keep it pays for the action themself.
- A sponsor also pays any [action fee](action-fees.md) the action charges.

Before protocol version 14 the key was accepted and stored but not acted on: the signer always paid.
Expand Down
4 changes: 2 additions & 2 deletions book/src/data-model/contract-moderation.md
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,7 @@ ContractUserModerationAction::RestoreDocument {

It names no identity and no id: the document is inside the bytes, and its id and owner with it. The transform checks, in order and each refusal paid: the document type exists (10406) and carries `moderatorAbilities.delete` (41115, only such a type keeps records), the signer is the owner or a moderator (41101, whoever deleted), the bytes decode under the type (a basic decoding error, never an execution error: the bytes are the signer's), the document has a removal record (`ContractDocumentRemovalNotFoundError`, 41119) that is not marked restored (`ContractDocumentAlreadyRestoredError`, 41122: the document is live), block time is within `SystemLimits::contract_document_restore_window_ms` of the removal, a week, the last millisecond included (`DocumentRestoreWindowElapsedError`, 41120), the bytes hash to what the record holds (`DocumentRestoreHashMismatchError`, 41121: the document as it was, not an edit of it), and no other document of the type holds a value of one of its unique indexes (`DuplicateUniqueIndexError`, 40105: the value was free while the document was gone, and someone may have taken it). The record read is billed; the hash pins everything else, so the owner, the revision, the timestamps, the references and the schema are not checked again. Whether the document's owner is banned is not asked either: a ban stops writes, it never removed documents.

The action carries the contract, the decoded document and the record marked restored by the signer at the block's time, so Drive puts the document back through the ordinary insert (`DocumentOperationType::AddDocument`, every index and aggregate of the type included) and replaces the record in place, without reading again. The restored document's storage flags name its owner, as they did before the deletion: the signer pays for the bytes, and the refund of a later deletion is the owner's, as it always was. Nothing the document type prices is charged, neither its creation token cost nor its `actionFees` creation fee, and no fee agreement is asked: a moderator undoes a moderation, it does not create content. The restore is proved by the record, now marked restored and holding the hash of the bytes the transition carried; the verifier reads the document's id out of those bytes under the contract's document type, so it needs the contract, which the SDKs register with their context provider before broadcasting.
The action carries the contract, the decoded document and the record marked restored by the signer at the block's time, so Drive puts the document back through the ordinary insert (`DocumentOperationType::AddDocument`, every index and aggregate of the type included) and replaces the record in place, without reading again. The restored document's storage flags name its owner: the signer pays for the bytes, and the refund of a later deletion is the owner's. A gas sponsor who held the deleted document's storage was settled by the deletion (forfeited, or refunded to them with `deleteRefundsOwner`), so the restore is new storage they have no claim on. Nothing the document type prices is charged, neither its creation token cost nor its `actionFees` creation fee, and no fee agreement is asked: a moderator undoes a moderation, it does not create content. The restore is proved by the record, now marked restored and holding the hash of the bytes the transition carried; the verifier reads the document's id out of those bytes under the contract's document type, so it needs the contract, which the SDKs register with their context provider before broadcasting.

Two consequences follow from the document coming back byte for byte. Its `$updatedAt` does not move, so a type with `moderatorAbilities.deleteWithin` may have settled it while it was gone: no moderator deletes it again alone until its author edits it, though the author still can, and on a type that sets `deleteSettled` the seated team can, by a fresh proposal (the action that deleted it ran and is closed). A deletion the team approved together is never restored: it is the only removal made after the document settled, since a moderator alone deletes up to the settling time and the team only after it, so the restore transform compares the removal time with the settling time of the document the bytes hash to (no read), and refuses the restore of a later removal, paid (`SettledDeletionNotRestorableError`, 41209), so no single moderator undoes what the leader and the members agreed on. And a type with a contested index can not carry `moderatorAbilities.delete` at all (`InvalidContractStructure`, 10231): a contested index only takes a document through a vote, which no restore can go through, so such a deletion could never be undone. The bytes are decoded under the type as the contract holds it when the restore is processed, and the hash is of the document serialized under the type as it was when the document was deleted: a contract update that changes the type's layout inside the window (a property added, say) leaves the record unrestorable, since bytes that decode under the new layout cannot hash to what the record holds. A client therefore serializes under the contract's current version, as Drive does, and keeps the document rather than the bytes.

Expand Down Expand Up @@ -260,7 +260,7 @@ ContractUserModerationAction::ChangeDocumentFields {

Basic structure refuses one that names no field or a system property (`InvalidContractModerationDocumentFieldsError`, 10905, unpaid). The transform (`transform_document_fields_change_v0`) checks, in order and each refusal paid: the document type exists (10406), every field is one it keeps for its moderators (`DocumentFieldNotChangeableByModeratorsError`, 41123), the signer moderates the contract (41101) and a seated team holds `changeDocumentFields` on the type (41201) and names a listed reason (41203), the document exists (40101) and has not expired (40140). It then builds the changed document: the stored one with each field set or removed, compared as a replace compares (`Value::equal_underlying_data`, so an integer sent at another width than the stored one is no change), `$revision` one higher (`OverflowError`, 10700, at `u64::MAX`), `$moderatedAt` the block's time and `$moderatedBy` the signer, everything else as stored, `$updatedAt` and its heights included. That document is judged as a replace judges one: `validate_document_properties` (the schema and `propertyConstraints`, with the `countOf` and `sumOf` totals read as they will be once it is stored, `read_property_constraint_aggregates_for_moderator_change`), `distinctFrom` and the shapes of `encryptedFor` properties, then, when a changed field is in a unique index, `Drive::validate_moderated_document_uniqueness`, the restore's check generalized to a changed document (only the changed fields are checked, and the document's own entries do not clash). Whoever owns the document is no protection: the fields are the moderators'. Nothing the document type prices is charged.

The action carries the contract and the changed document, and Drive stores it with `DocumentOperationType::UpdateDocument`, the replace's update, every index and aggregate of the type included. The document's storage flags name its owner, as a replace's do: the moderator pays for the bytes the change adds, and what the change frees (a smaller value, an index entry that moved) is refunded to the owner, who paid for it. A seated team's member does not have the change counted toward the team's action share: the changes of one document have no bound, and counting them would let a member farm it. A change that changes nothing is refused (10905) rather than written. `$updatedAt` does not move, so a change never opens a `moderatorAbilities.deleteWithin` window again: a moderator can not keep a post deletable by touching it.
The action carries the contract and the changed document, and Drive stores it with `DocumentOperationType::UpdateDocument`, the replace's update, every index and aggregate of the type included. The document's storage flags name its owner, as a replace's do: the moderator pays for the bytes the change adds, and what the change frees (a smaller value, an index entry that moved) is refunded to whoever paid for it, the owner, or the contract owner for a document whose storage they hold as its gas sponsor (whose stored document the update keeps with them). A seated team's member does not have the change counted toward the team's action share: the changes of one document have no bound, and counting them would let a member farm it. A change that changes nothing is refused (10905) rather than written. `$updatedAt` does not move, so a change never opens a `moderatorAbilities.deleteWithin` window again: a moderator can not keep a post deletable by touching it.

The stamp is two system properties of document serialization format 3 (bits 9 and 10 of its time field flags): absent on a document no moderator has written, set only here and by the batch transformer, which stamps a moderator's create or replace of such a field (an action it did not judge is written unstamped), carried over by a replace that leaves the fields alone and by every transfer, purchase and price update, and put back by a restore with the rest of the bytes. A type that keeps fields for its moderators may index either, never in a unique index (`apply_moderator_abilities`, 10231; the core index check admits the two names from parser generation 3, `ParserGeneration::admit_moderation_stamp_indexes`). See [System Properties](../contract-keywords/system-properties.md#moderatedat-and-moderatedby).

Expand Down
Loading
Loading