Governance and upgrades

Every governed change to Umbra's programs goes through one shared timelock: a change is proposed in public, waits a set delay, and only then can take effect. A few operator actions, which can only stop activity, take effect at once outside it. Above both sits the Solana program upgrade authority, which can replace a program's code outright.

How a governed change happensCopy Anchor Link

Each governed operation, such as approving a token or changing a fee, has its own authority: the one key that may propose it. A proposal is recorded on chain and waits that operation's delay, during which anyone can see it and the authority can cancel it. Once the delay has passed, anyone may execute it, and it applies exactly the change that was proposed. A proposal nobody executes within a day of opening expires.

The code requires every delay to be at least one slot, so no change can take effect in the transaction that proposes it. How long each delay actually is, is set at deployment. The timelock's rules are proven over a Lean model; see audits and verification.

What governance can changeCopy Anchor Link

• The shielded pool: which tokens can be deposited, the fee rates (capped at 500 basis points), the policy every transaction must meet, and where protocol fees are paid.
• The guardian node registry: activating and freezing guardian clusters. Each cluster also governs its own members and approved enclave code through a timelock of its own.
• The screener registry: registering, revoking and rotating the keys of the screener and the data endorser.
• The fee enclave program: which enclave code it accepts (its attestation policy), registering the enclave and handing its controller to a new key, activating, deactivating, freezing and unfreezing it, and closing its record.
• The attestation verifier: the AWS root of trust that enclave attestations must chain to.
• The zone registry: approving and revoking zones, the shape of the zone signer tree, and the cooldown between changes to a zone's signer. Each zone manages its own keys through a timelock of its own.
• The wUSDv program: resuming wraps after a pause, the yield cap and the deposit limit, its guardian, unfreezing it, and its token metadata.

Two programs, the P-384 signature verifier and the user registry, have no governance at all; only an upgrade changes them.

What governance cannot doCopy Anchor Link

No governed operation moves a note or pooled tokens, spends a note without a valid proof, or reads anything. Nor does any change which proofs the pool accepts: the keys the pool checks proofs against are compiled into the program, so only an upgrade changes them. Protocol fees go only to the payout account recorded for each token.

There is no switch that pauses the whole pool. Governance can freeze a guardian cluster or the fee enclave, revoke an attester, stop deposits of a token or revoke a zone, each after its delay, and none of these stops the escape hatch.

Actions outside the timelockCopy Anchor Link

A few keys can act at once, with no proposal and no delay. Each can only stop or slow activity; none can move funds.

• A guardian node's controller can restart its node or begin removing it from its cluster. Either takes the cluster out of service, halting value transactions and registrations until it recovers.
• The fee enclave's controller can restart or decommission the enclave, halting every value transaction until an enclave serves again.
• The wUSDv guardian can pause new wraps. Unwraps carry on, and only governance can resume wraps.
• Anyone can evict a guardian node whose enclave code its cluster no longer approves.

The program upgrade authorityCopy Anchor Link

Each program's Solana upgrade authority can replace its code in a single transaction, with no timelock and no warning. An upgrade can change any rule, including where pooled tokens go and which proofs the pool accepts. Who holds each upgrade authority is set at deployment and can be read on chain.

RelatedCopy Anchor Link