indexer

type Balance struct {
	PartyID         string `json:"party_id"`         // canton party (ERC-20: address)
	InstrumentAdmin string `json:"instrument_admin"` // instrumentId.admin
	InstrumentID    string `json:"instrument_id"`    // instrumentId.id
	Amount          string `json:"amount"`           // current balance, decimal string ≥ 0
}

type Config struct {
	// CIP56PackageID is the DAML package ID containing CIP56.Events.TokenTransferEvent.
	// Setting this pins the indexer to a specific package version; leave empty to
	// match the template across all package versions.
	CIP56PackageID string `yaml:"cip56_package_id" validate:"required"`

	// FilterMode controls which instruments are indexed.
	// "all"       — index every TokenTransferEvent on the stream.
	// "whitelist" — only index instruments listed in Instruments.
	FilterMode string `yaml:"filter_mode" default:"all" validate:"required,oneof=all whitelist"`

	// Instruments is the whitelist of CIP-56 instruments to index.
	// Only consulted when FilterMode is "whitelist".
	Instruments []InstrumentKey `yaml:"instruments"`

	// UtilityRegistryPackageID is the DAML package ID for the Utility Registry app
	// (Utility.Registry.App.V0.Model.Transfer.TransferOffer).
	// Leave empty to disable TransferOffer tracking.
	UtilityRegistryPackageID string `yaml:"utility_registry_package_id"`

	// UtilityRegistryHoldingPackageID is the DAML package ID for the Utility Registry
	// Holding template (Utility.Registry.Holding.V0.Holding). Required to track
	// USDCx-style balances — without it the indexer never sees Holding contract
	// create/archive events and balances for AllocationFactory-based instruments
	// stay at 0. Leave empty to disable Holding tracking.
	UtilityRegistryHoldingPackageID string `yaml:"utility_registry_holding_package_id"`
}

type EventFilter struct {
	InstrumentAdmin string
	InstrumentID    string
	PartyID         string
	EventType       EventType // empty = all types
}

type EventType string

type FilterMode int

type HoldingChange struct {
	ContractID   string
	IsArchived   bool
	LedgerOffset int64

	// Only populated for CREATED events. ARCHIVED events leave these empty and the
	// processor reads the matching row from indexer_holdings by ContractID.
	Owner           string
	InstrumentAdmin string
	InstrumentID    string
	Amount          string
	// Locked is true when the holding carries a lock (DAML `lock` is Some) — i.e. it
	// is escrowed by an outstanding transfer offer rather than spendable. Locked
	// holdings are excluded from indexed balances so a sender's balance reflects the
	// offered amount as deducted from offer creation until accept or claim-back.
	// Only meaningful for CREATED events.
	Locked bool
}

type InstrumentKey struct {
	Admin string `yaml:"admin"` // instrumentId.admin — the token admin/issuer party
	ID    string `yaml:"id"`    // instrumentId.id   — the token identifier (e.g. "DEMO")
}

type Page[T any] struct {
	Items []T   `json:"items"`
	Total int64 `json:"total"`
	Page  int   `json:"page"`
	Limit int   `json:"limit"`
}

type Pagination struct {
	Page  int
	Limit int
}

type ParsedEvent struct {
	// Instrument identification — fully qualified by both fields.
	InstrumentID    string `json:"instrument_id"`    // instrumentId.id  — token identifier (e.g. "DEMO", "PROMPT")
	InstrumentAdmin string `json:"instrument_admin"` // instrumentId.admin — token admin/issuer party

	// Issuer of the TokenTransferEvent contract (the token config issuer).
	Issuer string `json:"issuer"`

	// Transfer semantics, mirroring ERC-20 Transfer(from, to, value).
	EventType   EventType `json:"event_type"`
	Amount      string    `json:"amount"`                  // decimal string, e.g. "1.500000000000000000"
	FromPartyID *string   `json:"from_party_id,omitempty"` // nil for mints
	ToPartyID   *string   `json:"to_party_id,omitempty"`   // nil for burns

	// Bridge audit context extracted from meta.values (nil for native peer-to-peer transfers).
	ExternalTxID    *string `json:"external_tx_id,omitempty"`   // meta["bridge.externalTxId"]    — EVM transaction hash
	ExternalAddress *string `json:"external_address,omitempty"` // meta["bridge.externalAddress"] — EVM destination address
	Fingerprint     *string `json:"fingerprint,omitempty"`      // meta["bridge.fingerprint"]     — user fingerprint

	// Provenance.
	ContractID    string    `json:"contract_id"`    // TokenTransferEvent contract ID — idempotency key (event_id in store)
	TxID          string    `json:"tx_id"`          // Ledger transaction UpdateId
	LedgerOffset  int64     `json:"ledger_offset"`  // Ledger offset of the containing transaction
	Timestamp     time.Time `json:"timestamp"`      // Contract-level time from TokenTransferEvent.timestamp
	EffectiveTime time.Time `json:"effective_time"` // Ledger transaction effective time
}

type Token struct {
	// Identity — canonical composite key.
	InstrumentAdmin string `json:"instrument_admin"` // instrumentId.admin — token admin/issuer party (ERC-20: deployer)
	InstrumentID    string `json:"instrument_id"`    // instrumentId.id   — token symbol/identifier (ERC-20: symbol, e.g. "DEMO")

	// Roles.
	Issuer string `json:"issuer"` // issuer party on the TokenTransferEvent contract (ERC-20: minter role)

	// Supply (ERC-20: totalSupply()).
	// Running total, always ≥ 0. Incremented by each MINT amount, decremented by each BURN amount.
	// Updated atomically with every mint/burn via Store.ApplySupplyDelta.
	TotalSupply string `json:"total_supply"` // decimal string, e.g. "1000000.000000000000000000"

	// Holders (ERC-20: no standard equivalent, but a standard block-explorer metric).
	// Count of distinct parties currently holding a non-zero balance.
	// The store increments this when a balance first becomes positive, decrements when it returns to zero.
	HolderCount int64 `json:"holder_count"`

	// Provenance.
	FirstSeenOffset int64     `json:"first_seen_offset"` // ledger offset when this token was first indexed
	FirstSeenAt     time.Time `json:"first_seen_at"`     // ledger effective time when this token was first indexed
}

type Transfer struct {
	ContractID      string     `json:"contract_id"`
	Kind            string     `json:"kind"`   // "direct" | "offer"
	Status          string     `json:"status"` // "pending" | "expired" | "completed" | "canceled"
	FromPartyID     string     `json:"from_party_id"`
	ToPartyID       string     `json:"to_party_id"`
	InstrumentAdmin string     `json:"instrument_admin"`
	InstrumentID    string     `json:"instrument_id"`
	Amount          string     `json:"amount"`
	ExpiresAt       *time.Time `json:"expires_at,omitempty"` // offer executeBefore; nil for direct
	TxID            string     `json:"tx_id,omitempty"`      // ledger update id
	LedgerOffset    int64      `json:"ledger_offset"`
	CreatedAt       time.Time  `json:"created_at"`

	// Archived is a decode-time signal only — not persisted. Set by the offer
	// decoder on an ARCHIVED event so the processor finalizes the transfer with
	// the terminal Status the decoder derived from the archiving choice.
	Archived bool `json:"-"`
}

type TransferQuery struct {
	Role   TransferRole
	Status string // "" = all; pending / expired / completed / canceled / rejected
}

type TransferRole string