Cardano JS SDK | projection

This package is a library of generic projection types and utilities.

> [!TIP]
> Guide to Projections and Read Models in Event-Driven Architecture

If you're interested in projecting into PostgreSQL database, see projection-typeorm package.

If you're interested in projector application as run by Lace, see setup and README in cardano-services package.

Prerequisites

In order to understand how cardano-js-sdk projections work, you'll first need basic understanding of:

- Observables (we're using RxJS implementation)
- Chain Sync mini protocol (well explained in Ogmios docs)

Types

$3

All projections start by obtaining a source/producer¹, which is an Observable>. These events are very similar to Chain Sync events, but there are some important differences:

1. Block format is compatible with types from @cardano-sdk/core package.
2. Events include some additional properties: {eraSumaries, genesisParameters, epochNo, crossEpochBoundary}.
3. RollBackward events include block data (instead of just specifying the rollback point), and are emitted once for each rolled back block.

#### ExtraProps (Generic Parameter)

Source observable can be piped through a series of RxJS operators, which may add some properties to the event. In a nutshell, ProjectionEvent = ProjectionEvent<{}> & T. For more detail see Mappers.

$3

Since ProjectionEvent{eventType=RollBackward} includes block data, we must store some number (at least k, which is the "security parameter") of latest blocks so that if a fork/rollback happens, we can call StabilityWindowBuffer.getBlock(hash) in order to build a valid ProjectionEvent.

$3

This is our interface to Chain Sync and Local State Query protocols of Cardano node. The only implementation available in cardano-js-sdk is OgmiosObservableCardanoNode.

Utilities

$3

Creates a projection source (Observable) from:

- ObservableCardanoNode
- StabilityWindowBuffer
- Observable that emits block header of last processed event (local tip). This is used to find intersection point.

``mermaid
---
title: Bootstrap Algorithm
---
flowchart LR
subscribe[Subscribe] --> find-intersect{Find node\nintersection\nwith local tip}
find-intersect --> |Found| start[Start ChainSync\nfrom intersection]
start --> get-event{Get event\nfrom node,\ncheck type}
get-event --> |RollBackward| get-block[Get block from StabilityWindowBuffer]
get-event --> |RollForward| hydrate
start --> hydrate[Hydrate event\nwith additional\npropertes]
hydrate --> emit[Emit\nProjectionEvent]
find-intersect --> |Not Found| get-block[Get block from\nStabilityWindowBuffer]
get-block --> rollback[Create\nRollBackward\nevent]
rollback --> hydrate
rollback --> wait[Wait for\nlocal tip change]
wait --> is-rollback-point{Is rollback point?}
is-rollback-point --> |No| get-block
is-rollback-point --> |Yes| started-sync{Already started\nChain Sync?}
started-sync --> |Yes| get-event
started-sync --> |No| find-intersect
`

$3

Projections are typically

1. Interpreting the block (e.g. extracting some relevant properties from all transactions). Mappers is a namespace that contains a collection of RxJS operators that process the ProjectionEvent (block) and emit a new event object that has some additional properties.
2. Doing something with it (e.g. store into the database).

Here's an example:

`typescript
// source$: Observable>
source$.pipe(
// policyId is a parameter that should be provided
// by handle issuer, e.g. ADA Handle
Mappers.withHandles({ policyId }),
// type WithHandles = { handles: HandleOwnership; }
// Event type can also be inferred (no need for explicit type declaration)
tap((event: ProjectionEvent) => {
console.log('Handles found by withHandles operator', event.handles);
})
);
`

$3

#### InMemoryStabilityWindowBuffer

If your application doesn't need persistence, you can use in-memory implementation of StabilityWindowBuffer, which can also be used as local tip tracker for Bootstrap (provides Observable).

---

_1Currently our projection source observable is not a pure 'Producer', as events have a requestNext` method that is used to control the source. This is subject to change in the future._