Skip to content

refactor: move commit-and-undelegate scheduling service from magicblock-accounts to magicblock-services #1402

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
snawaz wants to merge 1 commit into from
Closed

refactor: move commit-and-undelegate scheduling service from magicblock-accounts to magicblock-services #1402

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
13 changes: 7 additions & 6 deletions .agents/context/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ Architecture rule: the RPC layer should route work to account sync and execution

### 3. Account synchronization

Owned primarily by `magicblock-chainlink`, `magicblock-account-cloner`, and `magicblock-accounts`.
Owned primarily by `magicblock-chainlink` and `magicblock-account-cloner`.

Responsibilities:

Expand All @@ -69,7 +69,7 @@ Responsibilities:
- subscribe to remote changes where needed,
- materialize local account/program state,
- provide account availability to RPC and transaction execution,
- hand scheduled commit work toward settlement.
- expose DLP request observations to background services that schedule settlement work.

Architecture rule: this layer prepares local state for execution. It should not decide post-execution account access rules; those belong to the execution/SVM path. Avoid fetch amplification, duplicate clone work, subscription churn, and unnecessary serialization in account availability paths.

Expand Down Expand Up @@ -106,11 +106,11 @@ Architecture rule: maintenance operations that can race execution must be coordi

### 6. Base-layer settlement

Owned primarily by `magicblock-program`, `magicblock-magic-program-api`, `magicblock-committor-service`, `magicblock-committor-program`, `magicblock-table-mania`, and `magicblock-rpc-client`.
Owned primarily by `magicblock-program`, `magicblock-magic-program-api`, `magicblock-services`, `magicblock-committor-service`, `magicblock-committor-program`, `magicblock-table-mania`, and `magicblock-rpc-client`.

Responsibilities:

- let programs schedule commits, commit-and-undelegate operations, intent bundles, and Magic Actions,
- let programs and validator background services schedule commits, commit-and-undelegate operations, intent bundles, and Magic Actions,
- persist and recover pending settlement work,
- build valid base-layer transactions,
- handle address lookup tables and large changesets,
Expand All @@ -128,7 +128,8 @@ Responsibilities:
- execute scheduled program tasks,
- replicate primary output to replicas,
- expose metrics/admin/operator hooks,
- provide reusable service infrastructure.
- provide reusable service infrastructure,
- ingest DLP undelegation requests and submit local scheduling transactions.

Architecture rule: background services should integrate through shared channels/service APIs rather than reaching through unrelated crate internals.

Expand Down Expand Up @@ -160,7 +161,7 @@ base-layer delegation exists
```text
program invokes Magic Program in ER
-> MagicContext records scheduled intent
-> validator-side processing picks up intent
-> validator-side services pick up or create the intent
-> committor builds/sends base-layer transaction(s)
-> commit keeps delegation active OR undelegation returns ownership after settlement
```
Expand Down
19 changes: 9 additions & 10 deletions .agents/context/crate-map.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ The validator is performance-sensitive. When changing any crate on RPC, account
| Crate | Purpose | Depends on | Used by | Notes |
|---|---|---|---|---|
| `magicblock-validator` | Main validator binary and process entrypoint. | `magicblock-api`, `magicblock-config`, `magicblock-core`, `magicblock-tui-client`, `magicblock-version` | End users/operators | Parses config, builds runtime, starts headless/TUI validator; see `.agents/context/crates/magicblock-validator.md` before changing this crate. |
| `magicblock-api` | Top-level service orchestration and `MagicValidator` implementation. | accounts, aperture, chainlink, committor, config, core, ledger, processor, replicator, task scheduler, admin/services | `magicblock-validator` | Owns startup/shutdown wiring for most services; see `.agents/context/crates/magicblock-api.md` before changing this crate. |
| `magicblock-api` | Top-level service orchestration and `MagicValidator` implementation. | accounts-db, aperture, chainlink, committor, config, core, ledger, processor, replicator, task scheduler, admin/services | `magicblock-validator` | Owns startup/shutdown wiring for most services; see `.agents/context/crates/magicblock-api.md` before changing this crate. |
| `magicblock-config` | Validator configuration model and layered config loading. | none | Most service crates | CLI/env/TOML/default config source; see `.agents/context/crates/magicblock-config.md` before changing configurable behavior. |
| `magicblock-core` | Shared channels, traits, account locks/helpers, intent/core types. | `magicblock-magic-program-api` | Most runtime crates | Central wiring layer; changes can affect scheduler, RPC, ledger, services, replication. See `.agents/context/crates/magicblock-core.md` before changing this crate. |
| `magicblock-version` | Build/version metadata. | none | `magicblock-validator`, `magicblock-aperture` | Keep version reporting stable for RPC/operator tooling; see `.agents/context/crates/magicblock-version.md` before changing this crate. |
Expand All @@ -28,32 +28,31 @@ The validator is performance-sensitive. When changing any crate on RPC, account
| Crate | Purpose | Depends on | Used by | Notes |
|---|---|---|---|---|
| `magicblock-processor` | Transaction scheduler, executor pool, SVM execution, commit-to-local-state path. | `magicblock-accounts-db`, `magicblock-core`, `magicblock-ledger`, `magicblock-magic-program-api`, `magicblock-metrics`, `magicblock-program` | `magicblock-api`, tests | Core execution path; preserve account locking and writable-account access invariants. |
| `magicblock-accounts-db` | Custom local account database. | `magicblock-config`, `magicblock-magic-program-api` | account cloner, accounts, aperture, API, chainlink, processor, replicator, tests/tools | Append-only mmap storage plus indexes/snapshots; maintenance requires scheduler pause. See `.agents/context/crates/magicblock-accounts-db.md` before changing this crate. |
| `magicblock-accounts-db` | Custom local account database. | `magicblock-config`, `magicblock-magic-program-api` | account cloner, aperture, API, chainlink, processor, replicator, tests/tools | Append-only mmap storage plus indexes/snapshots; maintenance requires scheduler pause. See `.agents/context/crates/magicblock-accounts-db.md` before changing this crate. |
| `magicblock-ledger` | Local ledger/history and latest block state. | `magicblock-core`, `magicblock-metrics`, `solana-storage-proto`, `test-kit` | aperture, API, processor, replicator, task scheduler, tools/tests | Stores tx/status/block history and latest blockhash/slot; see `.agents/context/crates/magicblock-ledger.md` before changing this crate. |
| `solana-storage-proto` | Generated/protobuf storage support. | none | `magicblock-ledger` | Low-level ledger serialization support; see `.agents/context/crates/storage-proto.md` before changing this crate. |

## Delegation, cloning, and account lifecycle crates

| Crate | Purpose | Depends on | Used by | Notes |
|---|---|---|---|---|
| `magicblock-chainlink` | Base-chain account/delegation coordination. | accounts-db, AML, config, core, magic-program API, metrics | account-cloner, accounts, aperture, API, magic program | Checks/clones remote accounts, tracks delegation state, coordinates base-layer reads. See `.agents/context/crates/magicblock-chainlink.md` before changing this crate. |
| `magicblock-account-cloner` | Fetches and injects base-layer accounts/programs into local validator state. | accounts-db, chainlink, committor-service, config, core, ledger, magic-program API, magic program, rpc-client | accounts, aperture, API | Distinguishes fee payer, delegated, and undelegated accounts; handles large/program clone paths. See `.agents/context/crates/magicblock-account-cloner.md` before changing this crate. |
| `magicblock-accounts` | Account manager and scheduled commit processing glue. | account-cloner, accounts-db, chainlink, committor-service, core, metrics, magic program | `magicblock-api` | Current active role is scheduled commit processing and pending intent recovery; see `.agents/context/crates/magicblock-accounts.md` before changing this crate. |
| `magicblock-chainlink` | Base-chain account/delegation coordination. | accounts-db, AML, config, core, magic-program API, metrics | account-cloner, aperture, API, magic program, services | Checks/clones remote accounts, tracks delegation state, coordinates base-layer reads and DLP request observations. See `.agents/context/crates/magicblock-chainlink.md` before changing this crate. |
| `magicblock-account-cloner` | Fetches and injects base-layer accounts/programs into local validator state. | accounts-db, chainlink, committor-service, config, core, ledger, magic-program API, magic program, rpc-client | aperture, API, services | Distinguishes fee payer, delegated, and undelegated accounts; handles large/program clone paths. See `.agents/context/crates/magicblock-account-cloner.md` before changing this crate. |
| `magicblock-aml` | External/cached risk-scoring integration. | `magicblock-config` (dev: `magicblock-core`) | `magicblock-chainlink` | Optional Range risk checks for post-delegation action signers; see `.agents/context/crates/magicblock-aml.md` before changing this crate. |

## Commit and base-layer settlement crates

| Crate | Purpose | Depends on | Used by | Notes |
|---|---|---|---|---|
| `magicblock-committor-service` | Executes scheduled base-layer intents: commit, undelegate, finalize, action. | committor program, core, metrics, magic program, rpc-client, table-mania | account-cloner, accounts, API | Durable commit pipeline; handles scheduling, transaction prep, buffers, ALTs, confirmations. See `.agents/context/crates/magicblock-committor-service.md` before changing this crate. |
| `magicblock-committor-service` | Accepts and executes scheduled base-layer intents: commit, undelegate, finalize, action. | accounts-db, account-cloner, chainlink, committor program, core, metrics, magic program, rpc-client, table-mania | account-cloner, API | Durable intent pipeline; accepts ER MagicContext intents, handles scheduling, transaction prep, buffers, ALTs, confirmations. See `.agents/context/crates/magicblock-committor-service.md` before changing this crate. |
| `magicblock-committor-program` | On-chain committor program. | none | `magicblock-committor-service` | Base-layer program side for changeset buffers/commit application; see `.agents/context/crates/magicblock-committor-program.md` before changing this crate. |
| `magicblock-table-mania` | Address lookup table management. | metrics, rpc-client | `magicblock-committor-service` | Creates/extends/deactivates/closes ALTs needed by commit transactions. See `.agents/context/crates/magicblock-table-mania.md` before changing this crate. |

## Magic Program and shared protocol crates

| Crate | Purpose | Depends on | Used by | Notes |
|---|---|---|---|---|
| `magicblock-program` | Magic Program implementation (`programs/magicblock`). | chainlink, core, magic-program API, test-kit | account-cloner, accounts, API, committor, processor, task scheduler, admin | Implements scheduling, cloning, ephemeral accounts, validator-only operations. |
| `magicblock-program` | Magic Program implementation (`programs/magicblock`). | chainlink, core, magic-program API, test-kit | account-cloner, API, committor, processor, services, task scheduler, admin | Implements scheduling, cloning, ephemeral accounts, validator-only operations. |
| `magicblock-magic-program-api` | Shared Magic Program instruction, PDA, args, and compatibility types. | none | core, accounts-db, chainlink, processor, magic program, services, cloner, API, test programs | Use this instead of duplicating Magic Program wire types; see `.agents/context/crates/magicblock-magic-program-api.md` before changing this crate. |
| `guinea` | Test-only program for validator behavior. | `magicblock-magic-program-api` | processor tests, test-kit | Used to exercise ephemeral/delegated behavior in tests. |

Expand All @@ -63,7 +62,7 @@ The validator is performance-sensitive. When changing any crate on RPC, account
|---|---|---|---|---|
| `magicblock-task-scheduler` | Program-scheduled task/crank service. | config, core, ledger, magic program | `magicblock-api` | SQLite-backed delay queue, retries/backoff, scheduled transaction submission. See `.agents/context/crates/magicblock-task-scheduler.md` before changing this crate. |
| `magicblock-replicator` | Primary/replica event replication over NATS JetStream. | accounts-db, config, core, ledger | `magicblock-api` | Preserves HA/replica replay behavior; primary and replica modes differ intentionally. |
| `magicblock-services` | Shared service utilities/adapters. | core, magic-program API | `magicblock-api` | Common service abstractions; keep generic. See `.agents/context/crates/magicblock-services.md` before changing this crate. |
| `magicblock-services` | Shared validator service adapters, including action callbacks and DLP undelegation request processing. | account-cloner, chainlink, core, magic-program API, metrics, magic program | `magicblock-api`, committor | Background adapters may bridge existing service contracts; keep orchestration in API and base-layer execution in committor. See `.agents/context/crates/magicblock-services.md` before changing this crate. |
| `magicblock-metrics` | Metrics helpers and instrumentation. | none | RPC, ledger, processor, chainlink, committor, table-mania, API | Prefer adding observability here rather than ad-hoc metrics code. See `.agents/context/crates/magicblock-metrics.md` before changing this crate. |

## Tools and test support
Expand All @@ -78,8 +77,8 @@ The validator is performance-sensitive. When changing any crate on RPC, account
## How to use this map

- For transaction correctness, start with `magicblock-processor`, then inspect `magicblock-accounts-db`, `magicblock-ledger`, and `magicblock-program` interactions.
- For delegation or account cloning bugs, start with `magicblock-chainlink`, `magicblock-account-cloner`, and `magicblock-accounts`.
- For commit or undelegation bugs, start with `magicblock-program`, `magicblock-accounts`, and `magicblock-committor-service`.
- For delegation or account cloning bugs, start with `magicblock-chainlink` and `magicblock-account-cloner`; for DLP undelegation request ingestion, also inspect `magicblock-services`.
- For commit or undelegation bugs, start with `magicblock-program`, `magicblock-services`, and `magicblock-committor-service`.
- For RPC behavior, start with `magicblock-aperture`; check `magicblock-chainlink` if reads trigger cloning.
- For validator lifecycle/startup/shutdown, start with `magicblock-api` and `magicblock-validator`.
- When adding, removing, renaming, or repurposing a crate, update this file and `AGENTS.md` in the same change.
Expand Down
8 changes: 4 additions & 4 deletions .agents/context/crates/magicblock-account-cloner.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,9 @@ Main consumers:

- `magicblock-api` creates `ChainlinkCloner::new(transaction_scheduler, latest_block)` during validator startup unless Chainlink is disabled for replica mode.
- `magicblock-chainlink` owns clone decisions and invokes this crate through `Arc<dyn Cloner>`-style generic wiring.
- `magicblock-accounts` aliases `ProdChainlink<ChainlinkCloner>` for scheduled commit / undelegation integration.
- `magicblock-services` aliases `ProdChainlink<ChainlinkCloner>` for DLP undelegation request integration.
- `magicblock-aperture` stores the same production Chainlink alias in shared RPC state; it reaches the cloner indirectly through Chainlink.
- `magicblock-api` and `magicblock-accounts` convert `AccountClonerError` where committor diagnostic helpers are used.
- `magicblock-api` converts `AccountClonerError` where committor diagnostic helpers are used.

Important upstream/downstream relationships:

Expand Down Expand Up @@ -299,7 +299,7 @@ Risks:
Inspect first:

- `magicblock-api/src/magic_validator.rs::init_chainlink`;
- type aliases `InnerChainlinkImpl` / `ChainlinkImpl` in `magicblock-api` and `magicblock-accounts`;
- type aliases `InnerChainlinkImpl` / `ChainlinkImpl` in `magicblock-api`, `magicblock-chainlink`, and `magicblock-services`;
- `magicblock-chainlink` production aliases and disabled replication mode behavior.

Risks:
Expand All @@ -316,7 +316,7 @@ Inspect first:
- `magicblock-account-cloner/src/util.rs::get_tx_diagnostics`;
- `magicblock-committor-service` error types;
- `magicblock-rpc-client` transaction log/CU helpers;
- `magicblock-api/src/errors.rs` and `magicblock-accounts/src/errors.rs` conversions.
- `magicblock-api/src/errors.rs` conversions.

Risks:

Expand Down
Loading
Loading