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
33 changes: 27 additions & 6 deletions docs/protocol/decision-proposals.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,10 +152,10 @@ rejected.
| Property | Type | Meaning |
| --- | --- | --- |
| `title` | string, 1 to 128 characters and at most 512 bytes, required | The question, in one line |
| `descriptionId` | identifier, required | The document saying what is being decided: a [reference whose target the proposal names](../../book/src/contract-keywords/refers-to-dynamic.md) |
| `descriptionContractId` | identifier, required | The contract that document lives in: `refersTo` a `contract` with `contractRequirements: { "moderation": "elected", "ownerProtected": false }` |
| `descriptionDocumentType` | string, 1 to 64 characters, required | That document's document type |
| `url` | string, `format: uri`, 1 to 512 characters and at most 512 bytes | Where the proposal is discussed |
| `descriptionId` | identifier | The document saying what is being decided, when the proposal points at one: a [reference whose target the proposal names](../../book/src/contract-keywords/refers-to-dynamic.md) |
| `descriptionContractId` | identifier, given with `descriptionId` and only with it | The contract that document lives in: `refersTo` a `contract` with `contractRequirements: { "moderation": "elected", "ownerProtected": false }` |
| `descriptionDocumentType` | string, 1 to 64 characters, given with `descriptionId` and only with it | That document's document type |
| `url` | string, `format: uri`, 1 to 512 characters and at most 512 bytes, required when `descriptionId` is left out | Where what is being decided is described, for a proposal that points at no description document; where it is discussed, for one that does |
| `open` | boolean, required | Whether anyone may enter choices. Only the proposal's owner may when it is `false` |

Indexes: `byOwner` (`$ownerId`, `$createdAt`) and `byCreatedAt` (`$createdAt`),
Expand All @@ -165,8 +165,26 @@ neither unique.

A proposal costs its storage and nothing else, so text held in it would be
cheap to fill with anything and could never be taken down: the proposal is
undeletable. It therefore holds no description. It points at a document that
does, hosted where moderators can remove it:
undeletable. It therefore holds no description. What is being decided is said
in one of two places, or both:

- **A description document**, hosted on Platform where an elected team can
remove it. The proposal names it with `descriptionId`,
`descriptionContractId` and `descriptionDocumentType`, and it is checked as
below.
- **A url**, for a description hosted anywhere else. Nothing on chain reads or
moderates what it points at: whoever serves it can change or remove it, and
nobody else can. A proposal holds at most 512 bytes of it.

Two `propertyConstraints` rules hold a proposal to that, on create and on
every edit (`DocumentPropertyConstraintViolatedError`):

| Rule | Condition | Refuses |
| --- | --- | --- |
| `describedByADocumentOrAUrl` | `{ "anyOf": [{ "present": "descriptionId" }, { "present": "url" }] }` | A proposal with neither |
| `descriptionDocumentNamedWhole` | `{ "in": [{ "countPresent": ["descriptionId", "descriptionContractId", "descriptionDocumentType"] }, [0, 3]] }` | A description document named in part: an id with no contract or no type, or a contract or a type with no id |

A proposal that points at a description document declares it this way:

```json
"descriptionId": {
Expand Down Expand Up @@ -282,6 +300,9 @@ What this does and does not give:
type's `position` order, that fills the `body` slot, then `bodyBytes`
(see [the binding rule](../../book/src/contract-keywords/refers-to-dynamic.md#documenttyperequirements)).
- `title` and `url` are still text of the proposal.
- A proposal described at a `url` alone gets none of the above. What the url
serves is outside the chain: it can change after choices were entered, and
no moderator can take it down. A client shows it as an outside link.

### `choice`

Expand Down
19 changes: 12 additions & 7 deletions packages/decision-proposals-contract/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,9 +61,14 @@ can see the proposal as it was when a choice was entered. Whether it is `open`
never changes. Creating it opens no vote and states no fund: the first choice
does.

The proposal holds no description of its own. It points at a document saying
what is being decided, in another contract, so that the description can be
taken down: the document type is a moderated one (its documents leave state
The proposal holds no description of its own. What is being decided is said
in one of two places, or both: at its `url`, for a description hosted
anywhere, which nothing on chain reads or moderates; or in a document the
proposal points at, in another contract, so that the description can be
taken down. A proposal gives at least one, and names a description document
with all three of its properties or none (the `describedByADocumentOrAUrl`
and `descriptionDocumentNamedWhole` rules). For a document, the document type
is a moderated one (its documents leave state
only through a moderator's recorded removal) holding a string or a byte array
that the removal takes away and that the document's author writes, the
contract is one whose moderators the masternodes elect and whose owner they
Expand All @@ -73,10 +78,10 @@ at any time after they are written.
| Property | Type | Meaning |
| --- | --- | --- |
| `title` | string, 1 to 128 characters and at most 512 bytes, required | The question, in one line |
| `descriptionId` | identifier, required | The document saying what is being decided |
| `descriptionContractId` | identifier, required | The contract that document lives in, one declaring elected moderation that does not protect its owner from the team |
| `descriptionDocumentType` | string, 1 to 64 characters, required | That document's document type |
| `url` | string, a URI of 1 to 512 characters and at most 512 bytes | Where the proposal is discussed |
| `descriptionId` | identifier | The document saying what is being decided, when the proposal points at one |
| `descriptionContractId` | identifier, given with `descriptionId` and only with it | The contract that document lives in, one declaring elected moderation that does not protect its owner from the team |
| `descriptionDocumentType` | string, 1 to 64 characters, given with `descriptionId` and only with it | That document's document type |
| `url` | string, a URI of 1 to 512 characters and at most 512 bytes, required when `descriptionId` is left out | Where what is being decided is described, for a proposal that points at no description document; where it is discussed, for one that does |
| `open` | boolean, required | Whether anyone may enter choices. Only the proposal's owner may when it is false |

Indexes: `byOwner` (`$ownerId`, `$createdAt`) lists an identity's proposals;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -321,7 +321,7 @@
}
}
},
"description": "The document saying what is being decided: a document of a moderated type its contract's elected team may delete, at any time after it is written, holding text its author wrote that the removal takes away with it",
"description": "The document saying what is being decided, when the proposal points at one: a document of a moderated type its contract's elected team may delete, at any time after it is written, holding text its author wrote that the removal takes away with it. Left out, with the two properties naming where it lives, by a proposal described at its url",
"position": 1
},
"descriptionContractId": {
Expand All @@ -337,14 +337,14 @@
"ownerProtected": false
}
},
"description": "The contract the description document lives in, one whose moderators the masternodes elect and whose owner they may moderate like anyone",
"description": "The contract the description document lives in, one whose moderators the masternodes elect and whose owner they may moderate like anyone. Given with descriptionId, and only with it",
"position": 2
},
"descriptionDocumentType": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "The document type of the description document",
"description": "The document type of the description document. Given with descriptionId, and only with it",
"position": 3
},
"url": {
Expand All @@ -353,7 +353,7 @@
"minLength": 1,
"maxLength": 512,
"maxBytes": 512,
"description": "Where the proposal is discussed",
"description": "Where what is being decided is described, for a proposal that points at no description document; where it is discussed, for one that does. Required when descriptionId is left out",
"position": 4
},
"open": {
Expand All @@ -366,9 +366,6 @@
"$createdAt",
"$updatedAt",
"title",
"descriptionId",
"descriptionContractId",
"descriptionDocumentType",
"open"
],
"immutable": [
Expand Down Expand Up @@ -444,8 +441,35 @@
}
}
],
"propertyConstraints": {
"describedByADocumentOrAUrl": {
"anyOf": [
{
"present": "descriptionId"
},
{
"present": "url"
}
]
},
"descriptionDocumentNamedWhole": {
"in": [
{
"countPresent": [
"descriptionId",
"descriptionContractId",
"descriptionDocumentType"
]
},
[
0,
3
]
]
}
},
"additionalProperties": false,
"description": "A question put to the masternodes whose answers are the choices entered for it. What is being decided is said by a document the proposal points at, of a moderated type of a contract whose moderators the masternodes elect, so that they can take it down. Anyone may enter choices when it is open, and only its owner when it is not. Its title, url and the description it points at may be changed for two hours after it is created; whether it is open never changes, and it is never deleted"
"description": "A question put to the masternodes whose answers are the choices entered for it. What is being decided is said in one of two places, or both: a document the proposal points at, of a moderated type of a contract whose moderators the masternodes elect, so that they can take it down; or a url, which nothing on chain moderates. Anyone may enter choices when it is open, and only its owner when it is not. Its title, url and the description it points at may be changed for two hours after it is created; whether it is open never changes, and it is never deleted"
},
"choice": {
"type": "object",
Expand Down
33 changes: 29 additions & 4 deletions packages/decision-proposals-contract/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -224,9 +224,9 @@ mod tests {
multiple_choice_proposal::properties::OPEN,
])
);
// The question holds no description of its own: it points at a document of a
// moderated type, of the contract and the type it names, holding a string or bytes
// that a moderator's removal takes away and that its author writes
// The question holds no description of its own. When it points at one, it is a
// document of a moderated type, of the contract and the type it names, holding a
// string or bytes that a moderator's removal takes away and that its author writes
let taken_with_the_document = serde_json::json!({
"allOf": [
{ "not": { "contains": ["$moderatorAbilities.deleteKeepsFields", "$property"] } },
Expand Down Expand Up @@ -294,13 +294,38 @@ mod tests {
.iter()
.filter_map(Value::as_str)
.collect();
// A description document is one of two ways to say what is being decided, so none
// of the three properties naming it is required, and neither is the url
for property in [
multiple_choice_proposal::properties::DESCRIPTION_ID,
multiple_choice_proposal::properties::DESCRIPTION_CONTRACT_ID,
multiple_choice_proposal::properties::DESCRIPTION_DOCUMENT_TYPE,
multiple_choice_proposal::properties::URL,
] {
assert!(required.contains(&property), "{property} is required");
assert!(!required.contains(&property), "{property} is not required");
}
// A proposal gives one of the two or both, and names a description document whole
assert_eq!(
question["propertyConstraints"],
serde_json::json!({
multiple_choice_proposal::rules::DESCRIBED_BY_A_DOCUMENT_OR_A_URL: {
"anyOf": [
{ "present": multiple_choice_proposal::properties::DESCRIPTION_ID },
{ "present": multiple_choice_proposal::properties::URL }
]
},
multiple_choice_proposal::rules::DESCRIPTION_DOCUMENT_NAMED_WHOLE: {
"in": [
{ "countPresent": [
multiple_choice_proposal::properties::DESCRIPTION_ID,
multiple_choice_proposal::properties::DESCRIPTION_CONTRACT_ID,
multiple_choice_proposal::properties::DESCRIPTION_DOCUMENT_TYPE
] },
[0, 3]
]
}
})
);
// Every question says whether it is open, for good
assert_eq!(
question["properties"][multiple_choice_proposal::properties::OPEN]["type"],
Expand Down
33 changes: 24 additions & 9 deletions packages/decision-proposals-contract/src/v1/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -34,27 +34,42 @@ pub mod document_types {

/// A question put to the masternodes whose answers are the choices entered for it. Any
/// identity may enter [`choice`]s when it is open, and only its owner when it is not; whoever
/// may enter them may enter several. What is being decided is not text of the proposal:
/// the proposal points at a document saying it, of a moderated document type of a contract
/// whose moderators the masternodes elect, so that a description can be taken down. Its
/// may enter them may enter several. What is being decided is not text of the proposal.
/// It is said in one of two places, or both: a document the proposal points at, of a
/// moderated document type of a contract whose moderators the masternodes elect, so that
/// a description can be taken down; or a url, which nothing on chain moderates. Its
/// owner may edit the title and url, and point it at another description, for two hours
/// after creating it, and every version is kept; whether it is open never changes.
/// Undeletable.
pub mod multiple_choice_proposal {
pub const NAME: &str = "multipleChoiceProposal";

pub mod rules {
/// The `propertyConstraints` rule holding a proposal to a description: the
/// document it points at, its url, or both.
pub const DESCRIBED_BY_A_DOCUMENT_OR_A_URL: &str = "describedByADocumentOrAUrl";
/// The `propertyConstraints` rule holding the three properties that name a
/// description document together: all given, or none.
pub const DESCRIPTION_DOCUMENT_NAMED_WHOLE: &str = "descriptionDocumentNamedWhole";
}

pub mod properties {
pub const TITLE: &str = "title";
/// The id of the document saying what is being decided. Its document type is a
/// moderated one holding a string or a byte array that a moderator's removal
/// takes away and that its author writes, which its contract's elected team may
/// delete from at any time.
/// The id of the document saying what is being decided, when the proposal points
/// at one. Its document type is a moderated one holding a string or a byte array
/// that a moderator's removal takes away and that its author writes, which its
/// contract's elected team may delete from at any time.
pub const DESCRIPTION_ID: &str = "descriptionId";
/// The id of the contract the description document lives in, one declaring
/// elected moderation that does not protect its owner from the team.
/// elected moderation that does not protect its owner from the team. Given with
/// the description's id, and only with it.
pub const DESCRIPTION_CONTRACT_ID: &str = "descriptionContractId";
/// The name of the description document's document type.
/// The name of the description document's document type. Given with the
/// description's id, and only with it.
pub const DESCRIPTION_DOCUMENT_TYPE: &str = "descriptionDocumentType";
/// Where what is being decided is described, for a proposal that points at no
/// description document, which must then give it; where it is discussed, for one
/// that does.
pub const URL: &str = "url";
/// Whether anyone may enter choices. Only the proposal's owner may when it is
/// false.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -250,13 +250,39 @@ describe('Decision Proposals Contract', () => {
expect(validateType('multipleChoiceProposal', await rawQuestion()).isValid()).to.be.true();
});

it('should not need a url', async () => {
it('should not need a url when it points at a description document', async () => {
const raw = await rawQuestion();
delete raw.url;

expect(validateType('multipleChoiceProposal', raw).isValid()).to.be.true();
});

it('should not need a description document when it gives a url', async () => {
const raw = await rawQuestion();
delete raw.descriptionId;
delete raw.descriptionContractId;
delete raw.descriptionDocumentType;

expect(validateType('multipleChoiceProposal', raw).isValid()).to.be.true();
});

it('should be described by a document, a url or both, the document named whole', () => {
// Judged when a proposal is written, not by the JSON Schema of its type
const { propertyConstraints } = decisionProposalsContractDocumentsSchema.multipleChoiceProposal;

expect(propertyConstraints).to.deep.equal({
describedByADocumentOrAUrl: {
anyOf: [{ present: 'descriptionId' }, { present: 'url' }],
},
descriptionDocumentNamedWhole: {
in: [
{ countPresent: ['descriptionId', 'descriptionContractId', 'descriptionDocumentType'] },
[0, 3],
],
},
});
});

it('should keep its text and its description editable for two hours, every version, and never be deleted', () => {
const { multipleChoiceProposal } = decisionProposalsContractDocumentsSchema;

Expand Down Expand Up @@ -368,9 +394,6 @@ describe('Decision Proposals Contract', () => {

[
'title',
'descriptionId',
'descriptionContractId',
'descriptionDocumentType',
'open',
].forEach((property) => {
it(`should require ${property}`, async () => {
Expand Down
Loading
Loading