Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Building the Voting Program

Pre-alpha. The devnet pre-alpha is a mock network with no MPC. Read the warning in the introduction first.

What You’ll Learn

  • How to define on-chain account layouts for councils, proposals and vote records
  • How to implement the CPI authority pattern for dWallet control — and bind each dWallet to its own governance
  • How quorum detection issues a signature voucher via CPI
  • How to prevent double voting using PDA-based vote records

Architecture

dWallet owner ──► CreateCouncil (members, quorum) ──► Council PDA ["council", dwallet]
                  ──► transfer ownership to CPI PDA

Member 1 ──► CastVote ──┐
Member 2 ──► CastVote ──┤
Member 3 ──► CastVote ──┼──► Quorum? ──► dwallet == proposal.dwallet? ──► issue_signature_voucher CPI ──► SignatureVoucher
                        │                                                                              │
                        └── VoteRecord PDAs (prevent double vote)                                      ▼
                                                                                              gRPC Sign request
                                                                                                       │
                                                                                                       ▼
                                                                                              64-byte signature

1. Account Layouts

Council PDA (["council", dwallet]) — 361 bytes

#![allow(unused)]
fn main() {
// Header
discriminator: u8,     // offset 0, always 3
version: u8,           // offset 1, always 1

// Fields
dwallet: [u8; 32],     // offset 2 — the dWallet this council governs
quorum: u32,           // offset 34 (LE)
member_count: u16,     // offset 38 (LE), 1..=10
bump: u8,              // offset 40 — canonical bump of this PDA
members: [[u8; 32]; 10], // offset 41 — first `member_count` entries valid
}

Proposal PDA (["proposal", proposal_id]) — 196 bytes

#![allow(unused)]
fn main() {
// Header
discriminator: u8,     // offset 0, always 1
version: u8,           // offset 1, always 1

// Fields
proposal_id: [u8; 32], // offset 2
dwallet: [u8; 32],     // offset 34 — the council's dWallet
message_digest: [u8; 32], // offset 66 — keccak256 of the message to sign
user_pubkey: [u8; 32], // offset 98 — key allowed to call gRPC Sign
signature_scheme: u16, // offset 130 (LE) — DWalletSignatureScheme, 5 = EdDSA/SHA-512
creator: [u8; 32],     // offset 132
yes_votes: u32,        // offset 164 (LE)
no_votes: u32,         // offset 168 (LE)
quorum: u32,           // offset 172 (LE) — copied from the council
status: u8,            // offset 176 — 0=Open, 1=Approved
signature_voucher_bump: u8, // offset 177
bump: u8,              // offset 178
_reserved: [u8; 16],   // offset 179
}

VoteRecord PDA (["vote", proposal_id, voter]) — 69 bytes

#![allow(unused)]
fn main() {
discriminator: u8,     // offset 0, always 2
version: u8,           // offset 1

voter: [u8; 32],       // offset 2
proposal_id: [u8; 32], // offset 34
vote: u8,              // offset 66 — 1=yes, 0=no
bump: u8,              // offset 67
}

2. CreateCouncil Instruction (disc = 2)

Signed by the dWallet’s current owner, before the ownership is transferred to the CPI PDA. The program reads the DWallet account (owner = dWallet program, discriminator 97, owner at offset 2) and requires the signer to be that owner; the council is created at the canonical ["council", dwallet] PDA, so there is exactly one per dWallet.

Data: [quorum(4), member_count(2), members(32 * member_count)]

Accounts:

#AccountFlagsDescription
0Council PDAwritableCreated via invoke_signed
1dWalletreadonlyThe dWallet account on the dWallet program
2dWallet ProgramreadonlyMust be the ika program (ID of the CPI crate), executable, and the dWallet account’s owner
3OwnersignerThe dWallet’s current owner
4Payerwritable, signerPays rent
5System ProgramreadonlyFor PDA creation

Rejects: quorum outside 1..=member_count, more than 10 members, duplicate members, a signer that is not the owner, a dWallet program account that is not the ika program, a dWallet account the ika program does not own, a council address other than the canonical PDA.

3. CreateProposal Instruction (disc = 0)

Data: [proposal_id(32), message_digest(32), user_pubkey(32), signature_scheme(2), signature_voucher_bump(1), bump(1)] = 100 bytes

Accounts:

#AccountFlagsDescription
0Proposal PDAwritableCreated via invoke_signed
1Council PDAreadonlyThe council of the dWallet
2dWalletreadonlyThe dWallet account on the dWallet program
3CreatorsignerMust be a council member
4Payerwritable, signerPays rent
5System ProgramreadonlyFor PDA creation

The council is verified (program-owned, council discriminator, dwallet field equals the passed dWallet, address equals ["council", dwallet, bump]) and the creator must be one of its members. The proposal’s quorum is the council’s.

4. CastVote Instruction (disc = 1)

Data: [proposal_id(32), vote(1), vote_record_bump(1), cpi_authority_bump(1)] = 35 bytes

Base accounts (always required):

#AccountFlags
0Proposal PDAwritable
1VoteRecord PDAwritable
2Council PDAreadonly
3Votersigner (must be a council member)
4Payerwritable, signer
5System Programreadonly

CPI accounts (when quorum will be reached):

#AccountFlags
6DWalletCoordinator PDAreadonly
7SignatureVoucher PDA (["signature_voucher", proposal_id], this program’s)writable
8dWalletreadonly — must be the proposal’s dWallet
9Voting Programreadonly
10CPI Authority PDAreadonly
11dWallet Programreadonly

5. The CPI Call

When yes_votes >= quorum, the program:

#![allow(unused)]
fn main() {
// The CPI authority PDA is shared by every dWallet this program controls:
// only the proposal's own dWallet may get a voucher.
if dwallet.address().as_array() != &proposal_dwallet {
    return Err(VotingError::DWalletMismatch.into());
}

let ctx = DWalletContext {
    dwallet_program,
    cpi_authority,
    caller_program,
    cpi_authority_bump,
};

// The voucher is this program's PDA for the proposal, so the program signs
// its creation with the PDA's seeds.
let voucher_bump_byte = [signature_voucher_bump];
let voucher_seeds = [
    Seed::from(b"signature_voucher" as &[u8]),
    Seed::from(proposal_id.as_ref()),
    Seed::from(voucher_bump_byte.as_ref()),
];

ctx.issue_signature_voucher(
    coordinator, signature_voucher, dwallet, payer, system_program,
    message_digest, [0u8; 32] /* no metadata */, signature_scheme,
    None /* owner: this program's CPI authority */,
    Some(user_pubkey) /* signing key */,
    Some(&voucher_seeds),
)?;

prop_data[PROP_STATUS] = STATUS_APPROVED;
}

The DWalletContext signs via invoke_signed with seeds ["__ika_cpi_authority", &[bump]], proving the voting program authorized this signing request. The dWallet program checks that the program controls the dWallet; the program itself checks that it is the right dWallet.

Source Code

FrameworkPath
Pinocchioexamples/voting/pinocchio/src/lib.rs
Nativeexamples/voting/native/src/lib.rs
Anchorexamples/voting/anchor/src/lib.rs (address = proposal.dwallet and council seeds constraints do the binding; the voucher account is unchecked, and the program signs for ["signature_voucher", proposal_id] with the stored bump, so the dWallet program refuses any other account in that slot as unsigned)