Skip to main content

​
Overview

All workflows must pass through a voting process before they can be executed. Voters review pending workflow proposals and decide whether to approve or deny them based on merit, feasibility, and budget considerations.

​
Voting Lifecycle

​
Voter Eligibility

Not all users can vote. Voter eligibility rules:

Must Have Voter Role

Only users with the isVoter flag set by admins can participate in voting.

Cannot Vote Own Proposals

Voters who are also the proposer of a workflow are excluded from voting on that specific workflow to prevent conflicts of interest.

​
Eligible Voter Count

For each workflow, the system calculates: 
interface WorkflowVotes {
  total_voters: number      // All voters minus proposer
  votes_cast: number        // How many have voted
  approve: number           // Approve vote count
  deny: number              // Deny vote count
  quorum_reached: boolean   // votes_cast >= 50% of total_voters
  quorum_threshold: number  // Calculated as total_voters / 2
}
From /home/daytona/workspace/source/frontend/types/workflow.ts:85-97

​
Quorum Requirements

Quorum is the minimum participation threshold for a vote to proceed:
1

Calculate Quorum

Quorum = 50% of total_voters (eligible voters for this workflow)
2

Track Participation

As voters cast ballots, votes_cast increments
3

Reach Quorum

When votes_cast >= quorum_threshold, quorum is reached
4

Start Countdown

A 24-hour countdown timer starts at quorum_reached_at timestamp
Quorum encourages broad participation. Workflows cannot be finalized without sufficient voter engagement.

​
Quorum Example

Scenario: 10 eligible voters
  • Quorum threshold: 5 voters (50%)
  • Votes cast: 3 approve, 1 deny = 4 total
  • Quorum reached? No (4 < 5)
  • Action: Workflow remains in pending, awaiting more votes
After one more vote:
  • Votes cast: 3 approve, 2 deny = 5 total
  • Quorum reached? Yes (5 >= 5)
  • Action: 24-hour countdown begins at quorum_reached_at

​
24-Hour Countdown

Once quorum is reached, a countdown timer provides a window for additional voting:
The 24-hour countdown allows voters who haven’t participated yet to review the workflow and cast their votes. This prevents hasty decisions and ensures all interested voters have an opportunity to participate.
  • quorum_reached_at: Unix timestamp when quorum was achieved
  • finalize_at: quorum_reached_at + 86400 (24 hours later)
  • finalized_at: Unix timestamp when vote was actually finalized
  • Workflow status remains pending
  • Additional voters can still cast ballots
  • Vote tallies update in real-time
  • Early finalization may occur if conditions are met
  • Workflow is evaluated on next vote endpoint call (lazy finalization)
  • Status changes to approved or rejected based on majority
  • finalized_at timestamp is recorded
  • Email notifications are sent to proposer and relevant parties
Vote finalization is currently lazy — it happens when the vote endpoint is called after the countdown expires. Scheduled background finalization is planned for a future update.

​
Early Finalization

Votes can be finalized before the 24-hour countdown if a supermajority is reached:

​
Early Finalization Conditions

Early finalization occurs when: 
// More than 50% of the FULL voter body (not just quorum) agrees
if (approve_votes > total_voters / 2) {
  // Early approve
} else if (deny_votes > total_voters / 2) {
  // Early deny
}

​
Early Finalization Example

Scenario: 10 eligible voters
  • Quorum threshold: 5 voters
  • Early finalization threshold: 6 voters with same decision (>50% of 10)
Case 1: Early Approve
  • Votes cast: 6 approve, 0 deny
  • Result: Workflow approved immediately (6 > 5, unanimous so far)
  • Countdown is bypassed
Case 2: Countdown Required
  • Votes cast: 4 approve, 2 deny = 6 total
  • Result: Quorum reached, but no supermajority
  • 24-hour countdown proceeds
Early finalization accelerates uncontroversial workflows while ensuring contentious proposals get full deliberation.

​
Vote Outcomes

​
Approved

A workflow is approved when:
  1. Quorum was reached
  2. 24-hour countdown elapsed (or early finalization threshold met)
  3. approve_votes > deny_votes (simple majority)
Approved workflows:
  • Status changes to approved
  • vote_decision set to "approve"
  • Workflow proceeds to execution phase
  • Proposer receives approval notification email

​
Rejected

A workflow is rejected when:
  1. Quorum was reached
  2. 24-hour countdown elapsed (or early finalization threshold met)
  3. deny_votes >= approve_votes (ties go to rejection)
Rejected workflows:
  • Status changes to rejected
  • vote_decision set to "deny"
  • Workflow cannot be executed
  • Proposer receives rejection notification email

​
Expired

A workflow expires when:
  • Status is pending for more than 14 days
  • Quorum was never reached or vote never finalized
Expired workflows:
  • Status changes to expired
  • No further voting allowed
  • Proposer can create a new workflow proposal if desired
Expired workflows indicate insufficient voter engagement. Consider revising the proposal or addressing concerns before resubmitting.

​
Admin Force Approve

Admins can bypass the voting process entirely: 
POST /admin/workflows/:workflow_id/force-approve
From /home/daytona/workspace/source/backend/handlers/app_workflow.go:2720-2780

​
Force Approve Behavior

  • Emergency workflows requiring immediate execution
  • Workflows with unanimous informal agreement
  • Administrative or maintenance workflows
  • Situations where the voting process would cause unacceptable delay
  • User must have admin role
  • Workflow must be in pending status
  • Faucet must have sufficient balance (same check as normal approval)
  • Status immediately changes to approved
  • vote_decision set to "admin_approve" (distinct from normal "approve")
  • vote_finalized_by_user_id records which admin approved
  • Approval email sent to proposer
The "admin_approve" decision value in the database distinguishes admin-approved workflows from voter-approved workflows for transparency and accountability.
Admin force approval should be used judiciously. It bypasses the community governance process.

​
Budget Constraints

Vote approval (whether by voters or admin) is blocked if the faucet cannot fund the workflow:

​
Faucet Balance Check

From /home/daytona/workspace/source/backend/handlers/app_workflow.go:3456-3471: 
// Approval blocked if unallocated balance < one week of workflow requirement
unallocatedTokens >= workflow.WeeklyBountyRequirement

Sufficient Balance

Workflow approval can proceed. Budget is allocated to the workflow upon approval.

Insufficient Balance

Approval is blocked even if vote passes. Status remains pending. Email notification sent about funding shortfall.
This check ensures approved workflows can actually be paid out, preventing approval of unfunded commitments.

​
Casting a Vote

Voters cast ballots through the voter interface: 
POST /voter/workflows/:workflow_id/vote

{
  "decision": "approve",  // or "deny"
  "comment": "Optional explanation for vote"
}
From /home/daytona/workspace/source/backend/handlers/app_workflow.go:2640-2718

​
Vote Properties

  • decision: "approve" or "deny" (required)
  • comment: Optional text explanation for the vote
  • my_decision: Returned in response, shows how current user voted
  • Immutable: Once cast, votes cannot be changed
Votes are permanent and cannot be edited. Review the workflow carefully before submitting your decision.

​
Deletion Proposals

Workflows can also be proposed for deletion through a similar voting process:

​
Deletion Vote Characteristics

  • Same quorum requirements (50% participation)
  • Same 24-hour countdown after quorum
  • Same early finalization rules
  • Admin can force approve deletions
  • Deletion targets can be a single workflow or an entire series
From /home/daytona/workspace/source/backend/handlers/app_workflow.go:2959-2977
Deletion proposals are particularly important for stopping problematic recurring workflows before they create additional instances.

​
Viewing Pending Votes

Voters access pending workflows at /voter: 
GET /voter/workflows
The response includes:
  • All workflows in pending status
  • Current vote tallies
  • Quorum progress
  • User’s own vote if already cast

​
Vote State Evaluation

The system evaluates vote state on every relevant API call:
  1. GetVoterWorkflows: Checks all pending workflows, finalizes any past countdown
  2. VoteWorkflow: Evaluates immediately after vote is cast
  3. GetProposerWorkflow: Proposers see updated vote status
This lazy evaluation pattern means votes are finalized “just in time” rather than on a strict schedule.
Future enhancement: Background job to finalize votes at exact countdown expiration rather than waiting for next API call.

​
Voting Best Practices

  • Read the full workflow description
  • Review all steps and bounties
  • Check credential requirements
  • Consider budget impact
  • Evaluate feasibility
Provide context for your vote, especially if denying:
  • “Budget too high for current allocation”
  • “Needs more specific deliverables in step 2”
  • “Excellent proposal, addresses community need”
Workflows stuck in voting delay community projects. Review pending workflows regularly and vote in a timely manner.
Recurring workflows have ongoing budget impact. A weekly workflow consumes 52x its bounty annually.

​
See Also

Workflows

Understand workflow structure and lifecycle

Roles

Learn about the voter role

Credentials

How credentials affect workflow access

Build docs developers (and LLMs) love

Get started for freeTalk to us