Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Core concepts

Entities

A Goal and a Budget share the same shape — a Budget is just a sub-goal under a parent. The root Goal has some extra fields (reward pool, oracle), but the core structure is the same.

Shared fields

Every goal node (Goal or Budget) has:

  • goal: human-readable definition
  • successCondition: oracleable end condition
  • deadline: must resolve by this timestamp
  • activationThreshold: minimum treasury balance required before spending can begin
  • fundingDeadline: timestamp by which activationThreshold must be reached
  • treasury: holds funds; streams to children
  • childRegistry: registry of eligible children (Budget_TCR for Goals, Allocation_TCR for Budgets)
  • invariants: "must not do" constraints (enforceable)

Goal (root)

Additional fields on the root Goal:

  • rewardRate: fraction of inflows reserved to the reward pool (default: 20%)
  • oracle: default is UMA Optimistic Oracle

Funding rule: if the Goal does not reach activationThreshold by fundingDeadline, staked $COBUILD can automatically return to stakers.

Budget (sub-goal)

Additional fields on a Budget:

  • parent: the parent Goal
  • executionDuration: countdown starts at activation (activation threshold reached)
  • runwayCap: if treasury balance is ≥ runwayCap, upstream inflow pauses
    • note: this is a runway cap / throttle, not a lifetime spend cap
  • lifetimeSpendCap (optional): maximum cumulative spend if enforced

Accounting definitions (conceptual)

To keep routing and rewards consistent, define balances once:

  • treasuryBalance: total tokens held by a goal treasury
  • RewardEscrowBalance: reserved reward pool held at the Goal
  • streamableBalance: treasuryBalance - RewardEscrowBalance

Allocation Mechanism (inside a budget)

A mechanism is a concrete way to pay contributors.

Types (examples):
  • Flow: continuous streaming to recipients
  • Round: time-bounded grant round

Mechanisms are listed via the budget's Allocation_TCR.

Staking

You stake $COBUILD on a Goal. Your $COBUILD is locked at the Goal level until the Goal resolves — but within the Goal, you can freely move stake between budgets at any time. The more stake on a budget, the larger its share of the stream.

Staking has two dimensions:

  • Stake allocation — which budgets your stake is on, and how much. You can reallocate between budgets freely.
  • Weight — the portion of your allocated stake actively counted in the routing split. You can set this to 0 to stop routing without moving your stake.

Weight (routing only)

Your weight on a budget determines how much of the stream that budget receives.

  • weight updates stream allocations immediately
  • setting weight to 0 stops routing to that budget

Goal-level lock

Your $COBUILD is locked at the Goal level until Goal resolution. This is your skin in the game.

  • you can move stake between budgets freely within a Goal
  • you cannot withdraw $COBUILD from the Goal until it resolves
  • points accrue on stake allocated to a budget — you keep earning as long as stake is there

Child staking semantics (default)

Child staking is a sub-allocation of a user's parent stake:

  • Σ childStake_u ≤ parentStake_u
  • you may adjust child weights at any time, but cannot exceed your parent stake allocation

Stake lifecycle (one budget)

  1. Stake $COBUILD on a Goal — tokens are locked at the Goal level.
  2. Allocate stake to budgets — movable between budgets at any time.
  3. Adjust weight (0..allocated stake) to reroute streams.
  4. Goal resolves → $COBUILD withdrawable.
Stake Lifecycle
From staking on a Goal to withdrawal
1
Stake on Goal
$COBUILD locked at the Goal level
2
Allocate to budgets
Move stake between budgets freely — streams reroute with weight
3
Reallocate anytime
Unstake from one budget, restake on another — points accrue while allocated
4
Goal resolves
$COBUILD withdrawable

Points (stake-time)

Points are the time-weighted accumulator used for rewards.

Baseline definition:

  • points_u,i = ∫ stake_u,i(t) dt

Intuition:

  • early stakers earn more than late stakers
  • persistent stakers earn more than short-term stakers
  • you can move stake between budgets, but points only accrue while stake is allocated
  • points are frozen during dispute windows

Reward pool (global, single pool)

A fixed fraction of Goal inflows is diverted into a global reward escrow.

  • default: 20% of all Goal inflows
  • this escrow is not streamed to budgets
  • rewards are only paid out if the Goal succeeds

Oracle + disputes

Cobuild relies on an oracle / dispute mechanism for:

  • TCR listing disputes (accept/reject budgets or mechanisms)
  • Budget success resolution (success/failure)
  • Goal success resolution

Default: UMA Optimistic Oracle for optimistic assertions with a dispute window.