Skip to content

Commit

Permalink
bootstrap mina funnel docs
Browse files Browse the repository at this point in the history
  • Loading branch information
ecioppettini committed Apr 23, 2024
1 parent 64ddefe commit 87d954b
Show file tree
Hide file tree
Showing 3 changed files with 128 additions and 0 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Generic Primitives

- [Generic](#generic), allowing you to provide an arbitrary contract ABI and the signature of the event to track, allowing you to collect data even from smart contracts not directly supported by the above types.

## Generic

Generic primitives allow getting all of the events or all the actions provided the address of a zkapp.

### Example configuration

```yaml
extensions:
- name: "mina generic event"
type: "mina-event-generic"
address: "B62qoP3xe9zZJmBDacZPL8roBivpVKhAiDNtpAM9RCAW579JnJo1ZL2"
startBlockHeight: 0
scheduledPrefix: "mge"
network: 'Mina'
- name: "mina generic action"
type: "mina-action-generic"
address: "B62qoP3xe9zZJmBDacZPL8roBivpVKhAiDNtpAM9RCAW579JnJo1ZL2"
startBlockHeight: 0
scheduledPrefix: "mga"
network: 'Mina'
```
## Concise format
```
minaGenericEvent = mge|data
minaGenericAction = mga|data
```

```ts
const minaGenericEvent: ParserRecord<MinaGenericEvent> = {
data: (keyName: string, input: string) => {
return JSON.parse(input);
},
};

const minaGenericAction: ParserRecord<MinaGenericAction> = {
data: (keyName: string, input: string) => {
return JSON.parse(input);
},
};
```

Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"label": "Mina Primitives"
}
77 changes: 77 additions & 0 deletions docs/home/300-react-to-events/3-funnel-types/600-mina-funnel.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Mina funnel

## Configuration

The Mina funnel requires access to historical chain data which is acquired
through an [archive
node](https://docs.minaprotocol.com/node-operators/archive-node). A connection
to the database is required.

`confirmationDepth` is expected be the same as the `k` setting in the underlying
network/archive. Likewise with `slotDuration`.

```yaml
Mina:
type: mina
archiveConnectionString: "postgresql://postgres:postgres@localhost:5432/archive"
confirmationDepth: 30,
slotDuration: 20,
```
- `slotDuration` is in seconds.
- `confirmationDepth` is in number of blocks.

Mina events are delayed by `slotDuration * confirmationDepth` seconds.

## Conceptually

This funnel has the following steps in the readData function:

1. Fetch blocks & timestamps from the underlying funnel. This can be either a funnel for a single chain, like the [block funnel](300-block-funnel.md), or it can be a collection of wrapped funnels involving multiple networks.
2. Fetch the confirmed mina block timestamp. This is done by querying the `blocks` table to get the latest block which has canonical status. This means that the block confirmation parameters are defined by the archive node configuration.
4. Query the database for events and actions in a certain timestamp range. The
upper bound of this timestamp range is defined by the blocks fetched at step 1. The lower bound is the upper bound on the previous round.
5. Merge the primitives with the underlying funnel.

### Finality

The merging of events with the underlying funnel works similarly to the
[parallel evm funnel](500-parallel-evm-funnel.mdx). The most important
difference is that timestamps from the _main_ chain get subtracted
`confirmationDepth * slotDuration` seconds. This means the events from the Mina
chain are delayed by this amount of time also.

### Finalizing blocks

Since events parsed by the state transition are final, we need to be sure that
we have processed all the Mina events that are associated with a certain block
height before supplying those the events to the state transition. To do this,
the Mina funnel will wait for the timestamp of the latest `canonical` block to
be greater or equal than the timestamp of the block data is getting merged into.
This is necessary because otherwise there is no guarantee that the needed blocks
are already propagated to the archive node, or in case there is a re-org.

Internally this is done by querying the `blocks` table for the latest block with a status
of `canonical`.

## Database

The following tables are used to retrieve the necessary information:

- account_identifiers
- accounts_accessed
- blocks
- blocks_zkapp_commands
- zkapp_account_update
- zkapp_account_update_body
- zkapp_commands
- zkapp_events
- zkapp_field
- zkapp_field_array

Usage is similar to the one used in [Archive-Node-Api](https://github.com/o1-labs/Archive-Node-API) except for the following:

- `blocks` are filtered by the `timestamp` column when needed.
- only blocks with `canonical` status are considered for anything.
- `zkapp_commands` is filtered by `hash` to paginate the results during presync.
- `blocks` is used to find the genesis timestamp and the latest finalized block.

0 comments on commit 87d954b

Please sign in to comment.