feat: add address projection

- new mappers: withStakeKeyRegistrations, withAddresses
- new stores: storeStakeKeyRegistrations, storeAddresses
- new projection type/name in cardano-services: 'address'

Author: mkazlauskas

packages/cardano-services/src/Projection/migrations/1690955710125-address-table.ts

@@ -0,0 +1,26 @@
+import { AddressEntity } from '@cardano-sdk/projection-typeorm';
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AddressTableMigrations1690955710125 implements MigrationInterface {
+  static entity = AddressEntity;
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      "CREATE TYPE \"public\".\"address_type_enum\" AS ENUM('0', '1', '2', '3', '4', '5', '6', '7', '8', '14', '15')"
+    );
+    await queryRunner.query(
+      'CREATE TABLE "address" ("address" character varying NOT NULL, "type" "public"."address_type_enum" NOT NULL, "payment_credential_hash" character(56), "stake_credential_hash" character(56), CONSTRAINT "PK_address_address" PRIMARY KEY ("address"))'
+    );
+    await queryRunner.query(
+      'CREATE INDEX "IDX_address_payment_credential_hash" ON "address" ("payment_credential_hash") '
+    );
+    await queryRunner.query('CREATE INDEX "IDX_address_stake_credential_hash" ON "address" ("stake_credential_hash") ');
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query('DROP INDEX "public"."IDX_address_stake_credential_hash"');
+    await queryRunner.query('DROP INDEX "public"."IDX_address_payment_credential_hash"');
+    await queryRunner.query('DROP TABLE "address"');
+    await queryRunner.query('DROP TYPE "public"."address_type_enum"');
+  }
+}

packages/cardano-services/src/Projection/migrations/1690964880195-stake-key-registrations-table.ts

@@ -0,0 +1,34 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+import { StakeKeyRegistrationEntity } from '@cardano-sdk/projection-typeorm';
+
+export class StakeKeyRegistrationsTableMigrations1690964880195 implements MigrationInterface {
+  static entity = StakeKeyRegistrationEntity;
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      'CREATE TABLE "stake_key_registration" ("id" bigint NOT NULL, "stake_key_hash" character(56) NOT NULL, "block_slot" integer NOT NULL, CONSTRAINT "PK_stake_key_registration_id" PRIMARY KEY ("id"))'
+    );
+    await queryRunner.query(
+      'CREATE INDEX "IDX_stake_key_registration_stake_key_hash" ON "stake_key_registration" ("stake_key_hash") '
+    );
+    await queryRunner.query(
+      'ALTER TABLE "stake_key_registration" ADD CONSTRAINT "FK_stake_key_registration_block_slot" FOREIGN KEY ("block_slot") REFERENCES "block"("slot") ON DELETE CASCADE ON UPDATE NO ACTION'
+    );
+
+    await queryRunner.query('ALTER TABLE "address" ADD "registration_id" bigint');
+    await queryRunner.query(
+      'ALTER TABLE "address" ADD CONSTRAINT "FK_address_registration_id" FOREIGN KEY ("registration_id") REFERENCES "stake_key_registration"("id") ON DELETE CASCADE ON UPDATE NO ACTION'
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query('ALTER TABLE "address" DROP CONSTRAINT "FK_address_registration_id"');
+    await queryRunner.query('ALTER TABLE "address" DROP COLUMN "registration_id"');
+
+    await queryRunner.query(
+      'ALTER TABLE "stake_key_registration" DROP CONSTRAINT "FK_stake_key_registration_block_slot"'
+    );
+    await queryRunner.query('DROP INDEX "public"."IDX_stake_key_registration_stake_key_hash"');
+    await queryRunner.query('DROP TABLE "stake_key_registration"');
+  }
+}

packages/cardano-services/src/Projection/migrations/index.ts

@@ -1,3 +1,4 @@
+import { AddressTableMigrations1690955710125 } from './1690955710125-address-table';
 import { AssetTableMigration1682519108365 } from './1682519108365-asset-table';
 import { BlockDataTableMigration1682519108359 } from './1682519108359-block-data-table';
 import { BlockTableMigration1682519108358 } from './1682519108358-block-table';
@@ -11,6 +12,7 @@ import { PoolMetadataTableMigration1682519108363 } from './1682519108363-pool-me
 import { PoolMetricsMigrations1685011799580 } from './1685011799580-stake-pool-metrics-table';
 import { PoolRegistrationTableMigration1682519108360 } from './1682519108360-pool-registration-table';
 import { PoolRetirementTableMigration1682519108361 } from './1682519108361-pool-retirement-table';
+import { StakeKeyRegistrationsTableMigrations1690964880195 } from './1690964880195-stake-key-registrations-table';
 import { StakePoolTableMigration1682519108362 } from './1682519108362-stake-pool-table';
 import { TokensQuantityNumericMigrations1691042603934 } from './1691042603934-tokens-quantity-numeric';
 import { TokensTableMigration1682519108368 } from './1682519108368-tokens-table';
@@ -35,5 +37,7 @@ export const migrations: ProjectionMigration[] = [
   HandleTableMigration1686138943349,
   CostPledgeNumericMigration1689091319930,
   NftMetadataTableMigration1690269355640,
+  AddressTableMigrations1690955710125,
+  StakeKeyRegistrationsTableMigrations1690964880195,
   TokensQuantityNumericMigrations1691042603934
 ];

packages/cardano-services/src/Projection/prepareTypeormProjection.ts

@@ -1,4 +1,5 @@
 import {
+  AddressEntity,
   AssetEntity,
   BlockDataEntity,
   BlockEntity,
@@ -10,14 +11,17 @@ import {
   PoolMetadataEntity,
   PoolRegistrationEntity,
   PoolRetirementEntity,
+  StakeKeyRegistrationEntity,
   StakePoolEntity,
   TokensEntity,
   TypeormStabilityWindowBuffer,
   createStorePoolMetricsUpdateJob,
+  storeAddresses,
   storeAssets,
   storeBlock,
   storeHandles,
   storeNftMetadata,
+  storeStakeKeyRegistrations,
   storeStakePoolMetadataJob,
   storeStakePools,
   storeUtxo
@@ -38,7 +42,8 @@ export enum ProjectionName {
   StakePool = 'stake-pool',
   StakePoolMetadataJob = 'stake-pool-metadata-job',
   StakePoolMetricsJob = 'stake-pool-metrics-job',
-  UTXO = 'utxo'
+  UTXO = 'utxo',
+  Address = 'address'
 }
 
 export interface ProjectionOptions {
@@ -65,11 +70,13 @@ const createMapperOperators = (
   return {
     filterMint,
     filterUtxo,
+    withAddresses: Mapper.withAddresses(),
     withCIP67: Mapper.withCIP67(),
     withCertificates: Mapper.withCertificates(),
     withHandles,
     withMint: Mapper.withMint(),
     withNftMetadata: Mapper.withNftMetadata({ logger }),
+    withStakeKeyRegistrations: Mapper.withStakeKeyRegistrations(),
     withStakePools: Mapper.withStakePools(),
     withUtxo: Mapper.withUtxo()
   };
@@ -79,11 +86,13 @@ type MapperName = keyof MapperOperators;
 type MapperOperator = MapperOperators[MapperName];
 
 export const storeOperators = {
+  storeAddresses: storeAddresses(),
   storeAssets: storeAssets(),
   storeBlock: storeBlock(),
   storeHandles: storeHandles(),
   storeNftMetadata: storeNftMetadata(),
   storePoolMetricsUpdateJob: createStorePoolMetricsUpdateJob(POOLS_METRICS_INTERVAL_DEFAULT)(),
+  storeStakeKeyRegistrations: storeStakeKeyRegistrations(),
   storeStakePoolMetadataJob: storeStakePoolMetadataJob(),
   storeStakePools: storeStakePools(),
   storeUtxo: storeUtxo()
@@ -93,6 +102,7 @@ type StoreName = keyof StoreOperators;
 type StoreOperator = StoreOperators[StoreName];
 
 const entities = {
+  address: AddressEntity,
   asset: AssetEntity,
   block: BlockEntity,
   blockData: BlockDataEntity,
@@ -103,6 +113,7 @@ const entities = {
   poolMetadata: PoolMetadataEntity,
   poolRegistration: PoolRegistrationEntity,
   poolRetirement: PoolRetirementEntity,
+  stakeKeyRegistration: StakeKeyRegistrationEntity,
   stakePool: StakePoolEntity,
   tokens: TokensEntity
 };
@@ -112,17 +123,20 @@ type EntityName = keyof Entities;
 type Entity = Entities[EntityName];
 
 const storeEntities: Partial<Record<StoreName, EntityName[]>> = {
+  storeAddresses: ['address'],
   storeAssets: ['asset'],
   storeBlock: ['block'],
   storeHandles: ['handle', 'asset', 'tokens', 'output'],
   storeNftMetadata: ['asset'],
   storePoolMetricsUpdateJob: ['stakePool', 'currentPoolMetrics', 'poolMetadata'],
+  storeStakeKeyRegistrations: ['block', 'stakeKeyRegistration'],
   storeStakePoolMetadataJob: ['stakePool', 'currentPoolMetrics', 'poolMetadata'],
   storeStakePools: ['stakePool', 'currentPoolMetrics', 'poolMetadata'],
   storeUtxo: ['tokens', 'output']
 };
 
 const entityInterDependencies: Partial<Record<EntityName, EntityName[]>> = {
+  address: ['stakeKeyRegistration'],
   asset: ['block', 'nftMetadata'],
   blockData: ['block'],
   currentPoolMetrics: ['stakePool'],
@@ -131,6 +145,7 @@ const entityInterDependencies: Partial<Record<EntityName, EntityName[]>> = {
   poolMetadata: ['stakePool'],
   poolRegistration: ['block'],
   poolRetirement: ['block'],
+  stakeKeyRegistration: ['block'],
   stakePool: ['block', 'poolRegistration', 'poolRetirement'],
   tokens: ['asset']
 };
@@ -158,22 +173,27 @@ export const getEntities = (entityNames: EntityName[]): Entity[] => {
 const mapperInterDependencies: Partial<Record<MapperName, MapperName[]>> = {
   filterMint: ['withMint'],
   filterUtxo: ['withUtxo'],
+  withAddresses: ['withUtxo'],
   withCIP67: ['withUtxo'],
   withHandles: ['withMint', 'filterMint', 'withUtxo', 'filterUtxo'],
   withNftMetadata: ['withCIP67', 'withMint'],
+  withStakeKeyRegistrations: ['withCertificates'],
   withStakePools: ['withCertificates']
 };
 
 const storeMapperDependencies: Partial<Record<StoreName, MapperName[]>> = {
+  storeAddresses: ['withAddresses'],
   storeAssets: ['withMint'],
   storeHandles: ['withHandles'],
   storeNftMetadata: ['withNftMetadata'],
+  storeStakeKeyRegistrations: ['withStakeKeyRegistrations'],
   storeStakePoolMetadataJob: ['withStakePools'],
   storeStakePools: ['withStakePools'],
   storeUtxo: ['withUtxo']
 };
 
 const storeInterDependencies: Partial<Record<StoreName, StoreName[]>> = {
+  storeAddresses: ['storeStakeKeyRegistrations'],
   storeAssets: ['storeBlock'],
   storeHandles: ['storeUtxo'],
   storeNftMetadata: ['storeAssets'],
@@ -184,6 +204,7 @@ const storeInterDependencies: Partial<Record<StoreName, StoreName[]>> = {
 };
 
 const projectionStoreDependencies: Record<ProjectionName, StoreName[]> = {
+  address: ['storeAddresses'],
   handle: ['storeHandles', 'storeNftMetadata'],
   'stake-pool': ['storeStakePools'],
   'stake-pool-metadata-job': ['storeStakePoolMetadataJob'],

packages/projection-typeorm/src/entity/Address.entity.ts

@@ -0,0 +1,30 @@
+import { Cardano } from '@cardano-sdk/core';
+import { Column, Entity, Index, JoinColumn, ManyToOne, PrimaryColumn } from 'typeorm';
+import { Hash28ByteBase16 } from '@cardano-sdk/crypto';
+import { StakeKeyRegistrationEntity } from './StakeKeyRegistration.entity';
+
+@Entity()
+export class AddressEntity {
+  @PrimaryColumn()
+  address?: Cardano.PaymentAddress;
+  @Column({ enum: Cardano.AddressType, type: 'enum' })
+  type?: Cardano.AddressType;
+  @Column('char', { length: 56, nullable: true })
+  @Index()
+  /**
+   * Applicable only for base/grouped, enterprise and pointer addresses
+   */
+  paymentCredentialHash?: Hash28ByteBase16 | null;
+  @Column('char', { length: 56, nullable: true })
+  @Index()
+  /**
+   * Applicable only for base/grouped and pointer addresses
+   */
+  stakeCredentialHash?: Hash28ByteBase16 | null;
+  @ManyToOne(() => StakeKeyRegistrationEntity, { nullable: true, onDelete: 'CASCADE' })
+  @JoinColumn()
+  /**
+   * Applicable only for pointer addresses
+   */
+  registration?: StakeKeyRegistrationEntity | null;
+}

packages/projection-typeorm/src/entity/StakeKeyRegistration.entity.ts

@@ -0,0 +1,20 @@
+import { BigIntColumnOptions, OnDeleteCascadeRelationOptions } from './util';
+import { BlockEntity } from './Block.entity';
+import { Column, Entity, Index, JoinColumn, ManyToOne, PrimaryColumn } from 'typeorm';
+import { Ed25519KeyHashHex } from '@cardano-sdk/crypto';
+
+@Entity()
+export class StakeKeyRegistrationEntity {
+  /**
+   * Computed from certificate pointer.
+   * Can be used to query by pointer using `Cardano.PointerToId` util.
+   */
+  @PrimaryColumn(BigIntColumnOptions)
+  id?: bigint;
+  @Column('char', { length: 56 })
+  @Index()
+  stakeKeyHash?: Ed25519KeyHashHex;
+  @ManyToOne(() => BlockEntity, OnDeleteCascadeRelationOptions)
+  @JoinColumn()
+  block?: BlockEntity;
+}

packages/projection-typeorm/src/entity/index.ts

@@ -11,3 +11,5 @@ export * from './Output.entity';
 export * from './CurrentPoolMetrics.entity';
 export * from './Handle.entity';
 export * from './NftMetadata.entity';
+export * from './Address.entity';
+export * from './StakeKeyRegistration.entity';

packages/projection-typeorm/src/operators/index.ts

@@ -9,3 +9,5 @@ export * from './storeHandles';
 export * from './util';
 export * from './storePoolMetricsUpdateJob';
 export * from './storeNftMetadata';
+export * from './storeAddresses';
+export * from './storeStakeKeyRegistrations';

packages/projection-typeorm/src/operators/storeAddresses.ts

@@ -0,0 +1,43 @@
+import { AddressEntity } from '../entity/Address.entity';
+import { Cardano, ChainSyncEventType } from '@cardano-sdk/core';
+import { Hash28ByteBase16 } from '@cardano-sdk/crypto';
+import { Mappers } from '@cardano-sdk/projection';
+import { QueryRunner } from 'typeorm';
+import { StakeKeyRegistrationEntity } from '../entity';
+import { certificatePointerToId, typeormOperator } from './util';
+
+const lookupStakeKeyRegistration = async (pointer: Cardano.Pointer | undefined, queryRunner: QueryRunner) => {
+  if (!pointer) return;
+  const registrationId = certificatePointerToId(pointer);
+  const stakeKeyRegistration = await queryRunner.manager
+    .getRepository(StakeKeyRegistrationEntity)
+    .findOne({ select: { stakeKeyHash: true }, where: { id: registrationId } });
+  if (!stakeKeyRegistration?.stakeKeyHash) return;
+  return Hash28ByteBase16.fromEd25519KeyHashHex(stakeKeyRegistration.stakeKeyHash);
+};
+
+export const storeAddresses = typeormOperator<Mappers.WithAddresses>(async (evt) => {
+  const { addresses, eventType, queryRunner } = evt;
+  if (addresses.length === 0 || eventType !== ChainSyncEventType.RollForward) return;
+  const addressEntities = await Promise.all(
+    addresses.map(async ({ paymentCredentialHash, stakeCredential, address, type }): Promise<AddressEntity> => {
+      const stakeCredentialHash =
+        typeof stakeCredential === 'string'
+          ? stakeCredential
+          : await lookupStakeKeyRegistration(stakeCredential, queryRunner);
+      return {
+        address,
+        paymentCredentialHash,
+        stakeCredentialHash,
+        type
+      };
+    })
+  );
+  await queryRunner.manager
+    .createQueryBuilder()
+    .insert()
+    .into(AddressEntity)
+    .values(addressEntities)
+    .orIgnore()
+    .execute();
+});

packages/projection-typeorm/src/operators/storeStakeKeyRegistrations.ts

@@ -0,0 +1,23 @@
+import { ChainSyncEventType } from '@cardano-sdk/core';
+import { Mappers } from '@cardano-sdk/projection';
+import { StakeKeyRegistrationEntity } from '../entity';
+import { certificatePointerToId, typeormOperator } from './util';
+
+export const storeStakeKeyRegistrations = typeormOperator<Mappers.WithStakeKeyRegistrations>(
+  async ({ eventType, queryRunner, block, stakeKeyRegistrations }) => {
+    // Deleted by db with ON DELETE CASCADE
+    if (eventType !== ChainSyncEventType.RollForward || stakeKeyRegistrations.length === 0) return;
+    const stakeKeyRegistrationsRepo = queryRunner.manager.getRepository(StakeKeyRegistrationEntity);
+    await stakeKeyRegistrationsRepo.insert(
+      stakeKeyRegistrations.map(
+        (reg): StakeKeyRegistrationEntity => ({
+          block: {
+            slot: block.header.slot
+          },
+          id: certificatePointerToId(reg.pointer),
+          stakeKeyHash: reg.stakeKeyHash
+        })
+      )
+    );
+  }
+);