Sol dApp Dev

intent

use this skill when you need to turn a solana product idea into a real, shippable application. covers deciding whether solana is actually the right foundation, defining the minimum viable product before code, separating on-chain from off-chain concerns, designing program accounts and authority flows, choosing a practical stack, and scaffolding a repo plan developers can execute immediately. this is for shipping real products with sensible tradeoffs, not for vague blockchain brainstorming or regulatory opinions. the assistant acts like a technical co-founder responsible for delivering a working solana product.

inputs

required context

• product idea or existing codebase (description of what the app does, primary users, step-by-step user flows)
• current stage (ideation, MVP design, existing codebase audit, or architecture improvement)
• solana cluster target (localnet, devnet, testnet, mainnet-beta)
• team capability level (experienced solana devs, first-time builders, hybrid)

required external connections

• solana rpc endpoint: env var SOLANA_RPC_URL (defaults to devnet; for production use managed provider like helius, quicknode, or triton)
• solana CLI tools: local installation of solana, anchor, solana-keygen, solana-test-validator, rustup, cargo, pnpm (see procedure step 2 for install guide)
• git repository: github or equivalent for source control and ci/cd
• npm/pnpm registry: for package management
• managed rpc provider credentials (if production): helius api key, quicknode endpoint, or triton token (env var names: HELIUS_API_KEY, QUICKNODE_URL, TRITON_TOKEN)
• database (if off-chain state required): postgres connection string (env var DATABASE_URL)
• redis (if queuing or caching): redis connection string (env var REDIS_URL, only if async jobs truly needed)
• webhook signer secret (if indexer to backend sync): env var WEBHOOK_SECRET
• deployment ci/cd: github actions, vercel, or equivalent with secrets management
• object storage (if uploads needed): aws s3, arweave, or equivalent credentials

optional inputs

• existing anchor programs or next.js codebases to audit
• specific performance or cost constraints
• third-party integrations (payment processors, analytics, custody providers)
• security requirements or threat model specifics

procedure

1) clarify the product definition (input: user narrative or pitch; output: clear product statement)

ask the user to describe:

• what the app does in plain terms (not "decentralized X", but "solves Y for Z users by doing W")
• who the primary user is and their constraints (retail trader, developer, creator, enterprise buyer, etc.)
• the step-by-step user flow (user opens app, does action 1, sees result 2, then action 3, etc.)
• why solana specifically helps (speed, cost, custody, permissionless settlement, or honest answer: "not sure yet")
• what would still work without blockchain (identify the actual blockchain-required piece)
• what is the smallest shippable version (feature cut, user cohort reduction, or launch scope)

validate that the core loop is clear. if it is not, stop and clarify before moving to architecture.

2) establish the technical baseline and install toolchain (input: team os and solana experience; output: local dev environment and repo scaffold)

guide the user through installing:

• rustup and cargo (rust toolchain manager): curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
• solana CLI: sh -c "$(curl -sSfL https://release.solana.com/v1.18.0/install)"
• solana-keygen and solana-test-validator (included with solana CLI)
• anchor via avm (anchor version manager): cargo install avm --locked && avm install latest && avm use latest
• pnpm: npm install -g pnpm
• spl-token CLI (if token accounts or minting involved): cargo install spl-token-cli

verify local setup by running solana --version and anchor --version. configure default rpc: solana config set --url devnet (or localhost for localnet dev).

3) design the system split (input: product definition; output: architecture diagram or text breakdown)

decompose the system into layers:

• on-chain program layer: rust anchor programs, account types, instructions, event emission
• backend/api layer: node.js service for business logic, signing, or coordination
• indexing or webhook sync layer: parses on-chain events and syncs state to off-chain db
• database and cache layer: postgres for durable state, redis only if caching or queues add clear value
• frontend/web or mobile app layer: next.js web app, react-native, or equivalent
• wallet and signing flows: wallet adapter integration, preflight checks, simulation
• third-party services: payment processors, analytics, storage, or external oracles

decide for each piece: is this strictly necessary for the mvp? what belongs on-chain vs off-chain?

4) design the on-chain program (input: product loop and system split; output: account types, pda strategy, instructions, events, authority model)

specify:

• account types: what data lives on-chain (e.g., user escrow account, marketplace listing, identity registry). use pdas for deterministic derivation.
• pda derivation: example seeds: [b"user", user_pubkey.as_ref()] or [b"escrow", payer.as_ref(), receiver.as_ref(), nonce.to_le_bytes()]. document why each seed is chosen.
• instructions: list each instruction (initialize, claim, settle, admin_update, etc.) with signer requirements and state changes.
• emitted events: what should be logged for indexers (user_claimed, escrow_released, score_updated, etc.). use anchor's emit! macro or raw logs.
• signer and authority rules: who can sign what (user, program, multisig, upgrade authority). be explicit about trust boundaries.
• upgrade authority model: who controls program upgrades. recommend a 2/3 multisig for production or governance if decentralization is needed.
• custody assumptions: who holds keys and how are they protected. distinguish between user wallets, server-side signers, and protocol escrows.
• rent and storage implications: calculate account size, rent per year, and whether rent exemption is required or swept.

keep account footprint minimal. omit data that can be stored off-chain or recomputed.

5) design the off-chain layer (input: on-chain design and product flow; output: api routes, workers, db schema, retry logic)

specify:

• api routes: list rest endpoints (POST /user/register, GET /user/{id}/balance, POST /escrow/settle, etc.) with request/response schemas.
• workers and queues: when async processing is truly needed (e.g., batch settlements, off-chain scoring). use bullmq or equivalent only if you have a concrete reason. most mvps do not need this.
• webhook consumers: if indexing is required, define webhook payload shape, signing secret validation, and retry logic (exponential backoff, max 10 retries, dead-letter queue).
• db tables: schema for user profiles, transaction history, audit logs, analytics. keep this schema simple for mvp.
• retry logic: how many times does a failed on-chain submission retry? what is the backoff strategy? when does the user see a permanent error?
• observability: logging, error tracking (sentry or equivalent), and metrics (transaction success rate, api latency). do not skip this.
• admin tools: simple dashboard or cli for operations (force a settlement, pause a market, view user balances). required for production.

decide: do you actually need a backend, or can the frontend sign transactions directly? if the user can sign directly and you only need to read state, you might not need a backend at all.

6) map the user transaction flow (input: product loop, on-chain design, off-chain design; output: sequence diagram or step-by-step narrative)

walk through the user experience:

• wallet connect: user opens app, clicks "connect wallet", selects a signer (phantom, ledger, marinade, etc.). app derives user account pda.
• preflight validation: app checks user balance, account state, and remaining compute budget. any blockers shown to user.
• transaction build: app constructs the solana transaction, adds instructions, sets fee payer, adds recent blockhash.
• simulation: optional but recommended: call simulateTransaction to catch errors before signing.
• signing: user reviews transaction in wallet ui and approves. wallet returns signed tx.
• submission: app submits tx to rpc. captures tx signature.
• confirmation: app polls for confirmation (skip commitment level for mvp, use default). set a timeout (30 seconds) and fall back to manual lookup.
• ui success/error states: show tx signature, block number, and success message. if failed, show reason and recovery options (retry, contact support, etc.).
• retry or recovery flow: if tx fails due to transient error (stale blockhash, network congestion), auto-retry up to 3 times with backoff. if permanent error, show user the reason and next steps.

be clear about what can go wrong: tx expires, account is locked by another operation, compute budget exceeded, etc.

7) design the build and deployment plan (input: all previous outputs; output: scoped mvp, phased roadmap, repo structure, test strategy, deployment checklist)

provide:

• mvp scope: list every feature that ships in week 1 (absolute minimum). cut everything else.
• phase 2 scope: features that ship after mvp is live (optional features, performance, secondary user flows).
• repo structure: monorepo using pnpm workspaces. defaults:
  • programs/ for anchor programs (one per subdirectory)
  • apps/web/ for next.js frontend
  • apps/api/ for node.js backend (if needed)
  • packages/sdk/ for generated idl clients and shared types
  • packages/config/ for shared environment and cluster config
  • infra/ for deployment manifests, env templates, and runbooks
  • docs/ for architecture decisions, security checklist, and deployment guide
• test plan: unit tests for programs (anchor test suite), integration tests for api (jest), e2e tests for frontend (cypress or equivalent). do not ship without these.
• deployment checklist: what must be true before shipping to mainnet (security review, testnet dry-run, runbook, emergency pause mechanism, monitoring, backup keys).
• security review checklist: missing signer checks, weak pda seeds, authority escalation, duplicate execution risk, oracle stagnation, escrow edge cases, admin abuse, indexer drift, dos vectors, upgrade compromise. identify the top 3 risks for your design and mitigate them before shipping.
• environment variables and secrets needed: see decision points below.

8) provide stack recommendations and cli commands (input: mvp scope and team experience; output: concrete tool choices and one-liners)

recommend:

• on-chain: rust + anchor, pdas for state, event emission for indexers, minimal account size
• frontend: next.js + typescript + @solana/wallet-adapter-react, responsive mobile design, explicit transaction status ui
• backend (if needed): node.js + nestjs or fastify, rest-first api, bullmq only if queuing is genuinely necessary
• data: postgres for durable state, redis only for caching or job queues, managed rpc provider for production uptime
• cli toolchain: solana, anchor, avm, rustup, cargo, pnpm, spl-token (if token operations)

provide the install and init commands:

# create solana program
anchor init my_program

# create next.js app
pnpm create next-app@latest --typescript --no-eslint --tailwind

# create nestjs backend (if needed)
npm i -g @nestjs/cli
nest new api

# local validator for dev/test
solana-test-validator

# deploy to devnet
anchor deploy --provider.cluster devnet

9) identify keys, secrets, and credentials required (input: architecture; output: categorized list of env vars and setup steps)

break down into three groups:

required immediately for mvp:

• local solana developer keypair (.config/solana/id.json; generated by solana-keygen new)
• rpc endpoint configuration (env var SOLANA_RPC_URL, default devnet)
• cluster selection (devnet for dev/test, mainnet-beta for prod)
• frontend app config (cluster, program id, rpc endpoint)

required later for production:

• managed rpc provider api key (helius, quicknode, triton; env vars HELIUS_API_KEY, QUICKNODE_URL, TRITON_TOKEN)
• database connection string (env var DATABASE_URL)
• redis connection string if queuing is used (env var REDIS_URL)
• jwt/session secret for api authentication (env var JWT_SECRET, generate with openssl rand -base64 32)
• webhook signing secret (env var WEBHOOK_SECRET, generate with openssl rand -base64 32)
• object storage credentials if uploads needed (aws s3 access key, secret, bucket name)
• analytics provider api key (optional, e.g., mixpanel token)
• ci/cd deployment secrets (github deploy key, vercel token, docker registry credentials)

not needed for this mvp (explicitly state what is not required):

• custodial signer or kms (unless you are holding user funds; most apps should not)
• governance token or dao (unless core mechanic)
• multiple programs (start with one)
• indexer infrastructure (start with rpc reads and optional webhook sync)
• load testing or k8s (premature)

document where each secret lives and who can access it. never commit secrets to git.

10) validate against solana-specific constraints (input: designed system; output: risk assessment)

reason clearly about:

• signer authority vs pda authority: if the program must enforce an action, use pda authority. if the user initiates, use signer. be explicit.
• account size and rent cost: calculate size of each account type. if over 10kb, justify. rent-exempt accounts (0.00231 sol per year). decide: is rent exempted or swept?
• transaction size constraints: solana txs are max 1232 bytes. if your instruction adds 20+ accounts or large data, you will exceed this. redesign or split into multiple txs.
• compute budget limits: default 200k cu per tx. estimate cu for your instruction (anchor overhead ~3k, program logic 50k-150k). if over 200k, use ComputeBudgetProgram::request_units() or redesign.
• replay and duplicate execution risk: if the user submits the same tx twice, does the program reject it or execute twice? use nonces or instruction-level idempotency keys.
• upgrade authority control: who can upgrade the program after launch? single keypair (risky), governance (complex), multisig (recommended for production).
• whether events are sufficient for indexing: if you emit events, can an off-chain indexer reconstruct all state from genesis? if not, you need to store more state on-chain or read raw accounts.
• whether account reads should be cached off-chain: if you read the same account 1000 times per day, cache it in redis to reduce rpc load.
• when to use one program versus multiple programs: start with one. only split if you have clear trust boundaries (user program vs governance program), upgrade cadence differences, or partner integration needs.

document the top 3 risks for your design and how you mitigate them.

decision points

does the user have a pre-existing codebase?

• if yes: inspect it first. identify working pieces to preserve. locate the most dangerous flaws (missing signer checks, oversized accounts, weak authority model). recommend incremental changes in priority order. avoid full rewrites unless the design is structurally broken.
• if no: start from scratch with the procedure above.

is solana actually justified for this product?

• if yes: solana's speed, cost, or permissionless settlement directly enables the core loop. example: low-fee payments, high-frequency trades, user-controlled escrow without intermediary.
• if no: recommend a simpler architecture (pure backend, traditional db, or a different chain). do not force solana. stating "we want to be web3" is not a reason.

does the product require trustless settlement or permissionless verification?

• if yes: more logic must be on-chain. example: peer-to-peer escrow, public reputation scoring, token minting rules.
• if no: push state and logic off-chain. example: user portfolios, notifications, admin panels, search.

does the app hold user funds or control custody?

• if yes: on-chain escrow or vault accounts required. explicit release rules, dispute paths, timeout paths, admin limitations must be coded. security review is non-optional.
• if no: simpler design. off-chain state is safe.

is the data large, verbose, or changing frequently?

• if yes: store off-chain (postgres, arweave, or ipfs). keep only proofs, hashes, or final outcomes on-chain.
• if no: can live on-chain if other constraints allow.

does the backend need to sign transactions on behalf of users?

• if yes: server-side signer required. use a kms or hardened vault. additional security review. more risk.
• if no: users sign directly via wallet. simpler, more trustless.

do you need a backend at all?

• if no: frontend can sign transactions directly and read chain state via rpc. saves infrastructure cost and complexity. works for mvp.
• if yes: you need api routes, webhooks, or async processing. justify each one.

does the mvp need an indexer?

• if no: frontend and backend read accounts directly from rpc. simpler, sufficient for early stage.