A governance pool API coordinates scarce decision rights or allocatable value across voters, members, judges, donors, projects, or automated agents. The pool may contain votes, reputation points, award credits, matching funds, donation budgets, or proposal capacity. These units look similar in a dashboard, but they carry different meanings. A vote expresses a decision. A point may measure participation. An award may be discretionary recognition. A donation allocation may move real money.
The first design rule is to keep these ledgers separate. Combining them into one “score” creates ambiguous rights and makes manipulation difficult to detect. The second rule is to snapshot eligibility and rules before a decision opens. The third is to preserve an audit trail without exposing private ballots or sensitive donor data.
Define the governance unit and its authority
Separate influence from value
For each pool, state what the unit can do, who issues it, whether it expires, whether it can be delegated, and whether it is transferable. One person may have one ballot but many nonvoting contribution points. Award credits may be issued to judges and spent on nominees. Donation credits may represent an instruction to distribute a sponsor’s budget, not a withdrawable balance.
Use distinct unit identifiers and account types. Never let a client send a free-form unit name and assume the server understands its legal or governance effect. The API should resolve a policy version that defines issuance, eligibility, weighting, caps, and settlement. Display labels can change; the underlying unit and rule identifiers should remain stable.
Choose an identity and eligibility model
Eligibility can be based on membership, verified identity, account age, contribution, token ownership, geography, employment, donor status, or an external registry. Each basis has privacy and fairness implications. The API should store the evidence reference and decision, not more personal data than necessary. Some programs need one-person-one-vote assurance; others intentionally weight organizations or contributions.
NIST’s current Digital Identity Guidelines describe identity proofing, authentication, and federation concepts that can inform assurance decisions, though a community or private program should tailor controls to its own risk rather than claiming federal compliance. Record the assurance method and date used for eligibility, and allow appeals or corrections through a governed process.
Snapshot the electorate and rules
Freeze eligibility reproducibly
When a ballot or allocation round opens, create an immutable snapshot of eligible accounts, weights, proposal set, unit balances, start and end times, tally method, quorum, tie rule, and disclosure policy. Without a snapshot, membership or point changes during the round can alter outcomes unpredictably. Later corrections should be explicit amendments with authority and a public or auditable reason.
Use a snapshot identifier in every ballot. A voter request should not depend on the current profile alone. If the account was eligible in the snapshot and later changes status, the policy defines whether the ballot remains valid. If a proposal is withdrawn, preserve its identifier and state rather than deleting it from history.
Separate ballot issuance from casting
Ballot issuance confirms that an eligible account has the right units for a round. Casting consumes or locks those rights according to the method. In a simple election, a ballot may be replaceable until close, with only the final version counted. In cumulative voting, units can be distributed across choices. In ranked choice, the ballot stores an ordered list rather than subtracting a balance per candidate.
Make idempotency and replacement rules explicit. Retrying the same cast request should not create another vote. A new request with an expected ballot version can replace the prior ballot when policy allows. The server returns a receipt identifier and status without necessarily revealing the private selection in ordinary logs.
Design ballot privacy deliberately
Some decisions are public and attributable. Others require secret ballots. Do not promise anonymity if administrators can trivially join voter identity and ballot rows. Separate eligibility records from encrypted ballot content, restrict join capability, and consider cryptographic or third-party techniques when strong secrecy is required. Explain what metadata remains visible, such as participation time or round membership.
Audit does not require publishing private selections. The system can prove that eligible ballots were included, duplicates were excluded, and the tally used the declared rules through controlled evidence and independent review. Retention should reflect the program’s obligations. Delete unnecessary authentication events while preserving the minimum record needed to verify the outcome.
Keep point issuance append-only
Points and awards need an immutable ledger with grant, earn, spend, expire, revoke, and adjustment entries. Each entry names the issuing authority, reason, evidence reference, policy version, and idempotency key. Corrections are compensating entries. A public leaderboard may use an aggregate, but the underlying ledger remains the source of truth.
Prevent circular issuance. A user should not create an activity that grants points and approve the same grant unless the program explicitly permits self-attestation. Apply caps, review thresholds, and anomaly detection. Separate reputation that affects governance from redeemable rewards; otherwise purchasing or trading a reward can silently purchase influence.
Model donation allocations as budget instructions
A donation allocation pool may give participants credits to direct a sponsor’s budget among approved recipients. The credits are not necessarily cash held for the participant. The API should distinguish pledged budget, allocated amount, approved distribution, payment submitted, and payment settled. Recipient eligibility and payment details belong in a controlled registry.
Apply caps, matching formulas, geographic or cause restrictions, and conflict-of-interest rules through versioned policy. A matching round may need anti-sybil controls because splitting one contribution across many identities can distort the match. Preserve raw contribution and allocation evidence for review, while limiting public disclosure of personal donor information.
Use multi-step approvals for consequential actions
Publishing a tally, issuing a large award, changing eligibility, or releasing donation funds may require more than one role. Represent approval requests with required approver classes, threshold, deadline, and conflict rules. An approver signs a decision against an immutable payload hash. If the payload changes, prior approvals no longer apply.
Emergency actions such as pausing a round should be narrow, time-bounded, and auditable. A pause stops new ballots without editing existing ones. Cancellation preserves the round and reason. Reopening after close should require a new policy decision rather than a hidden timestamp edit.
A governance pool surface
GET /governance-pools
POST /rounds
POST /rounds/{id}/snapshots
GET /rounds/{id}/eligibility/{account_id}
POST /ballots
PUT /ballots/{id}
POST /rounds/{id}/close
POST /rounds/{id}/tallies
GET /point-accounts/{id}/entries
POST /allocation-approvalsUse expected versions on mutable operations. The close operation should be idempotent and produce an immutable close record. Tally generation references the snapshot, ballot set, method version, and software build. If a recount occurs, it creates another tally record rather than replacing the first.
Plan for coercion, sybil attacks, and collusion
Threats depend on stakes. Low-value community badges need different controls from public grants or corporate elections. Common risks include multiple accounts, credential sharing, vote buying, coordinated point farming, compromised administrators, recipient fraud, and denial of service near a deadline. Build a threat model before choosing controls.
Rate limits and authentication are necessary but not sufficient. Use eligibility evidence, account linking signals where lawful, manual review, independent observers, and post-round anomaly analysis. Avoid opaque fraud scores that cannot be appealed. A flagged account may be held for review without automatically disclosing the detection method.
Publish rules before outcomes
Participants should be able to read the round rules, eligible options, weighting, deadlines, quorum, privacy model, tally method, appeal process, and distribution timeline before acting. The API can expose a signed or hashed policy document linked from the round. Changes after opening should be rare, versioned, and clearly announced.
After close, publish the appropriate level of evidence: totals, turnout, invalid ballot counts, allocation summary, approval record, and audit statement. Do not publish private identities merely in the name of transparency. Transparency means the process can be understood and reviewed, not that every datum is public.
Governance APIs encode legitimacy
A governance pool is not just a counter with a voting endpoint. It encodes who has authority, when that authority is measured, how it is exercised, and how outcomes become allocations or payments. Keep votes, points, awards, and donation budgets separate. Snapshot rules, preserve immutable ledgers, protect privacy, and require approvals for consequential changes.
Use the Pool Types directory to compare resource models and the credit ledger guide for reservation and accounting patterns.
