Skip to main content

types — wire / transfer

Package types defines the shared data model. Import path: github.com/ShywareLLC/core/shywire/types

AssetRecord​

An asset registered by the operator. shyware does not issue assets — it provides the anonymous transfer layer for an existing asset (e.g. USDC, a sovereign token).

type AssetRecord struct {
    AssetID     string `json:"asset_id"`     // operator-defined identifier (e.g. "usdc")
    Name        string `json:"name"`         // human-readable label
    Decimals    uint8  `json:"decimals"`     // precision; 6 for USDC-equivalent
    TotalSupply int64  `json:"total_supply"` // TotalMinted - TotalBurned; enforced by state
    CreatedAt   int64  `json:"created_at"`
}

AssetID is the canonical key. Choose a short, stable identifier — it appears in every TransferRecord and cannot be changed after registration.

TransferRecord — List 1​

An anonymous transfer. Contains the amount and asset, never the sender or recipient identity.

// TransferRecord is List 1 — an anonymous transfer with no identity field.
//
// transfer_id = H(TransferNonce) is random and unlinkable to the nullifier.
// Amount is plaintext in this scaffold; the production circuit replaces it with a
// Pedersen commitment (see TODO(circuit) in tx/tx.go).
type TransferRecord struct {
    SubmissionID string `json:"submission_id"` // H(TransferNonce) — no identity encoded
    AssetID    string `json:"asset_id"`
    Amount     int64  `json:"amount"`    // TODO(circuit): AmountCommitment []byte
    Timestamp  int64  `json:"timestamp"`
    Height     int64  `json:"height"`
}

SubmissionID is the only receipt the sender holds. It can be used to prove a transfer occurred (the record exists in List 1) without revealing the sender's identity.

ParticipantRecord — List 2​

A participation record. Contains the nullifier (a commitment to identity) never the amount.

// ParticipantRecord is List 2 — a participation record with no amount field.
//
// nullifier = H(wallet_address, transfer_id) prevents double-spend identically to how
// the voting protocol's ZK nullifier prevents double-voting.
type ParticipantRecord struct {
    SubmissionID   string `json:"submission_id"`
    IdentityHash string `json:"identity_hash"` // nullifier = H(wallet_address, transfer_id)
    Height       int64  `json:"height"`
}

IdentityHash is the nullifier. It is stored in List 2 and checked for uniqueness on every transfer. A duplicate nullifier causes the transaction to be rejected.

AccountRecord​

The on-chain balance for an account. The account is identified by a commitment — the wallet address itself never appears on-chain.

// AccountRecord holds the on-chain balance for an account.
// In the production circuit, Balance is replaced with a BalanceCommitment
// (Pedersen commitment) so balances are hidden while conservation is provable.
type AccountRecord struct {
    AccountCommitment string `json:"account_commitment"` // H(wallet_address) — public identifier
    AssetID           string `json:"asset_id"`
    Balance           int64  `json:"balance"`   // TODO(circuit): BalanceCommitment []byte
    UpdatedAt         int64  `json:"updated_at"`
    Height            int64  `json:"height"`
}

One AccountRecord per (AccountCommitment, AssetID) pair. An account must be registered with TxTypeRegisterAccount before it can receive or send transfers.

SupplyRecord​

Tracks the total minted and burned for an asset. Publicly queryable.

// SupplyRecord tracks total minted and burned for an asset.
// TotalSupply == TotalMinted - TotalBurned is enforced on every Mint and Burn tx.
type SupplyRecord struct {
    AssetID      string `json:"asset_id"`
    TotalMinted  int64  `json:"total_minted"`
    TotalBurned  int64  `json:"total_burned"`
    TotalSupply  int64  `json:"total_supply"` // invariant: TotalMinted - TotalBurned
    UpdatedAt    int64  `json:"updated_at"`
}

TotalSupply is the only quantity visible to the public. Individual balances are not queryable without operator credentials.

Error types​

// Returned when a transfer would take sender.Balance below zero.
type ErrorInsufficientBalance struct {
    AccountCommitment string
    AssetID           string
    Have              int64
    Need              int64
}

// Returned when a transfer references an unregistered asset.
type ErrorUnknownAsset struct {
    AssetID string
}

// Returned when a nullifier has already been used (double-spend attempt).
type ErrorDuplicateTransfer struct {
    IdentityHash string
}