types

Documentation

Overview

Package types defines ShadowLedger's core data structures: transactions, blocks, headers and shard sets, with deterministic canonical encodings.

Index

• Constants
• Variables
• func AddrDigest(a crypto.Address) uint64
• func ContractAddress(deployer crypto.Address, nonce uint64) crypto.Address
• func EncodeLogs(logs []Log) []byte
• func EncodeTxs(txs []Transaction) []byte
• type Block
  • func (b *Block) Body() []byte
• type EquivocationEvidence
• type Hash
  • func BodyHash(body []byte) Hash
  • func LogsRootOf(logs []Log) Hash
  • func MerkleRootOf(txs []Transaction) Hash
• type Header
  • func (h *Header) ID() Hash
  • func (h *Header) Sign(kp *crypto.KeyPair)
  • func (h *Header) SigningBytes() []byte
  • func (h *Header) VerifySig() error
• type Log
  • func DecodeLogs(data []byte) ([]Log, error)
• type ShardSet
• type ShardSpec
  • func (s ShardSpec) Total() int
• type Transaction
  • func DecodeTxs(data []byte) ([]Transaction, error)
  • func (t *Transaction) Hash() Hash
  • func (t *Transaction) IsCoinbase() bool
  • func (t *Transaction) Sign(kp *crypto.KeyPair)
  • func (t *Transaction) SigningBytes() []byte
  • func (t *Transaction) VerifySig() error

Constants

const (
	KindTransfer     uint8 = 0 // plain value transfer
	KindDeploy       uint8 = 1 // deploy a contract (Data = bytecode)
	KindCall         uint8 = 2 // call a contract (To = contract, Data = input words)
	KindRegister     uint8 = 3 // register as a validator, locking Amount as a bond
	KindUnregister   uint8 = 4 // exit the validator set, unlocking the bond
	KindSlash        uint8 = 5 // report equivocation; Data = two conflicting signed headers
	KindFaucet       uint8 = 6 // claim faucet $SHARD via PoW; Data = anchorHeight(8) || nonce(8)
	KindStorageProof uint8 = 7 // prove you store a committed shard; Data = height(8) || index(8) || shardBytes
)

Transaction kinds.

Variables

var (
	ErrBadPubKey       = errors.New("tx: bad pubkey length")
	ErrPubAddrMismatch = errors.New("tx: pubkey does not match from-address")
	ErrBadSignature    = errors.New("tx: invalid signature")
)

Transaction validation errors.

var (
	ErrBadBody = errors.New("types: malformed block body")
)

Encoding errors.

Functions

func AddrDigest

func AddrDigest(a crypto.Address) uint64

AddrDigest reduces an address to a uint64 the VM can use (e.g. CALLER).

func ContractAddress

func ContractAddress(deployer crypto.Address, nonce uint64) crypto.Address

ContractAddress derives a deployed contract's address from the deployer and the nonce used in the deploy tx (deterministic, like Ethereum's CREATE).

func EncodeLogs

func EncodeLogs(logs []Log) []byte

EncodeLogs / DecodeLogs are the canonical wire form of a block's logs (the bytes that get erasure-coded into log-shards).

func EncodeTxs

func EncodeTxs(txs []Transaction) []byte

EncodeTxs canonically serializes a transaction slice.

Types

type Block

type Block struct {
	Header Header        `json:"header"`
	Txs    []Transaction `json:"txs"`
}

Block bundles a header with its full transaction list (the erasure payload).

func (*Block) Body

func (b *Block) Body() []byte

Body returns the canonical encoding of the tx list — the bytes that get erasure-coded into shards. Reconstructing these bytes reconstructs the block.

type EquivocationEvidence

type EquivocationEvidence struct {
	A Header `json:"a"`
	B Header `json:"b"`
}

EquivocationEvidence is two conflicting headers signed by the same validator at the same height — provable double-signing, carried in a KindSlash tx.Data.

type Hash

type Hash = merkle.Hash

Hash is the project-wide 32-byte digest (shared with merkle).

func BodyHash

func BodyHash(body []byte) Hash

BodyHash returns the SHA-256 of the canonical body.

func LogsRootOf

func LogsRootOf(logs []Log) Hash

LogsRootOf is the merkle root over a block's logs (zero hash if none). This is the Ethereum-style commitment placed in the header.

func MerkleRootOf

func MerkleRootOf(txs []Transaction) Hash

MerkleRootOf computes the Merkle root over the tx hashes.

type Header

type Header struct {
	Height     uint64         `json:"height"`
	PrevHash   Hash           `json:"prev_hash"`
	MerkleRoot Hash           `json:"merkle_root"`
	Timestamp  int64          `json:"timestamp"`
	Validator  crypto.Address `json:"validator"`
	TxCount    uint32         `json:"tx_count"`
	Round      uint32         `json:"round"` // consensus round (leader-timeout fallback for liveness)
	Spec       ShardSpec      `json:"spec"`
	BodyHash   Hash           `json:"body_hash"` // SHA-256 of canonical body bytes
	LogsRoot   Hash           `json:"logs_root"` // merkle root over this block's event logs (Ethereum-style)
	Sig        []byte         `json:"sig"`       // validator ed25519 over SigningBytes
	ValPubKey  []byte         `json:"val_pubkey"`
}

Header is the lightweight block header that gossips network-wide.

func (*Header) ID

func (h *Header) ID() Hash

ID returns the block id = SHA-256 of the header signing bytes.

func (*Header) Sign

func (h *Header) Sign(kp *crypto.KeyPair)

Sign signs the header with the validator key pair.

func (*Header) SigningBytes

func (h *Header) SigningBytes() []byte

SigningBytes is the canonical header encoding the validator signs (excludes Sig and ValPubKey).

func (*Header) VerifySig

func (h *Header) VerifySig() error

VerifySig checks the validator signature and pubkey-address binding.

type Log

type Log struct {
	Contract crypto.Address `json:"contract"`
	Topics   []uint64       `json:"topics"`
	TxIndex  int            `json:"tx_index"`
}

Log is an event emitted by a contract via the LOG opcode. Logs are a hybrid:

• Ethereum-style: a merkle LogsRoot over the block's logs is committed in the block header (signed, part of the block id) — tamper-evident, verifiable.
• ShadowLedger-style: the log DATA itself is erasure-coded and rendezvous- distributed like block bodies — no node stores the whole log history; it is reconstructed on demand and checked against the committed LogsRoot.

func DecodeLogs

func DecodeLogs(data []byte) ([]Log, error)

DecodeLogs reverses EncodeLogs.

type ShardSet

type ShardSet struct {
	BlockID   Hash      `json:"block_id"`
	Spec      ShardSpec `json:"spec"`
	PaddedLen int       `json:"padded_len"` // length each data shard slot was padded to
	OrigLen   int       `json:"orig_len"`   // original body length (to trim after decode)
	ShardHash []Hash    `json:"shard_hash"` // len == Spec.Total(); hash of each shard
}

ShardSet is the commitment to a block's erasure shards.

type ShardSpec

type ShardSpec struct {
	K uint8 `json:"k"` // data shards
	M uint8 `json:"m"` // parity shards
}

ShardSpec captures the erasure parameters used to fragment a block body.

func (ShardSpec) Total

func (s ShardSpec) Total() int

Total returns K+M, the number of shards produced.

type Transaction

type Transaction struct {
	From    crypto.Address `json:"from"`
	To      crypto.Address `json:"to"`
	Amount  uint64         `json:"amount"`
	Fee     uint64         `json:"fee"`
	Nonce   uint64         `json:"nonce"`
	ChainID uint64         `json:"chain_id"` // network id — prevents cross-network replay
	Kind    uint8          `json:"kind"`     // 0 transfer, 1 deploy, 2 call
	Gas     uint64         `json:"gas"`      // execution gas limit (contract txs)
	Data    []byte         `json:"data"`     // deploy bytecode / call input
	PubKey  []byte         `json:"pubkey"`   // sender ed25519 pubkey (empty for coinbase)
	Sig     []byte         `json:"sig"`      // ed25519 over SigningBytes (empty for coinbase)
}

Transaction is an account-model value transfer or contract operation.

func DecodeTxs

func DecodeTxs(data []byte) ([]Transaction, error)

DecodeTxs reverses EncodeTxs.

func (*Transaction) Hash

func (t *Transaction) Hash() Hash

Hash returns the transaction id (SHA-256 of the full canonical encoding).

func (*Transaction) IsCoinbase

func (t *Transaction) IsCoinbase() bool

IsCoinbase reports whether this is a genesis/reward tx (no sender).

func (*Transaction) Sign

func (t *Transaction) Sign(kp *crypto.KeyPair)

Sign fills PubKey and Sig using the given key pair and sets From accordingly.

func (*Transaction) SigningBytes

func (t *Transaction) SigningBytes() []byte

SigningBytes is the canonical encoding signed by the sender (excludes Sig).

func (*Transaction) VerifySig

func (t *Transaction) VerifySig() error

VerifySig validates the signature and that the pubkey matches From. Coinbase txs are considered valid here (authorized separately by the chain).