Skip to content

C1: Cookie feature switches (Stage 1.0) - #1

Merged
sense112 merged 6 commits into
cookie/4.1.2from
cookie/c1-feature-switches
Nov 10, 2026
Merged

sense112 merged 6 commits into
cookie/4.1.2from
cookie/c1-feature-switches

Conversation

@n4pless

@n4pless n4pless commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

What this does

Lets the Cookie Squads multisig switch on Solana features on Cookie Chain without anyone holding a feature's private key, while every tool keeps behaving exactly as on Solana. This is Stage 1.0, step 2 of the Phase 1 plan, and the only change in release 4.1.2-cookie.1.

How

Shared alias table (feature-set/src/cookie.rs)

  • Every upstream feature F gets an alias address: the PDA ["cookie-alias", F] of the cookie-feature-gate program.
  • Denylist (no alias, can never be activated this way): the 4.1 Alpenglow placeholder and three features abandoned upstream (enable_loader_v4, enable_extend_program_checked, stake_minimum_delegation_for_rewards).
  • One definition, shared by the runtime and all tools. Upstream feature IDs are untouched.

Runtime (runtime/src/cookie/feature_alias.rs)

  • At each epoch boundary the bank reads F's own address first. If it holds a feature account, that is used (stock behaviour). Otherwise the alias is used, and it only counts if it is a valid feature account.
  • A plain account at F (anyone can send lamports to any address) does not block the alias. If neither is a feature account, whatever is at F is returned, as on stock Agave.

Tools behave as on Solana (new rule 2a in COOKIE-RULES.md)

  • solana feature status and feature activate, plus every CLI command that auto-detects features (vote, stake, cluster): an extension trait CookieFeatureAccounts on RpcClient. Call sites only swap the method name (get_account to get_feature_account, etc.). Same rule as the runtime: a plain account at F does not hide the alias.
  • solana-test-validator --clone-feature-set copies alias activations.
  • agave-ledger-tool create-snapshot --deactivate-feature-gate works for alias-activated features (emergency restarts).

Upstream files touched: three one-line hooks in runtime/src/bank.rs; module lines in runtime/src/lib.rs, cli/src/lib.rs, feature-set/src/lib.rs, test-validator/src/lib.rs; method-name swaps plus one import in cli/src/feature.rs and cli/src/vote.rs; one added call in test-validator/src/lib.rs; two lines in ledger-tool/src/main.rs; curve25519 feature in feature-set/Cargo.toml. Full list with reasons in COOKIE-TOUCHPOINTS.md.

Program (programs/cookie-feature-gate, ID CookmMGfe9ti8mrVkCFuZZsuAvjMSRagqh4t8Yxx4Ub4)

  • Initialize (program upgrade authority, once), Activate, Revoke, and a two-step authority handover: SetAuthority names a pending authority, which signs AcceptAuthority to take over.
  • Activate refuses the four denylisted ids. The program keeps its own copy of the list (src/denylist.rs); a test in feature-set fails if it differs from DENYLIST.
  • Standalone crate with its own [workspace]. Build with cargo-build-sbf (Agave 4.1.2 tools). SHA-256 of the reviewed build: 2a859550f70d466ae92c57a81f252c691a1be5fdbb694a7d02178221d0fbd0d1.

Safety

  • With no alias accounts on chain the release behaves exactly like stock 4.1.2. The feature set ID is unchanged (c763ae0a), so old and new validators agree during the rolling upgrade.
  • Only cookie-feature-gate can sign for its PDAs, so only it can create an alias. Lamports sent to an alias address are ignored by the runtime and handled by the program.
  • Lamports sent to an upstream feature address do not block its alias. On 20 October 2026 none of the 39 inactive feature addresses on Cookie Chain held any account.
  • Known differences from Solana are listed in COOKIE-TOUCHPOINTS.md: only the unused Rust RpcClient::get_feature_activation_slot, and genesis/local-cluster tooling.

Changes after review

  • e144561 (review of 10 Nov 2026, restart safety): an activated alias now beats a pending account at the upstream address. Before, someone holding a feature's own key could create a pending account there after an alias activation; running validators kept the feature on, but a validator restarting from a snapshot rebuilt it as off. One ranking (FeatureRecord: activated > pending > no feature account, upstream wins ties) is used by the runtime and the CLI helpers. New test: alias activation, then a pending upstream account, then a real snapshot save and restore; the feature stays active at its original slot. It failed before the fix.
  • 670ee7a (review of 10 Nov 2026):
    • solana program deploy/upgrade/write-buffer/extend now see switch activations: fetch_feature_set in cli/src/program.rs used the canonical ids only. One import and one method swap.
    • solana feature revoke no longer calls a pending alias "not submitted". It explains that only cookie-feature-gate can sign for the alias, so a switch request is withdrawn with a Revoke from the multisig. One added line in process_revoke; the logic is unit-tested.
    • The switch refuses denylisted ids, so a mistaken request cannot sit pending and switch on by itself if a later release drops one from the list.
    • The authority handover is two steps, so one bad proposal cannot hand the switch to an address nobody controls. Requiring both signatures in one transaction would not work between vaults of different multisigs. The config is now 66 bytes (version 2); version 1 was never deployed.
  • 0e17887886: a plain account at an upstream feature address no longer blocks its alias (runtime, shared client helpers, CLI single-account lookup). Tests added at every level. No new upstream touch points.

Tests

  • cargo test -p agave-feature-set --features agave-unstable-api --lib -- cookie: 3 tests.
  • cargo test -p solana-runtime --lib -- cookie::: 10 tests, including a restart from a real snapshot, including full activation across an epoch boundary, and activation with lamports already at the upstream address. Upstream runtime feature tests (32) still pass.
  • cd programs/cookie-feature-gate && cargo test: 9 unit tests.
  • cargo test -p agave-feature-set --features agave-unstable-api --lib -- cookie: includes the denylist drift test, checked to fail when an id differs.
  • cargo test -p solana-cli --lib: 40 tests, 4 of them for the revoke check.
  • programs/cookie-feature-gate/tests/e2e/run-e2e.sh cookie|stock: local test validator, 31 program and runtime checks (a denylisted activation refused; the two-step handover with a wrong signer, a missing signature and a repeat accept refused), including misuse attempts and lamports sent to both an alias address and an upstream feature address. In cookie mode both features activate at the epoch boundary, the Cookie CLI reports them as active, and --clone-feature-set copies them. On stock Agave the aliases are ignored. Both pass. Against the previous binaries the new upstream-address checks fail, as expected.
  • programs/cookie-feature-gate/tests/e2e/ledger-tool-check.sh: emergency deactivation of an alias-activated feature passes. Stock ledger-tool fails with "Feature-gate account does not exist".
  • cargo clippy ... -- -D warnings clean on all touched crates. Formatted with nightly rustfmt per rustfmt.toml.

Please check

  1. Any other consensus or tool paths that read feature accounts directly? I found the ones listed above.
  2. The denylist contents.
  3. The deployment steps in programs/cookie-feature-gate/README.md: deploy with a temporary upgrade authority, Initialize with the Squads vault as authority, then move the upgrade authority to the Squads vault.

🤖 Generated with Claude Code

n4pless and others added 4 commits October 20, 2026 18:49
Lets the Cookie Squads multisig activate upstream Agave features without
any feature's private key.

Runtime (runtime/src/cookie/feature_alias.rs):
- Every upstream feature F (except a small denylist: the 4.1 Alpenglow
  placeholder and three abandoned features) gets an alias PDA
  ["cookie-alias", F] of the cookie-feature-gate program.
- Bank::cookie_feature_account reads F's own account first (stock
  behaviour), else the alias, which must be a valid feature account.
- Three one-line hooks in bank.rs route feature-account reads and the
  activation-slot write through it. Upstream feature IDs are unchanged.
- With no alias accounts on chain, behaviour is identical to stock 4.1.2
  (feature set id unchanged: c763ae0a).

Program (programs/cookie-feature-gate, CookmMGfe9ti8mrVkCFuZZsuAvjMSRagqh4t8Yxx4Ub4):
- Initialize (upgrade authority only, once), SetAuthority, Activate,
  Revoke (CPI to the feature gate program, pending activations only).
- Activate handles a pre-funded alias address.

Tests:
- 7 runtime tests (alias table, end-to-end activation across an epoch
  boundary, precedence, non-feature aliases ignored, denylist).
- 7 program unit tests.
- tests/e2e: local test validator, 21 checks incl. misuse attempts;
  passes on the Cookie build, and on stock Agave the alias is ignored.
- Upstream runtime feature tests pass; clippy clean with -D warnings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Follows the new rule 2a in COOKIE-RULES.md: Cookie changes must not break
Solana-compatible interfaces.

- Move the alias table to agave-feature-set (feature-set/src/cookie.rs) so
  the runtime and all client tools share one definition. Runtime Cargo.toml
  is back to upstream.
- CLI: extension trait CookieFeatureAccounts on RpcClient. Call sites only
  swap the method name (get_account -> get_feature_account, etc.), so
  `solana feature status`, `feature activate`, and every command that
  auto-detects features (vote, stake, cluster) behave as on Solana.
- solana-test-validator --clone-feature-set copies alias activations.
- agave-ledger-tool create-snapshot --deactivate-feature-gate works for
  alias-activated features (emergency restarts).
- COOKIE-RULES.md: rule 2a (keep interfaces behaving like Solana) and a
  merge-pain rule.

Tests: feature-set (3), runtime (7 + 32 upstream feature tests), clippy
-D warnings on all touched crates, nightly rustfmt clean. E2E: Cookie CLI
reports the alias-activated feature as active, stock CLI does not;
--clone-feature-set copies it; ledger-tool deactivation passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Vault 3 (AEMq4AZiGU2smZJX4Y3hqrSmAocGJzBAyvNDWSQeQ4Xe) of the community
Squads multisig BQVAdo6L... (6 of 12) is both the switch authority and
the upgrade authority. Deployment steps updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Anyone can send lamports to any address. A plain account at an upstream
feature address F was taken as F's feature account, so the alias was never
read and the Cookie switch for F could be blocked for the cost of a transfer.

F now only counts if it holds a feature account; a feature account at F still
wins over the alias. Otherwise the alias is used if it is a feature account.
Failing both, whatever is at F is returned, as on stock Agave, so the ledger
tool still reports "not a Feature" for a plain account. The same rule applies
in the shared client helpers (missing_aliases / fill_from_aliases) and in the
CLI single-account lookup used by `solana vote-account`.

Tests:
- runtime: lamports at F plus a pending alias, across an epoch boundary,
  activates F; a plain account at F with no valid alias behaves as stock
- feature-set: helper tests for plain accounts at F
- e2e: feature H with lamports at its upstream address activates through
  its alias, shows active in the CLI and survives --clone-feature-set; stock
  Agave still ignores it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…two-step handover in the switch

CLI:
- `solana program deploy/upgrade/write-buffer/extend` built the cluster
  feature set from the canonical feature ids only (`fetch_feature_set`), so
  they would check programs against the wrong rules once a feature is
  activated through the switch. Swapped to `get_feature_accounts`.
- `solana feature revoke` reported a pending alias as "not submitted". It
  cannot withdraw one anyway: only cookie-feature-gate can sign for the
  alias. It now stops with that explanation (`cookie::check_revoke_target`,
  one added line in `process_revoke`; logic unit-tested).

cookie-feature-gate:
- `Activate` refuses the four denylisted ids, so a mistaken request cannot
  sit pending and switch on by itself if a later release drops one from the
  validator's list. The program keeps its own copy (`src/denylist.rs`); a
  test in feature-set fails if it differs from `DENYLIST`.
- Handing over the authority is two steps: `SetAuthority` names a pending
  authority, which signs the new `AcceptAuthority` (tag 4) to take over. A
  single-step handover could point the switch at an address nobody
  controls; requiring both signatures in one transaction would not work
  between vaults of different multisigs. Config is now 66 bytes (version 2:
  authority, pending flag, pending authority); version 1 was never
  deployed. New program SHA-256:
  2a859550f70d466ae92c57a81f252c691a1be5fdbb694a7d02178221d0fbd0d1.

Tests: program 9 unit tests; feature-set 4 (drift test proven to fail on
a changed id); CLI 40 (4 new); e2e cookie 31 program checks plus CLI and
--clone-feature-set checks (new: denylist refused, two-step handover with
wrong signer, missing signature and repeat accept rejected); e2e stock and
the ledger-tool emergency check pass; clippy -D warnings clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@n4pless

n4pless commented Nov 10, 2026

Copy link
Copy Markdown
Contributor Author

@sense112 Review fixes pushed in 670ee7a (CLI program deploy and revoke see Cookie switches; the switch refuses denylisted ids; two-step authority handover; denylist drift test). The program's SHA-256 changed to 2a859550…. Could you re-review? Details in the description under "Changes after review".

🤖 Generated with Claude Code

@sense112 sense112 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The CLI, denylist, and two-step handover in 670ee7a look right. One validator issue is still open: a pending account at the upstream feature address hides an alias that is already activated, and a restart then disagrees with a validator that has not restarted.

Comment thread runtime/src/cookie/feature_alias.rs Resolved
…agree

Review (sense112): a feature account at the upstream address won even when
it was only pending. After an alias activation, anyone holding the
feature's own key could create a pending account at the upstream address.
Running validators never re-check an active feature, but a restart from a
snapshot rebuilds the feature set from accounts (compute_active_feature_set
(false) from FeatureSet::default()), read the pending upstream account,
and came back with the feature off: a consensus split.

The upstream address and the alias are now ranked by
`agave_feature_set::cookie::FeatureRecord`: activated beats pending beats
no feature account; on a tie the upstream address wins, as on stock Agave.
One rule (`alias_wins`) used by the runtime (`cookie_feature_account`), the
bulk CLI helpers (`missing_aliases`, `fill_from_aliases`) and
`get_feature_account_with_commitment`.

New runtime test: a feature activated through its alias, then a pending
account at the upstream address, then a real snapshot round trip
(bank_to_full_snapshot_archive / bank_from_snapshot_archives). It failed
before the fix (feature None after restart) and passes after (active at
the original slot). Feature-set tests cover every ranking case.

Tests: runtime cookie 10, upstream feature 32, core_bpf_migration 49,
feature-set 5, CLI 40; e2e cookie and the ledger-tool check pass; clippy
-D warnings and nightly rustfmt clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sense112
sense112 merged commit 1f47903 into cookie/4.1.2 Nov 10, 2026
1 check passed
@sense112
sense112 deleted the cookie/c1-feature-switches branch November 10, 2026 20:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants