txray 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,79 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width,initial-scale=1" />
6
+ <meta
7
+ name="description"
8
+ content="Understand a Solana transaction. Explain failures, follow execution logs and export a diagnostic report locally."
9
+ />
10
+ <meta name="theme-color" content="#10171f" />
11
+ <title>Architecture | txray</title>
12
+ <link rel="icon" href="/mark.svg" type="image/svg+xml" />
13
+ <link rel="stylesheet" href="/styles.css" />
14
+
15
+ </head>
16
+ <body>
17
+ <a class="skip" href="#inspector">Skip to inspector</a>
18
+ <header class="site-header">
19
+ <a class="brand" href="/" aria-label="txray home"
20
+ ><img src="/mark.svg" width="32" height="32" alt="" />txray<span
21
+ >Solana Transaction Autopsy</span
22
+ ></a
23
+ >
24
+ <nav aria-label="Main">
25
+ <a href="/" >Inspector</a><a href="/guide">Guide</a
26
+ ><a href="/architecture" aria-current="page">Architecture</a>
27
+ </nav>
28
+ </header>
29
+ <main id="inspector" class="document"><article><h1>Architecture</h1>
30
+ <p><img src="architecture.svg" alt="txray architecture"></p>
31
+ <p>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.</p>
32
+ <div class="table-scroll"><table>
33
+ <thead>
34
+ <tr>
35
+ <th>Part</th>
36
+ <th>Responsibility</th>
37
+ </tr>
38
+ </thead>
39
+ <tbody><tr>
40
+ <td><code>src/cli.ts</code></td>
41
+ <td>npm executable, help, version and local port options</td>
42
+ </tr>
43
+ <tr>
44
+ <td><code>src/web/app.ts</code></td>
45
+ <td>Signature form, diagnostics, timeline, text copy and JSON download</td>
46
+ </tr>
47
+ <tr>
48
+ <td><code>src/app.ts</code></td>
49
+ <td>Local HTTP boundary, input checks, security headers and lookup limits</td>
50
+ </tr>
51
+ <tr>
52
+ <td><code>src/adapters/rpc.ts</code></td>
53
+ <td>Confirmed JSON RPC reads, exact integers, timeout and response cap</td>
54
+ </tr>
55
+ <tr>
56
+ <td><code>src/domain/</code></td>
57
+ <td>Response schema, account resolution, known errors, instruction decoding and log parsing</td>
58
+ </tr>
59
+ <tr>
60
+ <td><code>src/adapters/examples.ts</code></td>
61
+ <td>Clearly labeled fictional records, analyzed by the same domain code</td>
62
+ </tr>
63
+ </tbody></table></div>
64
+ <h2>Trust boundaries</h2>
65
+ <p>Only the fixed Mainnet and Devnet endpoints can be queried. User-supplied RPC URLs are not accepted. The server binds to <code>127.0.0.1</code> 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.</p>
66
+ <p>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 <code>meta.err</code> or establish a root cause by themselves.</p>
67
+ <p>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.</p>
68
+ <h2>Running and testing</h2>
69
+ <p><code>npm run demo</code> 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.</p>
70
+ <p><code>npx txray</code> 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.</p>
71
+ <p>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.</p>
72
+ <p><a href="/guide">Guide</a></p>
73
+ </article></main>
74
+ <footer>
75
+ Runs on your computer. No saved lookups, telemetry or wallet connection.
76
+ Public RPC availability varies.
77
+ </footer>
78
+ </body>
79
+ </html>
@@ -0,0 +1,17 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="960" height="530" viewBox="0 0 960 530" role="img" aria-labelledby="title desc">
2
+ <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>
3
+ <rect width="960" height="530" rx="12" fill="#10171f"/>
4
+ <g font-family="Arial,sans-serif" fill="#e3eaf0">
5
+ <text x="36" y="49" font-size="26" font-weight="700">From signature to diagnosis</text>
6
+ <text x="36" y="80" font-size="17" fill="#a2b1bf">Read-only. Local processing. No saved lookups.</text>
7
+ <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>
8
+ <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>
9
+ <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>
10
+ <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>
11
+ <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>
12
+ <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>
13
+ <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>
14
+ <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>
15
+ <text x="36" y="475" font-size="17" fill="#a2b1bf">No wallet, signing, database, cloud deployment or paid API.</text>
16
+ <text x="36" y="502" font-size="17" fill="#a2b1bf">Unknown errors and missing metadata remain visible.</text>
17
+ </g></svg>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 12 8"><path d="m1 1 5 5 5-5" fill="none" stroke="#a2b1bf" stroke-width="1.5"/></svg>
@@ -0,0 +1,66 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width,initial-scale=1" />
6
+ <meta
7
+ name="description"
8
+ content="Understand a Solana transaction. Explain failures, follow execution logs and export a diagnostic report locally."
9
+ />
10
+ <meta name="theme-color" content="#10171f" />
11
+ <title>Guide | txray</title>
12
+ <link rel="icon" href="/mark.svg" type="image/svg+xml" />
13
+ <link rel="stylesheet" href="/styles.css" />
14
+
15
+ </head>
16
+ <body>
17
+ <a class="skip" href="#inspector">Skip to inspector</a>
18
+ <header class="site-header">
19
+ <a class="brand" href="/" aria-label="txray home"
20
+ ><img src="/mark.svg" width="32" height="32" alt="" />txray<span
21
+ >Solana Transaction Autopsy</span
22
+ ></a
23
+ >
24
+ <nav aria-label="Main">
25
+ <a href="/" >Inspector</a><a href="/guide" aria-current="page">Guide</a
26
+ ><a href="/architecture">Architecture</a>
27
+ </nav>
28
+ </header>
29
+ <main id="inspector" class="document"><article><h1>Using txray</h1>
30
+ <p>Run <code>npx txray</code> with Node.js 22.18+. Open the printed local URL. Use <code>npx txray --port 4452</code> if the default port is busy. Press Ctrl+C to stop.</p>
31
+ <p>Paste a Solana transaction signature, select its network and choose <strong>Inspect transaction</strong>. A transaction signature is the public identifier of a transaction, not a wallet address.</p>
32
+ <p>Start with an <strong>offline example</strong> if you do not have a signature. All example values are fictional. No RPC request is made for an example.</p>
33
+ <h2>Read a result</h2>
34
+ <ol>
35
+ <li><strong>Diagnosis:</strong> a known runtime error gets a plain explanation. Custom program errors remain unknown; a code such as <code>6001</code> means different things in different programs.</li>
36
+ <li><strong>Failed instruction:</strong> <code>#2</code> means RPC index <code>1</code>. This identifies the top-level instruction, not necessarily the innermost cause of a nested failure.</li>
37
+ <li><strong>Fee and compute:</strong> the fee is the total recorded in metadata. Compute consumption comes from <code>meta.computeUnitsConsumed</code>. Missing values say <strong>Not reported</strong>, never zero.</li>
38
+ <li><strong>Instruction timeline:</strong> earlier instructions ran before the failure; later instructions did not run. Ordinary program state changes roll back. Fees and durable-nonce advancement can persist.</li>
39
+ <li><strong>Execution log:</strong> lines appear in recorded order. Indentation follows runtime invocation depth. A log&#39;s wording is evidence of what a program printed, not an independently verified explanation.</li>
40
+ </ol>
41
+ <p>An inner call can fail and be caught by its caller; only <code>meta.err</code> 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.</p>
42
+ <h2>Save or share</h2>
43
+ <p><strong>Copy report</strong> copies a text diagnosis. <strong>Export JSON</strong> 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.</p>
44
+ <p>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.</p>
45
+ <h2>Limits</h2>
46
+ <ul>
47
+ <li>Reads confirmed Mainnet or Devnet records. A confirmed record can still be affected by a fork; confirmed is not finalized.</li>
48
+ <li>Legacy, v0 and v1 are requested. Newer versions and unsupported shapes are reported explicitly.</li>
49
+ <li>v0 addresses resolve in static, loaded writable, loaded readonly order. Missing addresses remain unresolved.</li>
50
+ <li>v1 compute and absolute priority fees come from the message config. ComputeBudget instructions are ignored for v1 configuration.</li>
51
+ <li>The RPC supplies a total fee, not an exact base/priority split. Requested compute settings are shown separately, not presented as charged fees.</li>
52
+ <li>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.</li>
53
+ <li>Missing metadata, missing logs and runtime log truncation stay visible. txray cannot reconstruct omitted execution.</li>
54
+ <li>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.</li>
55
+ <li>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.</li>
56
+ </ul>
57
+ <p><a href="/architecture">Architecture</a></p>
58
+ <h2>Official references</h2>
59
+ <p><a href="https://solana.com/docs/rpc/http/gettransaction">Solana getTransaction</a>, <a href="https://solana.com/docs/core/transactions/versioned-transactions">versioned transactions</a>, <a href="https://solana.com/docs/core/fees">fees</a>, and <a href="https://solana.com/docs/references/clusters">RPC networks</a>.</p>
60
+ </article></main>
61
+ <footer>
62
+ Runs on your computer. No saved lookups, telemetry or wallet connection.
63
+ Public RPC availability varies.
64
+ </footer>
65
+ </body>
66
+ </html>
@@ -0,0 +1,180 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width,initial-scale=1" />
6
+ <meta
7
+ name="description"
8
+ content="Understand a Solana transaction. Explain failures, follow execution logs and export a diagnostic report locally."
9
+ />
10
+ <meta name="theme-color" content="#10171f" />
11
+ <title>txray | Solana Transaction Autopsy</title>
12
+ <link rel="icon" href="/mark.svg" type="image/svg+xml" />
13
+ <link rel="stylesheet" href="/styles.css" />
14
+ <script type="module" src="/app.js"></script>
15
+ </head>
16
+ <body>
17
+ <a class="skip" href="#inspector">Skip to inspector</a>
18
+ <header class="site-header">
19
+ <a class="brand" href="/" aria-label="txray home"
20
+ ><img src="/mark.svg" width="32" height="32" alt="" />txray<span
21
+ >Solana Transaction Autopsy</span
22
+ ></a
23
+ >
24
+ <nav aria-label="Main">
25
+ <a href="/" aria-current="page">Inspector</a><a href="/guide">Guide</a
26
+ ><a href="/architecture">Architecture</a>
27
+ </nav>
28
+ </header>
29
+ <main id="inspector">
30
+ <section class="entry" aria-labelledby="page-title">
31
+ <div class="intro">
32
+ <p class="section-label">Read-only transaction inspector</p>
33
+ <h1 id="page-title">See where it went wrong.</h1>
34
+ <p>
35
+ One signature. The outcome, the fee and the execution behind it.
36
+ </p>
37
+ </div>
38
+ <form id="inspect-form" novalidate>
39
+ <div class="signature-field">
40
+ <label for="signature">Transaction signature</label
41
+ ><input
42
+ id="signature"
43
+ name="signature"
44
+ autocomplete="off"
45
+ autocapitalize="none"
46
+ spellcheck="false"
47
+ maxlength="88"
48
+ placeholder="Paste a Solana transaction signature…"
49
+ aria-describedby="privacy"
50
+ />
51
+ </div>
52
+ <div class="network-field">
53
+ <label for="network">Network</label
54
+ ><select id="network" name="network">
55
+ <option value="mainnet-beta">Mainnet</option>
56
+ <option value="devnet">Devnet</option>
57
+ </select>
58
+ </div>
59
+ <button class="primary" type="submit">Inspect transaction</button>
60
+ </form>
61
+ <p class="privacy" id="privacy">
62
+ Live lookups send the signature to Solana's public RPC. No wallet or
63
+ funds needed.
64
+ </p>
65
+ <div class="examples">
66
+ <span>Try an offline example</span>
67
+ <div id="examples" class="example-buttons"></div>
68
+ </div>
69
+ </section>
70
+ <p id="error" class="error-message" role="alert" hidden></p>
71
+ <p id="activity" class="activity" role="status" aria-live="polite"></p>
72
+ <section id="empty" class="empty" aria-labelledby="empty-title">
73
+ <div class="scan-mark" aria-hidden="true">[ tx ]</div>
74
+ <h2 id="empty-title">Start with a transaction.</h2>
75
+ <p>
76
+ Paste a signature above, or explore an example without a network
77
+ request.
78
+ </p>
79
+ <div class="empty-key">
80
+ <span>Known errors, explained</span><span>Unknowns stay unknown</span
81
+ ><span>Export what you find</span>
82
+ </div>
83
+ </section>
84
+ <section id="result" aria-label="Transaction report" hidden>
85
+ <div class="report-toolbar">
86
+ <span
87
+ id="source-label"
88
+ data-testid="source-label"
89
+ class="source-label"
90
+ ></span>
91
+ <div class="report-actions">
92
+ <a id="explorer" target="_blank" rel="noopener noreferrer" hidden
93
+ >View on Explorer</a
94
+ ><button type="button" id="copy">Copy report</button
95
+ ><button type="button" id="export">Export JSON</button>
96
+ </div>
97
+ </div>
98
+ <div class="report-grid">
99
+ <div class="report-main">
100
+ <section id="diagnosis" class="diagnosis">
101
+ <p id="outcome" class="outcome"></p>
102
+ <h2 id="diagnosis-title"></h2>
103
+ <p id="explanation" data-testid="explanation"></p>
104
+ <p id="failure-note" class="failure-note" hidden></p>
105
+ </section>
106
+ <section class="section-block" aria-labelledby="instructions-title">
107
+ <div class="section-heading">
108
+ <h2 id="instructions-title">Instruction timeline</h2>
109
+ <span id="instruction-count"></span>
110
+ </div>
111
+ <p class="section-help">
112
+ Actions describe what was requested. A failed transaction does
113
+ not commit ordinary program state changes.
114
+ </p>
115
+ <ol id="instructions" class="instructions"></ol>
116
+ </section>
117
+ <section class="section-block" aria-labelledby="logs-title">
118
+ <div class="section-heading">
119
+ <h2 id="logs-title">Execution log</h2>
120
+ <span id="log-count"></span>
121
+ </div>
122
+ <p class="section-help">
123
+ Recorded order, with nested calls indented. Per-program compute
124
+ can overlap; it is not added together.
125
+ </p>
126
+ <div
127
+ id="logs"
128
+ class="logs"
129
+ tabindex="0"
130
+ aria-label="Execution log lines"
131
+ ></div>
132
+ </section>
133
+ </div>
134
+ <aside class="facts" aria-label="Transaction details">
135
+ <section>
136
+ <h2>At a glance</h2>
137
+ <dl>
138
+ <dt>Failed instruction</dt>
139
+ <dd
140
+ id="failed-instruction"
141
+ data-testid="failed-instruction"
142
+ ></dd>
143
+ <dt>Transaction fee</dt>
144
+ <dd id="fee" data-testid="fee" class="fact-value"></dd>
145
+ <dt>Compute used</dt>
146
+ <dd id="compute" data-testid="compute" class="fact-value"></dd>
147
+ <dt>Top-level failed program</dt>
148
+ <dd id="failed-program" class="address"></dd>
149
+ </dl>
150
+ </section>
151
+ <section>
152
+ <h2>Fee & compute details</h2>
153
+ <dl id="resources"></dl>
154
+ <p class="aside-note">
155
+ The RPC reports a total fee, not an exact base/priority split.
156
+ Requested settings are not a fee receipt.
157
+ </p>
158
+ </section>
159
+ <section>
160
+ <h2>Transaction</h2>
161
+ <dl id="identity"></dl>
162
+ </section>
163
+ <section id="warnings-section">
164
+ <h2>Data notes</h2>
165
+ <ul id="warnings" class="warnings"></ul>
166
+ </section>
167
+ <details class="raw-error">
168
+ <summary>Raw runtime error</summary>
169
+ <pre id="raw-error"></pre>
170
+ </details>
171
+ </aside>
172
+ </div>
173
+ </section>
174
+ </main>
175
+ <footer>
176
+ Runs on your computer. No saved lookups, telemetry or wallet connection.
177
+ Public RPC availability varies.
178
+ </footer>
179
+ </body>
180
+ </html>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="7" fill="#18232d"/><path d="M10 7H7v18h3m12-18h3v18h-3M12 12l8 8m0-8-8 8" fill="none" stroke="#90c9ee" stroke-width="2" stroke-linecap="round"/></svg>