balance

type Delta struct {
	TokenAccount string
	Kind         DeltaKind

	// Quarks is the amount credited, debited or drained. Ignored for
	// DeltaClose, and must be zero for DeltaAdjustUsdCostBasis.
	Quarks uint64

	// UsdCostBasis is added on credit and subtracted on debit. It is signed
	// so that a credit can also carry a downward reconciliation. Ignored for
	// DeltaDrain and DeltaClose, where the basis is zeroed along with the
	// balance. For DeltaAdjustUsdCostBasis it is the signed correction, added
	// as is.
	UsdCostBasis int64
}

type DeltaKind uint8

type ExternalCheckpointRecord struct {
	Id uint64

	TokenAccount   string
	Quarks         uint64
	SlotCheckpoint uint64

	LastUpdatedAt time.Time
}

type Record struct {
	Id uint64

	TokenAccount string
	OwnerAccount string
	MintAccount  string

	Quarks uint64

	// UsdCostBasis is the account's USD cost basis, in UsdQuarksPerUnit.
	// A cost basis may legitimately be negative.
	UsdCostBasis int64

	IsOpen bool

	// IsLocked indicates the timelock vault is still locked, so the account
	// is managed by OCP and every balance change flows through the ledger.
	// Once a vault unlocks, funds can move on chain without an intent, so the
	// record's values must not be trusted or aggregated: nothing may leave
	// the account through the ledger, while credits keep being recorded
	// against a balance that no longer reflects the chain. Unlocking is
	// one-way.
	IsLocked bool

	UpdatedAt time.Time
}

type Store interface {
	// Create creates a new balance record.
	//
	// ErrRecordExists is returned if the token account already has a record.
	Create(ctx context.Context, record *Record) error

	// Get gets the balance record for a token account.
	//
	// ErrRecordNotFound is returned if no record exists.
	Get(ctx context.Context, tokenAccount string) (*Record, error)

	// GetBatch gets balance records for a set of token accounts. Accounts
	// without a record are omitted from the result.
	GetBatch(ctx context.Context, tokenAccounts ...string) (map[string]*Record, error)

	// GetAllByOwner gets all balance records for an owner.
	//
	// ErrRecordNotFound is returned if no records exist.
	GetAllByOwner(ctx context.Context, owner string) ([]*Record, error)

	// GetAllByOwnerAndMint gets all balance records for an owner and mint.
	//
	// ErrRecordNotFound is returned if no records exist.
	GetAllByOwnerAndMint(ctx context.Context, owner, mint string) ([]*Record, error)

	// GetAllLockedByMint gets locked balance records for a mint with at
	// least minQuarks, paged by record ID. Unlocked records are excluded,
	// since funds can move on chain without an intent once a vault unlocks,
	// making their balances stale.
	//
	// ErrRecordNotFound is returned if no records exist.
	GetAllLockedByMint(ctx context.Context, mint string, minQuarks uint64, cursor query.Cursor, limit uint64, direction query.Ordering) ([]*Record, error)

	// CountLockedByMint counts locked records for a mint with at least
	// minQuarks. Unlocked records are excluded, since their balances are
	// stale.
	CountLockedByMint(ctx context.Context, mint string, minQuarks uint64) (uint64, error)

	// ApplyDeltas atomically applies a set of deltas. Either every delta is
	// applied or none are. Deltas are applied in SortDeltas order.
	//
	// Every delta must target an account with a record, otherwise
	// ErrRecordNotFound is returned and nothing is applied. Callers are
	// responsible for not producing deltas for accounts the ledger doesn't
	// track, like external wallets.
	//
	// ErrInsufficientBalance is returned when a debit exceeds the balance.
	// ErrBalanceChanged is returned when a drain or close doesn't match the
	// balance. ErrAccountClosed is returned when a credit, debit, drain or
	// close targets a closed account, which is frozen. ErrAccountUnlocked is
	// returned when a delta other than a credit targets an unlocked account,
	// whose record is no longer maintained. DeltaAdjustUsdCostBasis carries
	// no predicate: it moves no quarks, so it applies to closed and unlocked
	// accounts alike and only fails when the record is missing.
	ApplyDeltas(ctx context.Context, deltas ...*Delta) error

	// MarkAsUnlocked marks an account's timelock vault as unlocked, which is
	// one-way and idempotent. It is called in the same transaction that
	// commits the timelock record's transition out of the locked state, so
	// the flag cannot disagree with the timelock record it mirrors.
	//
	// ErrRecordNotFound is returned if no record exists.
	MarkAsUnlocked(ctx context.Context, tokenAccount string) error

	// SaveExternalCheckpoint saves an external balance at a checkpoint.
	//
	// ErrStaleCheckpoint is returned if the checkpoint is outdated
	SaveExternalCheckpoint(ctx context.Context, record *ExternalCheckpointRecord) error

	// GetExternalCheckpoint gets an exeternal balance checkpoint for a
	// given account.
	//
	// ErrCheckpointNotFound is returend if no DB record exists.
	GetExternalCheckpoint(ctx context.Context, account string) (*ExternalCheckpointRecord, error)
}