Skip to content

smartcontract: add Index account and standalone instructions#3256

Merged
martinsander00 merged 2 commits intomainfrom
ms/pda-derivation
Apr 1, 2026
Merged

smartcontract: add Index account and standalone instructions#3256
martinsander00 merged 2 commits intomainfrom
ms/pda-derivation

Conversation

@martinsander00
Copy link
Copy Markdown
Contributor

@martinsander00 martinsander00 commented Mar 12, 2026

Resolves: #3408

Summary

  • Introduce an Index account (PDA derived from entity type + lowercased code) for O(1) code-to-pubkey lookup and onchain uniqueness enforcement
  • Add standalone CreateIndex/DeleteIndex instructions (variants 104/105) for migration backfill of existing accounts
  • Add Index PDA derivation (get_index_pda) and Rust SDK command wrappers

Split PR (1/2). Integration into multicast group lifecycle follows in #3415.

New derivation workflow: #3256 (comment)

Diff Breakdown

Category Files Lines (+/-) Net
Onchain program 12 +373 / -4 +369
Rust SDK 4 +75 / -0 +75
Tests 2 +456 / -0 +456
CHANGELOG 1 +2 / -0 +2
Total 18 +906 / -4 +902

~50% tests, ~41% onchain program, ~9% Rust SDK

Key files (click to expand)
  • smartcontract/programs/doublezero-serviceability/src/state/index.rs — new Index account struct (account_type + pubkey + bump_seed) with Borsh serialization
  • smartcontract/programs/doublezero-serviceability/src/processors/index/create.rs — standalone CreateIndex processor
  • smartcontract/programs/doublezero-serviceability/src/processors/index/delete.rs — standalone DeleteIndex processor
  • smartcontract/programs/doublezero-serviceability/src/pda.rsget_index_pda() with case-insensitive seed derivation
  • smartcontract/sdk/rs/src/commands/index/create.rs — CreateIndex SDK command wrapper
  • smartcontract/sdk/rs/src/commands/index/delete.rs — DeleteIndex SDK command wrapper

Testing Verification

  • New index_test.rs with 5 tests: create, duplicate rejection, unauthorized create, delete, unauthorized delete
  • New test helpers for transactions with extra accounts
  • All existing tests continue to pass (no modifications to existing processors)

@martinsander00
Copy link
Copy Markdown
Contributor Author

How the Index Account Works

Create: A counter increments to get a new PDA address that doesn't repeat. We get the pubkey of that PDA and point to it in a new associated Index account (derived from the code). The multicast group PDA is derived from the counter; the Index PDA is derived from the code.

Delete: Both the group and the Index are closed.

Rename: The multicast group pubkey doesn't change on rename (it's still derived from the counter, which was set at creation). So:

  • Old Index (derived from old code) → points to multicast group pubkey → deleted
  • New Index (derived from new code) → points to the same multicast group pubkey → created

The Index PDA changes (because the code in its seeds changed), but it still points to the same multicast group account. The group's PDA never moves — only the "DNS record" pointing to it gets swapped.

Lookup: Since the Index PDA seeds are deterministic (["doublezero", "index", "multicast", lowercase(code)]), you can compute the Index address locally from just the code — no RPC calls needed for that part. Then you do one fetch to get the Index account, read its pk field, and one more fetch to get the actual multicast group. Two RPC calls total.

Before this, looking up by code meant fetching every multicast group account and scanning through them to find the one with a matching code — O(n).

@martinsander00 martinsander00 force-pushed the ms/pda-derivation branch 5 times, most recently from 7bde2d2 to dd81d51 Compare March 31, 2026 00:25
@martinsander00 martinsander00 changed the title smartcontract: add Index account for multicast group code uniqueness smartcontract: add Index account and standalone instructions Mar 31, 2026
Introduce an Index account (PDA derived from entity type + lowercased
code) for O(1) code-to-pubkey lookup. Add standalone CreateIndex and
DeleteIndex instructions (variants 104/105) for migration backfill.
Add Index PDA derivation and Rust SDK command wrappers.
@martinsander00 martinsander00 marked this pull request as ready for review March 31, 2026 04:54
Copy link
Copy Markdown
Contributor

@elitegreg elitegreg left a comment

Choose a reason for hiding this comment

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

I assume the ultimate plan is to not use CreateIndex, but rather, create the index account when something like CreateMulticastGroup occurs? If that's the case, I'd suggest splitting out the account verification/creation logic and having that be called by the process_* routines here and then you can use the functions later when you modify process_create_multicastgroup.

Also, I'd consider changing the name of code to something else, perhaps key or field. The index can be used for any string we want to be unique, not just codes.

@martinsander00 martinsander00 merged commit e22b5c0 into main Apr 1, 2026
33 checks passed
@martinsander00 martinsander00 deleted the ms/pda-derivation branch April 1, 2026 01:14
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.

Establish Index PDA account pattern

2 participants