Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
6 changes: 3 additions & 3 deletions book/src/contract-keywords/deletion.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ All refusals below are `InvalidContractStructure` (10231), checked on every pars

- Only on a type whose documents are mutable: without a replace there is nothing to retract with.
- Only on a contract that keeps a banlist or a suspension list: otherwise no owner is ever barred.
- The condition reads what an `immutable` entry's `when` may read: declared properties of the right kind, neither transient nor inside a transient object, the system times and heights the type lists in `required`, and the stored document through `$old.`. It reads no `countOf` or `sumOf`. When a contract is registered or updated, it also stays within the node limit of a rule and lists no condition twice.
- The condition reads what an `immutable` entry's `when` may read: declared properties of the right kind, neither transient nor inside a transient object, the system times and heights the type lists in `required`, `$revision`, and the stored document through `$old.`: its properties, owner, times, heights and revision. It reads no `countOf` or `sumOf`. When a contract is registered or updated, it also stays within the node limit of a rule and lists no condition twice.

## `deleteConstraints`

Expand Down Expand Up @@ -183,7 +183,7 @@ Without the keyword, the poll had to be undeletable for its votes to be sure it
### How it works

- **The owner's delete.** When the owner deletes a document, consensus fetches it, checks the owner, then checks every rule in name order against the stored document, and refuses the delete at the first rule it breaks with `DocumentDeleteConstraintViolatedError` (40147). The error names the document, the rule, and why it failed, with the reasons of [`propertyConstraints`](property-constraints.md#how-it-works). It is a state error, so the delete is paid for and the nonce is spent, and the document stays.
- **What a rule reads.** The stored document's properties, its `$ownerId` (the owner deleting it), and the times and heights the type lists in `required`, as stored. A `countOf` or `sumOf` reads a total from state as it will be once the document is gone: a total over the type's own documents no longer counts it, so `{ "greaterThanOrEqual": [{ "countOf": ["address", { "$ownerId": "$ownerId" }] }, 1] }` keeps the last address of each owner. Each total is a billed read.
- **What a rule reads.** The stored document's properties, its `$ownerId` (the owner deleting it), the times and heights the type lists in `required`, and its `$revision` on a type that keeps one, as stored, by their plain paths: the rule is judged on the stored document itself, so `$old.` is refused. A `countOf` or `sumOf` reads a total from state as it will be once the document is gone: a total over the type's own documents no longer counts it, so `{ "greaterThanOrEqual": [{ "countOf": ["address", { "$ownerId": "$ownerId" }] }, 1] }` keeps the last address of each owner. Each total is a billed read.
- **`$id` in a filter.** A filter may match a key by the document's own id, `"$id"`, which is what makes "while no vote points at it" a rule. The key must be an identifier property of the counted type. `$id` is a filter value in `propertyConstraints` too, as the example shows; it is not an operand anywhere else.
- **Only the owner's delete.** The contract's moderators delete as their abilities allow, and a `ttl` expires documents on time, whatever the rules say. A `refersTo` with `consume` may not target the type, since a consume deletes without a delete transition to judge. A banned or suspended owner, who may still delete its documents, is held to the rules like any other.
- **The totals are those of the block.** Each state transition of a block is applied before the next is validated, so a vote earlier in the block counts, and a vote later in the block finds the poll gone (`ReferencedEntityNotFoundError`, 40120).
Expand All @@ -194,7 +194,7 @@ Without the keyword, the poll had to be undeletable for its votes to be sure it
All refusals below are `InvalidContractStructure` (10231) unless noted.

- Only on a type whose owner deletes its stored documents: not `canBeDeleted: false` or `"onlyWhenConsumed"`, where there is no delete to gate, and not `indexOnly`, whose delete carries the row's values and is judged by its `propertyConstraints`. Checked on every parse.
- The grammar, the shape and the reads are those of a `propertyConstraints` rule (see [Rules at registration](property-constraints.md#rules-at-registration)): every path names a stored property of the kind it is read as, a time or height the type lists in `required`, no `$old.` path. Every `countOf` and `sumOf` counts a type of the contract with a tree that keeps the total. Unlike a `propertyConstraints` rule, a delete rule may total its own type when that type has a contested index: the total it reads at the delete is the stored one, which an awarded document is in like any other.
- The grammar, the shape and the reads are those of a `propertyConstraints` rule (see [Rules at registration](property-constraints.md#rules-at-registration)): every path names a stored property of the kind it is read as, a time or height the type lists in `required`, or `$revision` on a type that keeps one, and none starts with `$old.`, which the refusal says to drop, since the plain path already reads the stored document. Every `countOf` and `sumOf` counts a type of the contract with a tree that keeps the total. Unlike a `propertyConstraints` rule, a delete rule may total its own type when that type has a contested index: the total it reads at the delete is the stored one, which an awarded document is in like any other.
- The same limits, counted apart from `propertyConstraints`: at most 16 rules, each of at most 32 nodes, reading at most 4 distinct totals.
- A `refersTo` with `consume` may not target a type that declares the keyword.

Expand Down
6 changes: 3 additions & 3 deletions book/src/contract-keywords/moderator-abilities.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,11 +67,11 @@ A user files a report and can never edit it. A report starts with no `status`: t
### How it works

- A moderator changes the fields with the contract user moderation transition's `changeDocumentFields` action, naming the document type, the document id, the new value of each field (`null` removes one; in the JavaScript SDKs a field set to `undefined` is left out, as JSON leaves it out) and a reason.
- The transition is checked in this order, each refusal paid: the document type exists (`InvalidDocumentTypeError`, 10406); every field named is listed under `changeFields` (41123); the signer is a moderator of the contract (41101), and for a seated team the declaration gives it `changeDocumentFields` on the type (41201) and the reason names a reason document its proposal lists (41203); the document exists (40101) and has not expired (`DocumentExpiredError`, 40140); and the document as changed is still one of its type: its schema (`JsonSchemaError`, 10101), its `propertyConstraints` and its unique indexes (`DuplicateUniqueIndexError`, 40105). A change naming no field, or a system property, is refused before any state is read (10905).
- The transition is checked in this order, each refusal paid: the document type exists (`InvalidDocumentTypeError`, 10406); every field named is listed under `changeFields` (41123); the signer is a moderator of the contract (41101), and for a seated team the declaration gives it `changeDocumentFields` on the type (41201) and the reason names a reason document its proposal lists (41203); the document exists (40101) and has not expired (`DocumentExpiredError`, 40140); and the document as changed is still one of its type: its schema (`JsonSchemaError`, 10101), the [`propertyConstraints`](property-constraints.md#how-it-works) rules that read a field the change moves (directly or through `$old.`, which reads the document as stored before the change), `$revision` or a total (`DocumentPropertyConstraintViolatedError`, 10422), and its unique indexes (`DuplicateUniqueIndexError`, 40105). The other rules read only what the owner last wrote, and gave their verdict then. A change naming no field, or a system property, is refused before any state is read (10905).
- Whoever owns the document may have it changed, the contract owner and the moderators included: the fields are the moderators', not the owner's, so the protection that keeps moderators from deleting each other's documents does not apply.
- 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 document is updated in place. Every other property stays as it was, `$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. Nor is a `propertyConstraints` rule reading a referenced document judged: registration keeps such a rule from reading anything the change can break.
- 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.
- 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.
Expand Down
6 changes: 3 additions & 3 deletions book/src/contract-keywords/mutability.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,8 @@ The top-level properties a replace may not change, on a type whose documents can
### How it works

- On every replace, each property that differs from the stored document is checked against the list. A property listed by name is refused with `DocumentImmutablePropertyChangedError` (40128). A property listed with a condition is refused with the same error when its condition holds for this replace. "Differs" covers a changed value, a value the stored document did not have, and a value the replace leaves out.
- A condition takes the grammar of a [`propertyConstraints`](property-constraints.md) rule: comparisons, arithmetic, `in`, `present`, `absent`, `anyOf`, `allOf`, `not`, `ifThen`, `ifThenElse`, the system times and heights the type records, and `$ownerId`. It is judged, as a rule judges a replace, on the document the replace writes: its properties as the replace sets them, the stored `$createdAt` and `$transferredAt`, and the replace's block as `$updatedAt`.
- A path starting with `$old.` reads the stored document instead: `$old.status` is the status before the replace. Only a condition of `immutable`, or a type's [`retractedWhen`](deletion.md#retractedwhen), may read it, and only a schema property through it.
- A condition takes the grammar of a [`propertyConstraints`](property-constraints.md) rule: comparisons, arithmetic, `in`, `present`, `absent`, `anyOf`, `allOf`, `not`, `ifThen`, `ifThenElse`, the system times and heights the type records, `$revision`, and `$ownerId`. It is judged, as a rule judges a replace, on the document the replace writes: its properties as the replace sets them, the stored `$createdAt` and `$transferredAt`, the replace's block as `$updatedAt`, and the replace's revision.
- A path starting with `$old.` reads the stored document instead: `$old.status` is the status before the replace, `$old.$updatedAt` the time of the previous update, `$old.$revision` the previous revision. A [`propertyConstraints`](property-constraints.md#the-stored-version-old) rule and a type's [`retractedWhen`](deletion.md#retractedwhen) read it the same way; a [`deleteConstraints`](deletion.md#deleteconstraints) rule, judged on the stored document itself, does not.
- A property is frozen while its condition holds. If what the condition reads can change back, the property can become editable again: with `body` frozen by `$old.status`, a replace setting `status` back to `draft` still reads the stored `published`, so `body` stays frozen in that replace, and the next replace, reading the stored `draft`, may change it. For a freeze that lasts, list what the condition reads as well, or use a condition that cannot turn back, as a document's age or a filled-in value cannot.
- A condition is evaluated only when its property changes. A condition that faults, dividing by zero or overflowing, counts as holding: a fault never frees a property.
- Values are compared by their data, not their bytes: the order of an object's members and the width an integer is stored in do not count as changes. Freezing an object freezes everything inside it.
Expand All @@ -115,7 +115,7 @@ All refusals below are `InvalidContractStructure` (10231). The shape of the list
- Every entry is a string or an object with exactly `property` and `when`, and no property is listed twice.
- Every listed property is a declared top-level property. System properties (`$ownerId`, `$createdAt` and the rest) are refused, since the platform manages them. Nested paths such as `meta.author` are refused: list the object that contains them.
- No listed property may be `transient`: it is never stored, so every replace that supplies it while it is frozen would count as a change.
- A condition reads what a `propertyConstraints` rule may read of the type: declared properties of the right kind, neither transient nor inside a transient object, and system times and heights the type lists in `required`. It stays within the node limit of a rule, and lists no condition twice.
- A condition reads what a `propertyConstraints` rule may read of the type: declared properties of the right kind, neither transient nor inside a transient object, system times and heights the type lists in `required`, `$revision`, and any of them under `$old.`. It stays within the node limit of a rule, and lists no condition twice.
- A condition may not read a `countOf` or `sumOf` total: it reads the document alone, so a replace judges it without reading state.
- `immutableAllowSetting`, which earlier builds used to let a frozen property be filled in once, is refused and names the replacement: `{ "property": "p", "when": { "present": "$old.p" } }`.
- An immutable property may not hold a `deletableDocument` reference that a replace could not clear: a typed array of them, one inside an object, or one found by `findBy` whose key no function computes. A single reference by id held directly by the property is allowed, but only without a condition: once cleared, a replace the condition leaves free could set it to another document.
Expand Down
4 changes: 2 additions & 2 deletions book/src/contract-keywords/ownership-and-trading.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Whether an owner may give a document to another identity.
- The owner sends a transfer transition naming the document, the recipient and a `$revision` one higher than the stored one (`InvalidDocumentRevisionError`, 40106). Only the owner may transfer (`DocumentOwnerIdMismatchError`, 40102). The recipient does not have to agree.
- The document gets the recipient as its `$ownerId` and a new `$revision`. A price it was listed at is removed, so a transferred document is no longer for sale. When the type lists `$transferredAt` in `required`, it is set to the block's time, and likewise `$transferredAtBlockHeight` and `$transferredAtCoreBlockHeight` to the block heights.
- A transfer carries no property values, and `$creatorId` keeps naming the identity that created the document. The one change the platform makes itself: from protocol version 13, a DPNS `domain` that is transferred or sold has its `records.identity` pointed at the new owner.
- The document is checked as it will be stored, with its new owner: against the type's unique indexes (`DuplicateUniqueIndexError`, 40105), against a `distinctFrom: "$ownerId"` property (`DocumentPropertyNotDistinctError`, 10419), and against `propertyConstraints` rules that read `$ownerId` (`DocumentPropertyConstraintViolatedError`, 10422).
- The document is checked as it will be stored, with its new owner: against the type's unique indexes (`DuplicateUniqueIndexError`, 40105), against a `distinctFrom: "$ownerId"` property (`DocumentPropertyNotDistinctError`, 10419), and against the `propertyConstraints` rules that read what a transfer changes: `$ownerId`, `$transferredAt` and its heights or `$revision`, of the document or, through `$old.`, of the version before the transfer, or a total that depends on the owner (`DocumentPropertyConstraintViolatedError`, 10422; see [propertyConstraints](property-constraints.md#how-it-works)).
- On a moderated contract, a transfer to a banned or suspended identity is refused (`ContractModerationCounterpartyBarredError`, 41114).
- A transfer of a document past its `ttl` expiry is refused (`DocumentExpiredError`, 40140).
- With `keepsTransferHistory: true`, each transfer is also recorded in the document history contract. See [History](history.md).
Expand All @@ -88,7 +88,7 @@ Whether documents of the type can be sold through the platform's built-in market
- **Listing.** The owner sends a price update transition with a price in credits and the next `$revision`. Only the owner may set the price (40102). The price is stored with the document, the revision goes up, and `$updatedAt` is set when the type lists it in `required`.
- **Buying.** Any identity other than the owner sends a purchase transition naming the document, the next `$revision` and the price. A document with no price set is not for sale (`DocumentNotForSaleError`, 40108), and the price in the transition must equal the listed price exactly (`DocumentIncorrectPurchasePriceError`, 40109). An owner cannot buy its own document (10404).
- **What a purchase does.** The price moves from the buyer's credit balance to the seller's. The document gets the buyer as its `$ownerId` and a new `$revision`, the listing is removed, and `$transferredAt` is set when the type lists it in `required`. The buyer's credit balance must cover the price.
- The new owner is checked exactly as for a transfer: unique indexes (40105), `distinctFrom: "$ownerId"` (10419) and `propertyConstraints` rules that read `$ownerId` (10422).
- The new owner is checked exactly as for a transfer: unique indexes (40105), `distinctFrom: "$ownerId"` (10419) and the `propertyConstraints` rules that read `$ownerId`, `$transferredAt` and its heights or `$revision`, of either version, or a total that depends on the owner (10422).
- On a moderated contract, a banned or suspended buyer is refused like any barred writer, and so is a purchase from a banned or suspended seller (`ContractModerationCounterpartyBarredError`, 41114).
- A price update or a purchase of a document past its `ttl` expiry is refused (`DocumentExpiredError`, 40140).
- With `keepsPricingHistory` and `keepsPurchaseHistory`, each price update and each purchase is also recorded in the document history contract. See [History](history.md).
Expand Down
Loading
Loading