txray 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 - 2026-10-27
+
+- Install-and-run npm CLI: `npx txray`, with port, help and version options.
+- Built assets included in the package, with a clean-consumer install test.
+- Read-only confirmed Mainnet and Devnet transaction inspection.
+- Known runtime-error explanations, explicit unknown custom errors and missing-data states.
+- Legacy, v0 lookup-address and v1 transaction-config support.
+- Exact recorded fees, compute, instruction timeline and nested logs.
+- Dark local dashboard, fictional offline examples, text copy and JSON export.
+- In-app guide, architecture, API documentation and automated tests.

package/CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing
+
+Use Node.js 22.18+ and npm. Keep the tool read-only, local-first and small.
+
+```sh
+npm install
+npm run check
+npm run package:check
+npx playwright install chromium
+npm run test:e2e
+```
+
+`npm run package:check` installs the built tarball into a clean temporary consumer and tests its actual executable, assets and dependency audit. It needs registry access but never publishes.
+
+`npm run format` formats source and docs. `npm run dev` rebuilds browser assets once and watches the server; rerun `npm run build` after browser or documentation edits.
+
+Keep domain logic separate from RPC and HTTP. Test new error mappings against a documented program/runtime definition; never infer a custom error's meaning from its number or a log substring. Missing data must not become success or zero.
+
+Add regression tests for bug fixes. Use synthetic fixtures with an explicit label; never add private keys, `.env`, node_modules, build output, local ledgers or video production tools. Keep commits focused and use Conventional Commits.
+
+A useful bug report includes Node version, selected network, expected and observed behavior, and a minimal public transaction signature if sharing it is appropriate. Never include wallet keys or access tokens.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Royal Pinto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# txray
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Solana Transaction Autopsy.** Paste a transaction signature and understand the failure, fee and execution behind it.
+
+```sh
+npx txray
+```
+
+Requires **Node.js 22.18+**. Open **http://127.0.0.1:4450**, paste a signature and choose Mainnet or Devnet. Or start with a labeled offline example. No wallet, SOL, API key or account needed.
+
+![txray explaining a fictional insufficient-funds transaction](https://raw.githubusercontent.com/royalpinto007/txray/main/docs/screenshot.png)
+
+[Source on GitHub](https://github.com/royalpinto007/txray) · [npm package](https://www.npmjs.com/package/txray)
+
+Use `npx txray --port 4452` for another port. `--help` shows options; `--version` prints the installed version. Press Ctrl+C to stop.
+
+## Run from source
+
+Requires **Node.js 22.18+** and npm.
+
+```sh
+git clone https://github.com/royalpinto007/txray.git
+cd txray
+npm install
+npm run demo
+```
+
+## What you get
+
+- Plain explanations for known runtime errors. Unknown custom errors stay unknown.
+- Failed top-level instruction, program addresses and nested execution logs.
+- Exact recorded fees, compute consumption and requested compute settings.
+- Legacy, v0 and v1 support, with visible missing-data notes.
+- Copyable diagnostics and JSON export with the full returned record.
+
+Runs on your computer. No database, saved lookup history, telemetry or hosted service. Live signatures go to Solana's public RPC; availability, rate limits and historical coverage vary.
+
+The RPC provides a total fee, not an exact base/priority split. Decoding covers basic System transfer and Compute Budget instructions; other instruction data stays available without guessed meanings. This is an execution debugger, not a security verdict or a full balance-change explorer.
+
+**[Guide](docs/guide.md)** · **[Architecture](docs/architecture.md)** · **[Local API](docs/api.md)**
+
+Guide and architecture pages are also available inside the dashboard, offline.
+
+## Develop
+
+```sh
+npm run check
+npm run package:check
+npx playwright install chromium
+npm run test:e2e
+```
+
+Tests do not depend on public RPC. To use another local port: `PORT=4452 npm run demo`.
+
+[Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,9 @@
+# Security
+
+This is a local read-only debugger. No wallets or private keys are needed. Live signatures are sent to a fixed public RPC endpoint. No lookup data is written to disk automatically.
+
+Do not bind it publicly or use it as a hosted RPC proxy. Local processes with access to your machine can call a loopback service. Host and Origin checks reduce cross-site access; they are not user authentication.
+
+Keep Node.js and dependencies current. Avoid sharing exports containing information you did not intend to disclose, even though the transaction record is public.
+
+For a security issue, use the repository's private vulnerability reporting feature when available. Do not include secrets in public issues. Maintainer contact: royalpinto007@gmail.com.

package/dist/adapters/examples.js

@@ -0,0 +1,173 @@
+import { analyzeTransaction } from "../domain/analyze.js";
+import { toBase58 } from "../domain/base58.js";
+import { SYSTEM, COMPUTE } from "../domain/instructions.js";
+export const examples = [
+    {
+        id: "insufficient-funds",
+        title: "Insufficient funds",
+        description: "A known instruction failure, with earlier work rolled back.",
+    },
+    {
+        id: "unknown-program",
+        title: "Unknown program error",
+        description: "A custom error and nested calls, with no invented explanation.",
+    },
+    {
+        id: "successful-v0",
+        title: "Successful v0",
+        description: "A transfer using a loaded address from a lookup table.",
+    },
+    {
+        id: "missing-metadata",
+        title: "Missing metadata",
+        description: "A transaction whose outcome, fee and compute are unavailable.",
+    },
+    {
+        id: "v1-config",
+        title: "v1 transaction",
+        description: "Compute and priority fee settings read from the message config.",
+    },
+];
+const payer = toBase58(new Uint8Array(32).fill(7));
+const recipient = toBase58(new Uint8Array(32).fill(8));
+const unknown = toBase58(new Uint8Array(32).fill(9));
+function base() {
+    const limit = new Uint8Array([2, 64, 13, 3, 0]);
+    const transfer = new Uint8Array(12);
+    transfer[0] = 2;
+    transfer[4] = 64;
+    transfer[5] = 66;
+    transfer[6] = 15;
+    return {
+        slot: 321654987,
+        blockTime: 1760000000,
+        version: "legacy",
+        transaction: {
+            signatures: [toBase58(new Uint8Array(64).fill(11))],
+            message: {
+                header: {
+                    numRequiredSignatures: 1,
+                    numReadonlySignedAccounts: 0,
+                    numReadonlyUnsignedAccounts: 2,
+                },
+                recentBlockhash: payer,
+                accountKeys: [payer, recipient, COMPUTE, SYSTEM],
+                instructions: [
+                    {
+                        programIdIndex: 2,
+                        accounts: [],
+                        data: toBase58(limit),
+                    },
+                    { programIdIndex: 3, accounts: [0, 1], data: toBase58(transfer) },
+                    { programIdIndex: 3, accounts: [0, 1], data: toBase58(transfer) },
+                ],
+            },
+        },
+        meta: {
+            err: { InstructionError: [1, "InsufficientFunds"] },
+            fee: 5000,
+            computeUnitsConsumed: 18420,
+            preBalances: [25000, 0, 1, 1],
+            postBalances: [20000, 0, 1, 1],
+            loadedAddresses: { writable: [], readonly: [] },
+            innerInstructions: [],
+            logMessages: [
+                `Program ${COMPUTE} invoke [1]`,
+                `Program ${COMPUTE} success`,
+                `Program ${SYSTEM} invoke [1]`,
+                "Program log: fictional example: account lacks required funds",
+                `Program ${SYSTEM} consumed 18420 of 200000 compute units`,
+                `Program ${SYSTEM} failed: insufficient funds`,
+            ],
+        },
+    };
+}
+export function exampleTransaction(id) {
+    if (!examples.some((example) => example.id === id))
+        return null;
+    const raw = base();
+    if (id === "insufficient-funds")
+        return raw;
+    if (id === "missing-metadata")
+        return { ...raw, meta: null };
+    if (id === "unknown-program") {
+        raw.transaction.message.accountKeys.push(unknown);
+        raw.transaction.message.instructions[1].programIdIndex = 4;
+        raw.meta.err = { InstructionError: [1, { Custom: 6001 }] };
+        raw.meta.logMessages = [
+            `Program ${COMPUTE} invoke [1]`,
+            `Program ${COMPUTE} success`,
+            `Program ${unknown} invoke [1]`,
+            `Program ${SYSTEM} invoke [2]`,
+            `Program ${SYSTEM} consumed 120 of 197000 compute units`,
+            `Program ${SYSTEM} failed: custom program error: 0x1771`,
+            `Program ${unknown} consumed 2440 of 200000 compute units`,
+            `Program ${unknown} failed: custom program error: 0x1771`,
+        ];
+        raw.meta.computeUnitsConsumed = 2590;
+        return raw;
+    }
+    raw.meta.err = null;
+    raw.meta.computeUnitsConsumed = 450;
+    raw.transaction.message.instructions =
+        raw.transaction.message.instructions.slice(0, 2);
+    raw.meta.logMessages = [
+        `Program ${COMPUTE} invoke [1]`,
+        `Program ${COMPUTE} success`,
+        `Program ${SYSTEM} invoke [1]`,
+        `Program ${SYSTEM} success`,
+    ];
+    if (id === "successful-v0") {
+        raw.version = 0;
+        raw.transaction.message.accountKeys = [payer, COMPUTE, SYSTEM];
+        raw.transaction.message.instructions[0].programIdIndex = 1;
+        raw.transaction.message.instructions[1].programIdIndex = 2;
+        raw.transaction.message.instructions[1].accounts = [0, 3];
+        raw.meta.loadedAddresses.writable = [recipient];
+        raw.meta.preBalances = [2000000, 1, 1, 0];
+        raw.meta.postBalances = [995000, 1, 1, 1000000];
+        return {
+            ...raw,
+            transaction: {
+                ...raw.transaction,
+                message: {
+                    ...raw.transaction.message,
+                    addressTableLookups: [
+                        { accountKey: unknown, writableIndexes: [0], readonlyIndexes: [] },
+                    ],
+                },
+            },
+        };
+    }
+    raw.version = 1;
+    raw.meta.fee = 6000;
+    raw.meta.preBalances = [2000000, 0, 1, 1];
+    raw.meta.postBalances = [994000, 1000000, 1, 1];
+    return {
+        ...raw,
+        transaction: {
+            ...raw.transaction,
+            message: {
+                ...raw.transaction.message,
+                transactionConfig: {
+                    computeUnitLimit: 30000,
+                    priorityFee: 1000,
+                    heapSize: null,
+                    loadedAccountsDataSizeLimit: 200000,
+                },
+            },
+        },
+    };
+}
+export function inspectExample(id) {
+    const raw = exampleTransaction(id);
+    if (raw === null)
+        return null;
+    const signature = base().transaction.signatures[0];
+    return analyzeTransaction(raw, {
+        signature,
+        network: "devnet",
+        source: "example",
+        exampleId: id,
+    });
+}

package/dist/adapters/rpc.js

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import { TxrayError } from "../domain/errors.js";
+import { analyzeTransaction } from "../domain/analyze.js";
+import { requestSchema } from "../domain/schema.js";
+export const ENDPOINTS = {
+    devnet: "https://api.devnet.solana.com",
+    "mainnet-beta": "https://api.mainnet-beta.solana.com",
+};
+export const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+export function parseRpcJson(text) {
+    return JSON.parse(text, (_key, value, context) => typeof value === "number" &&
+        !Number.isSafeInteger(value) &&
+        context?.source &&
+        /^-?[0-9]+$/.test(context.source)
+        ? context.source
+        : value);
+}
+const envelope = z.object({
+    jsonrpc: z.literal("2.0"),
+    id: z.literal(1),
+    result: z.unknown().optional(),
+    error: z.object({ code: z.number(), message: z.string() }).optional(),
+});
+async function readBody(response) {
+    if (Number(response.headers.get("content-length")) > MAX_RESPONSE_BYTES) {
+        await response.body?.cancel();
+        throw new TxrayError("RESPONSE_TOO_LARGE", "RPC response exceeded the 2 MiB limit.");
+    }
+    if (!response.body)
+        throw new TxrayError("RPC_INVALID_RESPONSE", "RPC returned an empty response.");
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            size += chunk.value.byteLength;
+            if (size > MAX_RESPONSE_BYTES) {
+                await reader.cancel();
+                throw new TxrayError("RESPONSE_TOO_LARGE", "RPC response exceeded the 2 MiB limit.");
+            }
+            chunks.push(chunk.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    try {
+        return parseRpcJson(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw new TxrayError("RPC_INVALID_RESPONSE", "RPC returned unreadable JSON.");
+    }
+}
+export async function inspectTransaction(input, options = {}) {
+    const { signature, network } = requestSchema.parse(input);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 12000);
+    try {
+        const response = await (options.fetchImpl ?? fetch)(ENDPOINTS[network], {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+            },
+            redirect: "error",
+            signal: controller.signal,
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "getTransaction",
+                params: [
+                    signature,
+                    {
+                        encoding: "json",
+                        commitment: "confirmed",
+                        maxSupportedTransactionVersion: 1,
+                    },
+                ],
+            }),
+        });
+        if (response.status === 429) {
+            await response.body?.cancel();
+            const retry = Number(response.headers.get("retry-after"));
+            throw new TxrayError("RPC_RATE_LIMITED", "The public RPC is busy. Wait before retrying.", 429, Number.isFinite(retry) && retry > 0
+                ? Math.min(3600, Math.ceil(retry))
+                : 30);
+        }
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new TxrayError("RPC_UNAVAILABLE", `Public RPC returned HTTP ${response.status}. Try again later.`, 503);
+        }
+        const parsed = envelope.safeParse(await readBody(response));
+        if (!parsed.success)
+            throw new TxrayError("RPC_INVALID_RESPONSE", "RPC response did not match the expected format.");
+        const data = parsed.data;
+        if (data.error) {
+            if (data.error.code === -32015)
+                throw new TxrayError("UNSUPPORTED_VERSION", "The RPC cannot return this transaction version. Legacy, v0 and v1 are requested.");
+            throw new TxrayError("RPC_ERROR", `The RPC could not complete the lookup (code ${data.error.code}). Try again later.`);
+        }
+        if (data.result === null)
+            throw new TxrayError("TRANSACTION_NOT_FOUND", "Transaction not available on this network at confirmed commitment. Check the network; it may be unconfirmed, pruned or not found.", 404);
+        if (data.result === undefined)
+            throw new TxrayError("RPC_INVALID_RESPONSE", "RPC did not return a transaction result.");
+        try {
+            const report = analyzeTransaction(data.result, {
+                signature,
+                network,
+                source: "live",
+            });
+            if (report.raw.transaction.signatures[0] !== signature)
+                throw new Error("Signature mismatch");
+            return report;
+        }
+        catch {
+            throw new TxrayError("RPC_INVALID_RESPONSE", "The RPC transaction has an unsupported or malformed structure. No diagnosis was inferred.");
+        }
+    }
+    catch (error) {
+        if (error instanceof TxrayError)
+            throw error;
+        if (controller.signal.aborted)
+            throw new TxrayError("RPC_TIMEOUT", "The public RPC did not respond in time. Try again.", 504);
+        throw new TxrayError("RPC_UNAVAILABLE", "Could not reach the public RPC. Check your connection and try again.", 503);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/app.js

@@ -0,0 +1,111 @@
+import express from "express";
+import helmet from "helmet";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { inspectTransaction } from "./adapters/rpc.js";
+import { examples, inspectExample } from "./adapters/examples.js";
+import { TxrayError } from "./domain/errors.js";
+import { requestSchema } from "./domain/schema.js";
+export function createApp(options = {}) {
+    const app = express();
+    let active = 0;
+    let count = 0;
+    let since = Date.now();
+    app.disable("x-powered-by");
+    app.use(helmet({
+        contentSecurityPolicy: {
+            directives: {
+                defaultSrc: ["'self'"],
+                scriptSrc: ["'self'"],
+                styleSrc: ["'self'"],
+                imgSrc: ["'self'"],
+                connectSrc: ["'self'"],
+                fontSrc: ["'self'"],
+                objectSrc: ["'none'"],
+                frameAncestors: ["'none'"],
+                upgradeInsecureRequests: null,
+            },
+        },
+        strictTransportSecurity: false,
+    }));
+    app.use((req, res, next) => {
+        const host = req.headers.host;
+        if (!host ||
+            !/^(?:localhost|127\.0\.0\.1|\[::1\])(?::[0-9]{1,5})?$/.test(host) ||
+            (req.headers.origin && req.headers.origin !== `http://${host}`) ||
+            req.headers["sec-fetch-site"] === "cross-site")
+            return next(new TxrayError("FORBIDDEN", "Open txray through its local address.", 403));
+        res.setHeader("Cache-Control", "no-store");
+        next();
+    });
+    app.use("/api", (req, _res, next) => {
+        if (req.method === "POST" && !req.is("application/json"))
+            return next(new TxrayError("UNSUPPORTED_MEDIA_TYPE", "Send application/json.", 415));
+        next();
+    });
+    app.use(express.json({ limit: "16kb", strict: true }));
+    app.get("/api/health", (_req, res) => res.json({ ok: true, app: "txray", readOnly: true }));
+    app.get("/api/examples", (_req, res) => res.json(examples));
+    app.get("/api/examples/:id", (req, res, next) => {
+        const report = inspectExample(req.params.id);
+        if (!report)
+            return next(new TxrayError("EXAMPLE_NOT_FOUND", "Example not found.", 404));
+        res.json(report);
+    });
+    app.post("/api/transactions", async (req, res, next) => {
+        try {
+            const input = requestSchema.parse(req.body);
+            if (active >= (options.maxConcurrent ?? 4))
+                throw new TxrayError("LOOKUP_BUSY", "Another lookup is in progress. Try again shortly.", 429, 2);
+            if (Date.now() - since >= 60000) {
+                since = Date.now();
+                count = 0;
+            }
+            if (count >= 30)
+                throw new TxrayError("LOCAL_RATE_LIMIT", "Limit of 30 live lookups per minute reached. Wait before retrying.", 429, 60);
+            active++;
+            count++;
+            try {
+                res.json(await inspectTransaction(input, options));
+            }
+            finally {
+                active--;
+            }
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    const publicDir = fileURLToPath(new URL("../dist/public/", import.meta.url));
+    app.get("/guide", (_req, res) => res.sendFile("guide.html", { root: publicDir }));
+    app.get("/architecture", (_req, res) => res.sendFile("architecture.html", { root: publicDir }));
+    app.use(express.static(publicDir, { index: "index.html", etag: false }));
+    app.use((_req, _res, next) => next(new TxrayError("NOT_FOUND", "Page or API route not found.", 404)));
+    const errors = (error, _req, res, _next) => {
+        let failure;
+        if (error instanceof TxrayError)
+            failure = error;
+        else if (error instanceof z.ZodError)
+            failure = new TxrayError("INVALID_INPUT", "Enter a valid transaction signature and choose Mainnet or Devnet.", 400);
+        else if (typeof error === "object" &&
+            error !== null &&
+            "type" in error &&
+            error.type === "entity.too.large")
+            failure = new TxrayError("BODY_TOO_LARGE", "Request body exceeds 16 KiB.", 413);
+        else if (error instanceof SyntaxError)
+            failure = new TxrayError("INVALID_JSON", "Request body is not valid JSON.", 400);
+        else
+            failure = new TxrayError("INTERNAL_ERROR", "txray could not complete this request.", 500);
+        if (failure.retryAfter)
+            res.setHeader("Retry-After", String(failure.retryAfter));
+        res.status(failure.status).json({
+            error: {
+                code: failure.code,
+                message: failure.message,
+                ...(failure.retryAfter ? { retryAfter: failure.retryAfter } : {}),
+            },
+        });
+    };
+    app.use(errors);
+    return app;
+}

package/dist/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+try {
+    const { values } = parseArgs({
+        options: {
+            help: { type: "boolean", short: "h" },
+            version: { type: "boolean", short: "v" },
+            port: { type: "string" },
+        },
+        allowPositionals: false,
+    });
+    if (values.help) {
+        console.log(`txray | Solana Transaction Autopsy
+
+Usage: txray [--port 4450]
+
+  --port         Local dashboard port (default: PORT or 4450)
+  -h, --help     Show this help
+  -v, --version  Show the package version
+
+Open the printed localhost URL. Press Ctrl+C to stop.
+Read-only; no wallet, keys or funds required.`);
+    }
+    else if (values.version) {
+        const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        console.log(manifest.version);
+    }
+    else {
+        if (values.port !== undefined)
+            process.env.PORT = values.port;
+        await import("./server.js");
+    }
+}
+catch (error) {
+    console.error(`txray: ${error instanceof Error ? error.message : "Could not start. Run txray --help."}`);
+    process.exitCode = 1;
+}