> For the complete documentation index, see [llms.txt](https://dzhelezov.gitbook.io/hydra/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dzhelezov.gitbook.io/hydra/hydra_v1/docs/mappings.md).

# Mappings

A mapping file is a standalone typescript module defining how the Substrate events of interest should be handled by the Hydra indexer.

The event handlers (aka *mappings*) should by convention be named `<RuntimeModule>_<EventName>` . For example, a handler for `treasury.Proposal` events should be named `treasury_Proposal`

Each handler must have exactly two arguments exported by the Indexer: the `db` handle which gives access to the database and `SubstrateEvent` which contains all the necessary data extracted by the indexer from the Substrate chain.

Let us look at the sample mapping generated by the scaffolder

```typescript
import { SubstrateEvent, DB } from '../generated/indexer';
import { Proposal } from '../generated/graphql-server/src/modules/proposal/proposal.model';
import { ProposalStatus } from '../generated/graphql-server/src/modules/enums/enums';
import { assert } from 'console';
import * as BN from 'bn.js';

// New proposal
export async function handleProposed(db: DB, event: SubstrateEvent) {
  const { ProposalIndex } = event.event_params;
  if (event.extrinsic) {
    const proposal = new Proposal();
    proposal.proposalIndex = new BN(ProposalIndex.toString());
    proposal.value = new BN(event.extrinsic.args[0].toString());
    proposal.bond = new BN(event.extrinsic.args[0].toString());
    proposal.beneficiary = Buffer.from(event.extrinsic.args[1].toString());
    proposal.proposer = Buffer.from(event.extrinsic.signer.toString());
    proposal.status = ProposalStatus.NONE;

    await db.save<Proposal>(proposal);
  }
}
```

Note that required entity classes are exported from

```
../generated/graphql-server/src/modules/<entity type>/<entity type>
```

and this is where all the auto-generated classes live by default.

Next, the body of the handler transforms the event parameters and extrinsic arguments into the properties of the entity. There is currently no way to enforce type safety here and one should instead inspect the event parameters and extrinsics for the event in question. In the example above, we can consult the Kusama [explorer](https://kusama.subscan.io/extrinsic/0x1bba67ddb62117fc64710e35b6ccbef64d4df528d78310ccca725137e75823d4?event=2022835-5) and check that

* `ProposalIndex` is a single named param of `treasury.Proposed` event
* The extrinsic has to arguments: `value` and `beneficiary`, propagated to the entity in a straightforward fashion.

Type-safe mappings and runtime upgrades will be supported in future releases of Hydra.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dzhelezov.gitbook.io/hydra/hydra_v1/docs/mappings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.