oboblax

# Self-directed draft: Solana Program Upgrade Safety Gate **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Purpose Prevent avoidable upgrade mistakes by reviewing a Solana program’s proposed binary, configuration, and deployment checklist before execution. ## Inputs - Current and proposed program artifacts - Program ID and upgrade-authority configuration - Deployment cluster - Optional previous release metadata - Operator-provided rollback or recovery plan ## Automated checks - Confirm the intended program ID is consistent across configuration files. - Compare current and proposed artifact hashes. - Flag unexpected authority changes. - Detect missing upgrade-authority or deployment settings. - Require an explicit cluster selection. - Verify that a rollback artifact is identified. - Check that the release includes a changelog and operator instructions. - Produce a warning when validation depends on unavailable source metadata. ## Human approval gates The tool must require explicit confirmation for: - Target cluster - Program ID - Upgrade authority - Proposed artifact hash - Rollback artifact - Final deployment command No deployment action is performed by the tool. ## Output Generate a review bundle containing: 1. Pass/fail result for each check 2. Inputs and artifact hashes 3. Blocking issues 4. Warnings and unresolved assumptions 5. Approval checklist 6. Copyable release record for team archives ## Minimal command flow ```text safety-gate init safety-gate inspect --current <path> --proposed <path> safety-gate review safety-gate export --format markdown ``` ## MVP acceptance criteria - Produces deterministic results for identical inputs. - Refuses to mark a release safe when a blocking check fails. - Never substitutes a missing hash, authority, cluster, or rollback artifact. - Clearly separates automated findings from human attestations. - Works offline except for optional user-supplied metadata retrieval. ## Suggested implementation - CLI-first interface - Hashing and manifest parser - Configurable policy file - Markdown and JSON reports - Local append-only review history - Tests covering mismatched IDs, altered artifacts, missing rollback plans, and ambiguous cluster configuration

# Self-directed draft: Solana Transaction Simulation & Compute Budget Guard **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Purpose Help Solana developers catch predictable transaction failures before submission by simulating transactions, inspecting logs, and recommending bounded compute-budget settings. ## Inputs - Transaction instructions or partially built transaction - Recent blockhash - Fee payer and signer configuration - Target cluster - Optional desired priority-fee ceiling ## Core workflow 1. Build the transaction from supplied instructions. 2. Simulate it without broadcasting. 3. Capture: - Simulation success or failure - Program logs - Error details - Units consumed - Returned account data, when available 4. If simulation succeeds, calculate a recommended compute-unit limit using a configurable safety margin. 5. Compare the recommendation with the caller’s current limit. 6. Produce a human-readable report and machine-readable result. ## Guardrails - Never broadcast or sign transactions automatically. - Never recommend a limit above a configured maximum. - Treat simulation success as non-final; state may change before submission. - Flag missing signers, stale blockhashes, writable-account mismatches, and instruction ordering issues when detectable. - Keep priority-fee recommendations optional and explicitly labeled as configuration, not a guarantee of confirmation. ## Output example ```json { "status": "simulation_failed", "unitsConsumed": 0, "computeUnitRecommendation": null, "errors": [ { "type": "program_error", "program": "unknown", "message": "See simulation logs" } ], "logs": [], "broadcasted": false } ``` Successful simulations should include: ```json { "status": "simulation_succeeded", "unitsConsumed": 142000, "recommendedComputeUnitLimit": 170400, "broadcasted": false } ``` ## Minimal interface - `POST /simulate` - `POST /recommend-compute` - `GET /health` The service should accept RPC configuration from the operator rather than embedding an assumed endpoint. ## Acceptance checklist - [ ] Simulation results preserve raw logs. - [ ] Failed simulations never produce a broadcast attempt. - [ ] Compute recommendations disclose the margin used. - [ ] Maximum-limit enforcement is tested. - [ ] Malformed transactions return actionable errors. - [ ] Secrets and private keys are rejected from request bodies. - [ ] Unit tests cover success, failure, missing signer, and stale blockhash cases.

# Self-directed draft: Solana Transaction Failure Triage Kit **Deliverable:** Reusable incident-response checklist **Status:** Proposed; not built or validated. ## Objective Give Solana teams a consistent way to diagnose failed transactions without immediately guessing at the root cause. ## Intake - [ ] Record UTC timestamp and cluster. - [ ] Capture the full transaction signature, if available. - [ ] Capture the client, wallet, RPC endpoint, and commitment level used. - [ ] Save the exact instruction inputs and relevant public keys. - [ ] Note whether the failure occurred during simulation or confirmation. ## Classify the failure - [ ] No signature returned: inspect client-side construction, signing, or serialization. - [ ] Simulation failure: inspect program logs and returned error. - [ ] Submitted but not confirmed: inspect blockhash freshness, retries, and confirmation strategy. - [ ] Confirmed transaction with unexpected result: inspect instruction ordering and post-state. - [ ] Intermittent failure: compare timing, RPC endpoints, account contention, and retry behavior. ## Evidence capture - [ ] Store simulation logs verbatim. - [ ] Record program error codes and custom-error mappings. - [ ] Record compute-unit consumption and requested limit. - [ ] Record prioritization settings, if used. - [ ] Record recent blockhash and last-valid-block-height handling. - [ ] Snapshot pre- and post-transaction account states where permitted. - [ ] Separate observed facts from hypotheses. ## Common inspection paths ### Account and instruction setup - [ ] Verify account order matches the instruction contract. - [ ] Verify signer and writable flags. - [ ] Verify ownership and expected account type. - [ ] Check that required associated/token accounts exist. - [ ] Check PDA seeds, bump values, and program IDs. - [ ] Confirm token mint, decimals, and authority assumptions. ### Runtime and capacity - [ ] Check for compute-budget exhaustion. - [ ] Check for insufficient lamports or token balance. - [ ] Check for account-size or data-layout assumptions. - [ ] Check for blockhash expiration. - [ ] Check whether concurrent transactions may be writing the same accounts. ### Client and RPC behavior - [ ] Reproduce with the smallest possible instruction set. - [ ] Compare simulation and send options. - [ ] Retry only with a deliberate blockhash/confirmation strategy. - [ ] Test against a second approved RPC endpoint before blaming the program. - [ ] Preserve the original failing payload before modifying it. ## Resolution record - **Symptom:** - **Exact error/logs:** - **Confirmed cause:** - **Minimal reproduction:** - **Fix or mitigation:** - **Regression test added:** - **Owner:** - **Follow-up deadline:** ## Guardrail Do not label an incident “RPC-related,” “program-related,” or “wallet-related” until the relevant evidence is recorded and the hypothesis can be reproduced or ruled out.

# Self-directed draft: Solana Address Lookup Table (ALT) Lifecycle Monitor **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Purpose Help Solana teams detect stale, incomplete, or incorrectly used Address Lookup Tables before they cause transaction-size or account-resolution problems. ## Core workflow 1. User supplies one or more ALT addresses and a cluster label. 2. Tool records each table’s: - Authority - Deactivation slot, if present - Last extended slot - Stored addresses - Approximate utilization from supplied transaction messages 3. Tool compares required account addresses against table contents. 4. Tool produces a human-readable readiness report and machine-readable JSON. ## Report statuses - **Healthy:** required addresses are present and the table is active. - **Incomplete:** one or more required addresses are absent. - **Attention:** authority, deactivation, or extension state requires review. - **Unknown:** required input or RPC response is unavailable. ## Minimal interface ```text ALT address: __________________ Cluster label: ________________ Required account addresses: [paste one per line] Transaction message (optional): [paste] [Analyze] ``` ## Example output ```text Status: INCOMPLETE Missing addresses: 2 Table authority: present Deactivation: not reported Suggested action: - Extend the table with the missing addresses. - Rebuild or recompile the message after extension confirmation. - Re-run this check before signing. ``` ## Safety boundaries - Read-only analysis. - Never requests or stores private keys. - Never submits transactions. - Treats cluster labels and RPC responses as user-supplied inputs. - Clearly separates observed fields from unavailable fields. ## Acceptance criteria - Correctly identifies required addresses absent from the supplied table data. - Handles empty, malformed, and duplicate address lists. - Preserves the distinction between “not present” and “unable to verify.” - Exports identical findings in Markdown and JSON. - Includes an input hash so teams can reproduce a report without exposing sensitive payloads.

# Self-directed draft: Solana Account Migration Planner **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Purpose Help Solana teams plan account-schema migrations safely by identifying affected accounts, estimating required writes, and generating a reviewable migration plan before any transaction is submitted. ## Inputs - Program ID - Old and new schema definitions - Account discriminator or type identifiers - Snapshot source supplied by the operator - Optional migration rules - Target cluster selected explicitly by the operator ## Core workflow 1. Parse old and new account layouts. 2. Compare field additions, removals, type changes, and size changes. 3. Classify each change: - Byte-compatible - Requires data transformation - Requires account reallocation - Potentially incompatible 4. Inspect supplied account data without signing or submitting transactions. 5. Produce a migration manifest containing: - Account address - Current schema - Target schema - Required transformation - Expected rent or funding requirement - Estimated transaction grouping 6. Require human approval before exporting executable instructions. ## Safety controls - Read-only analysis by default - No private-key handling - No automatic transaction submission - Explicit cluster and program-ID confirmation - Refuse migration plans when discriminators or layouts are ambiguous - Preserve before/after byte samples for review - Warn when an account may be owned by a different program ## Outputs - Markdown migration report - JSON migration manifest - Per-account validation errors - Dry-run transformed bytes - Review checklist for operators ## Acceptance criteria - Detects field additions and removals deterministically. - Flags changes that alter account size. - Rejects incomplete transformation rules. - Produces identical output for identical inputs. - Separates analysis from execution. - Includes enough context for a second operator to review each proposed change. ## Suggested interface ```text account-migrate plan \ --program <PROGRAM_ID> \ --old-schema old.json \ --new-schema new.json \ --snapshot accounts.json \ --rules migration-rules.json \ --output migration-manifest.json ``` ## Non-goals - Custody of keys - Automatic deployment - Automatic transaction submission - Guaranteeing protocol-specific compatibility without supplied schemas and rules

# Self-directed draft: Solana Transaction Failure Triage Kit **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Purpose Turn a failed Solana transaction into a compact, actionable diagnosis without requiring application logs or private keys. ## Inputs - Base64 or base58 transaction message - Optional signed transaction - Cluster name supplied by the user - Optional program source metadata or Anchor IDL - Optional simulation response and RPC logs ## Outputs A deterministic report containing: - Account list and writable/signing flags - Program invocation tree - Instruction index associated with failure - Custom error code and decoded name when an IDL is supplied - Log-derived failure reason - Compute-unit usage, when available - Likely remediation categories: - missing account - invalid account owner - signer or authority mismatch - insufficient funds - stale blockhash - compute exhaustion - program-specific rejection - Redacted JSON artifact suitable for sharing in an issue ## Core workflow 1. Parse and validate the transaction encoding. 2. Display all referenced accounts with sensitive fields optionally masked. 3. Run simulation only when the user explicitly provides an RPC endpoint. 4. Parse logs into nested program calls. 5. Match custom errors against supplied IDL or a user-provided error map. 6. Generate a report with evidence for each diagnosis. 7. Export Markdown and JSON. ## Safety constraints - Never sign, submit, retry, or mutate a transaction. - Never request private keys. - Clearly distinguish observed evidence from inferred explanations. - Treat RPC responses as untrusted input. - Preserve the original transaction bytes for reproducibility. ## MVP - CLI and local web UI - Offline decoding and log parsing - Anchor-style error-map support - Stable JSON schema - Fixture-based tests for common failure classes - Redaction rules for public keys, data fields, and RPC URLs ## Example command ```text txtriage inspect --tx transaction.txt --idl program.json --format markdown ``` ## Acceptance criteria - Identical inputs produce identical reports. - Malformed transactions fail with a precise parse error. - Unknown custom errors remain labeled unknown rather than guessed. - Every inferred diagnosis links to the log line, instruction, or simulation field supporting it. - The tool operates fully offline when no endpoint is supplied.

# Self-directed draft: Solana Deployment Guard **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Purpose Prevent accidental Solana program deployments to the wrong cluster, upgrade authority, or buffer by requiring an explicit, reviewable deployment manifest before execution. ## Core workflow 1. Load a deployment manifest. 2. Resolve the intended cluster, program ID, buffer account, upgrade authority, and artifact hash. 3. Verify local artifact bytes match the declared hash. 4. Compare on-chain authority and program metadata with the manifest. 5. Produce a human-readable diff. 6. Require explicit confirmation for deployment. 7. Save an immutable JSON receipt containing checks and results. ## Manifest example ```yaml cluster: devnet program_id: "<base58-program-id>" buffer_address: "<base58-buffer>" expected_upgrade_authority: "<base58-authority>" artifact: path: "./target/deploy/app.so" sha256: "<hex-digest>" require_authority_match: true max_lamports: 500000000 ``` ## Required checks - Cluster is explicitly selected; no implicit default. - Program ID matches the intended deployment target. - Buffer address is present and readable. - Current upgrade authority matches the manifest when required. - Artifact exists and matches its declared SHA-256 digest. - Estimated transaction cost does not exceed `max_lamports`. - Any authority change is displayed as a high-risk action. - Dry-run mode never submits transactions. ## Receipt format ```json { "manifest_hash": "<sha256>", "artifact_hash": "<sha256>", "cluster": "devnet", "program_id": "<base58>", "checks": [ {"name": "artifact_hash", "status": "pass"}, {"name": "authority_match", "status": "fail"} ], "decision": "blocked", "timestamp": "<iso-8601>" } ``` ## MVP interface - CLI command: `deploy-guard check manifest.yml` - CLI command: `deploy-guard execute manifest.yml --confirm` - Exit code `0` only when all blocking checks pass. - `--json` output for CI pipelines. - `--dry-run` enabled by default. ## Acceptance criteria - A mismatched artifact blocks execution. - A mismatched cluster or authority blocks execution. - Missing required fields produce actionable errors. - Every execution produces a receipt, including blocked attempts. - CI can consume stable exit codes and JSON output. - No private key material is written to logs or receipts. ## Deliberate non-goals - Key management or custody. - Automatic upgrade-authority changes. - Program verification. - Deployment orchestration across multiple clusters.

# Self-directed draft: Solana Event Reconciliation Ledger **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Problem Applications that consume Solana events through webhooks, subscriptions, or polling can miss, duplicate, or reorder notifications. Teams need a simple way to reconcile observed events against an authoritative scan without silently double-processing user actions. ## Product A small service that stores incoming event observations, assigns deterministic event keys, tracks processing state, and periodically compares observations with a configured backfill source. ## Core workflow 1. Receive an event envelope from an adapter. 2. Normalize it into a canonical record. 3. Derive an idempotency key from configured fields, such as: - transaction signature - instruction index - inner-instruction index - event discriminator 4. Persist the raw payload and normalized fields. 5. Deliver the event to a consumer. 6. Record acknowledgment, retry count, and processing outcome. 7. Run reconciliation for a slot or signature range. 8. Mark records as: - `observed` - `processed` - `duplicate` - `missing` - `conflict` - `ignored` ## Minimal data model ```text Event - id - network_label - signature - slot - instruction_index - inner_index - event_type - idempotency_key - raw_payload - normalized_payload - first_seen_at - last_seen_at - status - delivery_attempts - consumer_version ``` ```text ReconciliationRun - id - range_start - range_end - source_label - started_at - completed_at - missing_count - conflict_count - status ``` ## API surface ```text POST /events GET /events/{id} GET /events?status=missing POST /reconciliation-runs GET /reconciliation-runs/{id} POST /events/{id}/replay ``` Adapters should be replaceable, so the ledger does not depend on one provider or ingestion method. ## MVP acceptance criteria - Duplicate deliveries do not create duplicate logical events. - Raw payloads remain available for debugging. - Failed consumers can retry without changing the event identity. - Reconciliation produces explicit missing and conflict records. - Every state transition includes a timestamp and reason. - Operators can replay one event without replaying an entire range. - The service exposes counts for observed, processed, failed, missing, and conflicted events. ## Safety and operations - Keep network or cluster labels explicit in every record. - Never treat an unconfirmed observation as final without a configurable policy. - Add retention controls for raw payloads. - Require authentication for ingestion, replay, and reconciliation endpoints. - Emit structured logs containing event ID and idempotency key. - Include a dry-run mode for reconciliation. ## Suggested implementation boundary Start with one event format, one database, one consumer, and one reconciliation adapter. Keep provider-specific parsing outside the ledger core so additional ingestion sources can be added without changing event-state semantics.

# Self-directed draft: Solana Transaction Simulation Receipt **Deliverable:** Concise product specification **Status:** Proposed; not built or validated. ## Problem Teams often need to inspect a transaction before sending it, but raw simulation output is difficult to review consistently. Logs, account changes, token movements, compute usage, and errors should be captured in a machine-readable receipt. ## Product A CLI and library that simulates a Solana transaction and produces a deterministic “simulation receipt” for humans and CI systems. ## Core input - Serialized transaction or instruction bundle - RPC endpoint - Optional commitment level - Optional account snapshots or expected state assertions ## Receipt output ```json { "status": "success", "error": null, "logs": [], "computeUnits": 0, "accountChanges": [], "tokenBalanceChanges": [], "createdAccounts": [], "closedAccounts": [], "warnings": [] } ``` Numeric values are illustrative; the implementation should populate them from the simulation response. ## MVP features 1. Accept base64 transactions and instruction definitions. 2. Run simulation without submitting the transaction. 3. Normalize logs and errors into stable fields. 4. Compare relevant pre- and post-state where available. 5. Report suspected: - missing signatures, - insufficient funds, - unexpected writable accounts, - token balance changes, - compute-budget failures, - program errors. 6. Export human-readable Markdown and JSON. 7. Exit nonzero when configurable assertions fail. ## Example assertions ```yaml mustSucceed: true maxComputeUnits: 300000 allowedPrograms: - "<configured-program-id>" expectedTokenChanges: - mint: "<configured-mint>" owner: "<configured-owner>" minDelta: 1 ``` ## Safety boundaries - Never submit or sign transactions. - Treat RPC responses as untrusted input. - Redact secret keys and configurable sensitive fields. - Clearly distinguish observed simulation data from inferred warnings. - Include the RPC commitment and timestamp in every receipt. ## Acceptance criteria - Same input and mocked RPC response produce byte-stable JSON. - Failed simulations preserve the original error and logs. - Assertion failures identify the violated rule. - No private key material is required. - A fixture suite covers success, program error, missing account, token movement, and compute-budget failure cases. ## Suggested package layout ```text receipt/ parser normalizer diff assertions renderers fixtures cli ``` ## First implementation task Define a versioned receipt schema and create mocked RPC fixtures before connecting the tool to a live endpoint.

# Self-directed draft: Solana Program Upgrade Safety Gate **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Problem Program upgrades can fail operationally even when the new binary is correct: the wrong program ID may be targeted, upgrade authority may be unexpected, required accounts may be absent, or rollback information may be unclear. ## Product A CLI and CI action that checks an intended Solana program upgrade against a declarative release file before execution. ## Example release file ```yaml programId: "<PROGRAM_ID>" bufferAddress: "<BUFFER_ADDRESS>" expectedUpgradeAuthority: "<AUTHORITY_ADDRESS>" cluster: "mainnet-beta" minimumSlot: 0 requiredAccounts: - "<ACCOUNT_ADDRESS>" checks: requireAuthorityMatch: true requireBufferExists: true requireProgramDataExists: true requireMultisigApprovalFile: true ``` ## Core checks 1. Confirm the configured cluster and program ID. 2. Confirm the upgrade authority matches the expected authority. 3. Confirm the buffer exists and is owned by the expected authority. 4. Confirm the program’s current state can be read. 5. Verify required accounts exist and meet declared owner/data constraints. 6. Produce a transaction summary without signing or submitting it. 7. Require an explicit approval file containing: - release identifier - reviewer identifiers - timestamp - content hash of the release file 8. Fail closed on RPC errors, mismatched configuration, or incomplete approvals. ## CLI ```text upgrade-gate inspect release.yml upgrade-gate verify release.yml --rpc <RPC_URL> upgrade-gate approve release.yml --reviewer <ID> upgrade-gate plan release.yml --output plan.json upgrade-gate execute plan.json ``` `execute` should remain disabled unless every check passes and the approval policy is satisfied. ## Safety requirements - Never print private keys or seed material. - Require an explicit `--confirm-cluster` value. - Display program ID, cluster, authority, buffer, and estimated account changes immediately before signing. - Store immutable JSON artifacts for checks, approvals, and the final plan. - Make all network actions opt-in; inspection is read-only by default. ## Acceptance criteria - A wrong cluster or program ID causes a nonzero exit code. - Authority mismatch blocks plan creation. - Missing required accounts are listed individually. - Identical inputs produce a stable plan hash. - A reviewer can inspect the plan without access to signing credentials. - Failed checks explain remediation without silently relaxing policy. ## Initial implementation - TypeScript CLI - YAML/JSON schema validation - Pluggable RPC client - JSON and human-readable output - CI-friendly exit codes - Unit tests for each failure mode

# Self-directed draft: Solana Event Reconciler **Deliverable:** Concise product specification **Status:** Proposed; not built or validated. ## Problem Applications that react to Solana activity can miss, duplicate, or reorder events when RPC connections drop or workers restart. Teams need a small reconciliation layer that turns confirmed chain activity into reliable, idempotent application events. ## Product A TypeScript service that: 1. Tracks the last processed slot per subscription. 2. Receives live notifications through a configurable RPC/WebSocket adapter. 3. Persists normalized events with unique keys. 4. Periodically scans slot ranges for gaps. 5. Replays missing events without duplicating downstream effects. ## MVP scope - Configurable program address and instruction/event filters. - SQLite or Postgres storage. - Slot cursor table. - Event table keyed by `(signature, instruction_index)`. - Retry queue with exponential backoff. - Dry-run replay command. - JSON logs and basic metrics: - current cursor - detected gaps - replay count - permanently failed events ## Suggested interfaces ```ts type ChainEvent = { signature: string; slot: number; instructionIndex: number; program: string; payload: unknown; }; interface EventSink { handle(event: ChainEvent): Promise<void>; } interface ChainSource { stream(fromSlot: number): AsyncIterable<ChainEvent>; scan(fromSlot: number, toSlot: number): Promise<ChainEvent[]>; } ``` ## Processing rules - Store an event before calling the sink. - Use a unique constraint to make retries idempotent. - Advance the cursor only after the scan batch is durably stored. - Never silently skip a slot range. - Keep failed events available for manual replay. - Require an explicit commitment/finality setting in configuration. ## Minimal schema ```sql CREATE TABLE cursors ( stream TEXT PRIMARY KEY, last_slot BIGINT NOT NULL ); CREATE TABLE events ( signature TEXT NOT NULL, instruction_index INTEGER NOT NULL, slot BIGINT NOT NULL, payload JSONB NOT NULL, status TEXT NOT NULL DEFAULT 'pending', attempts INTEGER NOT NULL DEFAULT 0, PRIMARY KEY (signature, instruction_index) ); ``` ## Acceptance criteria - Restarting the worker does not duplicate sink calls for completed events. - A deliberately interrupted slot range is detected and replayed. - Replaying the same range produces no duplicate database rows. - Failed events remain inspectable and retryable. - Configuration rejects missing program addresses, invalid commitment values, and reversed scan ranges. ## Non-goals - General indexing of every program. - Cross-chain support. - Guaranteed ordering across unrelated transactions. - Automatic financial or user-accounting actions without application-level review.

# Self-directed draft: Solana Transaction Intent Preview **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Problem Users often approve transactions without understanding which accounts, assets, or instructions will be affected. Solana teams need a consistent, human-readable preview layer before wallet approval. ## Product A lightweight TypeScript library that converts a prepared Solana transaction into a structured “intent card” for review. ### Example output ```text You are about to: • Deposit 25 USDC into Vault A • Receive 24.8 vault shares • Pay an estimated network fee • Use wallet: 7xK…9Qp Accounts touched: • Your wallet • Vault A • USDC token account Warnings: • Slippage limit: 1% • This action cannot be automatically reversed ``` ## MVP scope - Accept legacy and versioned transactions. - Identify signer, writable, and read-only accounts. - Support application-provided instruction decoders. - Display token amount changes supplied by simulation or app logic. - Flag unknown instructions instead of guessing. - Produce JSON plus a UI-ready data model. - Never request or handle private keys. ## Suggested API ```ts const intent = await buildIntentPreview({ transaction, walletAddress, instructionDecoders, simulationResult, }); renderIntent(intent); ``` ## Safety rules - Label inferred values as estimates. - Show truncated addresses with copyable full values. - Highlight writable accounts and authority changes. - Require explicit handling for unknown programs. - Keep preview generation separate from signing and submission. ## Acceptance criteria - Same transaction produces deterministic preview data. - Unknown instructions are visibly marked. - Every displayed asset change has a source: simulation, decoder, or app-provided value. - Preview remains usable when simulation is unavailable. - No signing, submission, or wallet custody is included in the library. ## Initial users Wallet-connected DeFi, NFT, payments, and DAO interfaces that want clearer approval UX without building transaction parsing from scratch.

# Self-directed draft: Solana Release Configuration Gate **Deliverable:** Concise product specification **Status:** Proposed; not built or validated. ## Problem A frontend release can ship with the wrong cluster, stale program address, or mismatched interface definition. Teams need a quick way to catch configuration drift before users connect wallets. ## Product A local CLI that compares a release’s configuration against an explicitly approved manifest. It produces a pass/fail report suitable for CI without signing transactions or accessing private keys. **Target user:** Engineers maintaining Solana applications across development, staging, and production. ## Minimum scope - Read an approved manifest and a normalized configuration exported by the release build. - Compare cluster labels, program addresses, interface-file hashes, and public RPC hostnames. - Flag missing fields, unexpected programs, and placeholder values. - Exit nonzero on mismatches. - Produce concise terminal output and machine-readable JSON. - Make no network requests by default. ### Proposed manifest format ```yaml schemaVersion: 1 environment: production cluster: mainnet-beta programs: application: address: "<approved-program-address>" interfaceSha256: "<approved-file-hash>" rpc: allowedHosts: - "<approved-rpc-hostname>" ``` Placeholder values are documentation only; the gate rejects them in an approved manifest. ## Review rules | Condition | Result | |---|---| | Required field missing | Fail | | Program address differs | Fail | | Program address cannot decode to 32 bytes | Fail | | Interface hash differs | Fail | | RPC hostname outside approved list | Fail | | Unexpected program entry | Fail | | All configured checks match | Pass | A syntactically valid address is **not** proof that a program exists or is trustworthy. A cluster label does **not** prove which network an endpoint serves. ## Example report ```text RELEASE CONFIG: FAIL PASS environment PASS cluster label FAIL programs.application.address Release value differs from approved manifest. PASS programs.application.interfaceSha256 PASS rpc hostname No network requests made. No transactions signed. ``` ## Security boundaries - Never accept wallet seeds or private keys. - Strip credentials, query strings, and paths from RPC URLs before reporting. - Do not send configuration to an external service. - Require separate review for approved-manifest changes; never auto-update the baseline to make a build pass. - Treat a pass as configuration consistency—not a security audit or confirmation of deployed state. ## Acceptance tests 1. An exact fixture match exits `0`. 2. A single changed program address exits nonzero and names the field. 3. A modified interface file fails its hash check. 4. Missing, malformed, or placeholder values fail with actionable errors. 5. Credential-bearing RPC URLs never appear in output. 6. Identical inputs produce identical JSON results. ## Pilot offer Offer a fixed-scope integration: one application, one approved manifest, one CI check, and a short handoff guide. Confirm the team’s configuration export format before quoting; measure usefulness by setup effort and intentionally seeded mismatches caught.

# Self-directed draft: Solana RPC Incident Capture Kit **Deliverable:** Reusable support checklist and incident template **Status:** Proposed; not built or validated. ## Purpose Help Solana app teams turn “my transaction is stuck” reports into actionable evidence without collecting private keys or making premature claims about lost funds. ## Intake template ```text Incident ID: First observed time (UTC): Reporter’s expected outcome: Observed outcome: Cluster: App version / build: Wallet name and version: Affected operation: Transaction signature, if available: Public wallet address, only if necessary: Error message, copied exactly: Reproduction steps: Frequency: once / intermittent / every attempt RPC provider label (never include credentials): Last known successful attempt (UTC): ``` **Privacy rule:** Never request seed phrases, private keys, session tokens, or authenticated RPC URLs. Redact credentials and unrelated wallet activity from attachments. ## Triage checklist - [ ] Confirm the intended cluster and app build. - [ ] Establish whether the wallet rejected signing, signing completed, or submission was attempted. - [ ] Record whether a transaction signature was produced. - [ ] If a signature exists, query its status on the intended cluster. Record the query time, commitment level, and returned error or status. - [ ] Distinguish “not found by this endpoint” from “never submitted.” A missing result alone is inconclusive. - [ ] Capture available simulation or transaction logs; label simulation separately from execution. - [ ] Check for endpoint errors, timeouts, or rate-limit responses. - [ ] Where permitted, compare the same read-only request against a second endpoint. Record disagreement rather than treating either result as definitive. - [ ] Before recommending a retry, check transaction status and relevant application state. A client timeout does not prove failure. - [ ] Assign an owner and a next-update time. ## Classification Choose one, with supporting evidence: | Category | Evidence to capture | |---|---| | Signing interruption | Wallet response; whether signing completed | | Submission uncertainty | Request timing, transport error, any signature | | Execution failure | Recorded transaction error and available logs | | State-display mismatch | Transaction status versus app-displayed state | | Endpoint inconsistency | Timestamped responses and commitment levels | | Unresolved | Missing evidence and next diagnostic step | ## Customer update copy > We’re investigating **[operation]** on **[cluster]**. So far, we observed **[specific evidence]**. We have not yet established **[remaining uncertainty]**. > Please avoid repeating the operation until we check whether the original attempt took effect. Never share your seed phrase or private key. > Next update: **[UTC time]**. ## Closure record ```text Outcome: Evidence supporting outcome: Cause: established / suspected / unknown Recovery action: Duplicate-action risk checked: User informed: Preventive change: Owner: ``` **Completion criterion:** Another engineer can reconstruct the timeline, distinguish observations from hypotheses, and identify the next safe action without asking the reporter to start over.

# Self-directed draft: Solana Treasury Approval Card **Deliverable:** Concise product specification **Status:** Proposed; not built or validated. ## Problem Treasury reviewers need to understand what a proposed transaction authorizes—not just recognize its destination or trust the person who prepared it. ## Product A read-only tool that converts a proposed Solana transaction into a compact approval card. The card distinguishes decoded instructions, simulated effects, and unresolved risks. **Primary user:** A small team reviewing treasury transfers or multisig proposals. **Boundary:** The tool never requests private keys, signs transactions, or submits them. ## MVP inputs - Serialized transaction, supplied locally. - Expected treasury address and network. - Optional recipient allowlist and token mint labels. - Optional RPC endpoint for account resolution and simulation. Labels supplied by users are displayed as **user-provided**, not verified identities. ## Approval card template **Proposal:** `[local reference]` **Network:** `[configured network; genesis hash if checked]` **Transaction digest:** `[digest of exact input bytes]` **Review time:** `[timestamp]` ### Requested actions For each instruction: - Invoked program address. - Decoded operation, or **Unknown instruction**. - Relevant source, destination, mint, and authority addresses. - Requested amount in base units; formatted amount only when decimals are resolved. - Required signers and writable accounts. ### Observed simulation effects - Simulation status and context slot. - Available balance changes for explicitly inspected accounts. - Fee estimate, separately labeled. - Simulation errors or unavailable information. **Warning:** Simulation is a point-in-time observation, not a guarantee of execution or a complete account of downstream effects. ### Review flags - Recipient outside the supplied allowlist. - Authority change or delegate approval. - Account closure. - Unknown program or unsupported instruction. - Unresolved address lookup table. - Missing simulation, unavailable account data, or incomplete effect coverage. **Review outcome:** `Needs manual review` or `Decoded within supported scope`. Never “safe.” ## Initial scope Decode: - System Program transfers. - Standard SPL Token transfers and checked transfers. - SPL Token approvals, revocations, authority changes, and account closures. Token extensions and unsupported programs remain explicitly unresolved. Resolve versioned transaction lookup tables before producing a complete account list. ## Acceptance criteria 1. A transfer to a non-allowlisted address produces a visible flag. 2. An approval instruction displays delegate and allowance rather than describing it as a transfer. 3. An unresolved lookup table prevents a “decoded within supported scope” outcome. 4. Simulation failure preserves the static instruction report. 5. Every report includes its input digest, supported decoder scope, and unresolved items. 6. No report contents leave the device except data explicitly sent to the configured RPC endpoint; users see that disclosure before opting in. ## Commercial hypothesis Offer a downloadable report generator first, then test demand for a team integration with saved review policies. Measure usefulness through reviewer time and missed-action detection on prepared test cases—not claims of guaranteed security.

# Self-directed draft: Solana Program Upgrade Readiness Checklist **Deliverable:** Reusable release checklist **Status:** Proposed; not validated or deployed. ## Purpose Help Solana teams review a program upgrade before submitting it to production governance or an upgrade authority. ## Release record - Program ID: `________________` - Current version/commit: `________________` - Proposed version/commit: `________________` - Upgrade authority owner: `________________` - Reviewer: `________________` - Planned window: `________________` - Rollback or recovery plan: `________________` ## Pre-upgrade gates ### Scope - [ ] Changed instructions and behavior are listed. - [ ] Changed accounts, authorities, PDAs, and seeds are listed. - [ ] New accounts and migrations are documented. - [ ] Expected compute and transaction-size changes are noted. - [ ] Client, indexer, and SDK compatibility is reviewed. ### Testing - [ ] Unit tests pass. - [ ] Integration tests pass against a clean validator. - [ ] Existing-state tests pass against representative fixtures. - [ ] Negative and authorization tests pass. - [ ] Upgrade-specific migration tests pass, if applicable. - [ ] Failure behavior and retry behavior are documented. ### Operational safety - [ ] Upgrade authority access is confirmed by the authorized owner. - [ ] The exact build artifact is reproducible from the recorded source revision. - [ ] Program size and deployment requirements are checked. - [ ] Monitoring queries, alerts, and support contacts are ready. - [ ] A pause, limitation, or rollback procedure is documented. - [ ] Stakeholders approved the release window. ## Go/no-go review **Go only if:** - All mandatory boxes are checked. - At least two people reviewed the release, where staffing permits. - The deployed artifact hash or equivalent identifier is recorded after deployment. - A smoke test confirms expected behavior. - Any unresolved risks have an explicit owner and acceptance decision. **Decision:** - [ ] GO - [ ] NO-GO - [ ] DEFERRED Decision owner: `________________` Notes: `________________` ## Post-upgrade verification - [ ] Program version or artifact identity is recorded. - [ ] Smoke tests pass. - [ ] Key instructions execute as expected. - [ ] Error rates and compute usage are reviewed. - [ ] Client and indexer outputs remain consistent. - [ ] Release notes and migration status are updated. - [ ] Follow-up issues are assigned owners and deadlines. ## Suggested implementation Package this checklist as: 1. A Markdown template in the repository. 2. A pull-request template requiring completion. 3. A small CLI that checks required fields and unchecked gates. 4. An append-only release record stored with each version tag.

# Self-directed draft: Solana Transaction Failure Triage Kit **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Problem When a Solana transaction fails, developers often need to correlate the signature, instruction index, program logs, account metadata, and compute usage manually. This slows support and makes bug reports inconsistent. ## Product A local CLI that turns a transaction signature or pasted simulation output into a structured, shareable failure report. ## Core command ```bash sol-triage inspect <SIGNATURE> --rpc <RPC_URL> ``` Optional input: ```bash sol-triage inspect --logs ./simulation.txt ``` ## Report contents - Transaction signature and inspection timestamp - Success/failure status - Error summary - Ordered program invocation tree - Log lines grouped by instruction - Failing instruction index, when identifiable - Compute-unit consumption, when present - Accounts referenced by the failing instruction - Suggested next debugging questions - Redacted JSON export for issue trackers ## Privacy defaults - Never print private keys, environment variables, or RPC credentials - Allow account-address masking: ```bash --mask-accounts ``` - Allow removal of raw instruction data: ```bash --omit-data ``` - Mark all inferred fields as “inferred” ## MVP scope 1. Parse pasted logs and RPC transaction responses. 2. Build a readable invocation tree. 3. Detect common error patterns from returned data and logs. 4. Export Markdown and JSON. 5. Support fixture-based tests for malformed, partial, and successful inputs. ## Explicit non-goals - Sending or retrying transactions - Automatically changing programs or accounts - Claiming that a diagnosis is certain - Requiring a hosted dashboard ## Example Markdown output ```text Transaction failure Failing program: <program> Instruction index: 2 Observed error: <error text> Compute units: <value, if available> Invocation path: caller └─ target program └─ nested program Likely investigation: - Confirm the failing account ownership. - Compare instruction arguments with the client serializer. - Reproduce using the captured simulation input. ``` ## Success criteria - A developer can turn raw failure data into a useful issue report in under one minute. - Reports remain useful when some RPC fields or logs are missing. - Sensitive values are excluded by default. - Every diagnostic statement distinguishes observed data from inference.

# Self-directed draft: Solana Account Layout Change Guard **Deliverable:** Concise MVP product specification **Status:** Proposed; not built or validated. ## Problem Changes to a program’s account serialization can make existing account data unreadable or misinterpreted. Teams need a focused pull-request check that exposes compatibility risks before release. ## Product A local-first CLI that compares two account schemas and tests whether the candidate decoder can read saved account fixtures. **Primary user:** Solana program developers maintaining persistent accounts. **Core question:** “Can our proposed code safely interpret the account data we already have?” ## MVP inputs - Baseline and candidate schemas, initially limited to supported Anchor IDL formats. - Synthetic or team-supplied binary account fixtures. - Optional manifest identifying each fixture’s account type and expected decoded fields. Fixtures remain local. No wallet connection, signing, or RPC access required. ## Checks | Change | Default result | |---|---| | Account discriminator changed | Block | | Fields removed, reordered, or types changed | Flag for review | | Enum variants reordered | Flag for review | | Field appended | Require fixture validation; never assume compatibility | | Unsupported schema construct | Inconclusive, not pass | | Candidate decoder fails on fixture | Block | | Decoded value differs from expected value | Block | Schema comparison is a risk screen, not a substitute for exercising the program’s actual deserialization behavior. ## Proposed interface ```text layout-guard compare \ --base baseline.json \ --candidate candidate.json \ --fixtures ./account-fixtures \ --expectations fixture-manifest.json ``` Outputs: - Human-readable summary for code review. - JSON report with account type, field path, risk, and supporting evidence. - Exit code: `0` for configured checks passed, `1` for blocking findings, `2` for incomplete analysis. **Illustrative finding:** ```text REVIEW: Position.status Enum variant order changed. Existing tag 1 could decode to a different variant. Next step: test historical fixtures and document the migration or backward-compatible decoding path. ``` ## Acceptance criteria - Detects every discriminator and field-order change in the supported test corpus. - Rejects truncated fixtures without crashing. - Distinguishes decoding failure from missing test coverage. - Produces deterministic reports for identical inputs. - Never labels an account type fixture-validated when no matching fixture was tested. - Lists supported schema versions and explicitly identifies skipped constructs. ## Boundaries Not a security audit or upgrade approval tool. It does not verify authorization, business logic, migration correctness, or compatibility across all live accounts. Zero-copy layouts and custom serializers are outside the first release. ## Commercial experiment Offer the CLI core freely; test demand for a paid CI package with configurable review gates and a reusable synthetic-fixture library. Before expanding scope, ask three teams to run it against a historical schema change and report missed risks, noisy findings, and setup friction. No revenue or demand is assumed.

# Self-directed draft: Solana Program Upgrade Readiness Checklist **Deliverable:** Reusable operational checklist **Status:** Proposed; not executed or validated. ## Objective Give Solana teams a repeatable process for preparing, approving, and verifying a program upgrade without relying on tribal knowledge. ## Pre-upgrade - [ ] Record current program ID, deployed binary hash, upgrade-authority arrangement, and release version. - [ ] Build the candidate binary from a clean, reproducible environment. - [ ] Compare the candidate against the previous release: - [ ] Instruction behavior - [ ] Account serialization and discriminators - [ ] PDA seeds and bump handling - [ ] CPI interfaces - [ ] Expected compute and account requirements - [ ] Test existing accounts and representative transactions. - [ ] Test rejected inputs, authorization failures, replay-like calls, and boundary values. - [ ] Confirm clients, indexers, scripts, and dashboards tolerate the change. - [ ] Define rollback or mitigation steps before approval. - [ ] Assign named owners for approval, upgrade execution, and verification. ## Approval packet Include: 1. Release identifier and source revision 2. Binary checksum 3. Change summary 4. Compatibility assessment 5. Test evidence and known limitations 6. Upgrade window 7. Rollback or emergency response procedure 8. Required sign-offs ## Upgrade execution - [ ] Announce a change freeze for dependent releases. - [ ] Verify the target environment and program ID. - [ ] Reconfirm authority and multisignature requirements. - [ ] Capture pre-upgrade state and health signals. - [ ] Execute the upgrade using the approved artifact only. - [ ] Record transaction signatures and timestamps internally. - [ ] Avoid unrelated changes during the observation window. ## Post-upgrade verification - [ ] Confirm the deployed binary matches the approved checksum. - [ ] Run a read-only smoke test. - [ ] Execute one authorized write path with a controlled fixture. - [ ] Confirm expected events, account changes, and CPI behavior. - [ ] Check client and indexer ingestion. - [ ] Review error rates, latency, and compute usage. - [ ] Obtain explicit go/no-go confirmation for normal operations. ## Stop conditions Pause or roll back according to the team’s authority model if: - The deployed artifact differs from the approved artifact. - A compatibility test fails. - Unauthorized state changes appear. - Dependent systems cannot parse new output. - The operator cannot prove which release is active. ## Suggested MVP format A small CLI or web form that: - Stores versioned checklists - Requires evidence attachments per gate - Prevents “complete” status without named owners - Generates a signed-off Markdown report - Exports an incident-ready timeline **Success criterion:** Any operator can reconstruct what changed, who approved it, what was verified, and what action is available if verification fails.

# Self-directed draft: Solana Transaction Failure Triage Kit **Deliverable:** MVP product specification **Status:** Proposed; not built, deployed, or validated. ## Purpose Help Solana developers turn simulation or transaction logs into a concise failure report that identifies: - The instruction and program where execution stopped - CPI call depth and parent-child relationships - Custom error codes and their source program - Compute-unit consumption by instruction - Likely remediation hints, clearly labeled as hypotheses ## Target users - Solana protocol engineers - SDK and wallet developers - QA teams - Support engineers diagnosing failed transactions ## Core workflow ```text triage-log transaction.log ``` The tool produces: 1. A short human-readable summary 2. A structured JSON report for CI and support systems 3. A trace tree showing outer instructions and CPIs 4. Warnings for ambiguous or incomplete log data ## Example report ```text RESULT: FAILED Failure location: depth: 2 program: <program identifier from log> reason: Custom error 0x1771 Trace: 0 outer instruction └─ 1 protocol instruction └─ 2 token-related CPI Compute units: consumed: <value from log> limit: <value if present> Confidence: failure location: high remediation: low Possible next checks: - Verify account ownership and mutability - Confirm signer privileges for the failing CPI - Compare supplied accounts with the instruction schema ``` Identifiers and values should be copied from input rather than inferred. ## MVP scope ### Input - Plain-text simulation logs - Transaction log arrays supplied through stdin or a file - Optional program-error dictionary supplied as JSON ### Output - Terminal summary with color disabled by default - JSON schema containing: - `success` - `failure` - `instructionTree` - `programIds` - `computeUnits` - `rawLines` - `warnings` ### Parsing rules - Preserve raw lines for auditability - Treat unknown log formats as warnings, not fatal parser errors - Track `invoke` and return boundaries as a best-effort call tree - Never present guessed error meanings as confirmed - Distinguish observed facts from suggested checks ## Acceptance criteria - Correctly preserves every input log line - Produces valid JSON for successful, failed, and malformed inputs - Identifies the deepest observed failing frame - Handles nested CPIs without losing parent context - Reports missing compute-unit data explicitly - Includes fixture tests for success, custom errors, nested calls, and truncated logs ## Future extensions - IDE error-panel integration - CI annotations for regression tests - Pluggable error dictionaries generated by each protocol - Compare two traces and highlight behavioral differences - Redacted support-bundle export for sharing logs safely ## Non-goals - Signing or submitting transactions - Claiming root cause when logs are insufficient - Fetching unverified metadata automatically - Replacing protocol-specific test suites

# Self-directed draft: Solana Account Contract Sentinel **Deliverable:** Product specification **Status:** Proposed; not built, deployed, or validated. ## Purpose Detect incompatible changes in Solana account layouts before they break indexers, APIs, dashboards, or client applications. ## Target users - Solana protocol teams - Indexer and data-platform engineers - SDK maintainers - QA and release engineers ## Core workflow 1. Register an account contract: - Program identifier - Account type name - Expected fields, types, offsets, and optional discriminant 2. Provide sample account data from fixtures or a configured RPC source. 3. Decode each sample against the registered contract. 4. Compare results with a previous snapshot. 5. Produce a compatibility report. ## MVP features - YAML or JSON contract definitions - Fixed-width and variable-length field support - Byte-offset and size validation - Optional account discriminant checks - Snapshot comparison between contract versions - Human-readable CLI output - Machine-readable JSON output - CI exit codes: - `0`: compatible - `1`: warning - `2`: breaking change - Fixture-only mode for deterministic testing ## Example contract ```yaml name: Position program: PROGRAM_ID discriminant: "base64:REPLACE_ME" fields: - name: owner type: pubkey - name: size type: i64 - name: active type: bool ``` ## Compatibility rules Flag as breaking when: - A required field is removed or reordered - A field type or width changes - A discriminant changes - Minimum account size decreases unexpectedly - A previously valid fixture no longer decodes Flag as warning when: - New trailing fields are added - Optional fields are introduced - Sample coverage is incomplete ## CLI sketch ```text sentinel check contracts/position.yaml \ --fixtures fixtures/position \ --baseline snapshots/position.json \ --format human ``` Output: ```text BREAKING Position.size: i64 -> u64 WARNING 2 fixtures lack the new field: settlement_mode RESULT release blocked ``` ## Non-goals - Mutating accounts - Publishing schemas automatically - Guaranteeing semantic correctness of program logic - Replacing protocol-specific integration tests ## Acceptance criteria - A team can define one account contract without writing application code. - CI detects a reordered or resized field. - Reports identify the account type, field, old shape, and new shape. - Fixture-only execution works without network access. - Every reported failure includes an actionable remediation hint. ## Suggested implementation boundary Start as a language-agnostic CLI with a small decoder interface. Keep RPC retrieval behind an optional adapter so the core comparison engine remains deterministic and easy to test.

# Self-directed draft: Solana Event Replay Workbench **Deliverable:** MVP product specification **Status:** Proposed; not built, deployed, or validated. ## Purpose Give Solana teams a local tool for replaying captured transaction or account-change events against application handlers, so parsing and business logic can be tested deterministically. ## Target users - Indexer and analytics developers - Wallet/backend engineers - QA teams testing event-driven services ## MVP workflow 1. Import newline-delimited JSON fixtures. 2. Validate each fixture against a declared schema. 3. Replay events in original or controlled order. 4. Run a user-provided handler through a simple adapter. 5. Record outputs, errors, latency, and state mutations. 6. Compare a new run with a saved baseline. ## Fixture format ```json { "event_id": "fixture-001", "slot": 123, "signature": "sample-signature", "source": "test", "accounts": [], "instructions": [], "metadata": {} } ``` The tool treats identifiers and payloads as test data; it does not fetch chain data. ## Core commands ```text replay init replay validate ./fixtures replay run ./fixtures --handler ./handler replay diff ./baseline ./current replay report --format html ``` ## Handler contract Input: ```json { "event": {}, "state": {} } ``` Output: ```json { "accepted": true, "emissions": [], "state_patch": {}, "warnings": [] } ``` A handler failure must identify the fixture, phase, and error without stopping the remaining replay unless strict mode is enabled. ## MVP features - JSONL fixture ingestion - Schema validation with actionable errors - Deterministic ordering and seeded randomness - Per-event timeout - Golden-output snapshots - Redacted structured logs - CLI and machine-readable report - Strict and best-effort execution modes ## Non-goals - RPC access - Mainnet monitoring - Private-key handling - Automatic fixture generation - Production deployment ## Acceptance criteria - Same fixture set and seed produce identical outputs. - One malformed event is reported with line number and field path. - A handler error is isolated to its event in best-effort mode. - Snapshot diffs show added, removed, and changed fields. - Reports contain no secret values by default. - A new contributor can run the sample suite using one documented command. ## Suggested implementation - TypeScript CLI - JSON Schema validation - SQLite or append-only JSON for run metadata - Adapter interface for arbitrary handlers - Snapshot files stored alongside fixtures ## Packaging Ship as a repository template containing: - CLI - Example fixtures - Example handler - Three intentional failure cases - CI command for replay and snapshot comparison - Short guide for adding a new event type

# Self-directed draft: Solana RPC Failover Drill Kit **Deliverable:** Reusable staging checklist **Status:** Proposed; not executed or validated. **Purpose:** Help a Solana team test whether its application behaves safely when an RPC endpoint becomes slow, unavailable, or inconsistent. ## Scope Test application behavior—not provider infrastructure. Inject faults through a local proxy or mocked RPC client. Use staging credentials and test wallets; never production signing keys. **Record before testing** - Application version: - Primary and fallback endpoint labels: - Commitment level: - Request timeout and retry limit: - Maximum acceptable recovery time: - Engineer responsible: ## Drill checklist | Injected fault | Required behavior | Evidence to capture | |---|---|---| | Read requests time out | Retry within a fixed budget, then fail over or show a recoverable error. | Request count, elapsed time, endpoint changes. | | Endpoint returns rate-limit errors | Apply capped backoff; avoid synchronized retry bursts. | Retry timing and total requests. | | Fallback returns older account state | Flag or reject stale results according to an explicit slot policy. | Response context slots and UI state. | | Submission response is lost | Treat outcome as unknown; reconcile the existing signature before offering a new transaction. | Signature, status checks, user messaging. | | WebSocket connection drops | Reconnect and reconcile state through HTTP reads; do not assume every event was received. | Disconnect interval and reconciliation result. | | Both endpoints fail | Stop automatic retries after the budget; preserve useful context without claiming success. | Final error state and recovery action. | ## Submission safety rules - Persist the signed transaction’s signature before submission. - Distinguish **not submitted**, **submitted with unknown outcome**, **confirmed**, and **failed**. - Rebroadcasting identical signed bytes is not the same as constructing a new transaction. - Do not automatically rebuild and re-sign an unresolved payment or other non-idempotent action. - For recent-blockhash transactions, track `lastValidBlockHeight`; expiry alone does not prove the original transaction never landed. - Before replacement, reconcile transaction status and application state. If uncertainty remains, require explicit user review. - Test durable-nonce transactions separately; this checklist does not define their expiry handling. ## Pass criteria - [ ] No silent success state during unresolved submission. - [ ] No automatic duplicate business action. - [ ] Retry traffic stays within the configured budget. - [ ] Stale data handling matches the documented policy. - [ ] Subscription recovery reconciles missed state. - [ ] Logs exclude private keys, auth tokens, and credential-bearing endpoint URLs. - [ ] Recovery time meets the team’s recorded target. ## Copy-ready incident summary > **Drill:** [fault] > **Expected:** [behavior] > **Observed:** [behavior] > **Result:** Pass / Fail / Inconclusive > **Evidence:** [local artifact identifier] > **Fix owner and next test:** [owner; action] **Potential product extension:** Package these scenarios as a configurable local fault proxy with a machine-readable pass/fail report. Validate usefulness with a team’s staging workflow before building a hosted service.

# Self-directed draft: Solana Transaction Intent Linter **Deliverable:** MVP product specification **Status:** Proposed; not built or validated. ## Problem Teams often present users with an opaque transaction that is difficult to review before signing. Developers need a consistent way to detect unexpected instructions, writable accounts, fee-payer changes, and program IDs during testing. ## Product A local CLI and TypeScript library that inspects a transaction message and produces: - A normalized instruction summary - Account roles: signer, writable, fee payer, or read-only - Program IDs invoked - A configurable policy result: `pass`, `warn`, or `fail` - Machine-readable JSON for CI and human-readable output for debugging The tool analyzes transaction structure only; it does not sign, submit, or custody transactions. ## Example policy ```yaml allowedPrograms: - "<program-id>" maxInstructions: 6 requireFeePayer: true denyUnexpectedWritableAccounts: true ``` ## MVP commands ```bash intent-lint inspect tx.json intent-lint check tx.json --policy policy.yaml intent-lint explain result.json ``` ## TypeScript API ```ts const report = inspectTransaction(transaction, { knownPrograms, labels, }); const result = evaluatePolicy(report, policy); ``` ## Core output ```json { "status": "warn", "programs": ["..."], "instructionCount": 3, "accounts": { "unexpectedWritable": ["..."] }, "findings": [ { "code": "UNEXPECTED_WRITABLE", "severity": "warning", "message": "Account is writable but not listed in policy." } ] } ``` ## Acceptance criteria - Parses legacy and versioned transaction messages from fixtures. - Produces deterministic JSON output. - Distinguishes signer, writable, fee-payer, and read-only roles. - Supports allowlisted program IDs and instruction-count limits. - Exits nonzero when a policy violation is found. - Includes fixtures for valid, warning, and failing transactions. - Never requires private keys or network access. ## Likely users - Wallet and dApp developers - QA engineers - Protocol SDK maintainers - Security reviewers writing CI checks ## Natural extension Add adapters that attach human-readable instruction names from a caller-supplied IDL or registry, without making external identity claims.

# Self-directed draft: Solana IDL Drift Watcher **Deliverable:** Concise product specification **Status:** Proposed; not built or validated. ## Problem Solana teams can ship a client package whose instructions no longer match the deployed program’s interface. This can create confusing failures, unsafe assumptions, and emergency debugging during releases. ## Product A CI tool that compares a repository’s expected program interface with a pinned deployment manifest and reports potentially breaking changes before release. ## MVP inputs - Program ID - Cluster name - Repository IDL or interface definition - Previously approved interface snapshot - Optional release label The tool should not sign, submit, or modify transactions. ## Checks 1. Instruction added or removed 2. Instruction argument renamed, reordered, added, or removed 3. Argument type changed 4. Account mutability or signer requirement changed 5. Account path or PDA seed metadata changed 6. Event or error definition changed 7. Program ID or cluster mismatch 8. Missing approval for an intentional breaking change ## Output Produce: - Human-readable Markdown report - Machine-readable JSON - Exit code: - `0`: no blocking changes - `1`: review required - `2`: invalid input or configuration error Example report: ```text IDL Drift Report Program: <program-id> Target: <cluster> BLOCKING - initialize: account `authority` changed from signer=true to signer=false REVIEW - withdraw: added argument `memo: string` Result: failed ``` ## Approval model Store an approved snapshot in version control. A change may be accepted only through an explicit command such as: ```bash idlwatch approve --reason "v2 authority model" ``` The approval record should include: - Snapshot hash - Commit identifier - Author - Reason - Timestamp supplied by the local environment ## Suggested CLI ```bash idlwatch check --config idlwatch.yml idlwatch diff --from approved --to current idlwatch approve --reason "..." ``` ## Configuration sketch ```yaml program: "<program-id>" cluster: "devnet" current: "target/idl/app.json" approved: ".idlwatch/approved.json" blocking: - signer_changes - type_changes - removed_instructions ``` ## Acceptance criteria - Detects each listed change category with fixture-based tests. - Produces deterministic JSON for identical inputs. - Never contacts a signer or broadcasts a transaction. - Fails closed when the program ID or cluster is missing. - Runs in a standard CI job without requiring private keys. - Documents known limitations for interfaces that cannot be reconstructed from the supplied metadata. ## First build slice Implement snapshot parsing, normalized structural diffing, Markdown/JSON output, and CI exit codes. Add fixtures for compatible changes, breaking changes, malformed files, and program-ID mismatches.

# Self-directed draft: Solana RPC Failover Drill Kit **Deliverable:** MVP product specification **Status:** Proposed; not built or validated. ## Problem A backup RPC endpoint is only useful if an application switches to it correctly. Teams need a repeatable way to test outage behavior without disrupting production or risking funds. ## Product A local fault-injection proxy and test runner for Solana applications. Engineers place it between their staging application and configured RPC endpoints, then simulate failures and inspect application behavior. **Primary user:** Backend or infrastructure engineer preparing for a release. **Core promise:** Turn “we have RPC failover” into a reproducible test with explicit pass/fail evidence. ## MVP scope - Proxy HTTP JSON-RPC requests to user-supplied endpoints. - Inject timeouts, HTTP 429 responses, malformed responses, and connection failures. - Select faults by endpoint, RPC method, duration, and deterministic seed. - Record request timing, routing decisions, retry counts, and recovery time. - Export a redacted JSON report and a compact CI summary. **Excluded:** Production traffic routing, signing, transaction construction, endpoint rankings, and WebSocket testing. ## Example drill configuration *Proposed configuration format:* ```yaml name: primary-read-outage seed: 17 endpoints: primary: ${PRIMARY_RPC_URL} backup: ${BACKUP_RPC_URL} safety: mode: read-only allowed_methods: - getSlot - getBalance fault: endpoint: primary methods: [getSlot, getBalance] type: timeout start_after_seconds: 10 duration_seconds: 30 assertions: backup_success_within_seconds: 8 max_attempts_per_operation: 4 no_writes_forwarded: true ``` Thresholds are operator-selected test criteria, not promises about network performance. ## Required scenarios | Drill | Injected condition | Expected behavior | |---|---|---| | Primary unavailable | All primary reads time out | Backup serves reads within the configured deadline | | Rate limiting | Primary returns HTTP 429 | Retries stay bounded; configured backoff is observed | | Invalid payload | Primary returns malformed JSON | App surfaces or recovers from the error without crashing | | Both unavailable | Both endpoints reject requests | App reports unavailability rather than presenting cached data as fresh | | Primary recovery | Fault ends | App follows its declared recovery policy without rapid endpoint switching | The application supplies operation IDs through a test adapter so retries can be distinguished from unrelated requests. Missing instrumentation produces **inconclusive**, not pass. ## Safety requirements - Default to an explicit read-method allowlist; reject all other methods. - Never request private keys or wallet seed phrases. - Redact endpoint credentials, URL query strings, and authorization headers. - Disable raw request and response capture by default. - Bind locally by default and require explicit opt-in for remote access. - Mark every report as synthetic fault-test evidence, not a production reliability guarantee. ## Acceptance criteria 1. Identical seeds reproduce the fault schedule, though upstream timings may vary. 2. Every assertion reports pass, fail, or inconclusive with supporting observations. 3. A fixture application that never switches endpoints fails the outage drill. 4. A fixture that switches within the deadline passes under controlled upstream responses. 5. Disallowed requests are rejected before reaching either upstream. 6. Automated secret scans find no fixture credentials in exported reports. ## Commercial hypothesis Offer the local runner freely; test demand for paid CI history, team-owned drill libraries, and release-gate reports. Validate willingness to pay before building hosted infrastructure. **First validation:** Ask three Solana engineering teams to run the outage drill in staging and identify whether its report changes a release decision.

# Self-directed draft: Solana Treasury Transaction Policy Linter **Deliverable:** MVP product specification **Status:** Proposed; not built, deployed, or validated. ## Purpose Give Solana treasury operators a pre-signing safety check for unsigned transactions. The linter identifies unexpected programs, accounts, instruction types, and spending amounts before a transaction reaches a signer. ## Target users - DAO and protocol treasury teams - Multisig signers - Finance and operations engineers - Security reviewers ## Core workflow 1. User pastes or uploads an unsigned transaction message. 2. User selects a policy profile. 3. The linter decodes supported instructions. 4. It compares the transaction against policy rules. 5. It produces a human-readable review report and machine-readable result. ## MVP policy rules - Allowed program IDs - Allowed instruction types - Allowed destination accounts - Maximum native-token transfer - Maximum SPL-token transfer - Required signer count - Blocked account list - Optional time-based approval window - Require memo or proposal reference ## Output Each check returns: - `PASS`, `WARN`, or `BLOCK` - Rule violated - Affected instruction and account - Expected policy value - Observed transaction value - Recommended reviewer action Example: ```text BLOCK — Unknown program Instruction 2 invokes an unapproved program. Observed: <program id> Allowed programs: 4 Action: verify the proposal and update policy only if intentional. ``` ## Security boundaries - Never request private keys, seed phrases, or wallet exports. - Never sign or broadcast transactions. - Treat RPC lookups as optional enrichment, not authorization. - Display raw addresses alongside labels. - Preserve the original transaction bytes for independent review. - Make policy changes auditable and versioned. ## Suggested architecture - **Parser:** Solana message and instruction decoder - **Rule engine:** Deterministic policy evaluation - **Renderer:** Terminal, JSON, and web report - **Policy store:** Versioned local files initially - **Test fixtures:** Hand-authored transactions covering transfers, token operations, approvals, and unknown instructions ## MVP acceptance criteria - Produces identical results for identical transaction and policy inputs. - Clearly distinguishes warnings from blocking violations. - Handles unsupported instructions without silently approving them. - Does not expose or persist signing secrets. - Includes fixture-based tests for every rule. - Lets a reviewer export a report containing transaction hash/message, policy version, findings, and timestamp. ## Positioning “Review treasury transactions before anyone signs—without giving the tool custody or signing power.”

# Self-directed draft: Solana Indexing Gap Detector **Deliverable:** Product specification **Status:** Proposed; not built, deployed, or validated. ## Purpose Help Solana teams detect and repair gaps between on-chain activity and their internal database, analytics pipeline, or customer-facing state. ## Target users - Protocol backend engineers - Data and indexing teams - Wallet and portfolio applications - Support teams investigating missing activity ## Core problem An indexer may miss slots, duplicate records, stop processing, or partially apply updates. Without a reconciliation workflow, teams discover inconsistencies only after users report them. ## MVP workflow 1. **Configure a monitored stream** - RPC endpoint or compatible data source - Program/account filters - Starting slot - Destination database or event sink 2. **Track processing health** - Last observed slot - Last successfully persisted slot - Processing lag - Duplicate count - Error count - Unresolved slot ranges 3. **Run reconciliation** - Select a slot range - Re-query matching transactions or account changes - Compare normalized event identifiers - Produce missing, duplicate, and conflicting records 4. **Repair safely** - Export a reviewable repair batch - Require explicit approval - Reprocess only approved items - Record operator, timestamp, and outcome ## Suggested event identity ```text event_id = hash( network, slot, transaction_signature, instruction_index, inner_instruction_index, account_scope ) ``` The implementation should allow teams to replace this identity scheme when their data model requires it. ## Dashboard - Current lag and trend - Healthy / delayed / stalled status - Slot coverage timeline - Missing-range queue - Recent reconciliation runs - Repair batches awaiting approval - Error samples grouped by cause ## Safety requirements - Never store private keys or signing material - Read-only chain access for detection and reconciliation - Immutable audit log for repairs - Idempotent reprocessing - Dry-run mode by default - Explicit network/environment labels - Redaction controls for sensitive account metadata ## Acceptance criteria - Detects an intentionally skipped slot range - Distinguishes missing events from duplicate events - Re-running the same repair creates no additional duplicates - Shows a clear reason when reconciliation cannot complete - Exports a machine-readable report and human-readable summary - Preserves an audit record for every approved repair ## Possible pricing shape - Free local CLI for one monitored stream - Team plan for scheduled checks, dashboards, and shared audit history - Enterprise plan for retention, access controls, and custom sinks ## Non-goals for MVP - Automatic irreversible writes - Custody or transaction signing - Guaranteed historical completeness - Replacing a team’s primary indexer

# Self-directed draft: Solana Transaction Receipt Kit **Deliverable:** MVP product specification **Status:** Proposed; not built, deployed, or validated. ## Purpose Help Solana application teams explain transaction outcomes clearly—and collect useful support evidence without exposing secrets. **Target buyer:** Engineering or support leads at wallet-connected applications. **Core problem:** A wallet approval, submitted transaction, and confirmed application outcome are different events. Interfaces that collapse them into “success” or “failed” can confuse users and encourage unsafe retries. ## MVP A framework-neutral receipt component with an optional React wrapper. It accepts transaction lifecycle events from the host application and displays: | State | User-facing copy | Available action | |---|---|---| | Awaiting approval | “Review this request in your wallet.” | Cancel locally | | Submitted | “Submitted. Waiting for confirmation.” | Copy signature | | Confirmed | “Transaction confirmed. Checking the result.” | View details | | Outcome verified | “Completed.” | Download receipt | | Execution failed | “This transaction failed. Review the details before trying again.” | View error | | Status unknown | “We couldn’t verify the status. Check before submitting again.” | Check status | | Outcome unresolved | “Transaction confirmed, but the app hasn’t verified the expected result.” | Contact support | Cancellation must not imply that an already-submitted transaction was reversed. ## Integration contract The host supplies: ```ts type ReceiptEvent = { operationId: string; attemptId: string; clusterLabel: string; state: | "awaiting_approval" | "submitted" | "confirmed" | "outcome_verified" | "execution_failed" | "status_unknown" | "outcome_unresolved"; observedAt: string; signature?: string; commitment?: string; safeErrorCode?: string; }; ``` - Each submission gets a distinct `attemptId`. - Only host-provided outcome verification can trigger “Completed.” - Confirmation level remains visible in details. - A local timeout produces “Status unknown,” not “Execution failed.” - Late observations update the same attempt; they do not create a new submission. ## Support receipt Export a versioned JSON file containing lifecycle timestamps, cluster label, attempt identifiers, signature, reported commitment, and sanitized error code. **Privacy defaults:** - No seed phrases, private keys, authentication headers, raw RPC URLs, or arbitrary logs. - Wallet addresses and signatures are hidden from export until the user explicitly includes them. - Warn that included transaction identifiers can reveal public activity. - No telemetry or server-side storage in the MVP. - Preview export contents before download. ## Acceptance checklist - [ ] Wallet rejection never appears as an onchain execution failure. - [ ] Network timeouts never offer an automatic resubmission. - [ ] Confirmation alone never marks an application outcome complete. - [ ] Duplicate and out-of-order events cannot regress a completed receipt. - [ ] An unknown status can resolve when later evidence arrives. - [ ] Conflicting terminal events surface a diagnostic warning. - [ ] Status changes are accessible to screen readers. - [ ] Exports contain only explicitly allowlisted fields. - [ ] Fixtures demonstrate every state without connecting a wallet. ## Scope and commercial hypothesis **Exclude:** transaction construction, signing, custody, automatic retries, explorer links, and application-specific outcome logic. **Potential paid offering:** a fixed-scope integration package covering lifecycle mapping, receipt styling, and a failure-state test suite. Pricing and willingness to pay remain untested. **First validation question:** Can a developer integrate the fixtures and a support agent distinguish “failed” from “unknown” without additional explanation?

# Self-directed draft: Solana Authority Map **Deliverable:** Product specification **Status:** Proposed; not built, deployed, or validated. ## Purpose Help Solana teams review administrative control across tokens, programs, and operational accounts before audits, launches, or governance changes. ## Target users - Protocol security teams - Token issuers - DAO contributors - Incident-response engineers ## MVP input - User-provided JSON or CSV exports - Optional address labels - Configurable authority fields and account types The tool must analyze supplied data only; it does not submit transactions or claim live chain state. ## Core workflow 1. Import an authority snapshot. 2. Normalize addresses and labels. 3. Group records by project, asset, or program. 4. Flag risky or incomplete configurations. 5. Export a review report for engineering and governance discussion. ## Detection rules - Authority held by an unlabeled address - Multiple critical authorities controlled by one address - Unexpected retained mint, freeze, upgrade, or close authority - Authority fields missing from an otherwise complete record - Duplicate or conflicting labels - Multisig metadata absent where a multisig is expected - Changes between two user-supplied snapshots Rules should be configurable rather than hard-coded as universal security judgments. ## Report format Each finding includes: - Severity: informational, review, or urgent - Resource and authority type - Current controller - Evidence source and snapshot timestamp - Why it was flagged - Suggested review action - Owner and status fields Exports: Markdown, CSV, and machine-readable JSON. ## Privacy and safety - Local-first processing by default - Never request seed phrases or private keys - Redact full addresses optionally - Clearly label snapshots as user-supplied and potentially stale - Preserve original evidence beside normalized results ## Acceptance criteria - Same input produces the same report - Every finding links to an input record - Unknown fields are preserved, not silently discarded - A reviewer can mark findings resolved without editing source data - Malformed records produce actionable validation errors ## Possible pricing Free local CLI; paid team features could include shared review queues, custom rule packs, and report templates.

# Self-directed draft: Solana RPC Failure Lab **Deliverable:** MVP product specification **Status:** Proposed; not built or validated. ## Purpose Help Solana application teams test what users see when RPC requests fail, return stale responses, or disagree—without risking funds or disrupting production endpoints. **Target buyer:** Engineering leads responsible for wallet-connected applications. **Core question:** Does the application recover safely, or leave users guessing whether an action succeeded? ## MVP A local JSON-RPC fault-injection proxy with a TypeScript test harness. Developers point a test application at the proxy, select a scenario, and run their existing integration tests. The proxy modifies configured responses and produces a reproducible event log. ### Included scenarios | Scenario | Injected behavior | Expected application behavior | |---|---|---| | Rate limiting | Return HTTP 429 for selected requests | Bounded retries; visible recovery state | | Slow reads | Delay selected read responses | Loading state ends or offers retry | | Stale balance | Replay an earlier fixture | Avoid treating stale data as fresh | | Unknown submission outcome | Forward submission, then drop response | Show uncertainty; reconcile before offering another action | | Endpoint disagreement | Serve conflicting status fixtures | Preserve an unresolved state rather than claim success | Fixtures are synthetic or supplied by the developer. Scenario names describe simulated conditions, not claims about network behavior. ## Interface Illustrative configuration: ```yaml scenario: submission-response-lost seed: 42 rules: - method: sendTransaction occurrence: 1 action: forward_then_drop_response - method: getSignatureStatuses occurrences: [1, 2] action: fixture fixture: status-unresolved.json ``` **Safety default:** Run against a local validator or mock upstream. Forwarding transaction submissions to any other endpoint requires explicit configuration and a startup warning. ## Outputs Each run generates: - A timestamped request/response timeline. - A record of injected faults. - Results for developer-defined assertions. - A replay bundle containing configuration, seed, and fixtures. - A compact CI report with failed assertions and relevant events. Exclude credentials and raw transaction payloads from logs by default. Replay bundles must flag missing redacted inputs rather than silently invent replacements. ## Acceptance criteria 1. Fixture-only runs with the same seed produce the same fault sequence. 2. Method-specific rules leave unrelated requests unchanged. 3. An example test fails when the UI reports success while status remains unresolved. 4. An example test passes when the UI shows uncertainty and reconciles status. 5. Retry-limit assertions detect excessive requests. 6. Submission forwarding is disabled unless explicitly enabled. 7. Reports distinguish application assertion failures from harness errors. ## Boundaries The first version does not simulate consensus, prove transaction finality, audit programs, or recommend production retry policies. WebSocket fault injection is out of scope. ## Revenue experiment Offer a fixed-scope integration package: connect the harness to one application flow, implement five failure tests, and hand over reusable CI configuration. **Validation gate:** Seek three engineering-team interviews and one paid pilot before expanding beyond HTTP RPC scenarios. Price remains an experiment, not an earnings claim.

# Self-directed draft: Solana Program Upgrade Dry-Run Kit **Deliverable:** Concise product specification **Status:** Proposed; not built, deployed, or validated. ## Purpose Give Solana teams a repeatable pre-release workflow for reviewing program upgrades, account migrations, and client compatibility before publishing a new build. ## Target users - Program engineers - Protocol maintainers - Release managers - Client SDK developers ## Core workflow ```text upgrade-kit prepare --program <address> --build ./target/deploy upgrade-kit inspect ./upgrade-report.json upgrade-kit verify ./upgrade-report.json --policy ./release-policy.yml ``` The tool produces a human-readable Markdown report and machine-readable JSON. ## MVP checks ### 1. Program identity - Expected program address matches the build configuration. - Deploy authority and upgrade authority are explicitly recorded. - Build artifact hash is captured. - Release environment is labeled: localnet, devnet, or mainnet. ### 2. Account compatibility Require a migration manifest for every changed account type: ```yaml accounts: - name: Position previous_size: 128 new_size: 160 migration: required authority: governance ``` Flag: - Reduced account size - Missing migration instructions - Changed serialized field order - Added fields without defined defaults - Changed account discriminators ### 3. Client compatibility Compare the previous and proposed IDL or interface manifest. Flag: - Removed instructions - Renamed arguments - Changed argument types - Removed account fields - New required accounts - Changed error codes ### 4. Resource budget Run configured instruction fixtures on localnet and record: - Compute units consumed - Return data size - Number of writable accounts - Number of signers - Transaction success or failure The report should mark any fixture exceeding a team-defined threshold. ### 5. Release gates A policy file defines required approvals: ```yaml fail_on: - identity_mismatch - missing_migration - incompatible_client_change - failed_fixture require: - artifact_hash - rollback_note - reviewer ``` Exit code `0` means eligible for review; nonzero means the report contains a blocking issue. ## MVP output ```text upgrade-report/ report.md report.json artifact.sha256 fixtures/ migration-checklist.md ``` Each finding includes: - Severity: blocker, warning, note - Evidence - Affected component - Suggested remediation - Owner field - Resolution status ## Acceptance criteria - A team can generate a report from one documented command. - Every blocking finding is reproducible from a fixture or manifest. - The same inputs produce a stable JSON report. - No deployment or upgrade action is performed by the tool. - Reports can be attached to a pull request or release record. ## Non-goals - Automatically deploying programs - Managing upgrade authorities - Guaranteeing runtime safety - Replacing code review or governance approval ## Future extensions - CI provider integrations - Governance-ready approval bundles - Historical report comparison - Test-validator snapshot support - Custom serializers for non-Anchor programs

# Self-directed draft: Solana Signing Intent Guard **Deliverable:** Concise product specification **Status:** Proposed; not built or validated. ## Purpose Help Solana application teams catch unintended transaction changes **before requesting a wallet signature**. **Target user:** Engineers maintaining swaps, deposits, withdrawals, or other transaction-building flows. ## MVP A TypeScript library that compares a constructed transaction against an application-defined intent. It returns structured findings suitable for blocking a signing request or displaying a warning. ```ts type SigningIntent = { feePayer: string; allowedPrograms: string[]; requiredSigners: string[]; maxLamportDebit?: bigint; tokenDebitLimits?: { mint: string; sourceAccount: string; maxBaseUnits: bigint; }[]; expectedRecipients?: string[]; }; type Finding = { severity: "block" | "warn"; code: string; instructionIndex?: number; message: string; }; ``` **Proposed interface** ```ts const report = await inspectIntent({ transaction, intent, accountResolver, }); if (report.status !== "pass") { // Stop signing or route to an explicit review flow. } ``` ## Required checks - Verify fee payer and required signer set against intent. - Resolve versioned-transaction address lookup tables; return `indeterminate` if resolution fails. - Flag instructions invoking programs outside the allowlist. - Decode supported native SOL and token transfers; compare amounts and recipients with intent. - Flag token approvals, authority changes, and account closures unless explicitly permitted. - Identify unsupported instructions rather than silently treating them as safe. **Report status:** `pass`, `block`, or `indeterminate`. A pass means supported checks passed—not that the transaction is universally safe. ## Trust boundary Static inspection cannot establish all runtime effects, particularly cross-program invocations. Supported instruction decoders must declare their coverage. Optional simulation may add evidence, but must not turn incomplete coverage into a safety guarantee. The library must inspect the exact message bytes sent for signing. If those bytes change, inspection must run again. ## Acceptance tests | Fixture | Expected result | |---|---| | Supported transfer matching intent | Pass | | Recipient substituted after construction | Block | | Unexpected token approval | Block | | Debit above the declared limit | Block | | Missing lookup-table data | Indeterminate | | Allowed program with unsupported instruction | Indeterminate | | Message modified after inspection | Require reinspection | ## Scope limits No private-key handling, transaction submission, wallet custody, or promise of exploit prevention. Exclude comprehensive arbitrary-program analysis from the MVP. ## Packaging and revenue hypothesis Offer a small library with test fixtures and machine-readable reports. Test willingness to pay for maintained decoder coverage and CI regression tooling through a fixed-scope pilot; pricing and demand remain unvalidated. **First useful release:** Native SOL transfers and explicitly documented token instruction variants, with adversarial fixtures proving that unsupported cases never receive a silent pass.

# Self-directed draft: Solana Transaction Lifecycle Observatory **Deliverable:** Product specification **Status:** Proposed; not built, deployed, or validated. ## Purpose Give application teams a single timeline for each submitted transaction: creation, signing, broadcast, confirmation, expiration, and user-visible outcome. ## Problem A transaction can appear successful in an application while failing or remaining unconfirmed on-chain. Teams need to distinguish: - Client-side construction failures - Wallet or signing failures - RPC submission failures - Blockhash expiration - Confirmation timeouts - Program-level errors - Successful execution with incorrect UI state ## MVP ### Inputs - Application-generated request ID - Wallet public key - Transaction signature, when available - Recent blockhash and last valid block height - RPC endpoint label - Client timestamp - Confirmation strategy - Sanitized simulation or RPC error data Do not collect private keys, seed phrases, or raw sensitive payloads. ### Core interface A searchable transaction table with: | Field | Example | |---|---| | Request ID | `checkout-1842` | | Signature | truncated display | | Current phase | `confirming` | | First observed | timestamp | | Blockhash expiry | block height | | RPC path | endpoint label | | Final result | success / failed / expired / unknown | | Failure class | parsed category | Each record opens a timeline showing state transitions and timestamps. ## Failure taxonomy 1. `build_failed` 2. `signing_rejected` 3. `broadcast_failed` 4. `already_processed` 5. `blockhash_expired` 6. `confirmation_timeout` 7. `program_error` 8. `transport_unknown` 9. `success` Unknown errors remain visible rather than being silently classified as failures. ## Alert rules - Confirmation exceeds a configurable duration - Blockhash expiry is approaching - Repeated failures share the same program error - A request receives multiple signatures - Application state says “success” while chain confirmation is absent - RPC responses disagree across configured endpoints ## Safety and privacy requirements - Redact instruction data by default - Hash internal request IDs before export - Encrypt stored records - Configurable retention period - Role-based access for production logs - Never infer success from broadcast acceptance alone ## Acceptance criteria - Every request has a terminal or explicitly `unknown` state. - Retries are linked to the original request. - Expired transactions are separated from program failures. - A developer can export one incident’s timeline as JSON. - The system remains useful when no signature is produced. ## Suggested implementation boundary Start as a small client SDK plus a local collector. Keep chain parsing modular so program-specific error decoders can be added without changing lifecycle tracking.

# Self-directed draft: Solana RPC Failover Drill Kit **Deliverable:** Reusable operational checklist **Status:** Proposed; not executed or validated. ## Purpose Help Solana application teams test whether an RPC outage causes duplicate submissions, misleading balances, or lost transaction tracking. **Intended user:** The engineer responsible for transaction submission and application reliability. ## Test boundaries - Use a local validator or devnet with dedicated test accounts. - Never use production keys or customer funds. - Inject failures through a test proxy or mocked RPC adapter. - Define acceptable recovery time and data freshness before testing. - Redact credentials and sensitive payloads from logs. ## Preparation - [ ] Identify primary and fallback RPC endpoints. - [ ] List methods the application uses, including subscriptions. - [ ] Document configured commitment levels and retry rules. - [ ] Record a baseline successful read and transaction flow. - [ ] Assign a unique application operation ID before transaction construction. - [ ] Capture each operation’s transaction signatures, endpoints, timestamps, and status transitions. - [ ] Confirm the UI can represent “pending” and “status unknown” without implying success or failure. ## Failure drills | Injected condition | Expected behavior | |---|---| | Primary endpoint times out | Switch or retry within the declared recovery budget; avoid unlimited retry loops. | | Primary returns rate-limit errors | Apply bounded backoff; avoid immediately flooding the fallback. | | Fallback reports an older slot | Detect freshness difference; do not silently present stale state as current. | | Submission succeeds but its response is dropped | Reconcile the known signature before creating a replacement transaction. | | WebSocket connection drops | Reconnect, restore subscriptions, and reconcile missed state through reads. | | Providers disagree about confirmation | Preserve the configured commitment requirement; show uncertainty rather than premature success. | | Transaction validity window expires | Check execution status before considering a replacement; do not assume expiry proves non-execution. | | Both endpoints fail | Stop automatic escalation, preserve operation records, and show an actionable degraded-state message. | ## Duplicate-execution guard Rebroadcasting the same signed transaction is different from constructing a replacement with a new blockhash and signature. - [ ] Track all signatures belonging to one application operation. - [ ] Do not treat a submission timeout as proof of failure. - [ ] Gate replacement transactions on reconciliation and application-specific safety rules. - [ ] For operations requiring exactly-once effects, test an application/program-level idempotency mechanism rather than relying on RPC failover alone. - [ ] Escalate unresolved execution status for review instead of automatically repeating a value-moving action. ## Release acceptance A drill passes only when: - Recovery stays within the team’s declared budget. - The UI never labels an unknown outcome as confirmed. - No duplicate application effect occurs in tested scenarios. - Retries stop at configured limits. - Logs can reconstruct every endpoint switch and replacement decision. - Unresolved operations remain recoverable after an application restart. ## Copyable result record ```text Build: Environment: Scenario: Operation ID: Signatures: Recovery budget / observed: Freshness budget / observed: Expected outcome: Observed outcome: Duplicate application effect: Final status or unresolved reason: Evidence location: Pass / fail: Owner and next action: ``` **Potential paid extension:** A team-specific adapter and drill report covering its actual submission flow. Pricing and demand remain unvalidated.

# Self-directed draft: Solana Program Upgrade Diff Gate **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Purpose Prevent accidental breaking changes when a Solana program is upgraded by comparing the proposed build against the currently approved release. ## User promise > “Know exactly what changed before an upgrade reaches production.” ## Target users - Solana protocol engineers - Security reviewers - Release managers - Multisig or upgrade-authority operators ## MVP workflow ```text build candidate → collect artifacts → compare → review findings → approve or reject ``` ## Inputs - Current program binary - Candidate program binary - Optional IDL or generated account schemas - A user-defined policy file ## Checks 1. **Binary identity** - Hash current and candidate artifacts. - Record build metadata supplied by the user. 2. **Interface changes** - Detect added, removed, or renamed instructions. - Compare instruction arguments and account constraints when metadata is available. 3. **Account layout risks** - Flag changed field order, type, size, or discriminator metadata. - Require explicit acknowledgement for migrations. 4. **Authority changes** - Highlight configured changes to upgrade authority, pause authority, or admin accounts. 5. **Policy violations** - Block releases matching rules such as: - “No account layout changes without migration notes.” - “No authority changes in routine releases.” - “Every release requires two reviewers.” ## Review output ```text Release: candidate-2025-01 Decision: BLOCKED Critical: - UserAccount layout differs from approved schema. Warnings: - 2 instructions changed argument metadata. - Migration note is missing. Required approvals: - [ ] Engineer - [ ] Security reviewer - [ ] Release manager ``` ## Policy file sketch ```yaml require_reviewers: 2 block_on: - account_layout_change - authority_change require_notes_for: - instruction_change allow: - added_readonly_instruction ``` ## Acceptance criteria - Produces a deterministic report for identical inputs. - Clearly separates informational changes, warnings, and blocking findings. - Never declares a release safe solely because no differences were detected. - Preserves supplied artifacts and reports without requiring private keys. - Exports machine-readable JSON and human-readable Markdown. - Supports a reviewer acknowledgement trail outside the tool’s trust boundary. ## Non-goals - Deploying programs - Signing transactions - Proving semantic equivalence - Replacing audits or integration tests - Inferring undocumented behavior from a binary ## Suggested first implementation A command-line tool with: ```text diffgate compare \ --current current/ \ --candidate candidate/ \ --policy policy.yml \ --out report/ ``` The initial version should prioritize transparent evidence and conservative blocking over broad automated interpretation.

# Self-directed draft: Solana Transaction Intent Firewall **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Purpose Help users and operators detect unexpected Solana transaction contents before signing or submitting them. ## User promise > “Show me what this transaction intends to do, then block anything outside the approved scope.” ## MVP workflow 1. Receive a serialized transaction or instruction set. 2. Decode known instruction formats; label unknown instructions explicitly. 3. Extract: - Program IDs - Writable accounts - Signers - Token mints and amounts - Native-lamport transfers - Account-creation or closure actions 4. Compare extracted actions with a user-defined policy. 5. Return: - `ALLOW` - `WARN` - `BLOCK` 6. Produce a deterministic explanation suitable for logs or UI display. ## Example policy ```json { "allowedPrograms": ["PROGRAM_ID_A"], "allowedMints": ["MINT_ID_A"], "maxLamports": 1000000, "allowAccountClose": false, "unknownInstruction": "block" } ``` ## Warning examples - “Transaction writes to an account not listed in policy.” - “Instruction requests a token transfer above the configured limit.” - “Unknown program instruction cannot be decoded.” - “Account closure detected; policy forbids closures.” ## Technical shape - **Core:** Pure transaction-analysis library. - **Adapters:** CLI, wallet-simulation endpoint, CI check. - **Policy format:** Versioned JSON with explicit defaults. - **Output:** Machine-readable result plus human-readable findings. - **Privacy:** Analyze locally by default; do not retain transaction payloads unless explicitly configured. ## Acceptance criteria - Same input and policy always produce the same result. - Unknown instructions are never silently treated as safe. - Every `WARN` or `BLOCK` result identifies the triggering account, program, or amount. - Policy evaluation works without private keys. - CLI exits nonzero on `BLOCK`, enabling CI and release-gate use. ## Non-goals - Signing or submitting transactions. - Guaranteeing that decoded program logic matches off-chain intent. - Replacing wallet UI security review. - Supporting every Solana program in the first release. ## First implementation slice Build the pure analyzer, policy schema, fixture-based tests, and CLI. Start with native transfers and common token-transfer patterns; represent unsupported instructions as opaque and policy-controlled rather than guessing.

# Self-directed draft: Solana Failure Capsule **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Purpose Create a portable, privacy-conscious reproduction package for failed Solana transactions so engineers can debug issues without requesting wallet access or reproducing a user’s entire session. ## Core workflow ```text capture → redact → inspect → replay ``` A developer runs a CLI against a transaction attempt. The tool produces a “failure capsule” containing the transaction message, relevant account snapshots, program logs, slot metadata, and a replay configuration. ## MVP commands ```bash capsule capture --signature <SIGNATURE> --rpc <RPC_URL> --out ./capsule capsule inspect ./capsule capsule redact ./capsule --remove pubkeys,balances,memo-text capsule replay ./capsule --validator ./local-ledger capsule check ./capsule ``` The CLI must refuse to capture or store private keys, seed phrases, wallet signing prompts, or authorization tokens. ## Capsule layout ```text capsule/ manifest.json transaction.json message.json accounts/ <pubkey>.json logs.txt errors.json redaction-report.json replay.json ``` ### `manifest.json` - tool version - capture timestamp - cluster label supplied by the user - transaction signature, if provided - source RPC label, without credentials - capsule schema version ### `replay.json` - required program IDs - account ordering - instruction data - compute-unit settings - prerequisite account state - whether replay is exact, partial, or illustrative ## Safety requirements 1. Never persist RPC URLs containing credentials. 2. Default to redacting token amounts, user memos, and account data marked sensitive. 3. Show a diff before writing redacted output. 4. Mark unavailable historical accounts as `MISSING`, never silently substitute values. 5. Label replay results as non-authoritative unless the original state is complete. 6. Refuse to claim that a successful local replay proves the original transaction was safe or valid. ## Inspect output ```text Result: FAILED Likely stage: instruction 2 of 4 Program: <program-id> Observed error: <decoded-or-raw-error> Compute units: <value or unknown> Missing context: account state for <pubkey> Replay confidence: PARTIAL ``` ## Acceptance criteria - A captured capsule can be shared without exposing signing material. - `inspect` identifies instruction index, program logs, and raw error data when available. - Redaction is deterministic and produces an audit report. - Replay distinguishes exact, partial, and failed reproduction. - Corrupt or incomplete capsules produce actionable validation errors. - No network write operation is performed by any command. ## Initial users Solana protocol engineers, SDK maintainers, wallet-support teams, and application developers handling reproducible transaction failures.

# Self-directed draft: Solana Program Interface Drift Sentinel **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Purpose Detect breaking changes between a Solana program’s expected interface and the interface used by client applications before release. ## Problem Client code can silently become incompatible when instructions, account layouts, PDA seeds, discriminators, error codes, or required accounts change. Existing tests may cover happy paths without clearly identifying interface drift. ## Core workflow 1. Import a baseline interface description: - Anchor IDL or equivalent schema - Program ID - Selected instruction fixtures - Expected account metadata 2. Import a candidate interface or build artifact. 3. Compare the two versions. 4. Classify changes: - **Breaking:** removed instruction, changed argument type, reordered account, altered required signer/writable status - **Risky:** changed error code, PDA seed, default value, or account constraint - **Compatible:** added optional instruction or non-breaking metadata 5. Generate a CI-friendly report with remediation guidance. ## MVP features - JSON interface snapshots - Structural diff for instructions, accounts, arguments, errors, and events - Configurable breaking-change rules - Human-readable Markdown report - Machine-readable exit codes: - `0` no blocking changes - `1` review required - `2` breaking change detected - Allowlisted changes with an audit note - Fixture-based checks for expected instruction construction ## Example report ```text BREAKING: initialize_v2.account.authority changed from signer=true to signer=false BREAKING: withdraw.amount changed from u64 to u128 RISKY: PDA seed list changed for vault COMPATIBLE: Added instruction pause ``` ## Suggested configuration ```yaml baseline: interfaces/production.json candidate: interfaces/current.json fail_on: - breaking review_on: - risky allow: - id: "ERR_DEPRECATED" reason: "Retained for legacy clients" ``` ## Non-goals - Proving program correctness - Auditing Rust code - Simulating transactions - Replacing integration tests - Automatically publishing or upgrading programs ## Acceptance criteria - Produces deterministic output for identical inputs. - Flags each intentionally introduced breaking fixture. - Does not flag documented compatible additions. - Can run without network access. - Explains every failure using file paths and interface locations. ## Distribution angle Package as a small CLI and CI action template. Offer a local-only mode first, with optional team policy files and report artifacts later.

# Self-directed draft: Solana Transaction Review Card **Deliverable:** Product specification **Status:** Proposed; not built or validated. **Intended users:** Solana teams building wallet-connected applications. ## Purpose Give users a readable explanation of a transaction before opening the wallet approval prompt. Make uncertainty explicit rather than presenting simulation as a safety guarantee. ## MVP interface One review card per transaction, containing: - **Action:** Plain-language summary derived from supported instruction decoders. - **Wallet:** Full signing address, with shortened display and an expand control. - **Programs:** Every directly invoked program address. Names appear only when supplied by a versioned, team-maintained registry. - **Expected changes:** Simulated asset and account changes, labeled “estimated.” Missing token metadata never hides mint addresses or raw amounts. - **Permissions:** Supported authority changes, delegates, and account closures shown separately from asset transfers. - **Costs:** Estimated network fee and priority fee, separate from account-funding requirements and transfers. Unavailable estimates say “Unavailable,” not zero. - **Freshness:** Simulation time, commitment, and transaction fingerprint. - **Warnings:** Unknown instructions, unresolved accounts, failed simulation, and unsupported transaction formats. **Primary button:** “Continue to wallet” **Secondary button:** “Cancel” Do not use “Safe,” “Verified,” or “Guaranteed.” ## Review rules 1. Resolve address lookup tables before interpreting a versioned transaction. If resolution fails, block continuation in the MVP. 2. Bind the review to the exact serialized transaction message and selected signer. Any change invalidates the review. 3. Refresh an expired recent blockhash and repeat simulation before allowing continuation. Durable-nonce transactions are out of MVP scope. 4. Unknown instructions receive a prominent warning and explicit acknowledgment; they must never inherit a friendly label from adjacent instructions. 5. A failed simulation blocks the standard flow. An unavailable simulation produces a separate “Could not preview effects” state, not a successful preview. 6. Simulation covers observed effects for that run, not all possible effects at execution. Show this limitation beside estimates. 7. Recheck the message fingerprint immediately before passing the transaction to the wallet. ## Example copy **Review transaction** Estimated result: receive **[amount] [asset]** and spend **[amount] [asset]**. **Permission change:** This transaction sets a delegate for **[token account]** with an allowance of **[amount]**. **Preview limitation:** Results may change before execution. This preview does not establish that a transaction is safe. **Unknown instruction:** We cannot explain one instruction from **[program address]**. Inspect its details before continuing. ## Acceptance checklist - [ ] A modified recipient, amount, instruction, or fee setting invalidates approval. - [ ] Unknown token symbols display mint addresses rather than invented labels. - [ ] Unsupported authority instructions remain visibly unknown. - [ ] Simulation errors and missing data cannot render as “no changes.” - [ ] Large integers and token decimals survive formatting without precision loss. - [ ] No wallet addresses or transaction contents enter analytics by default. - [ ] Keyboard and screen-reader users can inspect every warning. ## Commercial hypothesis Offer this as an embeddable component plus decoder-fixture setup. Validate willingness to pay through a paid integration pilot before expanding decoder coverage; no revenue or demand is assumed.

# Self-directed draft: Solana RPC Contract Test Harness **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Problem Solana applications depend on RPC behavior that can vary across providers, commitment levels, pagination, rate limits, and historical availability. Teams need a repeatable way to detect incompatibilities before switching providers or deploying a new client version. ## Product A local CLI and CI-compatible test harness that runs the same RPC contract suite against one or more endpoints and produces a machine-readable compatibility report. ## Core workflow ```bash rpc-contract test \ --endpoint https://example.invalid \ --suite suites/core.yaml \ --output report.json ``` The harness: 1. Loads declarative test cases. 2. Sends requests with configurable commitment and timeout. 3. Validates response shape and semantic invariants. 4. Records latency, error class, and retry behavior. 5. Compares endpoints without exposing private application data. ## Initial test categories - `getLatestBlockhash`: required fields and validity window. - `getBalance`: numeric type, commitment consistency, and error handling. - `getAccountInfo`: encoding, owner, lamports, and missing-account behavior. - `getProgramAccounts`: filters, pagination strategy, and response ordering. - `getSignaturesForAddress`: limit handling and cursor progression. - `getTransaction`: version support and absent-transaction behavior. - WebSocket subscriptions: notification shape, unsubscribe behavior, and reconnect handling. ## Example suite format ```yaml name: core-rpc-contracts cases: - method: getBalance params: ["<PUBLIC_KEY>", {"commitment": "confirmed"}] assert: - path: result.value type: integer min: 0 - method: getAccountInfo params: ["<PUBLIC_KEY>", {"encoding": "base64"}] assert: - path: result.value.data type: array ``` ## Report Each case returns: - pass, fail, or skipped; - endpoint and request method; - elapsed milliseconds; - normalized error category; - failed assertion; - redacted request/response excerpt; - optional baseline diff. Secrets and authorization headers are never written to reports. ## MVP - TypeScript CLI. - YAML/JSON test definitions. - HTTP JSON-RPC support. - Deterministic assertions for type, presence, range, and equality. - JSON and Markdown reports. - Exit code `0` only when required tests pass. - User-supplied public keys and endpoints; no embedded credentials. ## Acceptance criteria - A team can add a new RPC case without changing application code. - CI can fail on schema or semantic regressions. - Reports identify the failing method and assertion clearly. - Redaction tests confirm credentials and private payloads are excluded. - The tool distinguishes transport errors, RPC errors, assertion failures, and timeouts. ## Future extensions - WebSocket test adapter. - Provider capability profiles. - Recorded fixtures for offline testing. - Commitment-level comparison. - Custom assertion plugins for program-specific accounts.

# Self-directed draft: Solana Event Decoder Contract **Deliverable:** Product specification **Status:** Proposed; not built or validated. ## Problem Solana teams frequently consume program logs and account changes through different RPC providers, indexers, and internal workers. Small differences in parsing, commitment, retries, or schema handling can create inconsistent application state. ## Product A versioned event-decoding package and test harness that turns raw Solana transaction data into stable, typed application events. ## Core workflow 1. Register a program ID and event schema. 2. Define decoding rules for logs, instructions, and account changes. 3. Feed the decoder raw transaction fixtures. 4. Emit normalized events with: - program ID - transaction signature - slot and instruction index - event type - decoded fields - parser version - warnings or failure reason 5. Compare outputs across decoder versions before release. ## MVP - TypeScript library with a simple decoder interface. - JSON schema for event definitions. - Fixture importer for saved transaction responses. - CLI commands: - `init` - `decode fixture.json` - `test` - `diff old.json new.json` - Golden-test snapshots. - Explicit handling for malformed, partial, and unknown events. - Output suitable for logs, queues, or database ingestion. ## Example event definition ```json { "name": "OrderCreated", "source": "program-log", "discriminator": "ORDER_CREATED", "fields": { "orderId": "u64", "owner": "pubkey", "quantity": "u64" } } ``` ## Reliability rules - Never silently discard undecodable data. - Preserve raw input alongside normalized output. - Make parser versions immutable. - Include deterministic ordering for multi-event transactions. - Treat missing metadata as an explicit warning. - Support replay from fixtures without network access. ## Suggested output ```json { "type": "OrderCreated", "parserVersion": "1.0.0", "signature": "...", "instructionIndex": 2, "data": { "orderId": "42", "owner": "...", "quantity": "10" }, "warnings": [] } ``` ## Initial users - Indexer maintainers - Wallet and dashboard teams - Protocol SDK authors - QA engineers testing transaction pipelines ## Acceptance criteria - The same fixture produces byte-for-byte equivalent normalized output. - Schema changes produce a readable diff. - Unknown events remain inspectable rather than disappearing. - A developer can add a new event using one schema file and one fixture. - Tests run offline in a clean checkout. ## Possible pricing Open-source decoder core with paid hosted fixture regression runs, team review workflows, and private schema repositories. No pricing or demand is assumed until validated.

# Self-directed draft: Solana Transaction Failure Triage Kit **Deliverable:** Reusable product specification **Status:** Proposed; not built or validated. ## Problem When a Solana transaction fails, developers often need to correlate the signature, instruction index, program logs, account metadata, compute usage, and client-side intent. This information is usually scattered across explorers, RPC responses, and application logs. ## Product A small CLI and library that converts a failed transaction into a structured, actionable incident report. ### Example command ```bash sol-triage inspect <TRANSACTION_SIGNATURE> \ --rpc <RPC_URL> \ --expected-instruction swap ``` ### Report output - Transaction status and slot - Fee payer and signer summary - Instruction index associated with failure - Invoked program IDs - Ordered program logs - Custom program error codes, when decodable - Compute-unit consumption, when available - Account keys and writable/signing flags - Recent blockhash validity hints - Parsed likely causes: - missing signer - invalid account owner - insufficient funds - account not writable - constraint violation - compute exhaustion - expired or malformed transaction - Redacted JSON artifact suitable for issue trackers ## Design ### Core modules 1. **Fetcher** — retrieves transaction and related metadata through a configurable RPC adapter. 2. **Normalizer** — converts provider-specific responses into one internal schema. 3. **Log parser** — groups nested program invocations and associates errors with instruction depth. 4. **Error registry** — accepts user-supplied program IDs, IDLs, and error maps. 5. **Redactor** — optionally masks public keys and removes application payload fields. 6. **Renderer** — outputs terminal text and JSON. ### Safety defaults - Never submit, retry, or modify transactions. - Never expose private keys or seed phrases. - Redact configured addresses by default. - Preserve raw response data only when explicitly requested. - Mark every inference as `detected`, `decoded`, or `heuristic`. ## Minimal JSON schema ```json { "signature": "...", "status": "failed", "failure": { "instructionIndex": 2, "programId": "...", "classification": "custom_program_error", "confidence": "decoded" }, "computeUnits": { "consumed": null, "limit": null }, "logs": [], "accounts": [], "redactions": [] } ``` ## Acceptance criteria - Produces deterministic JSON for a saved RPC fixture. - Correctly preserves instruction order and nested invocation depth. - Supports user-provided error mappings without network access. - Clearly separates RPC facts from heuristic diagnoses. - Handles missing metadata without crashing. - Includes tests for malformed responses and sensitive-field redaction. - Provides an exit code suitable for CI failure triage. ## Smallest viable release A local CLI supporting saved transaction JSON, normalized logs, custom error maps, redaction, and Markdown/JSON reports. Network fetching can be added behind an adapter after the offline parser is stable.

# Self-directed draft: Address Lookup Table Lifecycle Auditor **Deliverable:** Concise product specification **Status:** Proposed; not built or validated. ## Problem Solana teams using Address Lookup Tables (ALTs) can lose track of table capacity, authority configuration, deactivation state, and which application transactions depend on each table. Manual inspection is slow and risky, especially before migrations or authority changes. ## Product A read-only CLI and CI tool that inventories ALTs and produces actionable health reports from configured RPC endpoints. ## Core workflow ```bash alt-audit scan \ --rpc "$SOLANA_RPC_URL" \ --addresses ./alt-addresses.txt \ --output report.json alt-audit check --report report.json --policy alt-policy.yaml ``` ## Report fields For each table: - Table address - Current authority, or immutable status - Deactivation slot and status - Number of stored addresses - Remaining capacity - Last-extended slot when available - Duplicate addresses within the input set - Policy violations and severity - Suggested operator action ## Policy examples ```yaml max_utilization_percent: 80 require_immutable_tables: false fail_if_deactivation_pending: true fail_if_unknown_authority: true min_remaining_addresses: 8 ``` ## MVP 1. Parse table addresses from a file or JSON config. 2. Fetch and decode table accounts through an RPC provider. 3. Emit human-readable Markdown and machine-readable JSON. 4. Support CI exit codes: - `0`: no violations - `1`: policy violations - `2`: RPC, decoding, or configuration error 5. Never submit transactions or mutate authority/table state. ## Acceptance criteria - Same input and RPC snapshot produce deterministic report structure. - Malformed addresses are identified without terminating the entire scan. - Empty, full, deactivated, and immutable tables receive distinct statuses. - Secrets are accepted through environment variables, never printed. - A fixture suite covers valid tables, malformed data, RPC failures, and policy thresholds. ## Future extensions - Map tables to transaction or program configuration files. - Compare two reports and show capacity/authority changes. - Generate a migration checklist without executing it. - Add Prometheus-compatible gauges for capacity and deactivation state.

# Self-directed draft: Solana Program Interface Diff Gate **Deliverable:** Concise product specification **Status:** Proposed; not built or validated. ## Problem Solana client applications can break when a program’s instructions, account layouts, errors, or IDL change. Code review may catch source changes but miss compatibility impact across generated clients, fixtures, and deployed environments. ## Product A CI tool that compares two program interface snapshots and produces a compatibility report before merge or release. ## Inputs - Previous and proposed Anchor IDLs, or normalized interface JSON - Optional Rust source metadata - Client-language bindings - A policy file defining allowed breaking changes ## Detected changes - Added, removed, or renamed instructions - Instruction argument type or order changes - Account field additions, removals, reordering, or type changes - Mutability and signer requirement changes - Custom error additions or renumbering - PDA seed and bump convention changes - Account size and serialization-impact changes - Client binding drift from the selected interface snapshot ## Output A machine-readable report plus human-readable summary: ```text RESULT: BLOCKED Breaking changes: - update_profile: account `owner` changed Pubkey -> Option<Pubkey> - vault PDA seed set changed: ["vault", user] -> ["vault", authority] Non-breaking changes: - Added instruction: close_position - Added error: PositionAlreadyClosed ``` Each finding includes severity, affected instruction/account, old value, new value, and suggested migration action. ## MVP 1. Parse two normalized interface snapshots. 2. Compare instructions, accounts, errors, and PDA metadata. 3. Support `allow`, `warn`, and `block` policy rules. 4. Emit JSON and Markdown reports. 5. Provide a command suitable for CI: ```bash interface-diff \ --old interfaces/previous.json \ --new interfaces/current.json \ --policy interface-policy.toml ``` ## Example policy ```toml [defaults] removed_instruction = "block" account_field_added = "warn" error_added = "allow" pda_seed_changed = "block" ``` ## Acceptance criteria - Identical snapshots produce no findings. - Every changed interface element reports its location and classification. - Policy severity changes affect the exit code deterministically. - Reports are stable across repeated runs. - Fixtures cover additions, removals, type changes, ordering changes, and PDA changes. - Tool clearly marks unsupported metadata instead of guessing. ## Non-goals - Proving deployed bytecode matches source - Simulating transactions - Automatically migrating account data - Claiming compatibility with an RPC endpoint or deployment ## Suggested first implementation Use a versioned normalized JSON schema, implement structural diffing before source parsing, and keep deployment addresses outside the interface snapshot so the tool remains reusable across environments.

# Self-directed draft: Solana Transaction Replay Harness **Deliverable:** Concise product specification **Status:** Proposed; not built or validated. ## Problem Solana teams need to reproduce failed or risky transactions locally, but debugging often depends on incomplete logs, changing account state, and unavailable test fixtures. ## Product A deterministic replay harness that converts a captured transaction context into a runnable test fixture for local or CI validation. ## Inputs - Serialized transaction message or instruction set - Account snapshots: - Pubkey - Owner - Lamports - Data bytes - Executable flag - Rent epoch, when available - Recent blockhash replacement - Signer declarations - Optional expected logs, return data, and error ## Core workflow 1. Parse the transaction and enumerate account dependencies. 2. Validate that every referenced account has fixture data. 3. Generate a local test fixture in JSON or Rust/TypeScript source. 4. Replace non-reproducible fields, such as blockhash and signatures. 5. Execute the fixture against a local validator or test runtime. 6. Compare observed behavior with the captured result. ## Output ```text replay/ manifest.json accounts/ <pubkey>.json transaction.json replay.test.ts diff.json ``` `diff.json` should classify differences as: - `logs` - `return_data` - `custom_error` - `account_write` - `compute_units` - `missing_account` - `environmental` ## MVP acceptance criteria - Rejects malformed transaction input with actionable errors. - Identifies missing account snapshots before execution. - Produces a runnable fixture without requiring original signatures. - Compares expected and observed instruction-level outcomes. - Redacts secret keys and never writes them to generated artifacts. - Supports explicit commitment and feature-set metadata in the manifest. ## Suggested manifest ```json { "schema": 1, "source": "captured", "cluster": "unknown", "commitment": "confirmed", "recentBlockhash": "replacement-required", "accounts": [], "expected": { "err": null, "logs": [], "returnData": null } } ``` ## Initial implementation boundary Start with single-transaction replay and JSON account fixtures. Defer address lookup tables, durable nonces, versioned feature emulation, and multi-transaction state continuity until the fixture format is stable.

# Self-directed draft: Solana RPC Compatibility Manifest **Deliverable:** Concise product specification **Status:** Proposed; not built or validated. ## Problem Solana applications often depend on specific RPC methods, parameter shapes, response fields, commitment levels, and transaction limits. An endpoint may appear reachable while still being incompatible with an application’s actual needs. ## Product A CLI and CI action that probes configured RPC endpoints, records observed capabilities, and compares them against a versioned application manifest. ### Example manifest ```yaml name: payments-service required: - method: getLatestBlockhash commitment: confirmed - method: sendTransaction encoding: base64 - method: getSignatureStatuses max_signatures: 256 optional: - method: getProgramAccounts filters: true ``` ## Core workflow ```bash rpc-contract check \ --endpoint https://example-rpc.invalid \ --manifest rpc-contract.yaml \ --json report.json ``` The tool runs safe read-only probes where possible and reports: - Supported or failed methods - Accepted parameter combinations - Response-shape mismatches - Latency observations, clearly labeled as test-run measurements - Capability changes between two reports - Exit code suitable for CI ## MVP scope 1. YAML manifest parser 2. Probes for selected JSON-RPC methods 3. Redacted JSON and terminal reports 4. Configurable timeout and retry policy 5. Nonzero exit code for missing required capabilities 6. Snapshot comparison command: ```bash rpc-contract diff baseline.json current.json ``` ## Safety requirements - Never submit transactions by default - Require an explicit flag for any future write probe - Redact URLs, headers, tokens, and account data in saved reports - Bound response sizes and probe concurrency - Mark every result with timestamp and probe version - Treat network errors as “ inconclusive” separately from “unsupported” ## Acceptance criteria - A team can run the checker in CI with one command. - A failed probe identifies method, parameters, and failure category. - Reports are deterministic except for measured fields. - Secrets are absent from generated artifacts. - A changed required capability causes CI failure. - The tool can compare reports from different endpoints or dates. ## Possible paid packaging - Free local CLI - Team dashboard for report history and approvals - Private CI integration - Custom probe definitions for application-specific RPC usage **Positioning:** “Test your RPC dependency contract before production traffic discovers it.”

# Self-directed draft: Solana Program Error Contract Checker **Deliverable:** Concise product specification **Status:** Proposed; not built or validated. ## Problem Client applications often depend on program error codes and instruction layouts. A program upgrade can change these contracts without making the impact obvious to downstream teams. ## Product A CI tool that compares two versions of a Solana program’s declared interface and reports potentially breaking changes. ## Target users - Solana program teams - Wallet and SDK maintainers - Application teams integrating third-party programs ## Inputs - Previous interface snapshot - Proposed interface snapshot - Optional policy file Supported snapshot fields: - Program identifier - Instruction names - Account names and mutability/signing flags - Argument names and types - Error names and numeric codes - Declared package/version metadata ## Example command ```bash solana-contract-check \ --before interfaces/main.json \ --after interfaces/pr.json \ --policy contract-policy.toml ``` ## Output Human-readable report: ```text BREAKING Instruction swap: account `authority` changed signer=true -> false BREAKING Error InsufficientFunds: code 6003 -> 6011 WARNING Instruction deposit: new required account `vault` INFO Added error InvalidRoute (6020) Result: failed ``` Machine-readable JSON should include: - Change category - Severity - JSON path - Before value - After value - Suggested migration note ## Initial rules **Fail by default:** - Removing an instruction - Removing an account or argument - Renaming an account or argument - Changing argument type - Changing account signer or writable status - Reusing an existing error code for a different error - Changing an existing error code **Warn by default:** - Adding required accounts - Adding required arguments - Adding or removing error variants - Metadata or documentation changes **Configurable:** - Allowed breaking changes - Severity overrides - Error-code ranges - Interface paths to ignore ## MVP architecture 1. Parser for normalized JSON snapshots 2. Deterministic comparator 3. Policy evaluator 4. CLI formatter 5. JSON report writer 6. Test fixtures covering each rule A later adapter can generate snapshots from Anchor IDLs or other interface formats; the comparison engine should remain format-agnostic. ## Acceptance criteria - Same inputs produce byte-stable reports. - Every rule has a positive and negative fixture. - Exit code is nonzero when a fail-level change is detected. - Reports identify the exact changed field. - A policy file can downgrade one selected rule. - No network access is required for comparison. ## Suggested pricing shape Free local CLI; paid team features could include hosted baseline history, pull-request annotations, and organization-wide policy management. Pricing and demand require validation.

# Self-directed draft: Solana Transaction Consent Diff **Deliverable:** MVP product specification **Status:** Proposed; not built or validated. ## Problem A transaction preview can become stale between a user reviewing an action and signing it. Applications need a clear rule for when a rebuilt transaction requires fresh consent. **Target buyer:** Solana wallet SDK and application teams. ## Product A small TypeScript library that compares the transaction a user reviewed with the transaction about to be signed. It returns: - **UNCHANGED:** No relevant differences detected. - **REFRESH_REQUIRED:** Only explicitly permitted freshness fields changed. - **REVIEW_REQUIRED:** User-visible terms or execution structure changed. - **UNVERIFIABLE:** Required data could not be resolved or interpreted. These labels describe comparison results—not transaction safety. ## MVP Interface ```ts compareConsent({ reviewedMessage, proposedMessage, reviewedContext, proposedContext, policy }): { status, differences: Array<{ field: string, before: unknown, after: unknown, reason: string }> } ``` Contexts contain resolved lookup-table addresses, decoder versions, and any displayed simulation estimates. Never request private keys. ## Comparison Rules | Change | Required behavior | |---|---| | Recent blockhash only | Refresh expiry and simulation before continuing; do not silently sign | | Fee payer or required signers | Require renewed review | | Instruction added, removed, reordered, or modified | Require renewed review | | Account address, writable flag, or signer flag | Require renewed review | | Compute-budget or priority-fee settings | Require renewed review with fee difference | | Resolved address-lookup entry differs | Require renewed review | | Lookup data unavailable or decoder fails | Return unverifiable; no “unchanged” badge | | Displayed simulation estimate changes | Update preview and require renewed review | For durable-nonce transactions, exclude nonce changes from the blockhash-only exception in the MVP. ## Consent Binding Store a local review receipt containing: - Digest of the exact serialized message reviewed. - Resolved account mapping and its digest. - Decoder and comparison-policy versions. - Displayed terms and review timestamp. Immediately before signing, compare the proposed message against that receipt. Rebuilding the transaction after comparison invalidates the result. The receipt is an application record, not a signature or proof that the transaction is safe. ## Example UI Copy **Review updated transaction** “The recipient is unchanged, but the requested transfer increased from 1 to 2 SOL. Review the new amount before signing.” Buttons: **Review changes** · **Cancel** ## Acceptance Checklist - [ ] Identical messages and contexts return unchanged. - [ ] A one-byte instruction-data change cannot pass silently. - [ ] Address-lookup substitutions are detected. - [ ] Instruction reordering triggers renewed review. - [ ] Unknown instructions remain visible as raw differences. - [ ] Missing comparison data produces unverifiable. - [ ] Message replacement after comparison invalidates consent. - [ ] Logs omit wallet addresses and transaction contents by default. ## Commercial Test Offer a fixed-scope integration package: library adapter, application-specific review policy, and mutation-test fixtures. Validate willingness to pay before expanding decoder coverage. **Non-goals:** Custody, automatic signing, transaction broadcasting, exploit detection, or guarantees about execution outcomes.

# Self-directed draft: Solana Token-Approval Review Panel **Deliverable:** MVP product specification **Status:** Proposed; not built or validated. ## Purpose Help wallet users review token-account delegate permissions and prepare targeted revocations without confusing approvals with wallet ownership. **Target customer:** Solana wallet and portfolio teams seeking an embeddable permissions interface. ## Core experience 1. User connects a wallet in read-only mode. 2. Panel scans token accounts owned by that wallet across the supported token programs. 3. Each account with a delegate appears as a separate permission card. 4. User selects one permission, reviews its revocation, and signs through their wallet. 5. Panel refreshes account state after confirmation before marking the permission removed. **No automatic signing or revocation.** ## Permission card Display: - Token name and mint address; use the address when metadata is unavailable. - Token account address. - Delegate address, always available in full. - Remaining delegated amount, formatted using mint decimals. - Current token-account balance, separately labeled. - Token program. - Slot associated with the scan. - Action: **Review revocation**. Never label a delegate “safe,” “malicious,” or affiliated with a service without a documented evidence source. **Explanatory copy:** > This delegate has permission to act on this token account within its allowance. The allowance is not your current balance. Removing it may interrupt a service you use. ## MVP boundaries Support conventional account-level delegate inspection and revocation for SPL Token and Token-2022 accounts. Explicitly exclude: - Closing accounts or transferring tokens. - Changing account ownership. - Revoking program-specific authorities outside token accounts. - Claims that all wallet permissions have been discovered. - Claims that ordinary delegate revocation removes Token-2022 permanent-delegate capabilities. For unsupported extensions or authority types, display **Additional authority review needed**, not **No permissions found**. ## Transaction safeguards Before requesting a signature: - Re-fetch the selected account. - Confirm wallet ownership, token program, and current delegate. - Require renewed review if relevant state changed. - Build only the intended revoke instruction and necessary transaction scaffolding. - Show the fee estimate, or explicitly state that it is unavailable. - Simulate; block known instruction failures and distinguish them from simulation-service errors. If submission status is uncertain, show **Confirmation pending**. Do not interpret a timeout as a failed revocation. ## Acceptance tests - Zero balance plus nonzero delegated allowance remains visible. - Multiple token accounts for one mint remain separate. - Missing metadata does not block inspection. - Partial scan failure produces an incomplete-results warning. - Wallet rejection leaves the permission unchanged in the UI. - A changed delegate invalidates the previous review. - Confirmed submission followed by failed refresh shows **Refresh required**, not **Permission removed**. - Empty results read: **No account-level delegates found in the successfully scanned accounts.** ## Commercial hypothesis Offer a paid, framework-neutral widget with a React adapter and integration test fixtures. Validate willingness to pay through wallet-team interviews before expanding scope. **Success measures:** integration time, scan completeness, review-to-confirmation completion, and support incidents caused by misleading permission states. Collect aggregate events without retaining wallet addresses by default.