PrivateVoting

SIP Protocol API Reference / PrivateVoting

Class: PrivateVoting

Defined in: @sip-protocol/sdk/dist/index-BYZbDjal.d.ts:8419

Private voting implementation with encryption

Enables confidential voting where votes are encrypted during the voting period and can be revealed later with the appropriate decryption key.

Examples

const voting = new PrivateVoting()

// Committee derives a shared encryption key
const encryptionKey = deriveCommitteeKey(...)

const encryptedVote = voting.castVote({
  proposalId: 'proposal-123',
  choice: 1, // yes
  weight: 1000n,
  encryptionKey,
})

// Store encrypted vote on-chain or in database
await storeVote(encryptedVote)

// After voting period ends, reveal votes
const decryptionKey = unlockTimelockKey(...)

const revealed = voting.revealVote(
  encryptedVote,
  decryptionKey
)

console.log(`Vote for proposal ${revealed.proposalId}:`)
console.log(`  Choice: ${revealed.choice}`)
console.log(`  Weight: ${revealed.weight}`)

// Committee member reveals vote when authorized
const committeeKey = getCommitteeMemberKey(memberId)

try {
  const revealed = voting.revealVote(encryptedVote, committeeKey)
  // Process revealed vote
} catch (e) {
  console.error('Unauthorized revelation attempt')
}

Constructors

Constructor

new PrivateVoting(): PrivateVoting

Returns

PrivateVoting

Methods

castVote()

castVote(params): EncryptedVote

Defined in: @sip-protocol/sdk/dist/index-BYZbDjal.d.ts:8446

Cast an encrypted vote

Encrypts vote data using XChaCha20-Poly1305 authenticated encryption. The encryption key is typically derived from:

Timelock encryption (reveals after specific time)
Committee multisig key (reveals by committee decision)
Threshold scheme (reveals when threshold reached)

Parameters

params

CastVoteParams

Vote casting parameters

Returns

EncryptedVote

Encrypted vote that can be stored publicly

Throws

If parameters are invalid

Example

const voting = new PrivateVoting()

const encryptedVote = voting.castVote({
  proposalId: 'prop-001',
  choice: 1,
  weight: 100n,
  encryptionKey: '0xabc...',
})

revealVote()

revealVote(vote, decryptionKey): RevealedVote

Defined in: @sip-protocol/sdk/dist/index-BYZbDjal.d.ts:8472

Reveal an encrypted vote

Decrypts vote data using the provided decryption key. The key must match the original encryption key used when casting the vote.

Parameters

vote

EncryptedVote

Encrypted vote to reveal

decryptionKey

string

Key to decrypt the vote (must match encryption key)

Returns

RevealedVote

Revealed vote data

Throws

If decryption fails (wrong key or tampered data)

Throws

If vote data is invalid

Example

const voting = new PrivateVoting()

try {
  const revealed = voting.revealVote(encryptedVote, decryptionKey)
  console.log(`Choice: ${revealed.choice}, Weight: ${revealed.weight}`)
} catch (e) {
  console.error('Failed to reveal vote:', e.message)
}

tallyVotes()

tallyVotes(votes, decryptionKey): EncryptedTally

Defined in: @sip-protocol/sdk/dist/index-BYZbDjal.d.ts:8525

Tally votes homomorphically

Aggregates encrypted votes by summing Pedersen commitments for each choice. Individual votes remain hidden - only the final tally can be revealed.

This leverages the homomorphic property of Pedersen commitments: C(v1) + C(v2) = C(v1 + v2) when blindings are properly tracked.

Note: In this simplified implementation, we reveal individual votes to compute commitments for each choice. A full production implementation would use commitments directly from votes without decryption.

Parameters

votes

EncryptedVote[]

Array of encrypted votes to tally

decryptionKey

string

Key to decrypt votes (committee key)

Returns

EncryptedTally

Encrypted tally with aggregated commitments per choice

Throws

If votes array is empty or has inconsistent proposal IDs

Throws

If decryption fails

Example

const voting = new PrivateVoting()
const encryptionKey = generateRandomBytes(32)

// Cast multiple votes
const votes = [
  voting.castVote({ proposalId: 'p1', choice: 0, weight: 100n, encryptionKey }),
  voting.castVote({ proposalId: 'p1', choice: 1, weight: 200n, encryptionKey }),
  voting.castVote({ proposalId: 'p1', choice: 0, weight: 150n, encryptionKey }),
]

// Tally homomorphically
const tally = voting.tallyVotes(votes, encryptionKey)
// tally contains: choice 0 -> commitment(250), choice 1 -> commitment(200)

revealTally()

revealTally(tally, decryptionShares): TallyResult

Defined in: @sip-protocol/sdk/dist/index-BYZbDjal.d.ts:8559

Reveal the final tally using threshold decryption

In a full threshold cryptography implementation, t-of-n committee members would each provide a decryption share. When enough shares are collected, the tally can be revealed.

Note: This simplified implementation uses a single decryption key. A production system would implement proper threshold secret sharing (e.g., Shamir’s Secret Sharing) for committee-based decryption.

Parameters

tally

EncryptedTally

Encrypted tally to reveal

decryptionShares

DecryptionShare[]

Decryption shares from committee members

Returns

TallyResult

Final tally results with revealed vote counts per choice

Throws

If tally is invalid or insufficient shares provided

Throws

If threshold reconstruction fails

Example

const voting = new PrivateVoting()

// After tallying...
const shares = [
  { memberId: 'member1', share: '0xabc...' },
  { memberId: 'member2', share: '0xdef...' },
  { memberId: 'member3', share: '0x123...' },
]

const results = voting.revealTally(encryptedTally, shares)
console.log(results.results) // { "0": 250n, "1": 200n }