feat(indexer/distributions): define distributions database schema

indexer/README.md

@@ -43,6 +43,9 @@ Indexer environment variables are documented in the repository root
 
 ## Status
 
-This workspace is currently a scaffold. The poller, database repositories,
-cursor persistence, event handlers, and GraphQL API are planned but not yet
-implemented.
+This workspace is currently a scaffold. The poller, cursor persistence,
+event handlers, and GraphQL API are planned but not yet implemented.
+
+The distributions domain database schema (`distribution_batch`, `claim_action`)
+is defined under `distributions/src/db/` with a SQL migration in
+`common/src/db/migrations/0002_create_distributions_schema.sql`.

indexer/common/src/db/migrations/0002_create_distributions_schema.sql

@@ -0,0 +1,77 @@
+-- Migration: 0002_create_distributions_schema
+-- Creates distribution_batch and claim_action tables for the distributions indexer domain.
+
+CREATE TABLE IF NOT EXISTS schema_migrations (
+  version     TEXT        NOT NULL PRIMARY KEY,
+  applied_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM schema_migrations WHERE version = '0002_create_distributions_schema'
+  ) THEN
+    RAISE NOTICE 'Migration 0002_create_distributions_schema already applied, skipping.';
+    RETURN;
+  END IF;
+
+  CREATE TABLE distribution_batch (
+    id               TEXT           NOT NULL,
+    contract_id      TEXT           NOT NULL,
+    distributor      TEXT           NOT NULL,
+    token            TEXT           NOT NULL,
+    total_amount     NUMERIC(78, 0) NOT NULL,
+    claimed_amount   NUMERIC(78, 0) NOT NULL DEFAULT 0,
+    recipient_count  INTEGER        NOT NULL DEFAULT 0,
+    status           TEXT           NOT NULL DEFAULT 'active',
+    paused_at        BIGINT,
+    resumed_at       BIGINT,
+    unique_ref       TEXT           NOT NULL,
+    ledger_number    BIGINT         NOT NULL,
+    tx_hash          TEXT           NOT NULL,
+    created_at       TIMESTAMPTZ    NOT NULL DEFAULT NOW(),
+    updated_at       TIMESTAMPTZ    NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT distribution_batch_pkey PRIMARY KEY (id),
+    CONSTRAINT distribution_batch_status_chk
+      CHECK (status IN ('active', 'paused', 'completed', 'cancelled')),
+    CONSTRAINT distribution_batch_total_amount_nonneg CHECK (total_amount >= 0),
+    CONSTRAINT distribution_batch_claimed_amount_nonneg CHECK (claimed_amount >= 0),
+    CONSTRAINT distribution_batch_recipient_count_nonneg CHECK (recipient_count >= 0)
+  );
+
+  CREATE INDEX distribution_batch_contract_id_idx
+    ON distribution_batch (contract_id);
+  CREATE INDEX distribution_batch_distributor_idx
+    ON distribution_batch (distributor);
+  CREATE INDEX distribution_batch_status_idx
+    ON distribution_batch (status);
+  CREATE INDEX distribution_batch_created_at_idx
+    ON distribution_batch (created_at);
+  CREATE INDEX distribution_batch_contract_status_idx
+    ON distribution_batch (contract_id, status);
+
+  CREATE TABLE claim_action (
+    id               UUID           NOT NULL DEFAULT gen_random_uuid(),
+    batch_id         TEXT           NOT NULL,
+    claimant         TEXT           NOT NULL,
+    amount           NUMERIC(78, 0) NOT NULL,
+    tx_hash          TEXT           NOT NULL,
+    ledger_number    BIGINT         NOT NULL,
+    event_timestamp  BIGINT         NOT NULL,
+    created_at       TIMESTAMPTZ    NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT claim_action_pkey PRIMARY KEY (id),
+    CONSTRAINT claim_action_batch_fk
+      FOREIGN KEY (batch_id) REFERENCES distribution_batch (id) ON DELETE CASCADE,
+    CONSTRAINT claim_action_amount_nonneg CHECK (amount >= 0)
+  );
+
+  CREATE INDEX claim_action_batch_id_idx ON claim_action (batch_id);
+  CREATE INDEX claim_action_claimant_idx ON claim_action (claimant);
+  CREATE INDEX claim_action_tx_hash_idx ON claim_action (tx_hash);
+  CREATE INDEX claim_action_batch_claimant_idx ON claim_action (batch_id, claimant);
+
+  INSERT INTO schema_migrations (version) VALUES ('0002_create_distributions_schema');
+END;
+$$;

indexer/distributions/package.json

@@ -15,6 +15,7 @@
     "type-check": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@fundable-indexer/common": "workspace:*"
+    "@fundable-indexer/common": "workspace:*",
+    "typeorm": "^0.3.20"
   }
 }

indexer/distributions/src/db/entity/ClaimAction.ts

@@ -0,0 +1,55 @@
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  Index,
+  JoinColumn,
+  ManyToOne,
+  PrimaryGeneratedColumn,
+} from "typeorm";
+
+import { DistributionBatch } from "./DistributionBatch.js";
+
+@Entity("claim_action")
+@Index("claim_action_batch_id_idx", ["batchId"])
+@Index("claim_action_claimant_idx", ["claimant"])
+@Index("claim_action_tx_hash_idx", ["txHash"])
+@Index("claim_action_batch_claimant_idx", ["batchId", "claimant"])
+export class ClaimAction {
+  @PrimaryGeneratedColumn("uuid")
+  id!: string;
+
+  @Column({ type: "varchar", comment: "Distribution batch this claim belongs to" })
+  batchId!: string;
+
+  @ManyToOne(
+    () => DistributionBatch,
+    (batch) => batch.claims,
+    { onDelete: "CASCADE" },
+  )
+  @JoinColumn({ name: "batchId" })
+  batch!: DistributionBatch;
+
+  @Column({ type: "varchar", comment: "Address that claimed tokens" })
+  claimant!: string;
+
+  @Column({
+    type: "numeric",
+    precision: 78,
+    scale: 0,
+    comment: "Claimed amount in the token's smallest unit",
+  })
+  amount!: string;
+
+  @Column({ type: "varchar", comment: "Transaction hash where the claim occurred" })
+  txHash!: string;
+
+  @Column({ type: "bigint", comment: "Ledger where the claim was recorded" })
+  ledgerNumber!: string;
+
+  @Column({ type: "bigint", comment: "On-chain timestamp of the claim" })
+  eventTimestamp!: string;
+
+  @CreateDateColumn()
+  createdAt!: Date;
+}

indexer/distributions/src/db/entity/DistributionBatch.ts

@@ -0,0 +1,97 @@
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  Index,
+  OneToMany,
+  PrimaryColumn,
+  UpdateDateColumn,
+} from "typeorm";
+
+import type { DistributionBatchStatus } from "../status.js";
+import { ClaimAction } from "./ClaimAction.js";
+
+@Entity("distribution_batch")
+@Index("distribution_batch_contract_id_idx", ["contractId"])
+@Index("distribution_batch_distributor_idx", ["distributor"])
+@Index("distribution_batch_status_idx", ["status"])
+@Index("distribution_batch_created_at_idx", ["createdAt"])
+@Index("distribution_batch_contract_status_idx", ["contractId", "status"])
+export class DistributionBatch {
+  @PrimaryColumn({
+    type: "varchar",
+    comment: "Deterministic batch ID from the Soroban contract",
+  })
+  id!: string;
+
+  @Column({ type: "varchar", comment: "Soroban contract that emitted the batch" })
+  contractId!: string;
+
+  @Column({ type: "varchar", comment: "Address that created the distribution batch" })
+  distributor!: string;
+
+  @Column({ type: "varchar", comment: "Token asset contract address" })
+  token!: string;
+
+  @Column({
+    type: "numeric",
+    precision: 78,
+    scale: 0,
+    comment: "Total allocated amount in the token's smallest unit",
+  })
+  totalAmount!: string;
+
+  @Column({
+    type: "numeric",
+    precision: 78,
+    scale: 0,
+    default: "0",
+    comment: "Total amount claimed so far in the token's smallest unit",
+  })
+  claimedAmount!: string;
+
+  @Column({ type: "integer", default: 0, comment: "Number of intended recipients" })
+  recipientCount!: number;
+
+  @Column({
+    type: "varchar",
+    default: "active",
+    comment: "Batch lifecycle status for pause/resume behavior",
+  })
+  status!: DistributionBatchStatus;
+
+  @Column({
+    type: "bigint",
+    nullable: true,
+    comment: "Unix timestamp when the batch was paused",
+  })
+  pausedAt!: string | null;
+
+  @Column({
+    type: "bigint",
+    nullable: true,
+    comment: "Unix timestamp when the batch was last resumed",
+  })
+  resumedAt!: string | null;
+
+  @Column({ type: "varchar", comment: "Contract-unique reference for the batch" })
+  uniqueRef!: string;
+
+  @Column({ type: "bigint", comment: "Ledger where the batch was created" })
+  ledgerNumber!: string;
+
+  @Column({ type: "varchar", comment: "Transaction hash that created the batch" })
+  txHash!: string;
+
+  @OneToMany(
+    () => ClaimAction,
+    (claim) => claim.batch,
+  )
+  claims!: ClaimAction[];
+
+  @CreateDateColumn()
+  createdAt!: Date;
+
+  @UpdateDateColumn()
+  updatedAt!: Date;
+}