Documentation
¶
Overview ¶
Package api provides the JSON REST API and wire-format codec for vote transactions that bypass the Cosmos SDK Tx envelope.
Index ¶
- Constants
- Variables
- func DecodeCeremonyTx(raw []byte) (byte, proto.Message, error)
- func DecodeVoteTx(raw []byte) (byte, types.VoteMessage, error)
- func EncodeCeremonyTx(msg proto.Message, tag byte) ([]byte, error)
- func EncodeVoteTx(msg types.VoteMessage) ([]byte, error)
- func IsCeremonyTag(b byte) bool
- func IsCustomTag(b byte) bool
- func IsVoteTag(b byte) bool
- func ParseLightwalletdURLs(csv string) []string
- func TagForMessage(msg types.VoteMessage) (byte, error)
- type BroadcastResult
- type Handler
- type HandlerConfig
- type SnapshotConfig
- type SnapshotData
- type VoteTxWrapper
Constants ¶
const ( TagDelegateVote byte = 0x02 TagCastVote byte = 0x03 TagSubmitTally byte = 0x05 // Auto-injected by PrepareProposal; never client-signed. TagAckExecutiveAuthorityKey byte = 0x08 // TagContributeDKG (0x0E) is auto-injected by PrepareProposal during the // Joint-Feldman DKG phase. Like Ack, it uses the custom wire format. TagContributeDKG byte = 0x0E // TagSubmitPartialDecryption (0x0D) is auto-injected by PrepareProposal // during the TALLYING phase of a threshold-mode round. Like MsgAck, it is // never client-signed and uses the custom wire format. TagSubmitPartialDecryption byte = 0x0D )
Vote transaction type tags. The first byte of the wire format identifies the message type. Tags 0x02–0x05 are vote-round transactions that use ZKP/RedPallas authentication. Tags 0x08, 0x0D, and 0x0E are ceremony/tally tags auto-injected by PrepareProposal that also use the custom wire format.
Tags 0x01, 0x06, 0x09, 0x0C are reserved for messages that use the standard Cosmos SDK Tx envelope (MsgCreateVotingSession, MsgRegisterPallasKey, MsgCreateValidatorWithPallasKey, MsgUpdateVoteManagers). They are not used by any encoder or decoder here — see sdk/README.md for the full byte map. Tag 0x0A is deliberately absent: it collides with the standard Cosmos Tx protobuf encoding (field 1, wire type 2).
Variables ¶
var DefaultLightwalletdURLs = []string{
"https://zec.rocks:443",
"https://lwdv3.zecwallet.co:443",
"https://zcash.mysideoftheweb.com:9067",
}
DefaultLightwalletdURLs is the fallback list of public lightwalletd servers. They are tried in order; the first successful response wins.
var ErrPIRRebuilding = errors.New("PIR server is rebuilding")
ErrPIRRebuilding is returned when the PIR server is rebuilding its snapshot. Callers can check with errors.Is(err, ErrPIRRebuilding) to distinguish this from other PIR errors and show an appropriate message to the user.
Functions ¶
func DecodeCeremonyTx ¶
DecodeCeremonyTx decodes raw wire-format bytes into a tag and a ceremony message (proto.Message). Tags 0x08 (Ack), 0x0D (PartialDecrypt), and 0x0E (ContributeDKG) use the custom wire format.
func DecodeVoteTx ¶
func DecodeVoteTx(raw []byte) (byte, types.VoteMessage, error)
DecodeVoteTx decodes raw wire-format bytes into a tag and VoteMessage. Returns an error if the bytes are too short, the tag is invalid, or protobuf decoding fails.
func EncodeCeremonyTx ¶
EncodeCeremonyTx serializes an auto-injected message into the custom wire format:
[1 byte: msg_type_tag] [N bytes: protobuf-encoded message]
Tags 0x08 (Ack), 0x0D (SubmitPartialDecryption), and 0x0E (ContributeDKG) use the custom wire format — all are auto-injected by PrepareProposal and never client-signed.
func EncodeVoteTx ¶
func EncodeVoteTx(msg types.VoteMessage) ([]byte, error)
EncodeVoteTx serializes a vote message into the wire format:
[1 byte: msg_type_tag] [N bytes: protobuf-encoded message]
func IsCeremonyTag ¶
IsCeremonyTag returns true if b is an auto-injected ceremony/tally transaction type tag that uses the custom wire format and is never client-signed. Currently: ContributeDKG (0x0E), Ack (0x08), and SubmitPartialDecryption (0x0D).
func IsCustomTag ¶
IsCustomTag returns true if b is a valid custom transaction type tag (vote-round 0x02–0x05 or ceremony 0x08/0x0D/0x0E). Other ceremony messages use standard Cosmos SDK transactions.
func IsVoteTag ¶
IsVoteTag returns true if b is a vote-round transaction type tag (0x02–0x05). MsgCreateVotingSession (0x01) now uses standard Cosmos SDK transactions.
func ParseLightwalletdURLs ¶
ParseLightwalletdURLs splits a comma-separated list of URLs. Returns nil for empty input (caller should fall back to defaults).
func TagForMessage ¶
func TagForMessage(msg types.VoteMessage) (byte, error)
TagForMessage returns the wire-format tag for a VoteMessage.
Types ¶
type BroadcastResult ¶
type BroadcastResult struct {
TxHash string `json:"tx_hash"`
Code uint32 `json:"code"`
Log string `json:"log,omitempty"`
}
BroadcastResult is the JSON response returned to clients after tx submission.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler provides JSON REST endpoints for vote transaction submission and query access.
func NewHandler ¶
func NewHandler(cfg HandlerConfig) *Handler
NewHandler creates a new REST API handler.
func (*Handler) RegisterQueryRoutes ¶
RegisterQueryRoutes registers vote query REST endpoints on the router.
GET /shielded-vote/v1/commitment-tree/{round_id}/latest
GET /shielded-vote/v1/commitment-tree/{round_id}/leaves?from_height=X&to_height=Y
GET /shielded-vote/v1/commitment-tree/{round_id}/{height}
GET /shielded-vote/v1/round/{round_id}
GET /shielded-vote/v1/rounds
GET /shielded-vote/v1/rounds/active
GET /shielded-vote/v1/tally/{round_id}/{proposal_id}
GET /shielded-vote/v1/tally-results/{round_id}
GET /shielded-vote/v1/vote-summary/{round_id}
GET /shielded-vote/v1/ceremony
GET /shielded-vote/v1/pallas-keys
GET /shielded-vote/v1/vote-managers
GET /shielded-vote/v1/genesis
func (*Handler) RegisterTxRoutes ¶
RegisterTxRoutes registers vote transaction submission endpoints on the router.
POST /shielded-vote/v1/delegate-vote → MsgDelegateVote POST /shielded-vote/v1/cast-vote → MsgCastVote POST /shielded-vote/v1/reveal-share → MsgRevealShare
MsgSubmitTally is proposer-only (auto-injected via PrepareProposal) and has no REST endpoint.
MsgCreateVotingSession is a standard Cosmos SDK transaction (signed by any vote manager) and should be submitted via svoted tx sign/broadcast or /cosmos/tx/v1beta1/txs.
Ceremony messages (MsgRegisterPallasKey, MsgCreateValidatorWithPallasKey, MsgUpdateVoteManagers) are also standard Cosmos SDK transactions.
MsgAckExecutiveAuthorityKey and MsgSubmitPartialDecryption have no REST endpoints — they are injected in-protocol via PrepareProposal.
type HandlerConfig ¶
type HandlerConfig struct {
// CometRPCEndpoint is the URL of the local CometBFT RPC server.
// Default: "http://localhost:26657"
CometRPCEndpoint string
// Snapshot configures external service URLs for fetching Zcash snapshot
// data (nc_root from lightwalletd, nullifier IMT root from IMT service).
Snapshot SnapshotConfig
}
HandlerConfig configures the REST API handler.
type SnapshotConfig ¶
type SnapshotConfig struct {
// PIRServiceURL is the URL of the PIR server that serves nullifier tree roots.
// Default: "http://localhost:3000"
PIRServiceURL string
// LightwalletdURLs is a list of gRPC addresses to try for lightwalletd.
// The first successful response wins. Falls back to DefaultLightwalletdURLs
// if empty.
LightwalletdURLs []string
}
SnapshotConfig holds service URLs for fetching Zcash snapshot data.
type SnapshotData ¶
type SnapshotData struct {
NullifierIMTRoot []byte // 32-byte Poseidon IMT root from the PIR service
SnapshotBlockhash []byte // 32-byte block hash at snapshot height
NcRoot []byte // 32-byte note commitment tree root (see below)
}
SnapshotData holds the Zcash mainnet data needed for MsgCreateVotingSession.
type VoteTxWrapper ¶
type VoteTxWrapper struct {
// RawBytes is the original wire-format bytes [tag || protobuf].
RawBytes []byte
// Tag is the message type tag (0x01–0x05 for vote-round, 0x08 for MsgAck).
Tag byte
// VoteMsg is the decoded vote message, used by the validation pipeline.
// Set for vote-round tags (0x01–0x05). Nil for ceremony messages.
VoteMsg types.VoteMessage
// CeremonyMsg is the decoded ceremony message (tag 0x08 only).
// Only MsgAckExecutiveAuthorityKey uses this path.
CeremonyMsg sdk.Msg
}
VoteTxWrapper wraps a vote module message so it can flow through BaseApp's standard tx lifecycle (TxDecoder → AnteHandler → MsgServiceRouter).
Vote transactions and MsgAckExecutiveAuthorityKey bypass the Cosmos SDK Tx envelope. They use a simple wire format: [1-byte tag || protobuf message]. This wrapper makes them compatible with sdk.Tx so BaseApp can process them alongside standard Cosmos transactions. All other ceremony messages now use standard Cosmos SDK transactions with proper signature verification.
func (*VoteTxWrapper) GetMsgs ¶
func (vtx *VoteTxWrapper) GetMsgs() []sdk.Msg
GetMsgs satisfies sdk.HasMsgs. Returns the single message as sdk.Msg. sdk.Msg is gogoproto.Message, which our protobuf-generated types implement.
Source Files