Documentation
¶
Overview ¶
Package supabase provides NeoAccounts-specific database operations.
Package supabase provides NeoAccounts-specific database operations.
Index ¶
- Constants
- func GetDefaultTokenConfig(tokenType string) (scriptHash string, decimals int)
- type Account
- type AccountBalance
- type AccountWithBalances
- type Repository
- func (r *Repository) AggregateTokenStats(ctx context.Context, tokenType string) (*TokenStats, error)
- func (r *Repository) Create(ctx context.Context, acc *Account) error
- func (r *Repository) Delete(ctx context.Context, id string) error
- func (r *Repository) DeleteBalances(ctx context.Context, accountID string) error
- func (r *Repository) GetBalance(ctx context.Context, accountID, tokenType string) (*AccountBalance, error)
- func (r *Repository) GetBalances(ctx context.Context, accountID string) ([]AccountBalance, error)
- func (r *Repository) GetBalancesForAccounts(ctx context.Context, accountIDs []string) ([]AccountBalance, error)
- func (r *Repository) GetByAddress(ctx context.Context, address string) (*Account, error)
- func (r *Repository) GetByID(ctx context.Context, id string) (*Account, error)
- func (r *Repository) GetWithBalances(ctx context.Context, id string) (*AccountWithBalances, error)
- func (r *Repository) List(ctx context.Context) ([]Account, error)
- func (r *Repository) ListAvailable(ctx context.Context, limit int) ([]Account, error)
- func (r *Repository) ListAvailableWithBalances(ctx context.Context, tokenType string, minBalance *int64, limit int) ([]AccountWithBalances, error)
- func (r *Repository) ListByLocker(ctx context.Context, lockerID string) ([]Account, error)
- func (r *Repository) ListByLockerWithBalances(ctx context.Context, lockerID string) ([]AccountWithBalances, error)
- func (r *Repository) ListLowBalanceAccounts(ctx context.Context, tokenType string, maxBalance int64, limit int) ([]AccountWithBalances, error)
- func (r *Repository) ListWithBalances(ctx context.Context) ([]AccountWithBalances, error)
- func (r *Repository) TryLockAccount(ctx context.Context, accountID, serviceID string, lockedAt time.Time) (bool, error)
- func (r *Repository) TryReleaseAccount(ctx context.Context, accountID, serviceID string) (bool, error)
- func (r *Repository) Update(ctx context.Context, acc *Account) error
- func (r *Repository) UpdateBalanceWithLock(ctx context.Context, accountID, serviceID, tokenType string, delta int64, ...) (int64, int64, int, bool, error)
- func (r *Repository) UpsertBalance(ctx context.Context, accountID, tokenType, scriptHash string, amount int64, ...) error
- type RepositoryInterface
- type TokenBalance
- type TokenStats
Constants ¶
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 ¶
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 ¶
GetByAddress fetches a pool account by address.
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 ¶
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 ¶
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.