diff --git a/public/locales/en/translation.json b/public/locales/en/translation.json index 8fbda6450..0ccae3965 100644 --- a/public/locales/en/translation.json +++ b/public/locales/en/translation.json @@ -110,7 +110,8 @@ "scrollSepoliaBlockExplorer": "Scroll Sepolia Explorer", "sepoliaRollupExplorer": "Rollup Explorer", "sepoliaBlockExplorer": "Scrollscan Explorer", - "canvasBadge": "Canvas & Badge Integration" + "canvasBadge": "Canvas & Badge Integration", + "transactionJourney": "Checking Transaction Journey" }, "technology": { "introduction": "Introduction", diff --git a/src/config/sidebar.ts b/src/config/sidebar.ts index 3cc4d78f7..66bfb5b74 100644 --- a/src/config/sidebar.ts +++ b/src/config/sidebar.ts @@ -166,6 +166,10 @@ export const getSidebar = () => { title: t("sidebar.developers.canvasBadge"), url: formatUrl("developers/guides/canvas-badge-integration"), }, + { + title: t("sidebar.developers.transactionJourney"), + url: formatUrl("developers/guides/checking-transaction-journey"), + }, // { // title: t("sidebar.developers.bridgingERC721NftThroughCustomGateway"), // url: formatUrl("developers/guides/"), diff --git a/src/content/docs/en/developers/_images/txJourneyDiagram.png b/src/content/docs/en/developers/_images/txJourneyDiagram.png new file mode 100644 index 000000000..335a0957c Binary files /dev/null and b/src/content/docs/en/developers/_images/txJourneyDiagram.png differ diff --git a/src/content/docs/en/developers/guides/checking-transaction-journey.mdx b/src/content/docs/en/developers/guides/checking-transaction-journey.mdx new file mode 100644 index 000000000..c28832796 --- /dev/null +++ b/src/content/docs/en/developers/guides/checking-transaction-journey.mdx @@ -0,0 +1,138 @@ +--- +section: developers +date: Last Modified +title: "Checking Transaction Journey Guide" +lang: "en" +permalink: "developers/guides/checking-transaction-journey" +excerpt: "This guide contains instructions on how you can check your transaction's journey." +--- + +import Aside from "../../../../../components/Aside.astro" +import ClickToZoom from "../../../../../components/ClickToZoom.astro" +import ToggleElement from "../../../../../components/ToggleElement.astro" +import txJourneyDiagram from "../_images/txJourneyDiagram.png" + +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. + +### Architecture Summary + + +_Diagram of Scroll transaction journey_ + +| Component | Role | +|-----------------------|---------------------------------------------------| +| Backend | Submits transaction. | +| Monitoring Service | Tracks transaction progress and logs events. | +| Scroll Internal Nodes | Handle transaction validation and mempool logic. | +| Scroll Sequencer | Orders transactions into blocks. | +| Axiom Logging | Receives logs for external visibility/analysis. | + +--- + +### Endpoint + +POST https://venus.scroll.io/v1/tx/journeys + +### Request Example + +```bash +curl -X POST "https://venus.scroll.io/v1/tx/journeys" \ + -H "Content-Type: application/json" \ + -d '{ + "tx_hashes": [ + "0xcf0982782692a521e6bcbf4f6c5d1db6ac1f2049b7c7304dd89a9522a61406f9" + ] + }' | jq +``` + +#### Response Fields + +| Field | Description | +|-------------------|-------------| +| `tx_hash` | Transaction hash queried. | +| `current_status` | Final status (`queued`,`pending`,`executed`,`dropped`,`reorged`,`replaced`). | +| `execution_status`| Result of execution (`successful`,`reverted`,`unknown`,`error`). | +| `first_seen_at` | First time the network detected this transaction. | +| `last_updated_at` | Most recent status update time. | +| `journey` | Detailed list of state transitions for the transaction. | + +#### Current Status + +| Stage | Description | +|-----------|-------------| +| `queued` | Transaction not yet executable, e.g. nonce gap or awaiting prior txs. | +| `pending` | Transaction valid and executable in mempool. | +| `executed` | Transaction included in a block. | +| `dropped` | Transaction removed due to expiration, mempool overflow, or invalid parameters. | +| `reorged` | Transaction was removed from the canonical chain after a chain reorganization. | +| `replaced` | Transaction replaced by a new transaction (same sender & nonce, higher gas price). | + +#### Execution Status + +| Status | Meaning | +|------------|---------| +| `successful`| Transaction executed successfully and included in a block. | +| `reverted` | Transaction failed during execution. | +| `unknown` | Transaction not yet executed. | +| `error` | Unexpected error in query node. Should rarely occur. | + +### Journey Field Example + +#### Queued +```json +{ + "event_type": "queued", + "timestamp": "2025-04-10T09:55:29.73Z", + "node_type": "l2geth-bootnode-0", + "event_detail": "Pooled new future transaction (into non-executable queues)" +} +``` + +#### Pending +```json +{ + "event_type": "pending", + "timestamp": "2025-04-10T09:55:29.73Z", + "node_type": "l2geth-bootnode-0", + "event_detail": "Transaction promoted from future queue to pending" +} +``` + +#### Executed +```json +{ + "event_type": "executed", + "timestamp": "2025-04-10T09:55:31.02Z", + "node_type": "l2geth-bootnode-0", + "event_detail": "TX is included in a block" +} +``` + +#### Dropped +```json +{ + "event_type": "dropped", + "timestamp": "2025-04-12T15:33:23.142Z", + "node_type": "l2geth-bootnode-0", + "event_detail": "Discarding invalid transaction when adding the transaction" +} +``` + +1. `Queued`: Transaction waiting for execution (e.g., nonce gap) +2. `Pending`: Transaction ready for inclusion by Scroll Sequencer. +3. `Executed`: Transaction included in a block. +4. (Optional) `Reorged`: Transaction may get reorged based on network conditions. +5. `Dropped` or `Replaced`: Transaction invalidated or replaced before execution. + +### Common Failure Reasons + +**Dropped:** +- Timeout: Stuck too long in queue. +- Mempool full. +- Invalid parameters (e.g., nonce too low, fee cap below block base fee). + +**Replaced:** +- Same nonce transaction with higher gas price replaces previous. + +**Reorged:** +- Block containing tx removed due to L2 chain reorganization. \ No newline at end of file