Skip to main content

tx — shystore

Package tx defines the wire-format types for shystore-v1 transactions.

Import path: github.com/NickCarducci/Shyware-SDK/protocol/tx

Type discriminators​

const (
    StoreTxTypeSecretStore       uint8 = 1
    StoreTxTypeSecretReveal      uint8 = 2
    StoreTxTypeSecretRotate      uint8 = 3
    StoreTxTypeBucketClose       uint8 = 4
    StoreTxTypeRegisterValidator uint8 = 5
    StoreTxTypeAdverseAction     uint8 = 6
)

Type values are scoped to the shystore ABCI app. The same uint8 values are reused independently in the shyvoting and shychat domains because each app dispatches from its own type set.

SecretStoreData​

type SecretStoreData struct {
    ScopingID                       string          `json:"scoping_id"`
    SubmissionNonce                    string          `json:"submission_nonce"`       // random 32-byte hex; SubmissionID = H(beacon || nonce)
    BeaconBlockHash                string          `json:"beacon_block_hash"`  // recent canonical block hash
    BeaconBlockHeight              int64           `json:"beacon_block_height"`
    SubmissionIdentifierDerivation string          `json:"submission_identifier_derivation,omitempty"` // "nonce_only" | "nonce_plus_payload"
    Timestamp                      int64           `json:"timestamp"`
    PartitionID                    string          `json:"partition_id,omitempty"` // "sealed" (default) | "public"
    Category                       string          `json:"category"`
    SealedPayload                  json.RawMessage `json:"sealed_payload"`     // AES-GCM ciphertext — ABCI never sees plaintext
    SenderPubKey                   string          `json:"sender_pub_key"`     // Ed25519 device key (hex)
    SenderSig                      string          `json:"sender_sig"`         // Sign(sk_s, SubmissionNonce + ":" + ScopingID)
    IDVAttestation                 json.RawMessage `json:"idv_attestation"`    // provider attestation over sender_pub_key
}

SealedPayload is AES-GCM encrypted by the sender before broadcast. The ABCI layer stores ciphertext in List 1 verbatim and has no access to plaintext. SenderSig provides oracle-forgery prevention — the IDV provider attests SenderPubKey but never holds sk_s.

SecretRevealData​

type SecretRevealData struct {
    ScopingID       string `json:"scoping_id"`
    SubmissionID       string `json:"submission_id"`
    SenderPubKey   string `json:"sender_pub_key"`
    SenderSig      string `json:"sender_sig"`     // Sign(sk_s, SubmissionID + ":" + ScopingID)
    IDVAttestation json.RawMessage `json:"idv_attestation"`
}

ExecuteSecretReveal validates the identity matches the List 2 entry and emits a reveal_requested event. The ABCI layer does not return plaintext; the off-chain reconciling authority processes the event to serve the sealed payload from the receipt store.

SecretRotateData​

type SecretRotateData struct {
    ScopingID        string          `json:"scoping_id"`
    OldSubmissionID     string          `json:"old_submission_id"`
    NewSubmissionNonce  string          `json:"new_submission_nonce"`
    NewSealedPayload json.RawMessage `json:"new_sealed_payload"`
    SenderPubKey    string          `json:"sender_pub_key"`
    SenderSig       string          `json:"sender_sig"` // Sign(sk_s, "rotate:" + NewSubmissionNonce + ":" + ScopingID)
    IDVAttestation  json.RawMessage `json:"idv_attestation"`
}

Rotation replaces the List 1 entry keyed by OldSubmissionID with a new entry keyed by H(NewSubmissionNonce). List 2 is unchanged. |L1| is constant after rotation. The "rotate:" prefix in SenderSig prevents a SecretStore signature replaying as a rotation.

BucketCloseData​

type BucketCloseData struct {
    ScopingID      string `json:"scoping_id"`
    ClosingHeight int64  `json:"closing_height"`
}

Triggers TwoListBase.ClosePeriod: enforces |L1| == |L2|, computes disjoint Merkle roots, requests KMS signature, commits ClosureRecord.

StoreAdverseActionData​

type StoreAdverseActionData struct {
    ScopingID            string `json:"scoping_id"`
    IdentityHash        string `json:"identity_hash"`
    ActionType          string `json:"action_type"` // "suppress" | "restore"
    ActionNonce         string `json:"action_nonce"`
    ReferencedActionID  string `json:"referenced_action_id,omitempty"`
    EligibilityAuth     string `json:"eligibility_auth"`     // Ed25519 sig from eligibility authority
    ReconciliationAuth  string `json:"reconciliation_auth"`  // Ed25519 sig from reconciling authority
}

Both authority signatures are required. ActionID = H(ActionNonce). The resulting StoreActionRecord is appended to the authority-action log and never deleted.

Stateless validation​

func ValidateStoreTx(t *Tx) error

Called during CheckTx. Checks required fields, nonce length, and signature format before stateful execution.