@alphscan/normalized-events

Normalized event types, categories, and factory for Alephium blockchain events. Used by the indexer to produce a consistent schema for RDS storage and complex queries.

Schema versioning

• NORMALIZED_EVENT_SCHEMA_VERSION – Bump when breaking changes require reindexing.
• Every event has schema_version and a unique id (chain:fromGroup:toGroup:block_number:tx_hash:log_index) for idempotency.

Base fields (every event)

| Field | Type | Description | |-------|------|-------------| | chain | string | Chain identifier (e.g. mainnet group) | | fromGroup | number | Alephium from-group index (0–3) | | toGroup | number | Alephium to-group index (0–3) | | block_number | number | Block number | | tx_hash | string | Transaction hash | | log_index | number | Event index within the tx | | token_address | string | null | Token/contract address when applicable | | from | string | null | Sender | | to | string | null | Recipient | | amount | string | null | Raw amount (smallest unit) | | amount_usd | string | null | USD value when available | | lock_until | number | null | Lock/vesting end timestamp | | dapp | string | null | Dapp/protocol id (e.g. "alephium-dex") | | authoring | string | null | Contract/address that emitted the event | | plugin | string | null | Plugin that generated this event | | normalizer | string | null | Normalizer that produced this event | | normalizer_version | number | null | Version of the normalizer | | creationDate | number | null | When this normalized event was first created (ms since epoch) | | lastUpdate | number | null | When this normalized event was last updated (ms since epoch) | | onChainDate | number | null | When the event occurred on chain (ms since epoch) | | dateIndexationMetrics | number | Date used for indexation metrics (ms since epoch); defaults to 1970-01-01 |

Categories and sub-kinds

1. Transfer – native_transfer, burn_native, token_transfer, send_to_bridge, received_from_bridge, send_to_cex, received_from_cex, genesis_release, treasury_mint, treasury_release
2. Token – genesis_mint, genesis_distribution, genesis_emission, token_emission, token_mint, token_burn, nft_transfer, nft_collection_mint, nft_collection_burn, nft_mint, nft_burn, wrap, unwrap
3. Chain – coinbase, burn_network_fees, pay_storage_fees
4. DEX – pool_creation, pool_destruction, add_liquidity, remove_liquidity, swap, mint_nft_position, burn_nft_position, push_order, delete_order, execute_order, vote_for_pool, claim_vote_rewards, claim_trading_fees, collect_fees
5. Lending – deposit_collateral, remove_collateral, borrow, repay, liquidation, liquidation_auction, redeem, open_trove, close_trove, adjust_trove, claim_collateral, supply, withdraw
6. Yield – stake, unstake, claim_staking, claim_fees, deposit, withdraw, compound, claim_rewards, vest, claim_vested
7. Governance – create_proposal, vote, vote_results, execute_proposal, cancel_proposal, queue_proposal, delegate
8. Contract life – contract_creation, contract_destruction, contract_update, contract_upgrade, contract_pause, contract_unpause
9. Game / prediction – create_game, create_market, bet, claim, add_to_pot, win, lose, resolve_market, cancel_market, refund
10. Oracle – oracle_update, oracle_get_random_seed, oracle_request_randomness, oracle_fulfill_randomness

Usage

import {
  createNormalizedEvent,
  EventCategory,
  TransferSubKind,
  buildEventId,
} from "@alphscan/normalized-events";

const event = createNormalizedEvent(
  {
    chain: "mainnet",
    fromGroup: 0,
    toGroup: 0,
    block_number: 12345,
    tx_hash: "0x…",
    log_index: 0,
    from: "addr1",
    to: "addr2",
    amount: "1000000000000000000",
    timestamp: Date.now(),
  },
  {
    category: "transfer",
    sub_kind: TransferSubKind.NATIVE_TRANSFER,
  }
);

Type guards

• isTransferEvent(e), isTokenEvent(e), isChainEvent(e), isDexEvent(e), isLendingEvent(e), isYieldEvent(e), isGovernanceEvent(e), isContractLifeEvent(e), isGameEvent(e), isOracleEvent(e)

Storage and export

• RDS: Use @alphscan/storage – createNormalizedEventStore({ relational }), CREATE_NORMALIZED_EVENTS_TABLE_SQL, eventToRow / rowToEvent.
• Export: eventsToJson, eventsToSqlLiteral, eventsToCsv, writeEventsToJsonFile, writeEventsToSqlFile, writeEventsToCsvFile from @alphscan/storage.