docs: add ephemeral SPL token lifecycle guide

[dhruvja]

What

Adds an end-to-end Ephemeral SPL Token lifecycle reference and aligns top-level skill routing with it.

• skill/ephemeral-spl-token.md documents two integration models:
  • Model A - SDK lifecycle: delegateSpl / transferSpl / undelegateIx / withdrawSpl, canonical-ATA balances on the ER, endpoint routing, and the Anchor app-program pattern using plain SPL CPI over delegated ATAs.
  • Model B - direct program surface: eATA/global-vault PDAs, ephemeral-spl-api exports, core instruction account metas, and low-level TypeScript builders.
• Adds guidance for validator selection and verification through getIdentity / router getDelegationStatus.
• Captures lifecycle gotchas from the examples: initVaultIfMissing, one undelegate per transaction, waiting for commits before withdrawal, idempotent mode consistency, endpoint/blockhash pairing, and rent PDA funding.
• Renames top-level references around the Ephemeral SPL Token lifecycle.
• Rebuilds generated dist/ artifacts.

Why

The skill needed a practical lifecycle guide for agents integrating SPL tokens on Ephemeral Rollups, with the SDK flow as the default path and direct ephemeral-spl-api usage documented as the lower-level path.

Testing

• Ran bash build.sh
• Ran python3 <skill-quality-gate>/scripts/skill_gate.py skill --run-tests
• Ran python3 <skill-self-heal>/scripts/audit_self_heal.py skill
• Checked the guidance against the upstream Ephemeral SPL Token repo and the magicblock-engine-examples/spl-tokens example.

Breaking changes

None. Documentation only.

Summary by CodeRabbit

• Documentation
  • Added a new guide covering the Ephemeral SPL Token lifecycle, including supported integration patterns, setup requirements, example workflows, and common pitfalls.
  • Updated an existing reference link to point to the current integration example for lamport top-ups.

[coderabbitai]

Walkthrough

The PR adds a new reference document for Ephemeral SPL token handling, covering SDK-driven and direct-program workflows, Anchor CPI usage, and operational caveats. It also updates one lamports-topup reference link to a new example app path.

Changes

Ephemeral SPL token lifecycle guide

Layer / File(s)	Summary
Overview and SDK lifecycle skill/ephemeral-spl-token.md	Introduces the guide, defines the two integration models, and documents the SDK-based deposit, transfer, undelegate, and withdraw flow with prerequisites and validator guidance.
Anchor app-program CPI flow skill/ephemeral-spl-token.md	Shows an Anchor program using SPL Token CPI on the Ephemeral Rollup and the matching client transaction setup.
Direct program surface skill/ephemeral-spl-token.md	Describes the PDA/state model and the low-level ephemeral-spl-api instruction and builder surfaces for direct contract integration.
Operational gotchas skill/ephemeral-spl-token.md	Lists consistency and sequencing checks for validators, rent/vault setup, commits, blockhash usage, idempotent mode, and model separation.

Lamports-topup reference update

Layer / File(s)	Summary
Updated example reference skill/lamports-topup.md	Changes the working reference path to the new handleLamportsTransfer example location.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• magicblock-labs/magicblock-dev-skill#3: Updates the lamports-topup guide’s reference path, which is directly related to the same skill documentation area.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding a new Ephemeral SPL Token lifecycle documentation guide.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dhruvja/docs/ephemeral-spl-token-lifecycle-guide

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

skill/ephemeral-spl-token.md (1)

44-49: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Separate the Model A and Model B state descriptions.

This paragraph says both models use the eATA/global-vault model, but Model A is defined earlier as the canonical ATA-on-ER flow with no eATA/vault PDA. As written, readers will derive the wrong accounts for the SDK path.

Proposed fix

-Both models share the same base-layer state: deposited tokens are locked in the global vault, the user's balance is recorded in the eATA, and the eATA is delegated to the delegation program.
-The difference is purely which surface you touch: canonical ATAs + SDK helpers (A) versus raw PDAs + program instructions (B).
+Model A: the delegated balance appears at the owner's canonical ATA on the ER, and clients use the SDK helpers.
+Model B: deposits are tracked with the eATA/global-vault PDAs and the raw program instruction surface.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@skill/ephemeral-spl-token.md` around lines 44 - 49, Separate the state
descriptions for Model A and Model B in the ephemeral-spl-token document: the
current paragraph in the section describing the two models incorrectly gives
both flows the eATA/global-vault model. Update the text around the Model A and
Model B descriptions so Model A clearly refers to the canonical ATA-on-ER SDK
helper flow, while Model B is the one that uses raw PDAs, eATA, and the global
vault; keep the account/state terminology consistent with the earlier
definitions.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@skill/ephemeral-spl-token.md`:
- Around line 44-49: Separate the state descriptions for Model A and Model B in
the ephemeral-spl-token document: the current paragraph in the section
describing the two models incorrectly gives both flows the eATA/global-vault
model. Update the text around the Model A and Model B descriptions so Model A
clearly refers to the canonical ATA-on-ER SDK helper flow, while Model B is the
one that uses raw PDAs, eATA, and the global vault; keep the account/state
terminology consistent with the earlier definitions.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: ccac746e-4fdc-44c4-8384-78f87516244a

📥 Commits

Reviewing files that changed from the base of the PR and between b59a6d0 and 44a1805.

📒 Files selected for processing (2)

• skill/ephemeral-spl-token.md
• skill/lamports-topup.md

[jonasXchen]

lgtm!