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
16 changes: 11 additions & 5 deletions docs/protocol/decision-proposals.md
Original file line number Diff line number Diff line change
Expand Up @@ -408,10 +408,14 @@ 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.

The Rust SDK (`dash_sdk::platform::decision_proposals::multiple_choice`) and the
The Rust SDK (`dash_sdk::platform::decision_proposals::multiple_choice`), the
JavaScript SDKs (`sdk.decisionProposals.multipleChoice` in `@dashevo/evo-sdk`,
the `*MultipleChoiceProposal*` methods of `@dashevo/wasm-sdk`) have helpers over
those:
the `*MultipleChoiceProposal*` methods of `@dashevo/wasm-sdk`) and the mobile
SDKs (the `dash_sdk_multiple_choice_proposal_*` C functions of `rs-sdk-ffi` and
the `platform_wallet_multiple_choice_proposal_*` ones of
`rs-platform-wallet-ffi`, wrapped by the Swift SDK and by the Kotlin SDK's
`Sdk.multipleChoiceProposals` and `PlatformWalletManager.multipleChoiceProposals`)
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;
Expand All @@ -425,5 +429,7 @@ those:
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.
Platform takes is checked by the contract, on chain. The mobile SDKs create
and edit a proposal and enter a choice through the platform wallet, which signs
and puts the document, where the Rust and JavaScript helpers return the document
to put.
19 changes: 13 additions & 6 deletions packages/kotlin-sdk/KotlinExampleApp/TEST_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,13 @@ Most Platform actions have hard preconditions. Establish these fixtures before s
| VOTE-11 | Edit a decision proposal's text | Platform | Thorough | βœ… | proposal | Detail β†’ Edit Text (`decisionProposal.edit`, shown only when a local wallet identity filed it) β†’ `editDecisionProposal.*` β†’ `PlatformWalletManager.decisionProposals.edit` (one `platform_wallet_decision_proposal_edit` call; no signing key is chosen in the app). Accepted for a day after creation; an edit that changes nothing is refused before anything is broadcast, and an edit that raced another one is refused by Platform (consensus code 40106) rather than overwriting it. The dialog cannot be dismissed while it broadcasts. |
| VOTE-12 | Masternode vote on a decision proposal (yes / no / abstain) | Platform | Thorough | βœ… | proposal, masternode | Detail β†’ Vote (`decisionProposal.vote`) β†’ `decisionProposalVote.choice` / `.proTxHash` / `.votingKey` / `.submit` β†’ `dash_sdk_decision_proposal_cast_vote`. The voting key shows as dots and a screenshot of the open dialog comes out blank (FLAG_SECURE). **Requires masternode voting credentials**; a vote from a regular wallet is refused (no voter identity). |
| VOTE-13 | Read a masternode's answer on a decision proposal | Platform | Thorough | βœ… | proposal, masternode, read-only | Vote dialog β†’ Read This Masternode's Answer (`decisionProposalVote.lookUp`) β†’ `dash_sdk_decision_proposal_get_masternode_vote`. No answer once the poll finished. |
| VOTE-14 | List multiple choice proposals (mine / newest, paged) | Platform | Thorough | βœ… | proposal, read-only | `QueriesListScreen` β†’ Multiple Choice Proposals (`votingQueries.multipleChoiceProposalsLink`) β†’ `MultipleChoiceProposalsScreen`: listing picker (`multipleChoiceProposals.listing`), identity picker for Mine (`multipleChoiceProposals.ownerPicker`), Load More (`multipleChoiceProposals.loadMore`). Needs protocol version 15; an earlier network shows a load error. |
| VOTE-15 | Create a multiple choice proposal | Platform | Thorough | βœ… | proposal | `MultipleChoiceProposalsScreen` + (`multipleChoiceProposals.create`) β†’ `CreateMultipleChoiceProposalScreen` (`createMultipleChoiceProposal.*`) β†’ `PlatformWalletManager.multipleChoiceProposals.create` (one `platform_wallet_multiple_choice_proposal_create` call; the success section shows the returned id). The Proposer section shows the processing fee read from `dash_sdk_multiple_choice_proposal_get_processing_fee` (`createMultipleChoiceProposal.processingFee`, 0.2 DASH at protocol version 15), which Platform charges on top of the fees. The description document is three optional fields (`.descriptionDocumentId` / `.descriptionDocumentContractId` / `.descriptionDocumentType`); the switch `.open` says whether anyone may enter choices. While it broadcasts, system Back does nothing, and a rotation or a bottom-tab switch does not cancel it. Platform refuses a proposal with neither a description document nor a url. Protocol version 15. |
| VOTE-16 | View a multiple choice proposal, its choices and its vote | Platform | Thorough | βœ… | proposal, read-only | `MultipleChoiceProposalDetailScreen` (row `multipleChoiceProposals.row.<id>`): the proposal, who enters choices (`multipleChoiceProposal.open`), the vote status (`multipleChoiceProposal.voteStatus`: no choice entered, voting open, or how it ended), every choice with its tally (`multipleChoiceProposal.choice.<choiceId>`), the none-of-the-choices and abstain tallies, and once the vote ended the kept choice (`multipleChoiceProposal.keptChoice`, read with `dash_sdk_multiple_choice_proposal_get_kept_choice`). |
| VOTE-17 | Enter a choice for a multiple choice proposal | Platform | Thorough | βœ… | proposal | Detail β†’ Enter a Choice (`multipleChoiceProposal.enterChoice`, shown when a loaded wallet holds an identity) β†’ `enterProposalChoice.ownerPicker` / `.title` / `.description` / `.submitButton` β†’ `PlatformWalletManager.multipleChoiceProposals.enterChoice` (one `platform_wallet_multiple_choice_proposal_enter_choice` call). The dialog shows the contest fund read from `dash_sdk_multiple_choice_proposal_get_choice_fund_to_join` (`enterProposalChoice.fund`), paid on top of the fees. The first choice opens the vote. Platform refuses a choice from anyone but the owner when the proposal is not open; the app does not pre-check it. The entry survives a rotation (the detail screen then shows its outcome), system Back does nothing while it broadcasts, and the action result names the new choice id. |
| VOTE-18 | Edit a multiple choice proposal | Platform | Thorough | βœ… | proposal | Detail β†’ Edit (`multipleChoiceProposal.edit`, shown only when a local wallet identity filed it) β†’ `editMultipleChoiceProposal.*` β†’ `PlatformWalletManager.multipleChoiceProposals.edit` (one `platform_wallet_multiple_choice_proposal_edit` call). Only the changed fields are sent; an emptied url, or three emptied description document fields, removes it. Accepted for two hours after creation (Platform refuses it afterwards; the app does not hide the button); an edit that changes nothing is refused before anything is broadcast, one that leaves neither a description document nor a url is refused by Platform, and one that raced another edit is refused with consensus code 40106. The dialog cannot be dismissed while it broadcasts. |
| VOTE-19 | Masternode vote among a multiple choice proposal's choices (a choice / none of the choices / abstain) | Platform | Thorough | βœ… | proposal, masternode | Detail β†’ Vote (`multipleChoiceProposal.vote`) β†’ `multipleChoiceProposalVote.choice` (every choice of the running vote by title and id, then None of the choices and Abstain) / `.proTxHash` / `.votingKey` / `.submit` β†’ `dash_sdk_multiple_choice_proposal_cast_vote`. The voting key shows as dots and a screenshot of the open dialog comes out blank (FLAG_SECURE); the dialog cannot be dismissed while it broadcasts. **Requires masternode voting credentials**; a vote from a regular wallet is refused (no voter identity). |
| VOTE-20 | Read a masternode's answer among a multiple choice proposal's choices | Platform | Thorough | βœ… | proposal, masternode, read-only | Vote dialog β†’ Read This Masternode's Answer (`multipleChoiceProposalVote.lookUp`) β†’ `dash_sdk_multiple_choice_proposal_get_masternode_vote`. No answer once the vote ended. |

### 4.6 Data Contracts β€” `Domain=Contract`

Expand Down Expand Up @@ -314,7 +321,7 @@ Counts are of rows reachable in the app (Status `βœ…`/`πŸ§ͺ`/`⚠️`); `πŸ”Œ`/`
|---|---|---|
| Essential | 21 | yes |
| Common | 29 | yes |
| Thorough | 42 | yes |
| Thorough | 49 | yes |
| Uncommon | 25 | yes |
| Manual | 1 (`CORE-08`) | no β€” physical device |

Expand All @@ -323,7 +330,7 @@ Counts are of rows reachable in the app (Status `βœ…`/`πŸ§ͺ`/`⚠️`); `πŸ”Œ`/`
| Layer | Count (approx.) |
|---|---|
| Core | 17 |
| Platform | ~80 |
| Platform | ~87 |
| Cross | 7 |
| Shielded | 16 |

Expand All @@ -337,7 +344,7 @@ Membership of each feature category across **all** sections (primary section mem
- **Identity** β€” `ID-01..15`, `SH-11`
- **Address** (DIP-17 platform addresses) β€” `ADDR-01..04`, `ADDR-06..09`, `ID-06`, `ID-08`, `ID-11`
- **DPNS** β€” `DPNS-01..08`
- **Voting** β€” `VOTE-01..13`, `DPNS-05`, `DPNS-08`
- **Voting** β€” `VOTE-01..20`, `DPNS-05`, `DPNS-08`
- **Contract** β€” `DC-01..04`
- **Document** β€” `DOC-01..15`
- **Token** β€” `TOK-01..20`
Expand All @@ -354,6 +361,6 @@ Tags are cross-cutting modalities. A test may appear under multiple tags.
- **contested** β€” `DPNS-05`, `DPNS-08`, `VOTE-01..06`
- **withdrawal** β€” `ID-10`, `ADDR-04`, `SH-08`, `SH-16`
- **regression** β€” `TOK-17`, `DP-10`
- **read-only** β€” `SH-13`, `SYS-05`, `SYS-06`, `VOTE-02..06`, `VOTE-08`, `VOTE-10`, `VOTE-13`, `TOK-18`, `TOK-19`
- **masternode** β€” `VOTE-01`, `VOTE-12`, `VOTE-13`
- **proposal** (decision proposals, protocol version 15): `VOTE-08..13`
- **read-only** β€” `SH-13`, `SYS-05`, `SYS-06`, `VOTE-02..06`, `VOTE-08`, `VOTE-10`, `VOTE-13`, `VOTE-14`, `VOTE-16`, `VOTE-20`, `TOK-18`, `TOK-19`
- **masternode** β€” `VOTE-01`, `VOTE-12`, `VOTE-13`, `VOTE-19`, `VOTE-20`
- **proposal** (decision proposals, yes/no and multiple choice, protocol version 15): `VOTE-08..20`
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,11 @@ import org.dashfoundation.example.ui.identity.AddIdentityKeyScreen
import org.dashfoundation.example.ui.identity.ContestDetailScreen
import org.dashfoundation.example.ui.identity.CreateDecisionProposalScreen
import org.dashfoundation.example.ui.identity.CreateIdentityScreen
import org.dashfoundation.example.ui.identity.CreateMultipleChoiceProposalScreen
import org.dashfoundation.example.ui.identity.DecisionProposalDetailScreen
import org.dashfoundation.example.ui.identity.DecisionProposalsScreen
import org.dashfoundation.example.ui.identity.MultipleChoiceProposalDetailScreen
import org.dashfoundation.example.ui.identity.MultipleChoiceProposalsScreen
import org.dashfoundation.example.ui.dashpay.AddContactScreen
import org.dashfoundation.example.ui.dashpay.ContactDetailScreen
import org.dashfoundation.example.ui.dashpay.ContactRequestsScreen
Expand Down Expand Up @@ -486,6 +489,19 @@ fun AppNavHost(
)
}

composable<MultipleChoiceProposalsList> { MultipleChoiceProposalsScreen(navController) }

composable<CreateMultipleChoiceProposal> {
CreateMultipleChoiceProposalScreen(navController)
}

composable<MultipleChoiceProposalDetail> { entry ->
MultipleChoiceProposalDetailScreen(
entry.toRoute<MultipleChoiceProposalDetail>().proposalId,
navController,
)
}

composable<GroupDetail> { entry ->
val route = entry.toRoute<GroupDetail>()
GroupDetailScreen(route.contractIdHex, route.position, navController)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -430,6 +430,23 @@ import kotlinx.serialization.Serializable
*/
@Serializable data class DecisionProposalDetail(val proposalId: String)

/**
* Multiple choice proposal listings: a local identity's and the newest
* (← `MultipleChoiceProposalsView.swift`). Reached from the Platform Queries list, beside
* [DecisionProposalsList].
*/
@Serializable object MultipleChoiceProposalsList

/** File a new multiple choice proposal (← `CreateMultipleChoiceProposalView`). */
@Serializable object CreateMultipleChoiceProposal

/**
* One multiple choice proposal: its choices and their tallies, how the vote ended, entering
* a choice, the edit and the masternode vote (← `MultipleChoiceProposalDetailView.swift`).
* [proposalId] is base58.
*/
@Serializable data class MultipleChoiceProposalDetail(val proposalId: String)

/**
* One contract group's members + live proposals (← `GroupDetailView.swift`).
* [position] is the group contract position inside the contract's
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ import org.dashfoundation.example.navigation.AddressQueries
import org.dashfoundation.example.navigation.DecisionProposalsList
import org.dashfoundation.example.navigation.Diagnostics
import org.dashfoundation.example.navigation.GroveDbPathElements
import org.dashfoundation.example.navigation.MultipleChoiceProposalsList
import org.dashfoundation.example.navigation.QueryDetail
import org.dashfoundation.example.ui.components.FormSection
import org.dashfoundation.example.ui.components.SubmitButton
Expand Down Expand Up @@ -136,6 +137,20 @@ fun QueriesListScreen(navController: NavHostController) {
.clickable { navController.navigate(DecisionProposalsList) }
.testTag("votingQueries.decisionProposalsLink"),
)
ListItem(
headlineContent = { Text("Multiple Choice Proposals") },
supportingContent = {
Text(
"Browse, file and edit questions answered by the choices entered " +
"for them, enter choices and vote among them (protocol " +
"version 15)",
style = MaterialTheme.typography.bodySmall,
)
},
modifier = Modifier
.clickable { navController.navigate(MultipleChoiceProposalsList) }
.testTag("votingQueries.multipleChoiceProposalsLink"),
)
ListItem(
headlineContent = { Text("Run All Queries") },
supportingContent = {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
package org.dashfoundation.example.ui.contracts

import org.dashfoundation.dashsdk.Sdk
import org.dashfoundation.dashsdk.voting.DecisionProposal
import org.dashfoundation.example.ui.identity.decode32ByteHex

/**
Expand Down Expand Up @@ -598,6 +597,105 @@ internal val QUERY_REGISTRY: List<QueryDefinition> = listOf(
?.toString()
},

// ── Multiple Choice Proposals (protocol version 15) ───────────────────
// The typed reads of `Sdk.multipleChoiceProposals`, shown as their
// Kotlin values. `MultipleChoiceProposalsScreen` is the full flow (list,
// file, edit, enter a choice, vote); these rows run each read on its own.
QueryDefinition(
name = "getMultipleChoiceProposal",
label = "Get Multiple Choice Proposal",
description = "Fetch a multiple choice proposal by its base58 id.",
inputs = listOf(QueryInput("proposalId", "Proposal ID", required = true)),
runsInDiagnostics = false,
) { sdk, inputs ->
sdk.multipleChoiceProposals.fetch(inputs.getValue("proposalId").trim())?.toString()
},
QueryDefinition(
name = "getMultipleChoiceProposalsByOwner",
label = "Get Multiple Choice Proposals by Owner",
description = "The multiple choice proposals an identity filed, in the order it filed them.",
inputs = listOf(
QueryInput("ownerId", "Owner Identity ID", required = true),
QueryInput("limit", "Limit", required = false, placeholder = "20"),
QueryInput("startAfter", "Start after proposal ID", required = false),
),
runsInDiagnostics = false,
) { sdk, inputs ->
sdk.multipleChoiceProposals.listByOwner(
ownerId = inputs.getValue("ownerId").trim(),
limit = inputs["limit"]?.trim()?.toIntOrNull() ?: 0,
startAfter = inputs["startAfter"]?.trim()?.takeIf { it.isNotEmpty() },
).describeProposals()
},
QueryDefinition(
name = "getMultipleChoiceProposalsByCreatedAt",
label = "Get Multiple Choice Proposals by Creation",
description = "Every multiple choice proposal, newest first.",
inputs = listOf(
QueryInput("limit", "Limit", required = false, placeholder = "20"),
QueryInput("startAfter", "Start after proposal ID", required = false),
),
runsInDiagnostics = false,
) { sdk, inputs ->
sdk.multipleChoiceProposals.listByCreatedAt(
limit = inputs["limit"]?.trim()?.toIntOrNull() ?: 0,
startAfter = inputs["startAfter"]?.trim()?.takeIf { it.isNotEmpty() },
).describeProposals()
},
QueryDefinition(
name = "getMultipleChoiceProposalVote",
label = "Get Multiple Choice Proposal Vote",
description = "The choices of a proposal with their tallies, and how the vote ended once it did.",
inputs = listOf(QueryInput("proposalId", "Proposal ID", required = true)),
runsInDiagnostics = false,
) { sdk, inputs ->
sdk.multipleChoiceProposals.vote(inputs.getValue("proposalId").trim()).toString()
},
QueryDefinition(
name = "getMultipleChoiceProposalKeptChoice",
label = "Get Multiple Choice Proposal Kept Choice",
description = "The choice a proposal's finished vote kept.",
inputs = listOf(QueryInput("proposalId", "Proposal ID", required = true)),
runsInDiagnostics = false,
) { sdk, inputs ->
sdk.multipleChoiceProposals.keptChoice(inputs.getValue("proposalId").trim())?.toString()
},
QueryDefinition(
name = "getMasternodeMultipleChoiceVote",
label = "Get Masternode Multiple Choice Vote",
description = "A masternode's answer among a proposal's choices while the vote runs.",
inputs = listOf(
QueryInput("proTxHash", "pro_tx_hash (64 hex chars, wire order)", required = true),
QueryInput("proposalId", "Proposal ID", required = true),
),
runsInDiagnostics = false,
) { sdk, inputs ->
val proTxHash = requireNotNull(decode32ByteHex(inputs.getValue("proTxHash"))) {
"pro_tx_hash must be 32 bytes (64 hex characters)"
}
sdk.multipleChoiceProposals
.masternodeVote(proTxHash, inputs.getValue("proposalId").trim())
?.toString()
},
QueryDefinition(
name = "getMultipleChoiceProposalProcessingFee",
label = "Get Multiple Choice Proposal Processing Fee",
description = "What creating a multiple choice proposal adds to the processing fee, in credits.",
inputs = emptyList(),
runsInDiagnostics = false,
) { sdk, _ ->
"${sdk.multipleChoiceProposals.processingFee()} credits"
},
QueryDefinition(
name = "getMultipleChoiceProposalChoiceFundToJoin",
label = "Get Choice Fund to Join",
description = "The contest fund a choice entered now for a proposal pays, in credits.",
inputs = listOf(QueryInput("proposalId", "Proposal ID", required = true)),
runsInDiagnostics = false,
) { sdk, inputs ->
"${sdk.multipleChoiceProposals.choiceFundToJoin(inputs.getValue("proposalId").trim())} credits"
},

// ── Protocol & Version ────────────────────────────────────────────────
QueryDefinition(
name = "getProtocolVersionUpgradeState",
Expand Down Expand Up @@ -898,7 +996,10 @@ internal val QUERY_REGISTRY: List<QueryDefinition> = listOf(
},
)

/** A decision proposal listing page as text: its size, then one proposal per line. */
private fun List<DecisionProposal>.describeProposals(): String =
/**
* A decision proposal listing page (yes/no or multiple choice) as text: its size, then one
* proposal per line.
*/
private fun List<Any>.describeProposals(): String =
"$size proposal" + (if (size == 1) "" else "s") +
joinToString(separator = "\n", prefix = if (isEmpty()) "" else "\n")
Loading
Loading