Cardano Updates

Signed-off-by: Akhil Repala <[email protected]>

Signed-off-by: Akhil Repala <[email protected]>

Signed-off-by: Akhil Repala <[email protected]>

by extracting the shared logic in helpers

# feat: replace 'apply indexes' with a native solution

Closes #736.

Moves the required Rosetta index lifecycle (create, validate, track
progress)
from the external `index-applier` sidecar container into `yaci-indexer`
itself.
After blockchain sync reaches tip, the indexer automatically creates all
16
Rosetta-required indexes, gates readiness on completion, and exposes
per-index
lifecycle state via a new actuator endpoint.

---

## Architecture: Before vs After

```
BEFORE
──────────────────────────────────────────────────────────────
  ┌─────────────────┐     ┌──────────────────┐
  │  yaci-indexer   │     │  index-applier   │
  │                 │     │  (sidecar)       │
  │  sync chain     │     │                  │
  │  expose data    │     │  apply-indexes   │
  │                 │     │  .sh             │
  └─────────────────┘     └──────────────────┘
          │                        │
          │                        │  psql + shell loop
          └──────────┬─────────────┘
                     ▼
              PostgreSQL DB
              (16 indexes)

AFTER
──────────────────────────────────────────────────────────────
  ┌───────────────────────────────────────────┐
  │              yaci-indexer                 │
  │                                           │
  │  sync chain                               │
  │  expose data                              │
  │  PgIndexService                           │
  │    └─ creates indexes when synced         │
  │    └─ gates readiness probe               │
  │    └─ exposes /actuator/rosetta-indexes   │
  └───────────────────────────────────────────┘
                     │
                     │  JDBC (autoCommit=true)
                     ▼
              PostgreSQL DB
              (16 indexes)
```

---

## Lifecycle State Machine

```mermaid
stateDiagram-v2
    [*] --> PENDING : startup (init)

    PENDING --> PENDING : sync not yet at tip
    PENDING --> APPLYING : node reaches tip\n(compareAndSet guard)

    APPLYING --> READY : all 16 indexes created\nsuccessfully
    APPLYING --> FAILED : ≥1 index failed\n(remaining still attempted)

    READY --> [*]
    FAILED --> [*]

    note right of PENDING
        Re-queries pg_index on startup.
        Skips to READY if all indexes
        already exist and are valid.
    end note

    note right of APPLYING
        Single background thread.
        Continue-on-failure: all 16
        indexes are always attempted.
    end note

    note right of FAILED
        Per-index errorMessage available
        via /actuator/rosetta-indexes.
        Recovery requires pod restart.
    end note
```

---

## Index Creation Flow

```mermaid
flowchart TD
    A([triggerIndexing called]) --> B{state ==\nPENDING?}
    B -- No --> Z([return — no-op])
    B -- Yes --> C[CAS: PENDING → APPLYING]
    C --> D[submit to RosettaIndexBuilder thread]

    D --> E[for each of 16 indexes]

    E --> F[queryIndexState from pg_index\nschema-filtered]

    F --> G{state?}

    G -- READY --> N[skip — already done]
    G -- INVALID or BUILDING --> H[DROP INDEX IF EXISTS\nschema.indexname]
    G -- MISSING --> I[CREATE INDEX CONCURRENTLY\nautoCommit=true]
    H --> I

    I --> J{success?}
    J -- Yes --> K[mark READY\nupdate lastProgressAt]
    J -- No --> L[mark FAILED\nlog error\nfailedCount++]

    K --> M{more indexes?}
    L --> M

    N --> M
    M -- Yes --> E
    M -- No --> O{failedCount == 0?}

    O -- Yes --> P[state = READY]
    O -- No --> Q[state = FAILED\nlog warning]
```

---

## Health Probe Behaviour

```mermaid
flowchart LR
    subgraph Readiness [Readiness Probe — /actuator/health/readiness]
        R1{connection\nalive?} -- No --> RD1[DOWN\nConnection]
        R1 -- Yes --> R2{synced\nto tip?}
        R2 -- No --> RD2[DOWN\nSyncing]
        R2 -- Yes --> R3{index lifecycle\n== READY?}
        R3 -- No --> RD3[DOWN\nApplying Indexes]
        R3 -- Yes --> RU[UP]
    end

    subgraph Liveness [Liveness Probe — /actuator/health/liveness]
        L1{state ==\nAPPLYING?} -- No --> LU[UP]
        L1 -- Yes --> L2{lastProgressAt\n< 15 min ago?}
        L2 -- Yes --> LU
        L2 -- No --> LD[DOWN\nStalled]
    end
```

> **Note**: FAILED state → Readiness DOWN, Liveness **UP**. This is
intentional —
> a stalled build warrants a pod restart (liveness kill), but a
permanently failed
> index does not. Operators diagnose via `/actuator/rosetta-indexes`.

---

## Actuator Endpoint

`GET /actuator/rosetta-indexes`

```json
{
  "overallState": "APPLYING",
  "lastProgressAt": "2026-04-22T10:31:05Z",
  "totalRequired": 16,
  "totalReady": 9,
  "totalMissing": 6,
  "totalFailed": 1,
  "indexes": [
    { "name": "idx_address_utxo_amounts_gin", "state": "READY",   "errorMessage": null },
    { "name": "idx_tx_input_tx_hash",         "state": "BUILDING", "errorMessage": null },
    { "name": "idx_block_hash",               "state": "FAILED",   "errorMessage": "permission denied for table block" },
    { "name": "idx_stake_address_hash_raw",   "state": "MISSING",  "errorMessage": null }
  ]
}
```

---

## Key Implementation Details

### Why `autoCommit=true`?
`CREATE INDEX CONCURRENTLY` is rejected by PostgreSQL inside a
transaction block.
The service uses a raw JDBC connection with explicit `autoCommit=true`
to guarantee
no transaction wrapping.

### Why continue-on-failure?
The 16 indexes span independent tables. All indexes are always attempted
so a single
permission error on one table does not block the remaining 15. Per-index
failure
detail is available via `/actuator/rosetta-indexes`.

### Schema-qualified DROP
Both `pg_index` queries and `DROP INDEX` statements are scoped to
`current_schema()`
to avoid cross-schema matches in multi-schema PostgreSQL deployments.

---

## Infrastructure Changes

| Area | Before | After |
|------|--------|-------|
| Docker Compose | `index-applier` sidecar container | Removed —
`yaci-indexer` handles indexes natively |
| `apply-indexes.sh` | Shell script (psql + yq loop) | Deleted |
| Postgres Dockerfile | Bundled `jq`, `yq`, `apply-indexes.sh` | Removed
(no longer needed) |
| Helm chart | `index-applier` Job + ConfigMap templates | Removed —
`indexApplier` section dropped |
| Helm profile resources | `indexApplier` blocks in entry/mid/advanced |
Removed |
| Healthcheck retries | 360 × 10 s = 1 hour | 1080 × 10 s = **3 hours**
(mainnet GIN build time) |
| Documentation | References to `index-applier` throughout | Updated to
reflect native approach |

---

## Package & Class Naming (yaci-indexer)

Classes were renamed for clarity as part of this PR:

| Old | New |
|-----|-----|
| `indexmanagement` package | `indexes` package |
| `RosettaIndexLifecycleService` | `IndexService` |
| `PostgreSQLRosettaIndexLifecycleService` | `PgIndexService` |
| `NoOpRosettaIndexLifecycleService` | `NoOpIndexService` |
| `RosettaIndexConfig` | `IndexCatalog` |
| `RosettaIndexesEndpoint` | `IndexesEndpoint` |
| `RosettaIndexProgressSnapshot` | `IndexProgress` |
| `RosettaIndexStallIndicator` | `IndexStallIndicator` |

---

## API module — cleanup

Removed dead `getIndexCommands()` from `RosettaIndexConfig` in the api
module.
The api never creates indexes — that is `PgIndexService`'s
responsibility.
The method was unused and has been deleted.

---

## Test Coverage

39 unit tests across 5 classes:

| Class | Scenarios |
|-------|-----------|
| `PgIndexServiceTest` | Init states, sync trigger, INVALID drop,
BUILDING drop, continue-on-failure, failure handling, double-trigger
guard |
| `IndexesEndpointTest` | APPLYING snapshot, READY (all pre-exist)
snapshot |
| `IndexStallIndicatorTest` | Stall detection, terminal state
distinction |
| `YaciSyncHealthIndicatorTest` | Readiness states including
APPLYING_INDEXES |
| `IndexCatalogParityTest` | Both module YAML files are byte-identical |

> `CREATE INDEX CONCURRENTLY` with `autoCommit=true` must be verified
against a real
> PostgreSQL instance — unit mocks cannot catch transaction-block
rejections.

in `mkStAnnTx`

Signed-off-by: Akhil Repala <[email protected]>

Following adjustements from the auto-derived impl re-used from serde:
- leverage `SignedEntityTypeDiscriminantMessage` to avoid defining +
  implementing deserialize on a an enum which define only the variants
  names
- use imports instead of absolute path
- rename visitors based on their implented symbol for clarity
- remove most magic strings by using `stringify!`
- use `ok_or` instead of `match` for error handling when visiting tuple
  variants

By re-using the expanded macro of serde derive.

Include the full type identity in generated expect-decoder cache keys instead
of using only the local type name plus flattened generic argument names.

This prevents decoder reuse between distinct types that share a local name
across modules, such as mod_a.ActionType and mod_b.ActionType, and also avoids
collisions between different generic shapes with the same flattened name.

Signed-off-by: Tripura Repalle <[email protected]>