|
| 1 | +# Handling Unparsed Blocks |
| 2 | + |
| 3 | +## 1. Overview |
| 4 | + |
| 5 | +In some cases, **yaci-core** may not be able to parse certain Cardano blocks due to unexpected or malformed data. To address this, **yaci-store** has introduced a feature that allows these **unparsed blocks to be ignored** and **stored in a separate error table** in the database, instead of halting the indexing process. |
| 6 | + |
| 7 | +With this graceful error handling in place, it's now possible to surface these parse-error blocks to exchanges and integrators so they can: |
| 8 | + |
| 9 | +- Detect if any of their transactions are present in an errored block. |
| 10 | +- Review and “mark checked” blocks if they do not impact their users or operations. |
| 11 | + |
| 12 | +This capability is exposed as **Cardano network-specific procedure calls**, using **Coinbase Mesh’s generic `/call` endpoint**, which supports **dynamic method routing**. This allows clients to query and update the state of errored blocks in a flexible and standardized way. |
| 13 | + |
| 14 | +Starting from **Rosetta-java version 1.3.0**, the parameter `CONTINUE_PARSING_ON_ERROR=true|false` has been introduced: |
| 15 | + |
| 16 | +- When it is set to `true`, yaci-core will skip unparsed blocks and add them to the error table. |
| 17 | +- When it is set to `false`, yaci-core will stop indexing when it encounters an unparsed block. |
| 18 | + |
| 19 | +--- |
| 20 | + |
| 21 | +## 2. How to Use |
| 22 | + |
| 23 | +You can interact with the parse-error block system through the `/call` endpoint. Below are the available operations. |
| 24 | + |
| 25 | +### 2.1 Review blocks that could not be fully parsed |
| 26 | + |
| 27 | +Use this call to get the list of blocks that failed to parse. |
| 28 | + |
| 29 | +#### Request |
| 30 | + |
| 31 | +```bash |
| 32 | +curl --location 'http://localhost:8082/call' \ |
| 33 | +--header 'Content-Type: application/json' \ |
| 34 | +--data '{ |
| 35 | + "network_identifier": { |
| 36 | + "blockchain": "cardano", |
| 37 | + "network": "preprod" |
| 38 | + }, |
| 39 | + "method": "get_parse_error_blocks", |
| 40 | + "parameters": { |
| 41 | + "status": "UNREVIEWED" |
| 42 | + } |
| 43 | +}' |
| 44 | +``` |
| 45 | +:::note |
| 46 | +- Pagination is not required, as the number of errored blocks is expected to be low. |
| 47 | +::: |
| 48 | +#### Response |
| 49 | +```json |
| 50 | +{ |
| 51 | + "result": { |
| 52 | + "parse_error_blocks": [ |
| 53 | + { |
| 54 | + "error_id": 1, |
| 55 | + "block_number": 3686994, |
| 56 | + "status": "UNREVIEWED", |
| 57 | + "lastUpdated": "2025-07-18T16:18:00.266457", |
| 58 | + "note": "Please review all transactions within a block, https://explorer.cardano.org/block/3686994" |
| 59 | + }, |
| 60 | + { |
| 61 | + "error_id": 2, |
| 62 | + "block_number": 3686995, |
| 63 | + "status": "UNREVIEWED", |
| 64 | + "lastUpdated": "2025-07-18T16:18:00.266457", |
| 65 | + "note": "Please review all transactions within a block, https://explorer.cardano.org/block/3686995" |
| 66 | + } |
| 67 | + ] |
| 68 | + }, |
| 69 | + "idempotent": false |
| 70 | +} |
| 71 | +``` |
| 72 | +📚 For detailed information, please see the **[API page](/cardano-rosetta-java/api#tag/call/post/call)**. |
| 73 | + |
| 74 | +### 2.2 Mark blocks as “checked” if they do not affect users or transactions |
| 75 | +After reviewing a block, you can mark it as reviewed with a comment and status. |
| 76 | +#### Request |
| 77 | + |
| 78 | +```bash |
| 79 | +curl --location 'http://localhost:8082/call' \ |
| 80 | +--header 'Content-Type: application/json' \ |
| 81 | +--data '{ |
| 82 | + "network_identifier": { |
| 83 | + "blockchain": "cardano", |
| 84 | + "network": "preprod" |
| 85 | + }, |
| 86 | + "method": "mark_parse_error_block_checked", |
| 87 | + "parameters": { |
| 88 | + "block_number": 3686994, |
| 89 | + "status": "REVIEWED_DOES_NOT_AFFECT_US", |
| 90 | + "comment": "no impact to operation", |
| 91 | + "checked_by": "Admin" |
| 92 | + } |
| 93 | +} |
| 94 | +``` |
| 95 | +:::note |
| 96 | +- `block_number` specifies which block to update. |
| 97 | +- `status` reflects the outcome of your review, e.g., REVIEWED_DOES_NOT_AFFECT_US. |
| 98 | +- Use `comment` and `checked_by` fields to provide audit context. |
| 99 | +::: |
| 100 | +
|
| 101 | +#### Response |
| 102 | +```json |
| 103 | +{ |
| 104 | + "result": { |
| 105 | + "parse_error_blocks_response": [ |
| 106 | + { |
| 107 | + "error_id": 1, |
| 108 | + "block_number": 3686994, |
| 109 | + "status": "REVIEWED_DOES_NOT_AFFECT_US", |
| 110 | + "comment": "no impact to operation", |
| 111 | + "checked_by": "Admin", |
| 112 | + "lastUpdated": "2025-07-28T04:25:57.632987219" |
| 113 | + } |
| 114 | + ] |
| 115 | + }, |
| 116 | + "idempotent": true |
| 117 | +} |
| 118 | +``` |
| 119 | +📚 For detailed information, please see the **[API page](/cardano-rosetta-java/api#tag/call/post/call)**. |
| 120 | +
|
| 121 | +### 2.3 What to do when unparsed blocks are detected |
| 122 | +When **yaci-core** encounters unparsed blocks, and you want to attempt parsing them again after resolving the issue (e.g. upgrading parser logic), follow these steps: |
| 123 | +
|
| 124 | +1. **Upgrade `yaci-core`** to the latest version that supports parsing the problematic block(s). |
| 125 | +2. **Remove the data volume** used by the indexer. |
| 126 | + ```bash |
| 127 | + docker compose --env-file .env.docker-compose \ |
| 128 | + --env-file .env.docker-compose-profile-mid-level \ |
| 129 | + -f docker-compose.yaml stop yaci-indexer |
| 130 | +
|
| 131 | + docker volume rm cardano-rosetta-java_data |
| 132 | + |
| 133 | + ``` |
| 134 | +3. **Restart the indexer service** using Docker Compose: |
| 135 | + ```bash |
| 136 | + docker compose --env-file .env.docker-compose \ |
| 137 | + --env-file .env.docker-compose-profile-mid-level \ |
| 138 | + -f docker-compose.yaml start yaci-indexer |
| 139 | + ``` |
| 140 | +
|
0 commit comments