Skip to content

Commit 98d7f5a

Browse files
Scroll-FilbertScroll-Filbert
authored
Merge pull request #440 from scroll-tech/filbertn/add-transaction-journey
Add transaction journey guide
2 parents 9b56dd1 + c835e41 commit 98d7f5a

File tree

4 files changed

+144
-1
lines changed

4 files changed

+144
-1
lines changed

‎public/locales/en/translation.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,8 @@
110110
"scrollSepoliaBlockExplorer": "Scroll Sepolia Explorer",
111111
"sepoliaRollupExplorer": "Rollup Explorer",
112112
"sepoliaBlockExplorer": "Scrollscan Explorer",
113-
"canvasBadge": "Canvas & Badge Integration"
113+
"canvasBadge": "Canvas & Badge Integration",
114+
"transactionJourney": "Checking Transaction Journey"
114115
},
115116
"technology": {
116117
"introduction": "Introduction",

‎src/config/sidebar.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -166,6 +166,10 @@ export const getSidebar = () => {
166166
title: t("sidebar.developers.canvasBadge"),
167167
url: formatUrl("developers/guides/canvas-badge-integration"),
168168
},
169+
{
170+
title: t("sidebar.developers.transactionJourney"),
171+
url: formatUrl("developers/guides/checking-transaction-journey"),
172+
},
169173
// {
170174
// title: t("sidebar.developers.bridgingERC721NftThroughCustomGateway"),
171175
// url: formatUrl("developers/guides/"),

‎src/content/docs/en/developers/_images/txJourneyDiagram.png

316 KB
Loading

‎src/content/docs/en/developers/guides/checking-transaction-journey.mdx

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
section: developers
3+
date: Last Modified
4+
title: "Checking Transaction Journey Guide"
5+
lang: "en"
6+
permalink: "developers/guides/checking-transaction-journey"
7+
excerpt: "This guide contains instructions on how you can check your transaction's journey."
8+
---
9+
10+
import Aside from "../../../../../components/Aside.astro"
11+
import ClickToZoom from "../../../../../components/ClickToZoom.astro"
12+
import ToggleElement from "../../../../../components/ToggleElement.astro"
13+
import txJourneyDiagram from "../_images/txJourneyDiagram.png"
14+
15+
This guide will help you to check the journey of a transaction through the **Scroll network**, how to inspect it via the `/tx/journeys` API, and interpret its lifecycle.
16+
17+
### Architecture Summary
18+
19+
<ClickToZoom src={txJourneyDiagram} />
20+
_Diagram of Scroll transaction journey_
21+
22+
| Component | Role |
23+
|-----------------------|---------------------------------------------------|
24+
| Backend | Submits transaction. |
25+
| Monitoring Service | Tracks transaction progress and logs events. |
26+
| Scroll Internal Nodes | Handle transaction validation and mempool logic. |
27+
| Scroll Sequencer | Orders transactions into blocks. |
28+
| Axiom Logging | Receives logs for external visibility/analysis. |
29+
30+
---
31+
32+
### Endpoint
33+
34+
POST https://venus.scroll.io/v1/tx/journeys
35+
36+
### Request Example
37+
38+
```bash
39+
curl -X POST "https://venus.scroll.io/v1/tx/journeys" \
40+
-H "Content-Type: application/json" \
41+
-d '{
42+
"tx_hashes": [
43+
"0xcf0982782692a521e6bcbf4f6c5d1db6ac1f2049b7c7304dd89a9522a61406f9"
44+
]
45+
}' | jq
46+
```
47+
48+
#### Response Fields
49+
50+
| Field | Description |
51+
|-------------------|-------------|
52+
| `tx_hash` | Transaction hash queried. |
53+
| `current_status` | Final status (`queued`,`pending`,`executed`,`dropped`,`reorged`,`replaced`). |
54+
| `execution_status`| Result of execution (`successful`,`reverted`,`unknown`,`error`). |
55+
| `first_seen_at` | First time the network detected this transaction. |
56+
| `last_updated_at` | Most recent status update time. |
57+
| `journey` | Detailed list of state transitions for the transaction. |
58+
59+
#### Current Status
60+
61+
| Stage | Description |
62+
|-----------|-------------|
63+
| `queued` | Transaction not yet executable, e.g. nonce gap or awaiting prior txs. |
64+
| `pending` | Transaction valid and executable in mempool. |
65+
| `executed` | Transaction included in a block. |
66+
| `dropped` | Transaction removed due to expiration, mempool overflow, or invalid parameters. |
67+
| `reorged` | Transaction was removed from the canonical chain after a chain reorganization. |
68+
| `replaced` | Transaction replaced by a new transaction (same sender & nonce, higher gas price). |
69+
70+
#### Execution Status
71+
72+
| Status | Meaning |
73+
|------------|---------|
74+
| `successful`| Transaction executed successfully and included in a block. |
75+
| `reverted` | Transaction failed during execution. |
76+
| `unknown` | Transaction not yet executed. |
77+
| `error` | Unexpected error in query node. Should rarely occur. |
78+
79+
### Journey Field Example
80+
81+
#### Queued
82+
```json
83+
{
84+
"event_type": "queued",
85+
"timestamp": "2025-04-10T09:55:29.73Z",
86+
"node_type": "l2geth-bootnode-0",
87+
"event_detail": "Pooled new future transaction (into non-executable queues)"
88+
}
89+
```
90+
91+
#### Pending
92+
```json
93+
{
94+
"event_type": "pending",
95+
"timestamp": "2025-04-10T09:55:29.73Z",
96+
"node_type": "l2geth-bootnode-0",
97+
"event_detail": "Transaction promoted from future queue to pending"
98+
}
99+
```
100+
101+
#### Executed
102+
```json
103+
{
104+
"event_type": "executed",
105+
"timestamp": "2025-04-10T09:55:31.02Z",
106+
"node_type": "l2geth-bootnode-0",
107+
"event_detail": "TX is included in a block"
108+
}
109+
```
110+
111+
#### Dropped
112+
```json
113+
{
114+
"event_type": "dropped",
115+
"timestamp": "2025-04-12T15:33:23.142Z",
116+
"node_type": "l2geth-bootnode-0",
117+
"event_detail": "Discarding invalid transaction when adding the transaction"
118+
}
119+
```
120+
121+
1. `Queued`: Transaction waiting for execution (e.g., nonce gap)
122+
2. `Pending`: Transaction ready for inclusion by Scroll Sequencer.
123+
3. `Executed`: Transaction included in a block.
124+
4. (Optional) `Reorged`: Transaction may get reorged based on network conditions.
125+
5. `Dropped` or `Replaced`: Transaction invalidated or replaced before execution.
126+
127+
### Common Failure Reasons
128+
129+
**Dropped:**
130+
- Timeout: Stuck too long in queue.
131+
- Mempool full.
132+
- Invalid parameters (e.g., nonce too low, fee cap below block base fee).
133+
134+
**Replaced:**
135+
- Same nonce transaction with higher gas price replaces previous.
136+
137+
**Reorged:**
138+
- Block containing tx removed due to L2 chain reorganization.

0 commit comments

Comments
 (0)