serviceability-instruction: multicastgroup + allowlist builders (RFC-26 R5) by juan-malbeclabs · Pull Request #4054 · malbeclabs/doublezero

juan-malbeclabs · 2026-07-13T18:46:47Z

Summary

RFC-26 R5 (stacked on the previous phase's branch). create/update (conditional multicast_group_block)/suspend/reactivate/delete, update_multicast_group_roles, and the four pub/sub allowlist add/remove builders.

All builders route through authorize() -> build_with_permission unless noted; each carries a verbatim account-layout doc-comment copied from its processor.

Testing Verification

Unit tests assert the exact AccountMeta list (incl. trailing [payer, system]) and the borsh tag byte for every builder, covering the conditional/variable-account paths.

Closes #4020. Part of RFC-26 (rfcs/rfc26-rust-instruction-builder-library.md).

PR stack (RFC-26 builder library)

Stacked PRs, merge in order (each is based on the previous one's branch):

serviceability-instruction: scaffold pure instruction-builder crate (RFC-26 R0) #4049 — R0 scaffold + exemplars
serviceability-instruction: device domain builders (RFC-26 R1) #4050 — R1 device
serviceability-instruction: link domain builders (RFC-26 R2) #4051 — R2 link
serviceability-instruction: user domain builders (RFC-26 R3) #4052 — R3 user
serviceability-instruction: location/exchange/contributor builders (RFC-26 R4) #4053 — R4 location/exchange/contributor
serviceability-instruction: multicastgroup + allowlist builders (RFC-26 R5) #4054 — R5 multicastgroup + allowlists ← this PR
serviceability-instruction: tenant + permission builders (RFC-26 R6) #4055 — R6 tenant + permission
serviceability-instruction: topology + feed builders (RFC-26 R7) #4056 — R7 topology + feed
serviceability-instruction: accesspass + resource builders (RFC-26 R8) #4057 — R8 accesspass + resource
serviceability-instruction: globalstate/globalconfig/allowlist/index/migrate builders (RFC-26 R9) #4058 — R9 globalstate/config/allowlist/index/migrate

R10 (commands/* migration + program-test) and RF (fixtures) follow as separate PRs.

…RFC-26 R0) (#4049) ## Summary RFC-26 **R0**: scaffold the pure, RPC-free instruction-builder crate `doublezero-serviceability-instruction` — SPL-style builders that return a single unsigned `Instruction` per serviceability instruction, no signing/sending. - `common::build` (no-permission trailing `[payer, system]`) + `common::build_with_permission` (the deferred, activate-in-one-place Permission append) + `compute_budget_prelude` (1.4M CU / 256 KiB). - Four exemplar builders establishing the pattern every later PR copies: `create_device`, `delete_device` (legacy/atomic), `create_link`, `create_subscribe_user`. - Deps limited to `doublezero-serviceability` + `solana-program` + `solana-system-interface` + `solana-compute-budget-interface` — no RPC tree. The `suspend_device` exemplar from the RFC was replaced with `delete_device` (`SuspendDevice` is a deprecated variant); the RFC and #4015 were updated, and the "length-detected family" classification was corrected (only `CreateUser` is length-detected). ## Why Instruction assembly is currently coupled to signing+sending inside `commands/*::execute()`; there is no reusable `build_xxx(args) -> Instruction`. See [rfcs/rfc26-rust-instruction-builder-library.md](rfcs/rfc26-rust-instruction-builder-library.md). ## Testing Verification - Unit tests assert the exact `AccountMeta` list (incl. trailing `[payer, system]`) and the borsh tag byte for each exemplar, including the `delete_device` legacy vs atomic layouts and the `create_subscribe_user` optional-feed placement. Closes #4015. Part of RFC-26. --- ### PR stack (RFC-26 builder library) Stacked PRs, merge in order (each is based on the previous one's branch): 1. #4049 — R0 scaffold + exemplars ← **this PR** 2. #4050 — R1 device 3. #4051 — R2 link 4. #4052 — R3 user 5. #4053 — R4 location/exchange/contributor 6. #4054 — R5 multicastgroup + allowlists 7. #4055 — R6 tenant + permission 8. #4056 — R7 topology + feed 9. #4057 — R8 accesspass + resource 10. #4058 — R9 globalstate/config/allowlist/index/migrate R10 (commands/* migration + program-test) and RF (fixtures) follow as separate PRs.

## Summary RFC-26 **R1** (stacked on the previous phase's branch). Complete the device domain on top of the R0 exemplars: update_device (max(old,new) dz_prefix block), set_device_health, and interface create/delete/update (Vpnv4 topology PDAs, segment-routing reconcile). All builders route through `authorize()` -> `build_with_permission` unless noted; each carries a verbatim account-layout doc-comment copied from its processor. ## Testing Verification - Unit tests assert the exact `AccountMeta` list (incl. trailing `[payer, system]`) and the borsh tag byte for every builder, covering the conditional/variable-account paths. Closes #4016. Part of RFC-26 ([rfcs/rfc26-rust-instruction-builder-library.md](rfcs/rfc26-rust-instruction-builder-library.md)). --- ### PR stack (RFC-26 builder library) Stacked PRs, merge in order (each is based on the previous one's branch): 1. #4049 — R0 scaffold + exemplars 2. #4050 — R1 device ← **this PR** 3. #4051 — R2 link 4. #4052 — R3 user 5. #4053 — R4 location/exchange/contributor 6. #4054 — R5 multicastgroup + allowlists 7. #4055 — R6 tenant + permission 8. #4056 — R7 topology + feed 9. #4057 — R8 accesspass + resource 10. #4058 — R9 globalstate/config/allowlist/index/migrate R10 (commands/* migration + program-test) and RF (fixtures) follow as separate PRs.

## Summary RFC-26 **R2** (stacked on the previous phase's branch). accept_link, update_link (LinkUpdateAuthority preamble + conditional tunnel_net / tunnel-resource / topology-union sections), delete_link (topology reference-count accounts), set_link_health. All builders route through `authorize()` -> `build_with_permission` unless noted; each carries a verbatim account-layout doc-comment copied from its processor. ## Testing Verification - Unit tests assert the exact `AccountMeta` list (incl. trailing `[payer, system]`) and the borsh tag byte for every builder, covering the conditional/variable-account paths. Closes #4017. Part of RFC-26 ([rfcs/rfc26-rust-instruction-builder-library.md](rfcs/rfc26-rust-instruction-builder-library.md)). --- ### PR stack (RFC-26 builder library) Stacked PRs, merge in order (each is based on the previous one's branch): 1. #4049 — R0 scaffold + exemplars 2. #4050 — R1 device 3. #4051 — R2 link ← **this PR** 4. #4052 — R3 user 5. #4053 — R4 location/exchange/contributor 6. #4054 — R5 multicastgroup + allowlists 7. #4055 — R6 tenant + permission 8. #4056 — R7 topology + feed 9. #4057 — R8 accesspass + resource 10. #4058 — R9 globalstate/config/allowlist/index/migrate R10 (commands/* migration + program-test) and RF (fixtures) follow as separate PRs.

## Summary RFC-26 **R3** (stacked on the previous phase's branch). create_user (length-detected -> build, no permission), update_user, delete_user, request_ban_user, check_user_access_pass, and set_user_bgp_status (metrics-publisher check, no authorize -> build). All builders route through `authorize()` -> `build_with_permission` unless noted; each carries a verbatim account-layout doc-comment copied from its processor. ## Testing Verification - Unit tests assert the exact `AccountMeta` list (incl. trailing `[payer, system]`) and the borsh tag byte for every builder, covering the conditional/variable-account paths. Closes #4018. Part of RFC-26 ([rfcs/rfc26-rust-instruction-builder-library.md](rfcs/rfc26-rust-instruction-builder-library.md)). --- ### PR stack (RFC-26 builder library) Stacked PRs, merge in order (each is based on the previous one's branch): 1. #4049 — R0 scaffold + exemplars 2. #4050 — R1 device 3. #4051 — R2 link 4. #4052 — R3 user ← **this PR** 5. #4053 — R4 location/exchange/contributor 6. #4054 — R5 multicastgroup + allowlists 7. #4055 — R6 tenant + permission 8. #4056 — R7 topology + feed 9. #4057 — R8 accesspass + resource 10. #4058 — R9 globalstate/config/allowlist/index/migrate R10 (commands/* migration + program-test) and RF (fixtures) follow as separate PRs.

…FC-26 R4) (#4053) ## Summary RFC-26 **R4** (stacked on the previous phase's branch). Three account_index-seeded CRUD domains (create/update/suspend/resume/delete). Exchange create/update carry globalconfig; set_device_exchange carries the device; create_contributor carries the owner. All builders route through `authorize()` -> `build_with_permission` unless noted; each carries a verbatim account-layout doc-comment copied from its processor. ## Testing Verification - Unit tests assert the exact `AccountMeta` list (incl. trailing `[payer, system]`) and the borsh tag byte for every builder, covering the conditional/variable-account paths. Closes #4019. Part of RFC-26 ([rfcs/rfc26-rust-instruction-builder-library.md](rfcs/rfc26-rust-instruction-builder-library.md)). --- ### PR stack (RFC-26 builder library) Stacked PRs, merge in order (each is based on the previous one's branch): 1. #4049 — R0 scaffold + exemplars 2. #4050 — R1 device 3. #4051 — R2 link 4. #4052 — R3 user 5. #4053 — R4 location/exchange/contributor ← **this PR** 6. #4054 — R5 multicastgroup + allowlists 7. #4055 — R6 tenant + permission 8. #4056 — R7 topology + feed 9. #4057 — R8 accesspass + resource 10. #4058 — R9 globalstate/config/allowlist/index/migrate R10 (commands/* migration + program-test) and RF (fixtures) follow as separate PRs.

…RFC-26 R5) create/update (conditional multicast_group_block on IP change)/suspend/reactivate/ delete, update_multicast_group_roles, and the four pub/sub allowlist add/remove builders. All route through authorize() -> build_with_permission. Refs #4020, RFC-26.

…castgroup create/delete/roles builders (RFC-26 R5 review)

…multicast_group path (RFC-26 R5 review)

ben-dz

All ten builders are byte-parity-correct against the on-chain processors and the reference SDK — tags, account order/writability/signer flags, the conditional-block path, and the forced allocation flags all check out. No blocking issues; three Low items only.

L1: add_multicast_group_pub_allowlist/add_multicast_group_sub_allowlist take user_payer both as an account parameter and inside args.user_payer, unbound — a caller can pass divergent values. Fails closed on-chain (no fund/authority risk) but is a fail-late footgun in a correct-by-construction crate and diverges from the SDK's single-source pattern. Derive the account meta from args.user_payer, or overwrite args.user_payer = *user_payer as the file already does for the allocation flags.
L2: update_multicast_group overrides the caller's use_onchain_allocation flag (flipping true→false when multicast_ip is None) with no rationale comment, unlike every other forced flag in the file. Add the one-line why and note the derivation in the doc-comment.
L3: the no-IP update test asserts only accounts.len() == 4 instead of the full AccountMeta vec like every other path; pin the full vec![mgroup, globalstate, payer, system].

…yer in allowlist builders, document derived update flag, pin no-IP update accounts

…4055) ## Summary RFC-26 **R6** (stacked on the previous phase's branch). Tenant CRUD + add/remove administrator + update_payment_status (globalstate writable on create, read-only elsewhere), and permission create/update/suspend/resume/delete (target PDA derived from args.user_payer). All builders route through `authorize()` -> `build_with_permission` unless noted; each carries a verbatim account-layout doc-comment copied from its processor. ## Testing Verification - Unit tests assert the exact `AccountMeta` list (incl. trailing `[payer, system]`) and the borsh tag byte for every builder, covering the conditional/variable-account paths. Closes #4021. Part of RFC-26 ([rfcs/rfc26-rust-instruction-builder-library.md](rfcs/rfc26-rust-instruction-builder-library.md)). --- ### PR stack (RFC-26 builder library) Stacked PRs, merge in order (each is based on the previous one's branch): 1. #4049 — R0 scaffold + exemplars 2. #4050 — R1 device 3. #4051 — R2 link 4. #4052 — R3 user 5. #4053 — R4 location/exchange/contributor 6. #4054 — R5 multicastgroup + allowlists 7. #4055 — R6 tenant + permission ← **this PR** 8. #4056 — R7 topology + feed 9. #4057 — R8 accesspass + resource 10. #4058 — R9 globalstate/config/allowlist/index/migrate R10 (commands/* migration + program-test) and RF (fixtures) follow as separate PRs.

## Summary RFC-26 **R7** (stacked on the previous phase's branch). Topology create/delete plus batched clear_topology / assign_topology_node_segments (single-chunk + *_batched; CLEAR_BATCH_SIZE=16 / BACKFILL_BATCH_SIZE=4 moved into the crate). Feed create/update/delete. All builders route through `authorize()` -> `build_with_permission` unless noted; each carries a verbatim account-layout doc-comment copied from its processor. ## Testing Verification - Unit tests assert the exact `AccountMeta` list (incl. trailing `[payer, system]`) and the borsh tag byte for every builder, covering the conditional/variable-account paths. Closes #4022. Part of RFC-26 ([rfcs/rfc26-rust-instruction-builder-library.md](rfcs/rfc26-rust-instruction-builder-library.md)). --- ### PR stack (RFC-26 builder library) Stacked PRs, merge in order (each is based on the previous one's branch): 1. #4049 — R0 scaffold + exemplars 2. #4050 — R1 device 3. #4051 — R2 link 4. #4052 — R3 user 5. #4053 — R4 location/exchange/contributor 6. #4054 — R5 multicastgroup + allowlists 7. #4055 — R6 tenant + permission 8. #4056 — R7 topology + feed ← **this PR** 9. #4057 — R8 accesspass + resource 10. #4058 — R9 globalstate/config/allowlist/index/migrate R10 (commands/* migration + program-test) and RF (fixtures) follow as separate PRs.

#4057) ## Summary RFC-26 **R8** (stacked on the previous phase's branch). Access-pass set (conditional tenant pair)/close/check-status/set-feeds, and resource-extension allocate/create/deallocate/close (resource PDA + associated account derived from the data-bearing args.resource_type). All builders route through `authorize()` -> `build_with_permission` unless noted; each carries a verbatim account-layout doc-comment copied from its processor. ## Testing Verification - Unit tests assert the exact `AccountMeta` list (incl. trailing `[payer, system]`) and the borsh tag byte for every builder, covering the conditional/variable-account paths. Closes #4023. Part of RFC-26 ([rfcs/rfc26-rust-instruction-builder-library.md](rfcs/rfc26-rust-instruction-builder-library.md)). --- ### PR stack (RFC-26 builder library) Stacked PRs, merge in order (each is based on the previous one's branch): 1. #4049 — R0 scaffold + exemplars 2. #4050 — R1 device 3. #4051 — R2 link 4. #4052 — R3 user 5. #4053 — R4 location/exchange/contributor 6. #4054 — R5 multicastgroup + allowlists 7. #4055 — R6 tenant + permission 8. #4056 — R7 topology + feed 9. #4057 — R8 accesspass + resource ← **this PR** 10. #4058 — R9 globalstate/config/allowlist/index/migrate R10 (commands/* migration + program-test) and RF (fixtures) follow as separate PRs.

…migrate builders (RFC-26 R9) (#4058) ## Summary RFC-26 **R9** (stacked on the previous phase's branch). init_global_state and migrate (no authorize -> build); setters, set_global_config (config PDA + all 8 resource pools), foundation/QA allowlist toggles, index create/delete. After this every buildable variant has a builder. All builders route through `authorize()` -> `build_with_permission` unless noted; each carries a verbatim account-layout doc-comment copied from its processor. ## Testing Verification - Unit tests assert the exact `AccountMeta` list (incl. trailing `[payer, system]`) and the borsh tag byte for every builder, covering the conditional/variable-account paths. Closes #4024. Part of RFC-26 ([rfcs/rfc26-rust-instruction-builder-library.md](rfcs/rfc26-rust-instruction-builder-library.md)). --- ### PR stack (RFC-26 builder library) Stacked PRs, merge in order (each is based on the previous one's branch): 1. #4049 — R0 scaffold + exemplars 2. #4050 — R1 device 3. #4051 — R2 link 4. #4052 — R3 user 5. #4053 — R4 location/exchange/contributor 6. #4054 — R5 multicastgroup + allowlists 7. #4055 — R6 tenant + permission 8. #4056 — R7 topology + feed 9. #4057 — R8 accesspass + resource 10. #4058 — R9 globalstate/config/allowlist/index/migrate ← **this PR** R10 (commands/* migration + program-test) and RF (fixtures) follow as separate PRs.

…4059) ## Summary RFC-26 **RF**: golden fixtures for the instruction builders + a CI drift guard. - Extend the serviceability fixture generator to depend on `doublezero-serviceability-instruction` and emit, per instruction, `ix_<name>.bin` (wire bytes = tag + borsh) and `ix_<name>.json` (`{ variant, data_hex, accounts: [{pubkey, is_signer, is_writable}] }`) from fixed, deterministic inputs. - Representative set covering the trickiest layouts: `create_device` (variable dz_prefix), `delete_device` (atomic close), `create_link`, `create_subscribe_user` (optional feed), `create_user` (length-detected), `clear_topology` / `assign_topology_node_segments` (batched), `set_global_config` (config PDA + all 8 pools). - `make generate-fixtures-check` (regenerate + fail on drift, scoped to the emitted `.bin`/`.json`) and a `fixtures-check` job in the `rust` workflow. These fixtures capture byte-for-byte the current SDK trailing convention (they will drive Go/Python/TS parity in a later phase). ## Testing Verification - `make generate-fixtures-check` passes (regenerated output is byte-identical to the committed fixtures); a hand-edited fixture makes it fail as expected. Closes #4026. Part of RFC-26 ([rfcs/rfc26-rust-instruction-builder-library.md](rfcs/rfc26-rust-instruction-builder-library.md)). --- ### PR stack (RFC-26 builder library) Stacked PRs, merge in order (each based on the previous one's branch): 1. #4049 — R0 scaffold + exemplars 2. #4050 — R1 device 3. #4051 — R2 link 4. #4052 — R3 user 5. #4053 — R4 location/exchange/contributor 6. #4054 — R5 multicastgroup + allowlists 7. #4055 — R6 tenant + permission 8. #4056 — R7 topology + feed 9. #4057 — R8 accesspass + resource 10. #4058 — R9 globalstate/config/allowlist/index/migrate 11. this PR — RF fixtures + CI guard R10 (commands/* migration + program-test) is the final PR and will carry the global changelog entry.

juan-malbeclabs added the skip-changelog label Jul 13, 2026

juan-malbeclabs force-pushed the feat/rfc26-r4-loc-exch-contrib-builders branch from 075ca84 to fc73f8b Compare July 21, 2026 17:02

juan-malbeclabs force-pushed the feat/rfc26-r5-multicastgroup-builders branch from 7c5a573 to d048e1a Compare July 21, 2026 17:02

juan-malbeclabs force-pushed the feat/rfc26-r4-loc-exch-contrib-builders branch from fc73f8b to eab1fb9 Compare July 21, 2026 17:19

juan-malbeclabs force-pushed the feat/rfc26-r5-multicastgroup-builders branch from d048e1a to 23e7ffe Compare July 21, 2026 17:19

juan-malbeclabs force-pushed the feat/rfc26-r4-loc-exch-contrib-builders branch from eab1fb9 to c324118 Compare July 22, 2026 18:04

juan-malbeclabs force-pushed the feat/rfc26-r5-multicastgroup-builders branch 2 times, most recently from 04b138f to c8dd426 Compare July 22, 2026 20:25

Base automatically changed from feat/rfc26-r4-loc-exch-contrib-builders to main July 22, 2026 23:56

juan-malbeclabs added 3 commits July 22, 2026 23:58

serviceability-instruction: force use_onchain_(de)allocation in multi…

2a4ca34

…castgroup create/delete/roles builders (RFC-26 R5 review)

serviceability-instruction: assert flag stays off on no-block update_…

d86dc93

…multicast_group path (RFC-26 R5 review)

juan-malbeclabs force-pushed the feat/rfc26-r5-multicastgroup-builders branch from c8dd426 to d86dc93 Compare July 23, 2026 00:00

juan-malbeclabs enabled auto-merge (squash) July 23, 2026 00:02

juan-malbeclabs requested a review from ben-dz July 23, 2026 00:53

ben-dz approved these changes Jul 23, 2026

View reviewed changes

Comment thread crates/doublezero-serviceability-instruction/src/multicastgroup.rs Outdated

Comment thread crates/doublezero-serviceability-instruction/src/multicastgroup.rs

Comment thread crates/doublezero-serviceability-instruction/src/multicastgroup.rs Outdated

serviceability-instruction: address R5 review — single-source user_pa…

d3cc954

…yer in allowlist builders, document derived update flag, pin no-IP update accounts

juan-malbeclabs merged commit f2a841a into main Jul 23, 2026
36 checks passed

juan-malbeclabs deleted the feat/rfc26-r5-multicastgroup-builders branch July 23, 2026 14:06

Navigation Menu

Uh oh!

serviceability-instruction: multicastgroup + allowlist builders (RFC-26 R5) - #4054

serviceability-instruction: multicastgroup + allowlist builders (RFC-26 R5)#4054
juan-malbeclabs merged 4 commits into
mainfrom
feat/rfc26-r5-multicastgroup-builders

juan-malbeclabs commented Jul 13, 2026 •

edited

Loading

Uh oh!

ben-dz left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

juan-malbeclabs commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing Verification

PR stack (RFC-26 builder library)

Uh oh!

ben-dz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

juan-malbeclabs commented Jul 13, 2026 •

edited

Loading