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
18 changes: 15 additions & 3 deletions docs/protocol/decision-proposals.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,8 @@ poll by id alone.

The create states the fund it pays as its prefunded voting balance: the name
`proposal` and exactly the decision proposal fund. The transition builders fill
it in for a proposal, as they do for a contested document. Any other fund is
it in for a proposal, as they do for a contested document, and a contest fund
given in the creation options leaves it as it is. Any other fund is
refused (`DecisionProposalFundMismatchError`, 11100), as is a rule outside the
limits below (`InvalidDecisionProposalRuleError`, 11101) and an end date outside
them (`DecisionProposalEndDateOutOfRangeError`, 41300). The mempool judges the
Expand Down Expand Up @@ -107,11 +108,22 @@ proposal before it closes.
The poll closes in a block whose time has reached its end date. Its result,
whether it passed with the yes, no and abstain voting power cast and the
voting power it needed, stays in the poll's stored info. Read it with
`getYesNoVotePollState`, naming the poll by its id (`YesNoVotePoll::unique_id`
of the `DecisionProposal` purpose): the response carries the poll as it was
`getYesNoVotePollState`, naming the poll by its id (`YesNoVotePollPurpose::unique_id`
of the `DecisionProposal` purpose, `decision_proposal_vote_poll_id` in
`dpp::decision_proposal`): the response carries the poll as it was
opened, its rule included, and once it has finished, the result and the blocks
it opened and closed in.

The result is signaling only. Nothing on Platform acts on a passed or failed
proposal (`on_yes_no_vote_poll_finished` does nothing for this purpose); what
it means is up to the people who read it.

## From the SDKs

The Rust SDK (`dash_sdk::platform::decision_proposals`) and the JavaScript SDKs
(`sdk.decisionProposals` in `@dashevo/evo-sdk`, the `*DecisionProposal*`
methods of `@dashevo/wasm-sdk`) build a proposal to create as a document, give
an existing one new text to replace it with, list proposals through the three
indexes a page at a time, and read and answer a proposal's poll by the
proposal's id. A masternode's vote names the poll by its id, which the SDKs
derive from the proposal's id with the protocol version they speak.
44 changes: 44 additions & 0 deletions packages/js-evo-sdk/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,7 @@ The SDK organises its API into domain-specific facades, each accessible as a pro
| [`sdk.shielded`](src/shielded/facade.ts) | Query shielded pool state, encrypted notes, anchors, and nullifier status |
| [`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 |

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 @@ -484,6 +485,49 @@ await sdk.documents.create({ document: resignation, identityKey, signer });

The leader reads either with `sdk.encryptedFor.decrypt`.

## Decision proposals

From protocol version 15 any identity can put a yes/no question to the masternodes: a `proposal` document of the decision proposals system contract (`3iNyoNwjCTkb7XS3RHyWUtLx7pgC6AFAEQNNDHzxqngF`). Creating it opens the proposal's vote poll, and the owner pays the decision proposal fund, 0.5 Dash, on top of the fees. The result is signaling only. `sdk.decisionProposals` builds proposals for `sdk.documents`, reads them with proved queries, and reads and answers their polls by the proposal's id:

```ts
// A question that passes with more than 60% yes, if at least 10% of the network answers
const draft = await sdk.decisionProposals.build({
ownerId: identity.id,
title: 'Raise the block size?',
description: 'Yes doubles it; no keeps it.',
url: 'https://forum.dash.org/t/block-size',
passPercent: 60, // 50 to 80
minimumTurnoutPercent: 10, // 0 to 50
endDate: BigInt(Date.now() + 14 * 24 * 3600 * 1000), // 1 to 4 weeks after the creating block
});
const proposal = await sdk.documents.create({ document: draft, identityKey, signer });

// The text can be edited for a day; the rule and the end date never change
const edited = await sdk.decisionProposals.buildEdit(proposal, { title: 'Raise the block size to 4 MB?' });
await sdk.documents.replace({ document: edited, identityKey, signer });

// The open proposals, closing soonest first; an identity's; every proposal, newest first
const open = await sdk.decisionProposals.byEndDate({ endDateFrom: BigInt(Date.now()), limit: 20 });
const mine = await sdk.decisionProposals.byOwner({ ownerId: identity.id });
const latest = await sdk.decisionProposals.byCreatedAt({ limit: 10 });

// The poll: its tallies while it runs, its result once it closes
const state = await sdk.decisionProposals.pollState(proposal.id);
if (state?.status === 'finished') console.log(state.result.passed);

// A masternode answers 'yes', 'no' or 'abstain' with its voting key
await sdk.decisionProposals.vote({
masternodeProTxHash: proTxHash,
proposalId: proposal.id,
voteChoice: 'yes',
votingKey,
signer: votingSigner,
});
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'`.

## 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
100 changes: 100 additions & 0 deletions packages/js-evo-sdk/src/decision-proposals/facade.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
import * as wasm from '../wasm.js';
import type { EvoSDK } from '../sdk.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.
*/
export class DecisionProposalsFacade {
private sdk: EvoSDK;

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

/**
* Builds a proposal to create with `sdk.documents.create`, which states the fund itself and
* returns the stored proposal with its final id.
*/
async build(options: wasm.DecisionProposalOptions): Promise<wasm.Document> {
const w = await this.sdk.getWasmSdkConnected();
return w.buildDecisionProposal(options);
}

/**
* A proposal with new text and its next revision, to replace with `sdk.documents.replace`.
* Platform accepts the edit for a day after the proposal is created.
*/
async buildEdit(proposal: wasm.Document, edit: wasm.DecisionProposalEdit): Promise<wasm.Document> {
const w = await this.sdk.getWasmSdkConnected();
return w.buildDecisionProposalEdit(proposal, edit);
}

/** 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.getDecisionProposal(proposalId);
}

/**
* One page of the proposals by end date, then by creation time. `endDateFrom: Date.now()`
* lists the open ones.
*/
async byEndDate(
query?: wasm.DecisionProposalsByEndDateQuery,
): Promise<Map<string, wasm.Document | undefined>> {
const w = await this.sdk.getWasmSdkConnected();
return w.getDecisionProposalsByEndDate(query);
}

/** 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.getDecisionProposalsByOwner(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.getDecisionProposalsByCreatedAt(query);
}

/** The id of a proposal's poll, as `sdk.voting.votePollsByEndDate` lists it. */
async pollId(proposalId: wasm.IdentifierLike): Promise<wasm.Identifier> {
const w = await this.sdk.getWasmSdkConnected();
return w.getDecisionProposalPollId(proposalId);
}

/**
* The status and tallies of a proposal's poll: started, with the voting power cast so far,
* or finished, with its result. Undefined for a proposal never created.
*/
async pollState(proposalId: wasm.IdentifierLike): Promise<wasm.YesNoVotePollState | undefined> {
const w = await this.sdk.getWasmSdkConnected();
return w.getDecisionProposalPollState(proposalId);
}

/**
* A masternode's answer on a proposal, or undefined when it has not voted on it or the poll
* finished.
*/
async masternodeVote(
proTxHash: wasm.IdentifierLike,
proposalId: wasm.IdentifierLike,
): Promise<wasm.MasternodeYesNoVote | undefined> {
const w = await this.sdk.getWasmSdkConnected();
return w.getMasternodeDecisionProposalVote(proTxHash, proposalId);
}

/** Votes on a proposal for a masternode, and returns the vote as Platform recorded it. */
async vote(options: wasm.DecisionProposalVoteOptions): Promise<wasm.Vote> {
const w = await this.sdk.getWasmSdkConnected();
return w.decisionProposalVote(options);
}
}
4 changes: 4 additions & 0 deletions packages/js-evo-sdk/src/sdk.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ import { VotingFacade } from './voting/facade.js';
import { ShieldedFacade } from './shielded/facade.js';
import { EncryptedForFacade } from './encrypted-for/facade.js';
import { ModerationChartersFacade } from './moderation-charters/facade.js';
import { DecisionProposalsFacade } from './decision-proposals/facade.js';

export interface ConnectionOptions {
version?: number;
Expand Down Expand Up @@ -77,6 +78,7 @@ export class EvoSDK {
public shielded!: ShieldedFacade;
public encryptedFor!: EncryptedForFacade;
public moderationCharters!: ModerationChartersFacade;
public decisionProposals!: DecisionProposalsFacade;
constructor(options: EvoSDKOptions = {}) {
// Apply defaults while preserving any future connection options
const { network = 'testnet', trusted = false, addresses, devnetName, quorumUrl, ...connection } = options;
Expand Down Expand Up @@ -117,6 +119,7 @@ export class EvoSDK {
this.shielded = new ShieldedFacade(this);
this.encryptedFor = new EncryptedForFacade(this);
this.moderationCharters = new ModerationChartersFacade(this);
this.decisionProposals = new DecisionProposalsFacade(this);
}

get wasm(): wasm.WasmSdk {
Expand Down Expand Up @@ -343,5 +346,6 @@ export { VotingFacade } from './voting/facade.js';
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 { wallet } from './wallet/functions.js';
export * from './wasm.js';
139 changes: 139 additions & 0 deletions packages/js-evo-sdk/tests/unit/facades/decision-proposals.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
import type { SinonStub } from 'sinon';
import init, * as wasmSDKPackage from '@dashevo/wasm-sdk';
import { EvoSDK } from '../../../dist/sdk.js';

describe('DecisionProposalsFacade', () => {
let wasmSdk: wasmSDKPackage.WasmSdk;
let client: EvoSDK;

let buildDecisionProposalStub: SinonStub;
let buildDecisionProposalEditStub: SinonStub;
let getDecisionProposalStub: SinonStub;
let getDecisionProposalsByEndDateStub: SinonStub;
let getDecisionProposalsByOwnerStub: SinonStub;
let getDecisionProposalsByCreatedAtStub: SinonStub;
let getDecisionProposalPollIdStub: SinonStub;
let getDecisionProposalPollStateStub: SinonStub;
let getMasternodeDecisionProposalVoteStub: SinonStub;
let decisionProposalVoteStub: SinonStub;

const ownerId = '5mjGWa9mruHnLBht3ntBi8CZ6sNk3hZZsQMgTvgQobjS';
const proposalId = '4EfA9Jrvv3nnCFdSf7fad59851iiTRZ6Wcu6YVJ4iSeF';
const proTxHash = 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2';

beforeEach(async function setup() {
await init();
const builder = wasmSDKPackage.WasmSdkBuilder.testnet();
wasmSdk = await builder.build();
client = EvoSDK.fromWasm(wasmSdk);

buildDecisionProposalStub = this.sinon.stub(wasmSdk, 'buildDecisionProposal').resolves({});
buildDecisionProposalEditStub = this.sinon.stub(wasmSdk, 'buildDecisionProposalEdit').returns({});
getDecisionProposalStub = this.sinon.stub(wasmSdk, 'getDecisionProposal').resolves(undefined);
getDecisionProposalsByEndDateStub = this.sinon.stub(wasmSdk, 'getDecisionProposalsByEndDate').resolves(new Map());
getDecisionProposalsByOwnerStub = this.sinon.stub(wasmSdk, 'getDecisionProposalsByOwner').resolves(new Map());
getDecisionProposalsByCreatedAtStub = this.sinon.stub(wasmSdk, 'getDecisionProposalsByCreatedAt').resolves(new Map());
getDecisionProposalPollIdStub = this.sinon.stub(wasmSdk, 'getDecisionProposalPollId').resolves({});
getDecisionProposalPollStateStub = this.sinon.stub(wasmSdk, 'getDecisionProposalPollState').resolves(undefined);
getMasternodeDecisionProposalVoteStub = this.sinon.stub(wasmSdk, 'getMasternodeDecisionProposalVote').resolves(undefined);
decisionProposalVoteStub = this.sinon.stub(wasmSdk, 'decisionProposalVote').resolves({});
});

describe('build()', () => {
it('should forward the options to buildDecisionProposal', async () => {
const options = {
ownerId,
title: 'Raise the block size?',
description: 'Yes doubles it; no keeps it.',
url: 'https://forum.dash.org/t/block-size',
passPercent: 60,
minimumTurnoutPercent: 10,
endDate: 1_700_000_000_000n,
};
await client.decisionProposals.build(options);
expect(buildDecisionProposalStub).to.be.calledOnceWithExactly(options);
});
});

describe('buildEdit()', () => {
it('should forward the proposal and the edit to buildDecisionProposalEdit', async () => {
const proposal = {} as wasmSDKPackage.Document;
const edit = { title: 'Raise the block size to 4 MB?', url: null };
await client.decisionProposals.buildEdit(proposal, edit);
expect(buildDecisionProposalEditStub).to.be.calledOnceWithExactly(proposal, edit);
});
});

describe('get()', () => {
it('should forward the proposal id to getDecisionProposal', async () => {
const result = await client.decisionProposals.get(proposalId);
expect(getDecisionProposalStub).to.be.calledOnceWithExactly(proposalId);
expect(result).to.equal(undefined);
});
});

describe('byEndDate()', () => {
it('should forward the query to getDecisionProposalsByEndDate', async () => {
const query = { endDateFrom: 1_700_000_000_000n, limit: 20 };
const result = await client.decisionProposals.byEndDate(query);
expect(getDecisionProposalsByEndDateStub).to.be.calledOnceWithExactly(query);
expect(result).to.be.instanceOf(Map);
});

it('should list from the start without a query', async () => {
await client.decisionProposals.byEndDate();
expect(getDecisionProposalsByEndDateStub).to.be.calledOnceWithExactly(undefined);
});
});

describe('byOwner()', () => {
it('should forward the query to getDecisionProposalsByOwner', async () => {
const query = { ownerId, startAfter: proposalId };
await client.decisionProposals.byOwner(query);
expect(getDecisionProposalsByOwnerStub).to.be.calledOnceWithExactly(query);
});
});

describe('byCreatedAt()', () => {
it('should forward the query to getDecisionProposalsByCreatedAt', async () => {
const query = { limit: 5 };
await client.decisionProposals.byCreatedAt(query);
expect(getDecisionProposalsByCreatedAtStub).to.be.calledOnceWithExactly(query);
});
});

describe('pollId()', () => {
it('should forward the proposal id to getDecisionProposalPollId', async () => {
await client.decisionProposals.pollId(proposalId);
expect(getDecisionProposalPollIdStub).to.be.calledOnceWithExactly(proposalId);
});
});

describe('pollState()', () => {
it('should forward the proposal id to getDecisionProposalPollState', async () => {
await client.decisionProposals.pollState(proposalId);
expect(getDecisionProposalPollStateStub).to.be.calledOnceWithExactly(proposalId);
});
});

describe('masternodeVote()', () => {
it('should forward the masternode and the proposal to getMasternodeDecisionProposalVote', async () => {
await client.decisionProposals.masternodeVote(proTxHash, proposalId);
expect(getMasternodeDecisionProposalVoteStub).to.be.calledOnceWithExactly(proTxHash, proposalId);
});
});

describe('vote()', () => {
it('should forward the options to decisionProposalVote', async () => {
const options = {
masternodeProTxHash: proTxHash,
proposalId,
voteChoice: 'yes' as const,
votingKey: {} as wasmSDKPackage.IdentityPublicKey,
signer: {} as wasmSDKPackage.IdentitySigner,
};
await client.decisionProposals.vote(options);
expect(decisionProposalVoteStub).to.be.calledOnceWithExactly(options);
});
});
});
Loading
Loading