indexer

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: 15 Imported by: 0

Documentation

Overview

Package indexer provides Neo N3 blockchain transaction indexing with VM execution tracing. IMPORTANT: This module uses ISOLATED Supabase credentials (INDEXER_ prefix) to prevent credential mixing with the main MiniApp platform.

Index

Constants

View Source
const (
	RoleSender      = "sender"
	RoleSigner      = "signer"
	RoleParticipant = "participant"
)

AddressRole constants for address-transaction relationships.

Variables

This section is empty.

Functions

func IsComplexTransaction

func IsComplexTransaction(scriptHex string) bool

IsComplexTransaction determines if a transaction involves contract invocations. Simple NEP-17 transfers only use System.Runtime.Notify, while complex transactions use System.Contract.Call to invoke other contracts.

Types

type AddressTx

type AddressTx struct {
	ID        int64     `json:"id" db:"id"`
	Address   string    `json:"address" db:"address"`
	TxHash    string    `json:"tx_hash" db:"tx_hash"`
	Role      string    `json:"role" db:"role"` // sender, signer, participant
	Network   Network   `json:"network" db:"network"`
	BlockTime time.Time `json:"block_time" db:"block_time"`
}

AddressTx links addresses to transactions for efficient querying.

type Config

type Config struct {
	// Supabase configuration (ISOLATED - uses INDEXER_ prefix)
	SupabaseURL        string
	SupabaseServiceKey string

	// PostgreSQL direct connection (ISOLATED)
	PostgresHost     string
	PostgresPort     int
	PostgresDB       string
	PostgresUser     string
	PostgresPassword string
	PostgresSSLMode  string

	// Neo RPC endpoints
	MainnetRPCURL string
	TestnetRPCURL string

	// EVM RPC endpoints
	NeoXMainnetRPCURL string
	NeoXTestnetRPCURL string
	EthereumRPCURL    string
	SepoliaRPCURL     string
	PolygonRPCURL     string
	AmoyRPCURL        string

	// Indexer settings
	Networks   []Network // Support multiple networks
	StartBlock uint64
	BatchSize  int
	Workers    int

	// Sync settings
	SyncInterval   time.Duration
	RetryInterval  time.Duration
	MaxRetries     int
	RequestTimeout time.Duration
}

Config holds the indexer configuration with isolated credentials.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a Config with default values.

func LoadFromEnv

func LoadFromEnv() (*Config, error)

LoadFromEnv loads configuration from environment variables. All variables use INDEXER_ prefix to isolate from main platform.

func (*Config) GetPostgresDSN

func (c *Config) GetPostgresDSN() string

GetPostgresDSN returns the PostgreSQL connection string.

func (*Config) GetRPCURL

func (c *Config) GetRPCURL(network Network) string

GetRPCURL returns the RPC URL for the specified network.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks if the configuration is valid.

type ContractCall

type ContractCall struct {
	ID              int64           `json:"id" db:"id"`
	TxHash          string          `json:"tx_hash" db:"tx_hash"`
	CallIndex       int             `json:"call_index" db:"call_index"`
	ContractAddress string          `json:"contract_address" db:"contract_address"`
	Method          string          `json:"method" db:"method"`
	ArgsJSON        json.RawMessage `json:"args" db:"args_json"`
	GasConsumed     string          `json:"gas_consumed" db:"gas_consumed"`
	Success         bool            `json:"success" db:"success"`
	ParentCallID    *int64          `json:"parent_call_id,omitempty" db:"parent_call_id"`
}

ContractCall represents a contract invocation within a transaction.

type Network

type Network string

Network represents the blockchain network type.

const (
	NetworkMainnet     Network = "mainnet"
	NetworkTestnet     Network = "testnet"
	NetworkNeoXMainnet Network = "neox-mainnet"
	NetworkNeoXTestnet Network = "neox-testnet"
	NetworkEthereum    Network = "ethereum"
	NetworkSepolia     Network = "sepolia"
	NetworkPolygon     Network = "polygon"
	NetworkPolygonAmoy Network = "polygon-amoy"
)

type Notification

type Notification struct {
	ID              int64           `json:"id" db:"id"`
	TxHash          string          `json:"tx_hash" db:"tx_hash"`
	NotifyIndex     int             `json:"notify_index" db:"notify_index"`
	ContractAddress string          `json:"contract_address" db:"contract_address"`
	EventName       string          `json:"event_name" db:"event_name"`
	StateJSON       json.RawMessage `json:"state" db:"state_json"`
}

Notification represents a contract event notification.

type OpcodeTrace

type OpcodeTrace struct {
	ID              int64  `json:"id" db:"id"`
	TxHash          string `json:"tx_hash" db:"tx_hash"`
	StepIndex       int    `json:"step_index" db:"step_index"`
	Opcode          string `json:"opcode" db:"opcode"`
	OpcodeHex       string `json:"opcode_hex" db:"opcode_hex"`
	GasConsumed     string `json:"gas_consumed" db:"gas_consumed"`
	StackSize       int    `json:"stack_size" db:"stack_size"`
	ContractAddress string `json:"contract_address,omitempty" db:"contract_address"`
	InstructionPtr  int    `json:"instruction_ptr" db:"instruction_ptr"`
}

OpcodeTrace represents a single VM opcode execution step.

type Service

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

Service is the main indexer service orchestrator.

func NewService

func NewService(cfg *Config) (*Service, error)

NewService creates a new indexer service.

func (*Service) GetStorage

func (s *Service) GetStorage() *Storage

GetStorage returns the storage instance.

func (*Service) GetTracer

func (s *Service) GetTracer() *Tracer

GetTracer returns the tracer instance.

func (*Service) Start

func (s *Service) Start(ctx context.Context) error

Start starts the indexer service.

func (*Service) Stop

func (s *Service) Stop() error

Stop stops the indexer service.

type Signer

type Signer struct {
	Account          string   `json:"account"`
	Scopes           string   `json:"scopes"`
	AllowedContracts []string `json:"allowed_contracts,omitempty"`
	AllowedGroups    []string `json:"allowed_groups,omitempty"`
}

Signer represents a transaction signer.

type Storage

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

Storage provides database operations for the indexer. Uses ISOLATED Supabase credentials (INDEXER_ prefix).

func NewStorage

func NewStorage(cfg *Config) (*Storage, error)

NewStorage creates a new storage instance with isolated credentials.

func (*Storage) Close

func (s *Storage) Close() error

Close closes the database connection.

func (*Storage) GetContractCalls

func (s *Storage) GetContractCalls(ctx context.Context, txHash string) ([]*ContractCall, error)

GetContractCalls retrieves contract calls for a transaction.

func (*Storage) GetOpcodeTraces

func (s *Storage) GetOpcodeTraces(ctx context.Context, txHash string) ([]*OpcodeTrace, error)

GetOpcodeTraces retrieves opcode traces for a transaction.

func (*Storage) GetSyncState

func (s *Storage) GetSyncState(ctx context.Context, network Network) (*SyncState, error)

GetSyncState retrieves the sync state for a network.

func (*Storage) GetSyscalls

func (s *Storage) GetSyscalls(ctx context.Context, txHash string) ([]*Syscall, error)

GetSyscalls retrieves syscalls for a transaction.

func (*Storage) GetTransaction

func (s *Storage) GetTransaction(ctx context.Context, hash string) (*Transaction, error)

GetTransaction retrieves a transaction by hash.

func (*Storage) GetTransactionsByAddress

func (s *Storage) GetTransactionsByAddress(ctx context.Context, address string, limit, offset int) ([]*Transaction, error)

GetTransactionsByAddress retrieves transactions for an address.

func (*Storage) SaveAddressTxs

func (s *Storage) SaveAddressTxs(ctx context.Context, addrTxs []*AddressTx) error

SaveAddressTxs batch inserts address-transaction relationships.

func (*Storage) SaveContractCalls

func (s *Storage) SaveContractCalls(ctx context.Context, calls []*ContractCall) error

SaveContractCalls batch inserts contract calls for a transaction.

func (*Storage) SaveOpcodeTraces

func (s *Storage) SaveOpcodeTraces(ctx context.Context, traces []*OpcodeTrace) error

SaveOpcodeTraces batch inserts opcode traces for a transaction.

func (*Storage) SaveSyscalls

func (s *Storage) SaveSyscalls(ctx context.Context, syscalls []*Syscall) error

SaveSyscalls batch inserts syscalls for a transaction.

func (*Storage) SaveTransaction

func (s *Storage) SaveTransaction(ctx context.Context, tx *Transaction) error

SaveTransaction inserts or updates a transaction.

func (*Storage) UpdateSyncState

func (s *Storage) UpdateSyncState(ctx context.Context, state *SyncState) error

UpdateSyncState updates the sync state for a network.

type SyncState

type SyncState struct {
	ID             int64     `json:"id" db:"id"`
	Network        Network   `json:"network" db:"network"`
	LastBlockIndex uint64    `json:"last_block_index" db:"last_block_index"`
	LastBlockTime  time.Time `json:"last_block_time" db:"last_block_time"`
	TotalTxIndexed int64     `json:"total_tx_indexed" db:"total_tx_indexed"`
	LastSyncAt     time.Time `json:"last_sync_at" db:"last_sync_at"`
	UpdatedAt      time.Time `json:"updated_at" db:"updated_at"`
}

SyncState tracks the indexer's synchronization progress.

type Syncer

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

Syncer synchronizes transactions from Neo N3 nodes.

func NewSyncer

func NewSyncer(cfg *Config, storage *Storage) (*Syncer, error)

NewSyncer creates a new transaction syncer for all configured networks.

func (*Syncer) Start

func (s *Syncer) Start(ctx context.Context) error

Start begins the synchronization loop.

func (*Syncer) Stop

func (s *Syncer) Stop()

Stop stops the synchronization loop.

type Syscall

type Syscall struct {
	ID              int64           `json:"id" db:"id"`
	TxHash          string          `json:"tx_hash" db:"tx_hash"`
	CallIndex       int             `json:"call_index" db:"call_index"`
	SyscallName     string          `json:"syscall_name" db:"syscall_name"`
	ArgsJSON        json.RawMessage `json:"args" db:"args_json"`
	ResultJSON      json.RawMessage `json:"result" db:"result_json"`
	GasConsumed     string          `json:"gas_consumed" db:"gas_consumed"`
	ContractAddress string          `json:"contract_address,omitempty" db:"contract_address"`
}

Syscall represents a system call made during transaction execution.

type Tracer

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

Tracer extracts VM execution traces from transactions.

func NewTracer

func NewTracer(storage *Storage) *Tracer

NewTracer creates a new VM tracer.

func (*Tracer) ExtractContractCalls

func (t *Tracer) ExtractContractCalls(txHash string, notifications []Notification) []*ContractCall

ExtractContractCalls extracts contract calls from notifications.

func (*Tracer) ParseScript

func (t *Tracer) ParseScript(txHash string, scriptHex string) ([]*OpcodeTrace, error)

ParseScript parses a transaction script into opcode traces.

func (*Tracer) SaveContractCalls

func (t *Tracer) SaveContractCalls(ctx context.Context, calls []*ContractCall) error

SaveContractCalls saves contract calls to storage.

func (*Tracer) SaveTraces

func (t *Tracer) SaveTraces(ctx context.Context, traces []*OpcodeTrace) error

SaveTraces saves opcode traces to storage.

type Transaction

type Transaction struct {
	Hash            string          `json:"hash" db:"hash"`
	Network         Network         `json:"network" db:"network"`
	BlockIndex      uint64          `json:"block_index" db:"block_index"`
	BlockTime       time.Time       `json:"block_time" db:"block_time"`
	Size            int             `json:"size" db:"size"`
	Version         int             `json:"version" db:"version"`
	Nonce           uint32          `json:"nonce" db:"nonce"`
	Sender          string          `json:"sender" db:"sender"`
	SystemFee       string          `json:"system_fee" db:"system_fee"`
	NetworkFee      string          `json:"network_fee" db:"network_fee"`
	ValidUntilBlock uint64          `json:"valid_until_block" db:"valid_until_block"`
	Script          string          `json:"script" db:"script"`
	VMState         string          `json:"vm_state" db:"vm_state"`
	GasConsumed     string          `json:"gas_consumed" db:"gas_consumed"`
	Exception       string          `json:"exception,omitempty" db:"exception"`
	TxType          TxType          `json:"tx_type" db:"tx_type"`
	SignersJSON     json.RawMessage `json:"signers" db:"signers_json"`
	CreatedAt       time.Time       `json:"created_at" db:"created_at"`
}

Transaction represents an indexed Neo N3 transaction.

type TxType

type TxType string

TxType represents the complexity type of a transaction.

const (
	TxTypeSimple  TxType = "simple"  // Simple NEP-17 transfers
	TxTypeComplex TxType = "complex" // Contract invocations
)

Jump to

Keyboard shortcuts

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