magicblock-labs · dhruvja · Jul 8, 2026 · Jul 2, 2026 · Jul 3, 2026 · Jul 7, 2026
diff --git a/README.md b/README.md
@@ -75,6 +75,7 @@ Produces:
 - VRF (Verifiable Random Function) for provable randomness
 - Magic Actions — base-layer instructions chained to an ER commit
 - Topping up delegated accounts with lamports via `lamportsDelegatedTransferIx`
+- Ephemeral SPL Token lifecycle: deposit, transfer, app-program CPI, undelegate, withdraw
 - Dual-connection architecture (base layer + ephemeral rollup)
 - Gaming and real-time app development on Solana
 - Private payments (deposits, transfers, withdrawals, and swaps via the Payments API, with optional bearer-token auth for private reads)
@@ -98,6 +99,7 @@ Change my roll_dice function to use VRF
 Set up a crank that updates game state every 100ms
 Add a Magic Action that updates my onchain leaderboard after every commit
 Top up my delegated fee payer with lamports
+Deposit SPL tokens into the ER, transfer them, and withdraw back to base layer
 Build a private USDC transfer flow using the Payments API
 Help me integrate MagicBlock into my Anchor program
 ```

diff --git a/build.sh b/build.sh
@@ -23,6 +23,7 @@ REFERENCES=(
     "delegation.md"
     "magic-actions.md"
     "lamports-topup.md"
+    "ephemeral-spl-token.md"
     "typescript-setup.md"
     "cranks.md"
     "vrf.md"
@@ -75,8 +76,8 @@ build_agents_md() {
         for ref in "${REFERENCES[@]}"; do
             local ref_path="$SKILL_DIR/$ref"
             if [ ! -f "$ref_path" ]; then
-                echo "Warning: missing reference file: $ref" >&2
-                continue
+                echo "Error: missing reference file: $ref" >&2
+                exit 1
             fi
             echo ""
             echo "---"
@@ -106,7 +107,10 @@ build_system_prompt() {
         echo ""
         for ref in "${REFERENCES[@]}"; do
             local ref_path="$SKILL_DIR/$ref"
-            if [ ! -f "$ref_path" ]; then continue; fi
+            if [ ! -f "$ref_path" ]; then
+                echo "Error: missing reference file: $ref" >&2
+                exit 1
+            fi
             local title
             title=$(extract_title "$ref_path")
             if [ -z "$title" ]; then title="$ref"; fi
@@ -123,7 +127,7 @@ build_cursor_mdc() {
     {
         cat <<'EOF'
 ---
-description: MagicBlock Ephemeral Rollups development patterns for Solana — delegation flows, Magic Actions, dual-connection architecture, cranks, VRF, lamports top-up, commit sponsorship, and private payments with swaps. Use when working on MagicBlock or Ephemeral Rollups.
+description: MagicBlock Ephemeral Rollups development patterns for Solana — delegation flows, Magic Actions, dual-connection architecture, cranks, VRF, lamports top-up, Ephemeral SPL Token smart-contract integration, commit sponsorship, and private payments with swaps. Use when working on MagicBlock or Ephemeral Rollups.
 globs:
 alwaysApply: false
 ---
@@ -132,7 +136,10 @@ EOF
         strip_frontmatter "$SKILL_DIR/SKILL.md"
         for ref in "${REFERENCES[@]}"; do
             local ref_path="$SKILL_DIR/$ref"
-            if [ ! -f "$ref_path" ]; then continue; fi
+            if [ ! -f "$ref_path" ]; then
+                echo "Error: missing reference file: $ref" >&2
+                exit 1
+            fi
             echo ""
             echo "---"
             echo ""

diff --git a/skill/SKILL.md b/skill/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: magicblock
-description: MagicBlock Ephemeral Rollups development patterns for Solana. Covers debugging live ER/delegation failures, router `getDelegationStatus`, delegation/undelegation flows, dual-connection architecture (base layer + ER), cranks for scheduled tasks, VRF for verifiable randomness, magic actions for atomic ER-commit + base-layer follow-ups, private payments API (deposits, transfers, withdrawals, swaps, and challenge/login auth flow), commit sponsorship and fee vault wiring, lamports top-up for delegated accounts, and TypeScript/Anchor integration. Use for high-performance gaming, real-time apps, private transfers and swaps, and fast transaction throughput on Solana.
+description: MagicBlock Ephemeral Rollups development patterns for Solana. Covers debugging live ER/delegation failures, router `getDelegationStatus`, delegation/undelegation flows, dual-connection architecture (base layer + ER), cranks for scheduled tasks, VRF for verifiable randomness, magic actions for atomic ER-commit + base-layer follow-ups, private payments API (deposits, transfers, withdrawals, swaps, and challenge/login auth flow), commit sponsorship and fee vault wiring, lamports top-up for delegated accounts, Ephemeral SPL Token integration (deposit/transfer/withdraw SPL tokens on the ER), and TypeScript/Anchor integration. Use for high-performance gaming, real-time apps, private transfers and swaps, delegated account workflows, and fast transaction throughput on Solana.
 ---
 
 # MagicBlock Ephemeral Rollups Skill
@@ -15,6 +15,7 @@ Use this Skill when the user asks for:
 - VRF (Verifiable Random Function) for provable randomness
 - Magic Actions — base-layer instructions chained to an ER commit
 - Topping up a delegated account's lamports via `lamportsDelegatedTransferIx`
+- Ephemeral SPL Token integration: deposit/transfer/withdraw SPL tokens on the ER via `delegateSpl`/`transferSpl`/`undelegateIx`/`withdrawSpl`, move delegated token accounts from an Anchor program, or CPI into the program via `ephemeral-spl-api`
 - Dual-connection architecture (base layer + ephemeral rollup)
 - Gaming and real-time app development on Solana
 - Private payments (deposits, transfers, withdrawals, and swaps via the Payments API, with optional bearer-token auth for private reads)
@@ -41,6 +42,8 @@ returned by router `getDelegationStatus`, and cloned into the ER with
 
 **Lamports top-up**: when a delegated account (e.g. a delegated fee payer) needs more lamports on the ER side, use `lamportsDelegatedTransferIx` from the SDK. The transaction is submitted on **base layer** — the Ephemeral SPL Token program creates a single-use lamports PDA, funds it, and delegates it so the ER credits the destination.
 
+**Ephemeral SPL Token**: deposited tokens are locked in a per-mint global vault on base layer while the balance is delegated to the ER, where it appears as a normal SPL token account at the owner's canonical ATA address. Clients drive the lifecycle with the SDK's `delegateSpl`/`transferSpl`/`undelegateIx`/`withdrawSpl` helpers; Anchor programs move the delegated balances with plain SPL Token CPI; contracts needing the raw instruction surface use `ephemeral-spl-api`.
+
 **Architecture**:
 ```
 ┌─────────────────┐     delegate      ┌─────────────────────┐
@@ -54,11 +57,13 @@ returned by router `getDelegationStatus`, and cloned into the ER with
 ## Default stack decisions (opinionated)
 
 1) **Programs: Anchor with ephemeral-rollups-sdk**
-   - Use `ephemeral-rollups-sdk` (0.14.x) with the `anchor` feature for Anchor 1.0.x
-     programs, or the `anchor-compat` feature for legacy Anchor 0.32.1 programs
+   - Use the target repo's existing `ephemeral-rollups-sdk` / Anchor versions unless the task is an explicit upgrade
+   - The SDK feature flag selects the Anchor line: `anchor` for Anchor 1.0.x programs, or `anchor-compat` for legacy Anchor 0.32.x programs
    - Apply `#[ephemeral]` macro before `#[program]`
    - Use `#[delegate]` and `#[commit]` macros for delegation contexts
 
+Version-sensitive work: treat versions in this skill as known-good snapshots or compatibility markers, not timeless latest recommendations. Before adding or changing dependencies, inspect the target repo's `Cargo.toml`, `package.json`, `rust-toolchain.toml`, lockfiles, and the relevant upstream manifests/docs. See [resources.md](resources.md) for the current snapshot and source links.
+
 2) **Dual Connections**
    - Base layer connection for initialization and delegation:
      `https://rpc.magicblock.app/devnet` or `https://rpc.magicblock.app/mainnet`
@@ -93,6 +98,7 @@ Always be explicit about:
 - PDA seeds matching between delegate call and account definition
 - Using `skipPreflight: true` for ER transactions
 - Waiting for state propagation after delegate/undelegate
+- For Ephemeral SPL Token flows, keeping the `idempotent` mode consistent across delegate/undelegate/withdraw, waiting for undelegation commits before withdrawing, and using `ephemeral-spl-api` exports (not copied bytes or guessed seeds) for direct CPI
 
 ### 4. Debug live delegation/routing failures
 For `InvalidWritableAccount`, missing private balances, validator mismatch, or
@@ -132,8 +138,26 @@ When you implement changes, provide:
 - Core delegation patterns: [delegation.md](delegation.md)
 - Magic Actions (post-commit base-layer instructions): [magic-actions.md](magic-actions.md)
 - Topping up a delegated account with lamports: [lamports-topup.md](lamports-topup.md)
+- Ephemeral SPL Token lifecycle (deposit, transfer, app-program CPI, undelegate, withdraw): [ephemeral-spl-token.md](ephemeral-spl-token.md)
 - TypeScript frontend setup: [typescript-setup.md](typescript-setup.md)
 - Cranks (scheduled tasks): [cranks.md](cranks.md)
 - VRF (randomness): [vrf.md](vrf.md)
 - Private Payments API: [private-payments.md](private-payments.md)
 - Reference links & versions: [resources.md](resources.md)
+
+## Terminal Self-Heal Proposal
+
+Before the final response, review the entire run against this skill's intended workflow.
+
+Check:
+- expected vs actual user-visible outputs
+- command, script, validation, and artifact results
+- missed coverage or skipped workflow steps
+- stale instructions or brittle wording
+- unexpected script/output mismatches
+- verification gaps
+- fallback or impromptu behavior
+
+If improvements are needed, propose concrete skill edits with file paths, rationale, and evidence.
+
+Stop after the proposal. Do not edit this skill, run mutation commands, or apply fixes unless the user explicitly approves in a later instruction.
diff --git a/skill/agents/openai.yaml b/skill/agents/openai.yaml
@@ -1,4 +1,4 @@
 interface:
   display_name: "MagicBlock"
   short_description: "MagicBlock Ephemeral Rollups development and debugging patterns"
-  default_prompt: "Use the magicblock skill to help integrate or debug MagicBlock Ephemeral Rollups in this Solana project, including router getDelegationStatus, delegation flows, transaction routing, cranks, VRF, or private payments."
+  default_prompt: "Use $magicblock to help integrate or debug MagicBlock Ephemeral Rollups in this Solana project, including router getDelegationStatus, delegation flows, the Ephemeral SPL Token lifecycle (deposit, transfer, app-program CPI, undelegate, withdraw), transaction routing, cranks, VRF, or private payments."
diff --git a/skill/delegation.md b/skill/delegation.md
@@ -4,6 +4,10 @@
 
 ### Dependencies
 
+Known-good active-example snapshot. Before changing a real project, inspect its
+existing manifests and [resources.md](resources.md); do not treat these versions
+as timeless latest recommendations.
+
 ```toml
 # Cargo.toml
 [dependencies]