supabase

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 28, 2026 License: MIT Imports: 6 Imported by: 0

README

AccountPool Supabase Repository

Persistence layer for infrastructure/accountpool.

This package owns all Supabase/PostgREST reads/writes for pool accounts and their per-token balances.

Tables

  • pool_accounts: account metadata (address, lock state, rotation flags)
  • pool_account_balances: per-token balances for each account

Repository Interface

See repository.go for the authoritative interface. Key categories:

  • Account CRUD: Create, Update, GetByID, List, ListAvailable, ListByLocker, Delete
  • Balance-aware reads: GetWithBalances, ListWithBalances, ListAvailableWithBalances, ListByLockerWithBalances
  • Balance ops: UpsertBalance, GetBalance, GetBalances, DeleteBalances
  • Stats: AggregateTokenStats

Usage

import accountpoolsupabase "github.com/R3E-Network/service_layer/infrastructure/accountpool/supabase"

repo := accountpoolsupabase.NewRepository(baseRepo)

accounts, err := repo.ListAvailableWithBalances(ctx, "GAS", nil, 10)
_ = accounts
_ = err

Documentation

Overview

Package supabase provides NeoAccounts-specific database operations.

Package supabase provides NeoAccounts-specific database operations.

Index

Constants

View Source
const (
	TokenTypeNEO = neoaccountstypes.TokenTypeNEO
	TokenTypeGAS = neoaccountstypes.TokenTypeGAS

	// Neo N3 MainNet script hashes
	NEOScriptHash = "0xef4073a0f2b305a38ec4050e4d3d28bc40ea63f5"
	GASScriptHash = "0xd2a4cff31913016155e38e474a2c06d08be276cf"

	// Decimals
	NEODecimals = 0
	GASDecimals = 8
)

Well-known token configurations

Variables

This section is empty.

Functions

func GetDefaultTokenConfig

func GetDefaultTokenConfig(tokenType string) (scriptHash string, decimals int)

GetDefaultTokenConfig returns the script hash and decimals for well-known tokens.

Types

type Account

type Account struct {
	ID           string    `json:"id"`
	Address      string    `json:"address"`
	PublicKey    string    `json:"public_key,omitempty"`
	EncryptedWIF string    `json:"encrypted_wif,omitempty"`
	KeyVersion   int       `json:"key_version,omitempty"`
	GenBatch     string    `json:"generation_batch,omitempty"`
	CreatedAt    time.Time `json:"created_at"`
	LastUsedAt   time.Time `json:"last_used_at"`
	TxCount      int64     `json:"tx_count"`
	IsRetiring   bool      `json:"is_retiring"`
	LockedBy     string    `json:"locked_by,omitempty"`
	LockedAt     time.Time `json:"locked_at,omitempty"`
}

Account represents an account pool account with locking support. Balance is now tracked per-token in the AccountBalance table.

type AccountBalance

type AccountBalance struct {
	AccountID  string    `json:"account_id"`
	TokenType  string    `json:"token_type"`  // "NEO", "GAS", or custom NEP-17
	ScriptHash string    `json:"script_hash"` // NEP-17 contract address (script hash)
	Amount     int64     `json:"amount"`
	Decimals   int       `json:"decimals"`
	UpdatedAt  time.Time `json:"updated_at"`
}

AccountBalance represents a per-token balance for an account. Stored in pool_account_balances table.

type AccountWithBalances

type AccountWithBalances struct {
	Account
	Balances map[string]TokenBalance `json:"balances"` // key: token_type
}

AccountWithBalances combines account metadata with all token balances.

func NewAccountWithBalances

func NewAccountWithBalances(acc *Account) *AccountWithBalances

NewAccountWithBalances creates an AccountWithBalances from an Account.

func (*AccountWithBalances) AddBalance

func (a *AccountWithBalances) AddBalance(bal *AccountBalance)

AddBalance adds a token balance to the account.

func (*AccountWithBalances) GetBalance

func (a *AccountWithBalances) GetBalance(tokenType string) int64

GetBalance returns the balance for a specific token type. Returns 0 if the token type is not found.

func (*AccountWithBalances) HasSufficientBalance

func (a *AccountWithBalances) HasSufficientBalance(tokenType string, minAmount int64) bool

HasSufficientBalance checks if account has at least minAmount of the specified token.

func (*AccountWithBalances) IsEmpty

func (a *AccountWithBalances) IsEmpty() bool

IsEmpty returns true if all token balances are zero.

type Repository

type Repository struct {
	// contains filtered or unexported fields
}

Repository provides NeoAccounts-specific data access methods.

func NewRepository

func NewRepository(base *database.Repository) *Repository

NewRepository creates a new NeoAccounts repository.

func (*Repository) AggregateTokenStats

func (r *Repository) AggregateTokenStats(ctx context.Context, tokenType string) (*TokenStats, error)

AggregateTokenStats calculates aggregate statistics for a token type. Uses batch query to avoid N+1 problem.

func (*Repository) Create

func (r *Repository) Create(ctx context.Context, acc *Account) error

Create inserts a new pool account.

func (*Repository) Delete

func (r *Repository) Delete(ctx context.Context, id string) error

Delete deletes a pool account by ID.

func (*Repository) DeleteBalances

func (r *Repository) DeleteBalances(ctx context.Context, accountID string) error

DeleteBalances deletes all token balances for an account.

func (*Repository) GetBalance

func (r *Repository) GetBalance(ctx context.Context, accountID, tokenType string) (*AccountBalance, error)

GetBalance fetches a specific token balance for an account.

func (*Repository) GetBalances

func (r *Repository) GetBalances(ctx context.Context, accountID string) ([]AccountBalance, error)

GetBalances fetches all token balances for an account.

func (*Repository) GetBalancesForAccounts

func (r *Repository) GetBalancesForAccounts(ctx context.Context, accountIDs []string) ([]AccountBalance, error)

GetBalancesForAccounts fetches all token balances for multiple accounts in a single query. This avoids the N+1 query problem when hydrating accounts with balances.

func (*Repository) GetByAddress

func (r *Repository) GetByAddress(ctx context.Context, address string) (*Account, error)

GetByAddress fetches a pool account by address.

func (*Repository) GetByID

func (r *Repository) GetByID(ctx context.Context, id string) (*Account, error)

GetByID fetches a pool account by ID.

func (*Repository) GetWithBalances

func (r *Repository) GetWithBalances(ctx context.Context, id string) (*AccountWithBalances, error)

GetWithBalances fetches an account with all its token balances.

func (*Repository) List

func (r *Repository) List(ctx context.Context) ([]Account, error)

List returns all pool accounts.

func (*Repository) ListAvailable

func (r *Repository) ListAvailable(ctx context.Context, limit int) ([]Account, error)

ListAvailable returns unlocked, non-retiring accounts up to limit.

func (*Repository) ListAvailableWithBalances

func (r *Repository) ListAvailableWithBalances(ctx context.Context, tokenType string, minBalance *int64, limit int) ([]AccountWithBalances, error)

ListAvailableWithBalances returns unlocked, non-retiring accounts with balances. If tokenType is specified, filters by minimum balance of that token.

func (*Repository) ListByLocker

func (r *Repository) ListByLocker(ctx context.Context, lockerID string) ([]Account, error)

ListByLocker returns accounts locked by a specific service.

func (*Repository) ListByLockerWithBalances

func (r *Repository) ListByLockerWithBalances(ctx context.Context, lockerID string) ([]AccountWithBalances, error)

ListByLockerWithBalances returns accounts locked by a service with their balances.

func (*Repository) ListLowBalanceAccounts

func (r *Repository) ListLowBalanceAccounts(ctx context.Context, tokenType string, maxBalance int64, limit int) ([]AccountWithBalances, error)

ListLowBalanceAccounts returns accounts with balance below the specified threshold. This is useful for auto top-up workers that need to find accounts requiring funding.

func (*Repository) ListWithBalances

func (r *Repository) ListWithBalances(ctx context.Context) ([]AccountWithBalances, error)

ListWithBalances returns all accounts with their token balances.

func (*Repository) TryLockAccount

func (r *Repository) TryLockAccount(ctx context.Context, accountID, serviceID string, lockedAt time.Time) (bool, error)

TryLockAccount attempts to lock an account if it is currently unlocked and active. Returns true when the account was locked by this call.

func (*Repository) TryReleaseAccount

func (r *Repository) TryReleaseAccount(ctx context.Context, accountID, serviceID string) (bool, error)

TryReleaseAccount atomically releases an account lock if locked by the given service. Returns true if the account was released, false if not locked by this service.

func (*Repository) Update

func (r *Repository) Update(ctx context.Context, acc *Account) error

Update updates a pool account by ID.

func (*Repository) UpdateBalanceWithLock

func (r *Repository) UpdateBalanceWithLock(ctx context.Context, accountID, serviceID, tokenType string, delta int64, absolute *int64) (int64, int64, int, bool, error)

UpdateBalanceWithLock atomically updates balance while verifying lock ownership. This method prevents race conditions by verifying the lock in the same query that updates the balance. Returns (oldBalance, newBalance, txCount, wasUpdated, error) wasUpdated is false if account is not locked by the given service

func (*Repository) UpsertBalance

func (r *Repository) UpsertBalance(ctx context.Context, accountID, tokenType, scriptHash string, amount int64, decimals int) error

UpsertBalance creates or updates a token balance for an account.

type RepositoryInterface

type RepositoryInterface interface {
	// Account CRUD operations
	Create(ctx context.Context, acc *Account) error
	Update(ctx context.Context, acc *Account) error
	GetByID(ctx context.Context, id string) (*Account, error)
	GetByAddress(ctx context.Context, address string) (*Account, error)
	List(ctx context.Context) ([]Account, error)
	ListAvailable(ctx context.Context, limit int) ([]Account, error)
	ListByLocker(ctx context.Context, lockerID string) ([]Account, error)
	TryLockAccount(ctx context.Context, accountID, serviceID string, lockedAt time.Time) (bool, error)
	TryReleaseAccount(ctx context.Context, accountID, serviceID string) (bool, error)
	Delete(ctx context.Context, id string) error

	// Balance-aware account operations
	GetWithBalances(ctx context.Context, id string) (*AccountWithBalances, error)
	ListWithBalances(ctx context.Context) ([]AccountWithBalances, error)
	ListAvailableWithBalances(ctx context.Context, tokenType string, minBalance *int64, limit int) ([]AccountWithBalances, error)
	ListByLockerWithBalances(ctx context.Context, lockerID string) ([]AccountWithBalances, error)
	ListLowBalanceAccounts(ctx context.Context, tokenType string, maxBalance int64, limit int) ([]AccountWithBalances, error)

	// Balance operations
	UpsertBalance(ctx context.Context, accountID, tokenType, scriptHash string, amount int64, decimals int) error
	GetBalance(ctx context.Context, accountID, tokenType string) (*AccountBalance, error)
	GetBalances(ctx context.Context, accountID string) ([]AccountBalance, error)
	GetBalancesForAccounts(ctx context.Context, accountIDs []string) ([]AccountBalance, error)
	DeleteBalances(ctx context.Context, accountID string) error
	// UpdateBalanceWithLock atomically updates balance while verifying lock ownership
	// Returns (oldBalance, newBalance, txCount, wasUpdated, error)
	// wasUpdated is false if account is not locked by the given service
	UpdateBalanceWithLock(ctx context.Context, accountID, serviceID, tokenType string, delta int64, absolute *int64) (int64, int64, int, bool, error)

	// Statistics
	AggregateTokenStats(ctx context.Context, tokenType string) (*TokenStats, error)
}

RepositoryInterface defines NeoAccounts-specific data access methods. This interface allows for easy mocking in tests.

type TokenBalance

type TokenBalance = neoaccountstypes.TokenBalance

TokenBalance is the API representation of a token balance.

type TokenStats

type TokenStats = neoaccountstypes.TokenStats

TokenStats represents aggregated statistics for a token type.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL