sync

Documentation

Overview

Package sync bridges on-chain activity into plain-text accounting: it transforms chain transactions (native, token, and internal sub-transfers plus gas) into balanced accounting model entries, and persists a per-(wallet, network) watermark so repeated syncs resume where they left off and dedup by transaction hash.

Index

• func SaveSyncState(dir string, s SyncState) error
• func TransformToEntry(in SyncTransformInput) (*model.Entry, error)
• type BQInternalTx
• type BQKeyValue
• type BQRow
• type BQTokenTxn
• type SyncState
  • func LoadSyncState(dir, walletId, network string) (SyncState, bool, error)
• type SyncTransformInput

Functions

func SaveSyncState

func SaveSyncState(dir string, s SyncState) error

SaveSyncState writes the watermark file atomically (write-to-temp + rename).

func TransformToEntry

func TransformToEntry(in SyncTransformInput) (*model.Entry, error)

TransformToEntry turns one aggregated transaction (with its sub-rows) into a model.Entry. The wallet's address drives leg classification: legs where the wallet is from→outbound, to→inbound, fee address→fee. Each token/internal leg becomes its own posting; the counter-side rolls up into a single placeholder Unknown account so the entry balances.

Returns (nil, nil) when the transaction does not actually touch the wallet (we still get these in BQ if InvolvedAccounts is permissive). Callers should treat that as "skip silently."

Types

type BQInternalTx

type BQInternalTx struct {
	ToAddress   string       `json:"ToAddress"`
	FromAddress string       `json:"FromAddress"`
	Amount      string       `json:"Amount"`
	TxnStatus   string       `json:"TxnStatus"`
	Memo        string       `json:"Memo"`
	ID          string       `json:"ID"`
	IsFee       bool         `json:"IsFee"`
	Metadata    []BQKeyValue `json:"Metadata"`
}

type BQKeyValue

type BQKeyValue struct {
	Key   string `json:"Key"`
	Value string `json:"Value"`
}

type BQRow

type BQRow struct {
	TxnID            string         `json:"TxnID"`
	SubTxnID         string         `json:"SubTxnID"`
	CreatedTime      time.Time      `json:"CreatedTime"`
	TxnHash          string         `json:"TxnHash"`
	TxnStatus        string         `json:"TxnStatus"`
	BlockNumber      string         `json:"BlockNumber"`
	BlockID          string         `json:"BlockID"`
	ToAddress        string         `json:"ToAddress"`
	FromAddress      string         `json:"FromAddress"`
	Amount           string         `json:"Amount"`
	Fee              string         `json:"Fee"`
	FeeAddress       string         `json:"FeeAddress"`
	Logs             []string       `json:"Logs"`
	Memo             []string       `json:"Memo"`
	Metadata         []BQKeyValue   `json:"Metadata"`
	TokenTxns        []BQTokenTxn   `json:"TokenTxns"`
	InternalTxns     []BQInternalTx `json:"InternalTxns"`
	InvolvedAccounts []string       `json:"InvolvedAccounts"`
	DetailsID        string         `json:"DetailsID"`
}

BQRow mirrors blockchain-query-svc's BQRow shape on the wire. Field names match Go's default JSON encoding (TitleCase) because the aggregator persists rows via encoding/json with no tags. See services/blockchain-query-svc/ internal/core/ports/bqloader.go.

type BQTokenTxn

type BQTokenTxn struct {
	ToAddress    string       `json:"ToAddress"`
	FromAddress  string       `json:"FromAddress"`
	TokenAddress string       `json:"TokenAddress"`
	Amount       string       `json:"Amount"`
	TxnStatus    string       `json:"TxnStatus"`
	Memo         string       `json:"Memo"`
	ID           string       `json:"ID"`
	IsFee        bool         `json:"IsFee"`
	Metadata     []BQKeyValue `json:"Metadata"`
}

type SyncState

type SyncState struct {
	WalletId            string `json:"walletId"`
	Network             string `json:"network"`
	LastBlockTimeUnixMs int64  `json:"lastBlockTimeUnixMs"`
	LastTxnHash         string `json:"lastTxnHash,omitempty"`
}

SyncState is the per-(wallet, network) sync watermark. Persisted alongside the keystore as `wallet-<id>.sync-<network>.json`. The watermark survives reorgs because the sync command always re-scans a small overlap window and dedups by txn hash.

func LoadSyncState

func LoadSyncState(dir, walletId, network string) (SyncState, bool, error)

LoadSyncState reads the watermark file. Returns a zero-valued state and (ok=false) when the file does not exist; both states are safe to use.

type SyncTransformInput

type SyncTransformInput struct {
	Wallet          *wallet.Wallet // for tagging; only Id and Address are read
	Network         wallet.Network
	WalletAccount   string // base account, e.g. "Assets:Crypto:ethereum:alice"
	Payload         []byte // raw aggregated BQ rows (JSON array)
	BlockTimeUnixMs int64
	BlockNumber     uint64
	TxnHash         string
	// Confirmed controls the entry's status: true → cleared (*), false → pending (!).
	// Callers compute this from a confirmation-window check on block time.
	Confirmed bool
}

SyncTransformInput is the per-transaction input to TransformToEntry.