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
23 changes: 21 additions & 2 deletions docs/protocol/decision-proposals.md
Original file line number Diff line number Diff line change
Expand Up @@ -406,5 +406,24 @@ A multiple choice proposal and its choices are ordinary documents and an
ordinary contest: the SDKs' document create builds both (a `choice` create is
given its contest fund like any contested create), and their contested resource
queries and masternode vote read and answer the vote, with a choice's document
id wherever they name a contender by an identity id. They have no helpers of
their own yet.
id wherever they name a contender by an identity id.

The Rust SDK (`dash_sdk::platform::decision_proposals::multiple_choice`) and the
JavaScript SDKs (`sdk.decisionProposals.multipleChoice` in `@dashevo/evo-sdk`,
the `*MultipleChoiceProposal*` methods of `@dashevo/wasm-sdk`) have helpers over
those:

- build a proposal, its edit and a choice as documents to create or replace;
- give the proposal's processing fee and the fund a choice entered now pays;
- list proposals by owner and by creation time;
- read the vote by the proposal's id: every choice with its tally while it
runs, the result with every choice's final tally afterwards, and the choice
that was kept;
- build a masternode's vote from a choice's document id, abstain, or none of
the choices (a lock), and read the answer a masternode gave.

The contest a proposal's choices run in is named from the proposal's id alone
(`dpp::decision_proposal::multiple_choice::multiple_choice_proposal_vote_poll`).
The helpers write what they are given: which descriptions, texts and choices
Platform takes is checked by the contract, on chain. The mobile SDKs have no
multiple choice helpers yet.
59 changes: 59 additions & 0 deletions packages/js-evo-sdk/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,7 @@ The SDK organises its API into domain-specific facades, each accessible as a pro
| [`sdk.encryptedFor`](src/encrypted-for/facade.ts) | Encrypt and decrypt the byte properties a document type declares `encryptedFor`, for any contract |
| [`sdk.moderationCharters`](src/moderation-charters/facade.ts) | Read a contract's seated charter, its team, proposals and join requests; build join and resignation requests |
| [`sdk.decisionProposals`](src/decision-proposals/facade.ts) | Build, edit, list and read decision proposals; read their polls and vote on them as a masternode |
| [`sdk.decisionProposals.multipleChoice`](src/decision-proposals/multiple-choice-facade.ts) | Build, edit, list and read multiple choice proposals and their choices; read the vote among the choices and vote in it as a masternode |

A `wallet` namespace is also exported with utilities for BIP39 mnemonic generation and validation, BIP44/DIP9/DIP13 key derivation (path helpers included), extended-key conversion (`xprvToXpub`, `deriveChildPublicKey`), key-pair generation and import (`generateKeyPair`, `keyPairFromWif`, `keyPairFromHex`), public-key-to-address conversion, address validation, message signing, and Dashpay contact-key derivation. See [`src/wallet/functions.ts`](src/wallet/functions.ts) for the full list.

Expand Down Expand Up @@ -579,6 +580,64 @@ const answer = await sdk.decisionProposals.masternodeVote(proTxHash, proposal.id

`sdk.voting.masternodeVote` also answers a yes/no poll as `sdk.voting.votePollsByEndDate` lists it, with `voteChoice: 'yes' | 'no' | 'abstain'`.

### Multiple choice proposals

A question with more than two answers is a `multipleChoiceProposal` document of the same contract, and each answer is a `choice` document. The choices contend in a masternode vote that the first choice opens, and the one with the most votes is kept. `sdk.decisionProposals.multipleChoice` builds both for `sdk.documents`, and reads and answers the vote by the proposal's id. A choice is named by its document id, in a vote and in the vote's state:

```ts
const multipleChoice = sdk.decisionProposals.multipleChoice;

// Described by a document of an elected-moderation contract, at a url, or both.
// The owner pays the processing fee on top of the fees; the create does not state it.
const fee = await multipleChoice.processingFee(); // 0.2 Dash, in credits
const draft = await multipleChoice.build({
ownerId: identity.id,
title: 'Which block size?',
descriptionDocument: { id: postId, contractId: forumContractId, documentType: 'post' },
url: 'https://forum.dash.org/t/block-size',
open: true, // anyone may enter choices; false leaves them to the owner
});
const proposal = await sdk.documents.create({ document: draft, identityKey, signer });

// The title, url and description document can be edited for two hours; `open` never changes
const edited = await multipleChoice.buildEdit(proposal, { title: 'Which block size, then?' });
await sdk.documents.replace({ document: edited, identityKey, signer });

// A choice pays the contest fund, which the create states itself
const fund = await multipleChoice.choiceFund(proposal.id); // 0.1 Dash until the vote holds 250 choices
const choiceDraft = await multipleChoice.buildChoice({
ownerId: identity.id,
proposalId: proposal.id,
title: 'Double it',
description: 'Twice the size it is today.',
});
const choice = await sdk.documents.create({ document: choiceDraft, identityKey, signer });

// An identity's proposals; every proposal, newest first
const mine = await multipleChoice.byOwner({ ownerId: identity.id });
const latest = await multipleChoice.byCreatedAt({ limit: 10 });

// The vote: every choice with its tally while it runs, its result once it ended
const vote = await multipleChoice.voteState(proposal.id);
for (const [choiceId, { choice: document, voteTally }] of vote.choices) {
console.log(choiceId, document?.properties.title, voteTally);
}
if (vote.result) console.log(vote.result.keptChoiceId?.toBase58());
const kept = await multipleChoice.keptChoice(proposal.id);

// A masternode answers with a choice's document id, 'abstain' or 'noneOfTheChoices'
await multipleChoice.vote({
masternodeProTxHash: proTxHash,
proposalId: proposal.id,
voteChoice: { choiceId: choice.id },
votingKey,
signer: votingSigner,
});
const given = await multipleChoice.masternodeVote(proTxHash, proposal.id);
```

`multipleChoice.votePoll(proposal.id)` gives the vote as a vote poll for `sdk.voting` and the contested resource queries.

## Immutable properties (`immutable`)

From protocol version 14 a mutable document type can freeze some of its top-level properties with the doctype-level `immutable` list, while the rest of the document stays replaceable. An entry naming a property freezes it at creation. An entry `{ property, when }` freezes it for any replace its condition holds for: the condition takes the grammar of a `propertyConstraints` rule, is judged on the document the replace writes (whose `$updatedAt` is the replace's block time), and reads the stored document through `$old.` paths.
Expand Down
7 changes: 7 additions & 0 deletions packages/js-evo-sdk/src/decision-proposals/facade.ts
Original file line number Diff line number Diff line change
@@ -1,17 +1,24 @@
import * as wasm from '../wasm.js';
import type { EvoSDK } from '../sdk.js';
import { MultipleChoiceProposalsFacade } from './multiple-choice-facade.js';

/**
* Decision proposals (protocol version 15): yes/no questions any identity puts to the
* masternodes. A proposal is a `proposal` document of the decision proposals system contract;
* creating it opens its vote poll, and its owner pays the decision proposal fund, 0.5 Dash.
* Nothing acts on a result. Every read is a proved query.
*
* A question with more than two answers is a multiple choice proposal: see `multipleChoice`.
*/
export class DecisionProposalsFacade {
private sdk: EvoSDK;

/** Multiple choice proposals, their choices and the vote among them. */
public multipleChoice: MultipleChoiceProposalsFacade;

constructor(sdk: EvoSDK) {
this.sdk = sdk;
this.multipleChoice = new MultipleChoiceProposalsFacade(sdk);
}

/**
Expand Down
131 changes: 131 additions & 0 deletions packages/js-evo-sdk/src/decision-proposals/multiple-choice-facade.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
import * as wasm from '../wasm.js';
import type { EvoSDK } from '../sdk.js';

/**
* Multiple choice proposals (protocol version 15): questions whose answers are the choices
* entered for them. A proposal is a `multipleChoiceProposal` document and an answer a `choice`
* document of the decision proposals system contract. The choices contend in a masternode
* vote that the first choice opens, and the one with the most votes is kept. A choice is named
* by its document id, in a vote and in the vote's state. Every read is a proved query.
*/
export class MultipleChoiceProposalsFacade {
private sdk: EvoSDK;

constructor(sdk: EvoSDK) {
this.sdk = sdk;
}

/**
* Builds a proposal to create with `sdk.documents.create`, which returns the stored proposal
* with its final id. Its owner pays the processing fee `processingFee()` gives on top of the
* fees.
*/
async build(options: wasm.MultipleChoiceProposalOptions): Promise<wasm.Document> {
const w = await this.sdk.getWasmSdkConnected();
return w.buildMultipleChoiceProposal(options);
}

/**
* A proposal with a new title, url or description document and its next revision, to replace
* with `sdk.documents.replace`. Platform accepts the edit for two hours after the proposal
* is created.
*/
async buildEdit(
proposal: wasm.Document,
edit: wasm.MultipleChoiceProposalEdit,
): Promise<wasm.Document> {
const w = await this.sdk.getWasmSdkConnected();
return w.buildMultipleChoiceProposalEdit(proposal, edit);
}

/**
* Builds a choice to create with `sdk.documents.create`, which states the contest fund and
* returns the stored choice with its final id, the id a vote towards it carries.
*/
async buildChoice(options: wasm.MultipleChoiceProposalChoiceOptions): Promise<wasm.Document> {
const w = await this.sdk.getWasmSdkConnected();
return w.buildMultipleChoiceProposalChoice(options);
}

/** What creating one proposal adds to the processing fee of its batch, in credits. */
async processingFee(): Promise<bigint> {
const w = await this.sdk.getWasmSdkConnected();
return w.getMultipleChoiceProposalProcessingFee();
}

/** The fund a choice entered now for a proposal pays, in credits. */
async choiceFund(proposalId: wasm.IdentifierLike): Promise<bigint> {
const w = await this.sdk.getWasmSdkConnected();
return w.getMultipleChoiceProposalChoiceFund(proposalId);
}

/** A proposal by id, or undefined when there is none. */
async get(proposalId: wasm.IdentifierLike): Promise<wasm.Document | undefined> {
const w = await this.sdk.getWasmSdkConnected();
return w.getMultipleChoiceProposal(proposalId);
}

/** One page of an identity's proposals, by creation time. */
async byOwner(
query: wasm.DecisionProposalsByOwnerQuery,
): Promise<Map<string, wasm.Document | undefined>> {
const w = await this.sdk.getWasmSdkConnected();
return w.getMultipleChoiceProposalsByOwner(query);
}

/** One page of every proposal, newest first. */
async byCreatedAt(
query?: wasm.DecisionProposalsPageQuery,
): Promise<Map<string, wasm.Document | undefined>> {
const w = await this.sdk.getWasmSdkConnected();
return w.getMultipleChoiceProposalsByCreatedAt(query);
}

/**
* The vote among a proposal's choices as a vote poll, for `sdk.voting` and the contested
* resource queries.
*/
async votePoll(proposalId: wasm.IdentifierLike): Promise<wasm.VotePoll> {
const w = await this.sdk.getWasmSdkConnected();
return w.getMultipleChoiceProposalVotePoll(proposalId);
}

/**
* The vote among a proposal's choices: every choice with its tally while the vote runs, and
* its result with every choice's final tally once it ended.
*/
async voteState(proposalId: wasm.IdentifierLike): Promise<wasm.MultipleChoiceProposalVote> {
const w = await this.sdk.getWasmSdkConnected();
return w.getMultipleChoiceProposalVote(proposalId);
}

/**
* The choice the finished vote of a proposal kept, or undefined while the vote runs and when
* it kept none.
*/
async keptChoice(proposalId: wasm.IdentifierLike): Promise<wasm.Document | undefined> {
const w = await this.sdk.getWasmSdkConnected();
return w.getMultipleChoiceProposalKeptChoice(proposalId);
}

/**
* The answer a masternode gave in the vote among a proposal's choices, or undefined when it
* has not voted in it or the vote ended.
*/
async masternodeVote(
proTxHash: wasm.IdentifierLike,
proposalId: wasm.IdentifierLike,
): Promise<wasm.MasternodeMultipleChoiceVote | undefined> {
const w = await this.sdk.getWasmSdkConnected();
return w.getMasternodeMultipleChoiceProposalVote(proTxHash, proposalId);
}

/**
* Votes in the vote among a proposal's choices for a masternode, and returns the vote as
* Platform recorded it.
*/
async vote(options: wasm.MultipleChoiceProposalVoteOptions): Promise<wasm.Vote> {
const w = await this.sdk.getWasmSdkConnected();
return w.multipleChoiceProposalVote(options);
}
}
1 change: 1 addition & 0 deletions packages/js-evo-sdk/src/sdk.ts
Original file line number Diff line number Diff line change
Expand Up @@ -460,6 +460,7 @@ export { ShieldedFacade } from './shielded/facade.js';
export { EncryptedForFacade } from './encrypted-for/facade.js';
export { ModerationChartersFacade } from './moderation-charters/facade.js';
export { DecisionProposalsFacade } from './decision-proposals/facade.js';
export { MultipleChoiceProposalsFacade } from './decision-proposals/multiple-choice-facade.js';
export { PrivateDocumentsFacade } from './private-documents/facade.js';
export { wallet } from './wallet/functions.js';
export * from './wasm.js';
Loading
Loading