helper

type BroadcastResult struct {
	TxHash string `json:"tx_hash"`
	Code   uint32 `json:"code"`
	Log    string `json:"log"`
}

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

type Config struct {
	// Disable turns off the helper server entirely.
	Disable bool `mapstructure:"disable"`

	// APIToken protects POST /shielded-vote/v1/shares when set (checked via X-Helper-Token).
	APIToken string `mapstructure:"api_token"`

	// ExposeQueueStatus enables the benchmark-only GET /shielded-vote/v1/queue-status
	// endpoint. Keep this off by default to avoid exposing per-round queue
	// counts to observers.
	ExposeQueueStatus bool `mapstructure:"expose_queue_status"`

	// DBPath is the path to the SQLite database file. Use ":memory:" for testing.
	DBPath string `mapstructure:"db_path"`

	// ProcessInterval is how often to check for shares ready to submit (seconds).
	ProcessInterval int `mapstructure:"process_interval"`

	// ChainAPIPort is the port of the chain's REST API (localhost).
	// Used for submitting MsgRevealShare via POST. Defaults to 1317 — the
	// standard Cosmos SDK [api] address port that svoted serves. Setting
	// this to a port where no server listens causes every share to fail
	// broadcast silently (`connection refused` warnings in the log while
	// the helper keeps accepting and proving new shares), which surfaces
	// to voters as zero-value tallies with no user-visible error.
	ChainAPIPort int `mapstructure:"chain_api_port"`

	// MaxConcurrentProofs limits concurrent proof generation goroutines.
	MaxConcurrentProofs int `mapstructure:"max_concurrent_proofs"`

	// AdminURL is the base URL of the admin server for registration and
	// heartbeat (e.g. "https://admin.example.com"). When empty, heartbeat
	// is disabled.
	AdminURL string `mapstructure:"admin_url"`

	// HelperURL is this server's own public URL as seen by clients
	// (e.g. "https://1-2-3-4.sslip.io"). When empty, heartbeat is disabled.
	HelperURL string `mapstructure:"helper_url"`

	// SentryDSN is the Sentry DSN for error tracking. When empty, Sentry is
	// disabled. Can also be set via the SENTRY_DSN environment variable at
	// runtime (app.toml takes precedence if set).
	SentryDSN string `mapstructure:"sentry_dsn"`
}

type EncryptedShareWire struct {
	C1         string `json:"c1"`          // base64, 32 bytes
	C2         string `json:"c2"`          // base64, 32 bytes
	ShareIndex uint32 `json:"share_index"` // 0..15
}

type EnqueueResult int

type Helper struct {
	Store                 *ShareStore
	Processor             *Processor
	APIToken              string
	ExposeQueueStatus     bool
	VCHash                VCHashFunc
	ShareNullifierChecker ShareNullifierChecker
	Logger                log.Logger
}

type MsgRevealShareJSON struct {
	ShareNullifier           string `json:"share_nullifier"` // base64, 32 bytes
	EncShare                 string `json:"enc_share"`       // base64, 64 bytes (C1||C2)
	ProposalID               uint32 `json:"proposal_id"`
	VoteDecision             uint32 `json:"vote_decision"`
	Proof                    string `json:"proof"`         // base64
	VoteRoundID              string `json:"vote_round_id"` // base64, 32 bytes
	VoteCommTreeAnchorHeight uint64 `json:"vote_comm_tree_anchor_height"`
}

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

type ProofGenerator interface {
	// GenerateShareRevealProof generates a share reveal proof.
	// merklePath: 772-byte serialized Merkle path (from votetree.TreeHandle.Path)
	// shareComms: 16 × 32-byte per-share Poseidon commitments
	// primaryBlind: 32-byte blind factor for the revealed share
	// encC1, encC2: 32-byte compressed Pallas points of the revealed share
	// Returns proof bytes, nullifier (32 bytes), tree root (32 bytes).
	GenerateShareRevealProof(
		merklePath []byte,
		shareComms [16][32]byte,
		primaryBlind [32]byte,
		encC1 [32]byte,
		encC2 [32]byte,
		shareIndex uint32,
		proposalID, voteDecision uint32,
		roundID [32]byte,
	) (proof []byte, nullifier [32]byte, treeRoot [32]byte, err error)
}

type PulseConfig struct {
	AdminURL        string // Admin server base URL (e.g. "https://admin.example.com")
	HelperURL       string // Own public URL (e.g. "https://1-2-3-4.sslip.io")
	OperatorAddress string // Bech32 operator address derived from validator key
	Moniker         string // Node moniker from CometBFT config
	Sign            SignFn
	Logger          log.Logger
}

type QueueStatus struct {
	Total     int `json:"total"`
	Pending   int `json:"pending"`
	Submitted int `json:"submitted"`
	Failed    int `json:"failed"`
}

type QueuedShare struct {
	Payload     SharePayload
	State       ShareState
	Attempts    int
	VoteEndTime uint64 // unix seconds; 0 if unknown
}

type RoundInfoFetcher func(roundID string) (voteEndTime uint64, err error)

type RoundStatusChecker func(roundID string) (isActive bool, err error)

type ShareNullifierChecker func(roundIDHex string, shareNullifier []byte) (bool, error)

type ShareNullifierCheckerGetter func() ShareNullifierChecker

type SharePayload struct {
	SharesHash   string             `json:"shares_hash"`   // base64, 32 bytes
	ProposalID   uint32             `json:"proposal_id"`   // proposal being voted on
	VoteDecision uint32             `json:"vote_decision"` // 0=support, 1=oppose, 2=skip
	EncShare     EncryptedShareWire `json:"enc_share"`     // the share to relay
	TreePosition uint64             `json:"tree_position"` // VC leaf index
	VoteRoundID  string             `json:"vote_round_id"` // hex, 32 bytes
	ShareComms   []string           `json:"share_comms"`   // base64, 16 × 32-byte Poseidon commitments
	PrimaryBlind string             `json:"primary_blind"` // base64, 32 bytes
	SubmitAt     uint64             `json:"submit_at"`     // unix seconds; 0 = immediate (last-moment)
}

type ShareState int

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

type SignFn func(payload string) (signature, pubKey string, err error)

type TreeReader interface {
	// SetRoundID selects the voting round for subsequent tree lookups.
	SetRoundID(roundID []byte)

	// GetTreeStatus returns lightweight tree statistics (leaf count + anchor height).
	GetTreeStatus() (TreeStatus, error)

	// MerklePath returns the 772-byte serialized Poseidon Merkle authentication
	// path for the leaf at position, anchored to the checkpoint at anchorHeight.
	// anchorHeight must correspond to a checkpoint that exists in the persistent
	// tree (i.e. a block height at which Checkpoint was called by EndBlocker).
	MerklePath(position uint64, anchorHeight uint32) ([]byte, error)

	// LeafAt returns the raw 32-byte vote commitment stored at the given tree
	// position, or nil if no leaf exists at that index.
	LeafAt(position uint64) ([]byte, error)
}

type TreeStatus struct {
	LeafCount    uint64 `json:"leaf_count"`
	AnchorHeight uint64 `json:"anchor_height"`
}

type VCHashFunc func(roundID, sharesHash [32]byte, proposalID, voteDecision uint32) ([32]byte, error)