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 /api/v1/shares when set (checked via X-Helper-Token).
	APIToken string `mapstructure:"api_token"`

	// ExposeQueueStatus enables the benchmark-only GET /api/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"`

	// MinDelay is the minimum delay floor (seconds). No share will be
	// submitted sooner than this after receipt, preventing near-zero
	// exponential samples from making shares trivially linkable.
	// Default: 90 (3 × default ProcessInterval).
	MinDelay int `mapstructure:"min_delay"`

	// 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.
	ChainAPIPort int `mapstructure:"chain_api_port"`

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

	// PulseURL is the base URL for the server heartbeat endpoint
	// (e.g. "https://shielded-vote.vercel.app"). When empty, heartbeat is disabled.
	PulseURL string `mapstructure:"pulse_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"`
}

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
	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
	// encC1X, encC2X: 32-byte x-coordinates of the revealed share
	// Returns proof bytes, nullifier (32 bytes), tree root (32 bytes).
	GenerateShareRevealProof(
		merklePath []byte,
		shareComms [16][32]byte,
		primaryBlind [32]byte,
		encC1X [32]byte,
		encC2X [32]byte,
		shareIndex uint32,
		proposalID, voteDecision uint32,
		roundID [32]byte,
	) (proof []byte, nullifier [32]byte, treeRoot [32]byte, err error)
}

type PulseConfig struct {
	PulseURL        string // Vercel base URL (e.g. "https://shielded-vote.vercel.app")
	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 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
	ShareIndex   uint32             `json:"share_index"`   // redundant with enc_share.share_index
	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
}

type ShareState int

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

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

type TreeReader interface {
	// 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)