Documentation
¶
Overview ¶
Package account is the business-logic layer for Stellar accounts. An account ties a Stellar public key to a user, along with a derivation index and a lifecycle status. Service wraps the account repository and adds the rules the repository does not enforce: input validation, uniqueness, and status transitions.
Build a Service with NewService, passing the account and user repositories. It exposes creation, lookups (by ID, public key, or user), the next derivation index, soft delete/restore, and status updates. Requests and responses are the DTOs in dto.go; failures are the sentinel errors in errors.go, which handlers map onto HTTP status codes.
Status lifecycle ¶
An account moves through active, suspended, frozen, blocked, and closed. Not every move is legal: UpdateStatus consults a transition table and rejects an illegal change with ErrInvalidStatusTransition. closed is terminal — nothing transitions out of it — and a soft-deleted account cannot be modified at all.
Transactions ¶
Each mutating call has a WithTx variant that runs inside a *gorm.DB the caller owns, so an account can be created in the same database transaction as the user it belongs to. Because that user may not yet be visible to queries outside the transaction, CreateWithTx skips the user-existence check and relies on the foreign key for referential integrity. The derivation index can likewise be passed in when the caller has already reserved one inside the transaction.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // Resource not found errors ErrAccountNotFound = errors.New("account not found") // Conflict errors ErrPublicKeyAlreadyExists = errors.New("public key already registered") ErrAccountAlreadyDeleted = errors.New("account is already deleted") // Business logic errors ErrCannotModifyDeletedAccount = errors.New("cannot modify deleted account") ErrInvalidStatusTransition = errors.New("invalid status transition") ErrCannotDeleteLastAccount = errors.New("cannot delete the last active account") // Validation errors ErrInvalidInput = errors.New("invalid input") ErrInvalidPublicKey = errors.New("invalid public key format") ErrInvalidStatus = errors.New("invalid account status") ErrInvalidAccountIndex = errors.New("invalid account index") )
Account service specific errors
Functions ¶
This section is empty.
Types ¶
type AccountResponse ¶
type AccountResponse struct {
ID string `json:"id"`
UserID string `json:"user_id"`
PublicKey string `json:"public_key"`
AccountIndex int `json:"account_index"`
Status string `json:"status"`
ChainStatus string `json:"chain_status"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
AccountResponse represents the response containing account information
type CreateAccountRequest ¶
type CreateAccountRequest struct {
UserID string `json:"user_id" validate:"required"`
PublicKey string `json:"public_key" validate:"required"`
AccountIndex *int `json:"account_index,omitempty"` // Optional: if provided, use this index instead of auto-generating
}
CreateAccountRequest represents the request to create a new Stellar account
type Service ¶
type Service interface {
// Account management
Create(ctx context.Context, req CreateAccountRequest) (*AccountResponse, error)
CreateWithTx(ctx context.Context, tx *gorm.DB, req CreateAccountRequest) (*AccountResponse, error)
GetByID(ctx context.Context, id string) (*AccountResponse, error)
GetByPublicKey(ctx context.Context, publicKey string) (*AccountResponse, error)
GetByUserID(ctx context.Context, userID string) (*AccountResponse, error)
GetNextAccountIndex(ctx context.Context, userID string) (int, error)
GetNextAccountIndexWithTx(ctx context.Context, tx *gorm.DB) (int, error)
Delete(ctx context.Context, id string) error
Restore(ctx context.Context, id string) error
// Status management
UpdateStatus(ctx context.Context, id string, req UpdateAccountStatusRequest) (*AccountResponse, error)
// UpdateChainStatus records the account's on-chain lifecycle state.
UpdateChainStatus(ctx context.Context, id string, chainStatus string) error
}
Service defines the interface for account business logic operations
func NewService ¶
func NewService(repo repository.AccountRepository, userRepo repository.UserRepository) Service
NewService creates a new account service instance
type UpdateAccountStatusRequest ¶
type UpdateAccountStatusRequest struct {
Status string `json:"status" validate:"required,oneof=active suspended frozen closed"`
}
UpdateAccountStatusRequest represents the request to update account status
Source Files