Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion cloud/guardian/policy.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -507,7 +507,7 @@ function decodeFields(ev) {
case "vault:change_executed":
return { kind: "change_executed", id: u64(f[0]), changeKind: f[1]?.[0] };
// A stop, a guardian ejected, a restore and a restore approval
// (programs/floor/src/lib.rs, `ev::ABORTED` and the others). These went
// (programs/floor/src/lib.rs `ev`, emitted from the handlers in programs/floor/src/). These went
// to "other" and were dropped: a stop was noticed only by the minute's
// config check (45 s late on a validator), and one a quorum undid within
// the minute, an ejection or a restore approval never at all (docs/09,
Expand Down
6 changes: 3 additions & 3 deletions cloud/test/sim.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -305,9 +305,9 @@ const data = (name, ...fields) => `Program data: ${[b64(Buffer.from(name)), ...f
const inFloor = (...lines) => [`Program ${FLOOR} invoke [1]`, ...lines, `Program ${FLOOR} success`];

test("Floor's stop, ejection, restore and approval are decoded from their real layouts, for watched programs only (finding 76, 7)", () => {
// programs/floor/src/lib.rs: ABORTED [program, who, snapshot_valid u8, t i64],
// EJECTED [program, removed], RESTORED [program, signers u8],
// APPROVED [program, pending_id u64, approvals u8].
// programs/floor/src/: ABORTED [program, who, snapshot_valid u8, t i64] and
// RESTORED [program, signers u8] in stop.rs, EJECTED [program, removed] in
// guardians.rs, APPROVED [program, pending_id u64, approvals u8] in proposals.rs.
const logs = inFloor(
data("floor:aborted", key(WATCHED), key(OWNER), Uint8Array.of(1), i64le(1_700_000_000)),
data("floor:ejected", key(WATCHED), key(OTHER)),
Expand Down
8 changes: 4 additions & 4 deletions docs/06-FLOOR.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ text (vaddr 2^32): mov64 r1, 0 ; mov64 r2, len ; syscall sol_log_ ; mov64 r0, 0x

## 6. Instructions

Account lists and data layouts are documented above each handler in `programs/floor/src/lib.rs`.
Account lists and data layouts are documented above each handler in `programs/floor/src/`: `register.rs`, `stop.rs` (stage, pin, abort, restore, close a buffer), `proposals.rs` (propose, veto, approve, execute, cancel) and `guardians.rs` (heartbeat, eject, replace the recovery key); the instruction and event ids are in `lib.rs`.

| # | Instruction | Signer | Effect |
|---|---|---|---|
Expand All @@ -106,12 +106,12 @@ Account lists and data layouts are documented above each handler in `programs/fl

## 7. Measured

Real agave loader, LiteSVM with the mainnet feature set (`programs/tests/tests/floor.rs`), measured 8 Oct 2026 on a macOS (arm64) build of this tree:
Real agave loader, LiteSVM with the mainnet feature set (`programs/tests/tests/floor.rs`), measured 14 Oct 2026 on a macOS (arm64) build of this tree:

| Operation | Compute units |
|---|---|
| Stop a ~200 KB program, including byte-for-byte snapshot verification | 10,312 |
| Restore the ~200 KB snapshot (guardian quorum) | 8,149 |
| Stop a ~200 KB program, including byte-for-byte snapshot verification | 10,461 |
| Restore the ~200 KB snapshot (guardian quorum) | 8,225 |

A snapshot buffer costs rent for a copy of the program (about 5,080 lamports per byte at current rent, the same on mainnet and devnet on 28 Sep 2026; about 1.04 SOL for 200 KB). The rent is returned when a restore consumes the buffer. A pin that is replaced or cleared by an upgrade, and a proposal's buffer after a cancel or a stop, return theirs through `close_buffer` (the owner), and a release closes the abort buffer and the pin. That is the price of a one-instruction, trustless undo.

Expand Down
2 changes: 1 addition & 1 deletion docs/07-INTEGRATION.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 07 — Integration guide (and Harbor, the reference integration)

Exact account lists and data layouts are documented above each handler in `programs/floor/src/lib.rs` and `programs/vault/src/*.rs`. Working instruction builders (Rust) are in `programs/tests/tests/common/`, and the zero-dependency JavaScript client is in `cloud/lib/`.
Exact account lists and data layouts are documented above each handler in `programs/floor/src/*.rs` and `programs/vault/src/*.rs`. Working instruction builders (Rust) are in `programs/tests/tests/common/`, and the zero-dependency JavaScript client is in `cloud/lib/`.

## 1. Floor (Tier 0): one instruction, zero code changes

Expand Down
159 changes: 159 additions & 0 deletions programs/floor/src/guardians.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
//! Guardians: who is a live guardian, which guardians signed, the guardian-set
//! payload, and the instructions that act on the set (heartbeat, eject, and
//! the owner replacing the recovery key with a live quorum).

use crate::*;

/// Index of a signing, live guardian.
pub(crate) fn live_guardian(
c: &Config,
a: &AccountView,
now_s: i64,
) -> Result<usize, ProgramError> {
require_signer(a)?;
let i = c
.guardian_index(&key(a))
.ok_or(FloorError::NotLiveGuardian)?;
if c.alive_mask(now_s) & (1 << i) == 0 {
return Err(FloorError::NotLiveGuardian.into());
}
Ok(i)
}

/// Bitmap of guardians among `signers`. Each must sign and be a current
/// guardian; bits are only ever set for occupied slots.
pub(crate) fn guardian_signers(c: &Config, signers: &[AccountView]) -> Result<u8, ProgramError> {
let pairs = signers.iter().map(|s| (key(s), s.is_signer()));
signer_bits(&c.guardians, c.guardian_count, pairs).map_err(|e| {
match e {
SignerError::NotSigner => FloorError::MissingSignature,
SignerError::NotGuardian => FloorError::NotLiveGuardian,
}
.into()
})
}

/// Parses `[count u8][count × 32][threshold u8][interval i64]` with the
/// core's `GuardianSet::parse` (the Vault parses with the same function), and
/// returns the set and the number of argument bytes it used.
pub(crate) fn parse_guardian_set(
args: &[u8],
owner: &[u8; 32],
recovery: &[u8; 32],
) -> Result<(GuardianSet, usize), ProgramError> {
GuardianSet::parse(args, [owner, recovery]).map_err(|e| {
match e {
GuardianSetError::Truncated => FloorError::InvalidInstruction,
GuardianSetError::BadCount | GuardianSetError::BadKey => FloorError::InvalidGuardians,
GuardianSetError::BadThreshold => FloorError::InvalidThreshold,
GuardianSetError::BadInterval => FloorError::InvalidInterval,
}
.into()
})
}

// ---------------------------------------------------------------------------
// 9. Heartbeat Accounts: 0 config [w], 1 guardian [s].
// ---------------------------------------------------------------------------
// A dead guardian cannot revive itself; only a new guardian set (a delayed,
// vetoable proposal) brings it back.
pub(crate) fn heartbeat(program_id: &Address, accounts: &mut [AccountView]) -> ProgramResult {
let mut c = load_config(program_id, acc(accounts, 0)?)?;
let t = now()?;
let i = live_guardian(&c, acc(accounts, 1)?, t)?;
c.last_heartbeat[i] = t;
save_config(&mut accounts[0], &c)?;
sys::event(&[ev::HEARTBEAT, &c.program, &[i as u8], &t.to_le_bytes()]);
Ok(())
}

// ---------------------------------------------------------------------------
// 10. Eject a guardian (live quorum of the others, instant)
// ---------------------------------------------------------------------------
// Accounts: 0 config [w], 1.. guardians [s]. Data: target index u8.
pub(crate) fn eject(
program_id: &Address,
accounts: &mut [AccountView],
args: &[u8],
) -> ProgramResult {
let mut c = load_config(program_id, acc(accounts, 0)?)?;
let target = *args.first().ok_or(FloorError::InvalidInstruction)?;
let t = now()?;
let approvals = guardian_signers(&c, accounts.get(1..).unwrap_or(&[]))?;
if !can_eject(
approvals,
c.alive_mask(t),
c.threshold,
target,
c.guardian_count,
) {
return Err(FloorError::CannotEject.into());
}
let (i, n) = (target as usize, c.guardian_count as usize);
let removed = c.guardians[i];
for j in i..n - 1 {
c.guardians[j] = c.guardians[j + 1];
c.last_heartbeat[j] = c.last_heartbeat[j + 1];
}
c.guardians[n - 1] = [0; 32];
c.last_heartbeat[n - 1] = 0;
c.guardian_count -= 1;
c.pending_approvals = 0; // indices shifted; approvals must be given again

// A pending guardian set was written before this ejection and may still
// name the ejected key: withdraw it, so it cannot bring that key back.
// The owner may propose again; it waits again.
if c.pending_kind == kind::SET_GUARDIANS {
c.clear_pending();
}
save_config(&mut accounts[0], &c)?;
sys::event(&[ev::EJECTED, &c.program, &removed]);
Ok(())
}

// ---------------------------------------------------------------------------
// 12. Replace the recovery key (the owner with a live guardian quorum, at once)
// ---------------------------------------------------------------------------
// Accounts: 0 config [w], 1 owner [s], 2.. guardians [s] forming a live quorum.
// Data: the new recovery key[32] (all zero: none).
//
// A stolen recovery key can only propose, but it can do that forever: each
// proposal takes the slot from the owner's, and nothing else could replace
// it. The owner and a live quorum together can, at once (a delayed proposal
// would sit in the slot the stolen key takes). Together they already decide
// more than this (a guardian's stop and a quorum-approved restore install
// code at once); neither can alone.
pub(crate) fn replace_recovery(
program_id: &Address,
accounts: &mut [AccountView],
args: &[u8],
) -> ProgramResult {
let mut c = load_config(program_id, acc(accounts, 0)?)?;
let owner = acc(accounts, 1)?;
require_signer(owner)?;
if key(owner) != c.owner {
return Err(FloorError::NotOwner.into());
}
let recovery = k32_arg(args, 0)?;
if recovery == c.owner || c.guardian_index(&recovery).is_some() {
return Err(FloorError::InvalidInstruction.into());
}
let alive = c.alive_mask(now()?);
let signers = guardian_signers(&c, accounts.get(2..).unwrap_or(&[]))?;
if !quorum(signers & alive, alive, c.threshold) {
return Err(FloorError::NoQuorum.into());
}
c.recovery = recovery;
// What the replaced key proposed, or a pending new recovery key, is void.
if c.pending_by_recovery == 1 || c.pending_kind == kind::SET_RECOVERY {
c.clear_pending();
}
save_config(&mut accounts[0], &c)?;
sys::event(&[
ev::RECOVERY_REPLACED,
&c.program,
&recovery,
&[signers & alive],
]);
Ok(())
}
Loading