Fees & Billing
Fee vaults, schedules, billing templates, and protocol-level monetization
Fees
| Instruction | Description |
|---|---|
init_fee_vault | Create the protocol fee vault. |
deposit_fees | Top up the prepaid fee balance (real lamport transfer into the vault). |
withdraw_unused_fees | Return prepaid surplus to the owner (cannot touch accrued fees). |
set_fee_splits | Set the recipient split table (bps sum to 10000) and the low-balance mode. |
collect_fees | Sweep the accrued bucket — split-aware across recipients, or drain to one. |
update_fee_recipient | Change the protocol fee recipient. |
close_fee_vault | Close the fee vault (refused with outstanding accrued/debt). |
The effective fee is debited from the prepaid balance into the accrued bucket at finalize_execution (success
only — denied/expired proposals are free). When the prepaid balance is short, the low-balance mode decides:
Block refuses execution, Degrade records fee_debt_usd, and Warn skips accrual. The protocol floor is
included in fee computation whenever a fee is accrued.
Fee models & schedule
A per-treasury FeeScheduleAccount sidecar (kept off the treasury record for stack-frame headroom) defines
what is charged: a base rate, per-transaction-type overrides, volume tiers, min/max clamps, flat and
recurring (subscription / AUM) fees, and discounts (FHE subsidy, reputation, referral) — merged across the
protocol / integrator / owner layers. Absent a sidecar, the treasury's legacy ProtocolFees is used as a
single base tier.
| Instruction | Description |
|---|---|
init_fee_schedule | Create the sidecar and store a coherence-validated schedule (integrator layer bounded by ProtocolConfig). |
update_fee_schedule | Replace the schedule (re-validated and re-bounded). |
close_fee_schedule | Close the schedule sidecar. |
Billing templates & org profiles
A BillingTemplate mirrors policy templates for fee posture: author a schedule once (or fork a built-in
BillingProfileKind — Payroll, TradingDesk, DaoTreasury, GrantProgram, VendorPayments, ColdStorage,
Specialty) and apply it across treasuries within the protocol bounds. An org profile composes a policy
template and a billing template into one apply call.
| Instruction | Description |
|---|---|
create_billing_template | Author a billing template or fork a BillingProfileKind (validated). |
update_billing_template | Overwrite the schedule/metadata and bump the version. |
close_billing_template | Close a billing template and reclaim rent. |
apply_billing_template | Write a template's schedule onto a treasury's fee sidecar (shared templates allow foreign owners). |
apply_org_profile | Apply a policy template and a billing template to a treasury in one call, each through its own validation. |
Monetization control plane
The global ProtocolConfig singleton is the root of fee control: a protocol authority — distinct from any
treasury owner — sets a non-bypassable per-transaction fee floor and the bounds within which integrators
may charge. Fee computation reads the floor directly, so zeroing a treasury's own schedule cannot escape it.
Economic changes are staged and applied behind a timelock.
| Instruction | Description |
|---|---|
init_protocol_config | Bootstrap the ProtocolConfig singleton and set the protocol authority (callable once). |
update_protocol_config | Stage an economic change (fee floor, creation fee, integrator bounds, recipient, settlement asset) behind the update timelock. |
commit_protocol_config | Apply a staged change once its timelock has elapsed. |
Fee enforcement
The protocol floor is enforced at fee-computation time — zeroing a treasury's own fee schedule cannot reduce the computed rate below the floor.