Solana subscriptions skill

Solana Subscriptions

Build bounded token-pull flows with Solana's shared Subscriptions program. Start with a deterministic plan, then implement only the chosen model against the official SDK.

Program ID: De1egAFMkMWZSN5rYXRj9CAdheBamobVNubTsi9avR44

Operating Procedure

1. Identify who defines the terms, whether the cap resets, and who pulls funds.
2. Write a planner input and run scripts/plan_subscription.py.
3. Confirm every assumption in the planner output before generating transactions.
4. Read the relevant recipe in references/sdk-recipes.md.
5. Implement the complete create, collect, cancel/revoke, query, and rent-recovery lifecycle.
6. Test on localnet or devnet. Do not use mainnet or request a real wallet signature unless the user explicitly asks.
7. Report the selected model, signers, accounts, base-unit amounts, lifecycle, and test evidence.

Choose the Model

Need	Model	Terms set by	Typical examples
One total cap, optionally expiring	Fixed delegation	User	Agent budget, capped checkout, one-time allowance
Cap resets each period	Recurring delegation	User	Payroll, contractor payments, recurring agent budget
Reusable merchant tier accepted by many users	Subscription plan	Merchant	SaaS, API tier, membership

When the request is ambiguous, ask:

• Does the allowance reset?
• Does the user or merchant define the amount and cadence?
• Is this a reusable public tier or a bilateral agreement?
• Who is allowed to pull, and where may funds land?
• What ends the authorization?

Read references/decision-guide.md for lifecycle and operational tradeoffs.

Plan Before Coding

Create a JSON file:

{
  "use_case": "agent_budget",
  "token_program": "spl-token",
  "amount": "25.00",
  "token_decimals": 6,
  "expiry_ts": 1789000000,
  "nonce": 0
}

Run:

python3 scripts/plan_subscription.py --spec plan.json

The planner rejects ambiguous decimal amounts, missing cadence, incompatible token settings, and unsupported memo-required destinations. Treat its JSON as an implementation checklist, not as a transaction.

Implementation Rules

• Use decimal strings at product boundaries and bigint base units in transaction code. Never use JavaScript floating-point numbers for token amounts.
• Initialize one Subscription Authority per (user, mint) and reuse it.
• Use the real stored init_id when available. Do not treat close-and-recreate as revocation; revoke the specific delegation or cancel the subscription.
• Treat a successful plan or delegation creation as authorization, not proof that future collection will succeed. Balances, approvals, freezes, and token-account existence can change.
• Keep collection idempotent off-chain. Persist the billing period and transaction signature before granting service.
• Model failed pulls and delinquency in the application database; the on-chain subscription does not do this for the application.
• Make cancellation, revoke, and rent recovery visible product flows.
• For Token-2022, test the exact mint extensions and transfer-hook account resolution. Reject memo-required destination accounts unless the official program adds support.
• Pin package versions in examples and state which version was verified. This skill's recipes were checked against @solana/subscriptions 0.4.0.

Required Test Matrix

At minimum, cover:

• exact base-unit conversion;
• maximum allowed pull and one-unit-over rejection;
• expiry or period-boundary behavior;
• unauthorized puller rejection;
• cancellation or revoke;
• insufficient balance or removed approval;
• duplicate collection-worker retry;
• rent recovery;
• Token-2022 extension behavior when applicable.

Prefer the upstream repository's local Surfpool/LiteSVM tests for program-level verification. Application tests may mock RPC only when they still assert instruction inputs and idempotency state.

Deliverable Format

Return:

• selected model and why;
• authority, delegatee/puller, receiver, payer, and required signers;
• human amount, token decimals, and exact base units;
• account and instruction lifecycle;
• collection-worker and retry behavior;
• cancellation/revoke path;
• tests run and remaining external proof.

References

• Read references/decision-guide.md for model selection, account topology, lifecycle, rent, and production operations.
• Read references/sdk-recipes.md for official TypeScript SDK setup and instruction shapes.
• Read references/source-index.md before updating version-sensitive facts.