txray 0.0.0-stage → 0.1.0

package/dist/server.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { createApp } from "./app.js";
+try {
+    const port = z.coerce
+        .number()
+        .int()
+        .min(1024)
+        .max(65535)
+        .parse(process.env.PORT ?? 4450);
+    const server = createApp().listen(port, "127.0.0.1", () => {
+        console.log(`txray: http://127.0.0.1:${port}`);
+        console.log("Read-only. No wallet, keys or funds required.");
+    });
+    server.requestTimeout = 16000;
+    server.headersTimeout = 10000;
+    server.on("error", (error) => {
+        console.error(error.code === "EADDRINUSE"
+            ? `Port ${port} is already in use. Set another PORT.`
+            : "Could not start txray.");
+        process.exitCode = 1;
+    });
+}
+catch {
+    console.error("PORT must be an integer between 1024 and 65535.");
+    process.exitCode = 1;
+}

package/docs/api.md

@@ -0,0 +1,37 @@
+# Local API
+
+Base address: `http://127.0.0.1:4450`. JSON responses are not cached. There is no authentication; the server binds to loopback and rejects foreign Host and Origin headers. This is a local tool, not a hosted service.
+
+## Inspect a live transaction
+
+```sh
+curl http://127.0.0.1:4450/api/transactions \
+  -H 'Content-Type: application/json' \
+  -d '{"signature":"YOUR_TRANSACTION_SIGNATURE","network":"devnet"}'
+```
+
+`signature` must decode to 64 bytes of base58. `network` is `devnet` or `mainnet-beta`. Extra fields, arbitrary URLs and oversized request bodies are rejected. The placeholder above must be replaced before running.
+
+The server calls `getTransaction` with `encoding: "json"`, `commitment: "confirmed"` and `maxSupportedTransactionVersion: 1`.
+
+A report contains `schemaVersion`, `signature`, `network`, `source`, `checkedAt`, `slot`, `version`, `status`, `diagnosis`, `fee`, `compute`, `instructions`, `logs`, `warnings`, `summaryText` and `raw`. Unavailable values are `null` or carry an explicit unknown state. Monetary values and large integers use exact decimal strings. `raw` is the validated RPC record, with known integer fields normalized to strings and unknown fields retained.
+
+Instruction `index` is zero-based; `number` is one-based. The identified failed program is the top-level program. Inner calls and logs are preserved without claiming a verified innermost cause. Requested settings do not establish the exact charged base/priority fee split.
+
+## Offline examples
+
+- `GET /api/examples`: example names and descriptions.
+- `GET /api/examples/insufficient-funds`: a complete fictional report.
+- Other IDs: `unknown-program`, `successful-v0`, `missing-metadata`, `v1-config`.
+
+Examples run the same analyzer without querying RPC. Every example report has `source: "example"`.
+
+`GET /api/health` reports that the local HTTP server is running; it does not assert RPC availability.
+
+## Errors and bounds
+
+Errors use `{ "error": { "code": "TRANSACTION_NOT_FOUND", "message": "..." } }` with a non-200 status. Not found is 404; invalid input is 400; rejected origin is 403; non-JSON body is 415; excessive request size is 413; throttling is 429; RPC problems use 502, 503 or 504. Throttled responses include `Retry-After` when available.
+
+The server accepts 16 KiB JSON requests and 2 MiB RPC responses, with a 12-second RPC timeout, four concurrent lookups and 30 live lookups per minute. No automatic retries. A null RPC result may mean wrong network, unconfirmed, pruned or unavailable history; it does not prove nonexistence.
+
+Browser export is a local download of this report, not another API call.

package/docs/architecture.md

@@ -0,0 +1,32 @@
+# Architecture
+
+![txray architecture](architecture.svg)
+
+The browser asks a local Express server for a transaction. The server queries a fixed public Solana RPC endpoint, validates the response, and runs a pure analyzer. No database, wallet, hosted backend or paid API is required.
+
+| Part                       | Responsibility                                                                          |
+| -------------------------- | --------------------------------------------------------------------------------------- |
+| `src/cli.ts`               | npm executable, help, version and local port options                                    |
+| `src/web/app.ts`           | Signature form, diagnostics, timeline, text copy and JSON download                      |
+| `src/app.ts`               | Local HTTP boundary, input checks, security headers and lookup limits                   |
+| `src/adapters/rpc.ts`      | Confirmed JSON RPC reads, exact integers, timeout and response cap                      |
+| `src/domain/`              | Response schema, account resolution, known errors, instruction decoding and log parsing |
+| `src/adapters/examples.ts` | Clearly labeled fictional records, analyzed by the same domain code                     |
+
+## Trust boundaries
+
+Only the fixed Mainnet and Devnet endpoints can be queried. User-supplied RPC URLs are not accepted. The server binds to `127.0.0.1` and checks Host, Origin and cross-site fetch headers. The browser uses a same-origin content security policy. Log text is inserted as text, never HTML.
+
+The RPC response is the source of observations. Known runtime errors are mapped conservatively; custom errors have no guessed meanings. Fee amounts and large integers remain exact decimal strings. Per-program logs do not override `meta.err` or establish a root cause by themselves.
+
+Live results stay in process memory for the request and in the current browser view. They are not written to disk. Examples contain no real transaction claims. The only file output is a user-requested browser export.
+
+## Running and testing
+
+`npm run demo` builds the TypeScript server, bundles the small browser entry and generates the guide and architecture pages. Both pages are available inside the dashboard without a Markdown viewer or internet.
+
+`npx txray` starts the prebuilt server and browser assets from the installed package. Consumers do not need TypeScript or build tools. The npm archive includes only built runtime files, public documentation and the license.
+
+Unit tests cover domain behavior. API tests replace the external fetch boundary, while running real handlers. Browser tests use a local test server and exercise the full form, rendering and export path without a public RPC dependency.
+
+[Guide](guide.md)

package/docs/architecture.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="530" viewBox="0 0 960 530" role="img" aria-labelledby="title desc">
+<title id="title">txray architecture</title><desc id="desc">A local browser sends a transaction signature to a local Express server. The server reads a fixed Solana RPC endpoint, validates the response, and analyzes errors and logs. Results return to the dashboard for copy or JSON export. Offline examples bypass RPC. No data is stored.</desc>
+<rect width="960" height="530" rx="12" fill="#10171f"/>
+<g font-family="Arial,sans-serif" fill="#e3eaf0">
+<text x="36" y="49" font-size="26" font-weight="700">From signature to diagnosis</text>
+<text x="36" y="80" font-size="17" fill="#a2b1bf">Read-only. Local processing. No saved lookups.</text>
+<g fill="#18232d" stroke="#334553"><rect x="36" y="124" width="256" height="112" rx="9"/><rect x="352" y="124" width="256" height="112" rx="9"/><rect x="668" y="124" width="256" height="112" rx="9"/><rect x="352" y="307" width="256" height="112" rx="9"/><rect x="36" y="307" width="256" height="112" rx="9"/><rect x="668" y="307" width="256" height="112" rx="9"/></g>
+<text x="56" y="162" font-size="22" font-weight="700">Local dashboard</text><text x="56" y="191" font-size="16" fill="#a2b1bf">Signature + network</text><text x="56" y="216" font-size="16" fill="#a2b1bf">127.0.0.1:4450</text>
+<text x="372" y="162" font-size="22" font-weight="700">Express server</text><text x="372" y="191" font-size="16" fill="#a2b1bf">Validate input and response</text><text x="372" y="216" font-size="16" fill="#a2b1bf">Timeout, size and lookup caps</text>
+<text x="688" y="162" font-size="22" font-weight="700">Solana public RPC</text><text x="688" y="191" font-size="16" fill="#a2b1bf">Mainnet / Devnet</text><text x="688" y="216" font-size="16" fill="#a2b1bf">getTransaction (confirmed)</text>
+<text x="372" y="347" font-size="22" font-weight="700">Pure analyzer</text><text x="372" y="377" font-size="16" fill="#a2b1bf">Errors, instructions, logs</text><text x="372" y="402" font-size="16" fill="#a2b1bf">Exact fees and compute</text>
+<text x="56" y="347" font-size="22" font-weight="700">Readable report</text><text x="56" y="377" font-size="16" fill="#a2b1bf">Timeline and diagnostics</text><text x="56" y="402" font-size="16" fill="#a2b1bf">Copy text / export JSON</text>
+<text x="688" y="347" font-size="22" font-weight="700">Offline examples</text><text x="688" y="377" font-size="16" fill="#a2b1bf">Fictional records</text><text x="688" y="402" font-size="16" fill="#a2b1bf">Same analyzer, no RPC</text>
+<g stroke="#90c9ee" stroke-width="2" fill="none"><path d="M295 178h50m-9-7 9 7-9 7M611 166h50m-9-7 9 7-9 7M661 198h-50m9-7-9 7 9 7M480 242v57m-7-9 7 9 7-9M345 363h-45m9-7-9 7 9 7M661 363h-45m9-7-9 7 9 7"/></g>
+<text x="36" y="475" font-size="17" fill="#a2b1bf">No wallet, signing, database, cloud deployment or paid API.</text>
+<text x="36" y="502" font-size="17" fill="#a2b1bf">Unknown errors and missing metadata remain visible.</text>
+</g></svg>

package/docs/guide.md

@@ -0,0 +1,41 @@
+# Using txray
+
+Run `npx txray` with Node.js 22.18+. Open the printed local URL. Use `npx txray --port 4452` if the default port is busy. Press Ctrl+C to stop.
+
+Paste a Solana transaction signature, select its network and choose **Inspect transaction**. A transaction signature is the public identifier of a transaction, not a wallet address.
+
+Start with an **offline example** if you do not have a signature. All example values are fictional. No RPC request is made for an example.
+
+## Read a result
+
+1. **Diagnosis:** a known runtime error gets a plain explanation. Custom program errors remain unknown; a code such as `6001` means different things in different programs.
+2. **Failed instruction:** `#2` means RPC index `1`. This identifies the top-level instruction, not necessarily the innermost cause of a nested failure.
+3. **Fee and compute:** the fee is the total recorded in metadata. Compute consumption comes from `meta.computeUnitsConsumed`. Missing values say **Not reported**, never zero.
+4. **Instruction timeline:** earlier instructions ran before the failure; later instructions did not run. Ordinary program state changes roll back. Fees and durable-nonce advancement can persist.
+5. **Execution log:** lines appear in recorded order. Indentation follows runtime invocation depth. A log's wording is evidence of what a program printed, not an independently verified explanation.
+
+An inner call can fail and be caught by its caller; only `meta.err` determines the transaction outcome. Nested calls can report overlapping compute consumption. txray does not add those lines together. Scheduling cost units are a separate metric from compute units.
+
+## Save or share
+
+**Copy report** copies a text diagnosis. **Export JSON** saves the diagnosis and the full returned transaction record, including logs and instructions. Large integer values are decimal strings so exports do not round balances or fees.
+
+Live lookup signatures are sent to the selected official public RPC. txray stores no lookup history and makes no wallet requests. Exports are saved only when you request one.
+
+## Limits
+
+- Reads confirmed Mainnet or Devnet records. A confirmed record can still be affected by a fork; confirmed is not finalized.
+- Legacy, v0 and v1 are requested. Newer versions and unsupported shapes are reported explicitly.
+- v0 addresses resolve in static, loaded writable, loaded readonly order. Missing addresses remain unresolved.
+- v1 compute and absolute priority fees come from the message config. ComputeBudget instructions are ignored for v1 configuration.
+- The RPC supplies a total fee, not an exact base/priority split. Requested compute settings are shown separately, not presented as charged fees.
+- Only basic System transfer and Compute Budget instructions are decoded. Unknown instruction bytes remain available. No token transfer, price, profit or full balance-change interpretation is inferred.
+- Missing metadata, missing logs and runtime log truncation stay visible. txray cannot reconstruct omitted execution.
+- Public RPC can rate limit, block access or lack historical records. A not-found result does not prove a transaction never existed. Check network and retry later.
+- No automatic retries. Live calls time out after 12 seconds, responses are capped at 2 MiB, and the local server permits four concurrent lookups and 30 live lookups per minute.
+
+[Architecture](architecture.md)
+
+## Official references
+
+[Solana getTransaction](https://solana.com/docs/rpc/http/gettransaction), [versioned transactions](https://solana.com/docs/core/transactions/versioned-transactions), [fees](https://solana.com/docs/core/fees), and [RPC networks](https://solana.com/docs/references/clusters).

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "txray",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "A local-first Solana transaction debugger. Follow execution, explain failures and export diagnostics.",
+  "author": "Royal Pinto <royalpinto007@gmail.com>",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "demo": "npm run build && node dist/server.js",
+    "start": "node dist/server.js",
+    "dev": "npm run build && tsx watch src/server.ts",
+    "build": "tsc -p tsconfig.build.json && node scripts/build.mjs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test tests/*.test.ts",
+    "test:e2e": "npm run build && playwright test",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test && npm run build",
+    "prepack": "npm run build",
+    "package:check": "npm run build && node scripts/check-package.mjs"
+  },
+  "dependencies": {
+    "express": "^5.3.0",
+    "helmet": "^8.3.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@playwright/test": "^1.64.1",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.20.5",
+    "@types/supertest": "^7.2.1",
+    "esbuild": "^0.28.2",
+    "eslint": "^10.13.0",
+    "marked": "^18.1.1",
+    "prettier": "^3.9.10",
+    "supertest": "^7.3.1",
+    "tsx": "^4.23.15",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.72.0"
+  },
+  "bin": {
+    "txray": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "docs/*.md",
+    "docs/*.svg",
+    "docs/screenshot.png",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/royalpinto007/txray.git"
+  },
+  "homepage": "https://www.npmjs.com/package/txray",
+  "bugs": {
+    "url": "https://github.com/royalpinto007/txray/issues"
+  },
+  "keywords": [
+    "solana",
+    "transaction",
+    "debugger",
+    "rpc",
+    "logs",
+    "compute-units",
+    "developer-tools",
+    "cli",
+    "local-first",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}