slhdsafx

package
v0.2.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 13, 2026 License: BSD-3-Clause Imports: 20 Imported by: 0

Documentation

Overview

Package slhdsafx provides SLH-DSA (FIPS 205) hash-based post-quantum credentials for high-assurance UTXO spending on X-Chain.

SLH-DSA is a stateless hash-based signature scheme that provides security against both classical and quantum computer attacks. Hash-based signatures have the strongest security assumptions of any PQ scheme.

This package supports six parameter sets across three security levels:

  • SHA2-128f / SHAKE-128f: 128-bit security, fast signing
  • SHA2-192f / SHAKE-192f: 192-bit security, balanced (default)
  • SHA2-256f / SHAKE-256f: 256-bit security, highest security

"f" (fast) variants are used over "s" (small) because UTXO spending prioritizes signing latency over signature size.

Index

Constants

View Source 
const (
	// SHA2-128f (NIST Level 1, fast)
	SLH128fPubKeyLen = 32
	SLH128fSigLen    = 17088

	// SHA2-192f (NIST Level 3, fast) - DEFAULT
	SLH192fPubKeyLen = 48
	SLH192fSigLen    = 35664

	// SHA2-256f (NIST Level 5, fast)
	SLH256fPubKeyLen = 64
	SLH256fSigLen    = 49856
)

Signature and public key sizes from FIPS 205 specification.

View Source 
const (
	// CostPerSignature is the compute cost per SLH-DSA signature verification.
	// Benchmarked at ~862us vs secp256k1 ~40us (21.5x ratio).
	// secp256k1 CostPerSignature = 1000, so SLH-DSA = 22000.
	CostPerSignature uint64 = 22000
)
View Source 
const Name = "slhdsafx"

Variables

View Source 
var (
	ErrNilCredential      = errors.New("nil SLH-DSA credential")
	ErrEmptyCredential    = errors.New("empty SLH-DSA credential")
	ErrInvalidSignature   = errors.New("invalid SLH-DSA signature")
	ErrInvalidSecLevel    = errors.New("invalid SLH-DSA security level")
	ErrSignatureTooShort  = errors.New("SLH-DSA signature too short")
	ErrMismatchedSecLevel = errors.New("signature length doesn't match security level")
)
View Source 
var (
	ErrWrongVMType                    = errors.New("wrong vm type")
	ErrWrongTxType                    = errors.New("wrong tx type")
	ErrWrongOpType                    = errors.New("wrong operation type")
	ErrWrongUTXOType                  = errors.New("wrong utxo type")
	ErrWrongInputType                 = errors.New("wrong input type")
	ErrWrongCredentialType            = errors.New("wrong credential type")
	ErrWrongOwnerType                 = errors.New("wrong owner type")
	ErrMismatchedAmounts              = errors.New("utxo amount and input amount are not equal")
	ErrWrongNumberOfUTXOs             = errors.New("wrong number of utxos for the operation")
	ErrWrongMintCreated               = errors.New("wrong mint output created from the operation")
	ErrTimelocked                     = errors.New("output is time locked")
	ErrTooManySigners                 = errors.New("input has more signers than expected")
	ErrTooFewSigners                  = errors.New("input has less signers than expected")
	ErrInputOutputIndexOutOfBounds    = errors.New("input referenced a nonexistent address in the output")
	ErrInputCredentialSignersMismatch = errors.New("input expected a different number of signers than provided in the credential")
	ErrWrongSig                       = errors.New("wrong signature")
)
View Source 
var (
	ErrNilInput                    = errors.New("nil input")
	ErrInputIndicesNotSortedUnique = errors.New("address indices not sorted and unique")
)
View Source 
var (
	ErrNilOutputOwners     = errors.New("nil SLH-DSA output owners")
	ErrNilPublicKey        = errors.New("nil SLH-DSA public key")
	ErrThresholdExceeded   = errors.New("threshold exceeds number of addresses")
	ErrOutputUnoptimized   = errors.New("output representation should be optimized")
	ErrOutputNotSpendable  = errors.New("output not yet spendable")
	ErrInvalidPubKeyLength = errors.New("invalid SLH-DSA public key length")
)
View Source 
var ErrNoValueInput = errors.New("input has no value")
View Source 
var (
	ErrNoValueOutput = errors.New("output has no value")
)
View Source 
var (

	// ID that this Fx uses when labeled
	ID = ids.ID{'s', 'l', 'h', 'd', 's', 'a', 'f', 'x'}
)

Functions

This section is empty.

Types

type Credential 

type Credential struct {
	// Level indicates the SLH-DSA parameter set
	Level SecurityLevel `serialize:"true" json:"securityLevel"`
	// Sigs contains the SLH-DSA signatures (variable length based on Level)
	Sigs [][]byte `serialize:"true" json:"signatures"`
}

Credential contains SLH-DSA signatures for spending UTXOs.

func NewCredential 

func NewCredential(level SecurityLevel, sigs [][]byte) (*Credential, error)

NewCredential creates a new SLH-DSA credential at the specified security level

func NewCredential192f 

func NewCredential192f(sigs [][]byte) (*Credential, error)

NewCredential192f creates a credential using the recommended SLH-DSA-SHA2-192f level

func (*Credential) MarshalJSON 

func (cr *Credential) MarshalJSON() ([]byte, error)

MarshalJSON marshals the credential to JSON with hex-encoded signatures

func (*Credential) UnmarshalJSON 

func (cr *Credential) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals JSON into the credential

func (*Credential) Verify 

func (cr *Credential) Verify() error

Verify validates the credential structure (not cryptographic validity).

type Factory 

type Factory struct{}

func (*Factory) New 

func (*Factory) New() any

type Fx 

type Fx struct {
	VM VM
	// contains filtered or unexported fields
}

Fx describes the SLH-DSA feature extension for post-quantum secure UTXO spending

func (*Fx) Bootstrapped 

func (fx *Fx) Bootstrapped() error

func (*Fx) Bootstrapping 

func (*Fx) Bootstrapping() error

func (*Fx) CreateOutput 

func (*Fx) CreateOutput(amount uint64, ownerIntf interface{}) (interface{}, error)

CreateOutput creates a new output with the provided control group worth the specified amount

func (*Fx) Initialize 

func (fx *Fx) Initialize(vmIntf interface{}) error

func (*Fx) InitializeVM 

func (fx *Fx) InitializeVM(vmIntf interface{}) error

func (*Fx) VerifyCredentials 

func (fx *Fx) VerifyCredentials(utx UnsignedTx, in *Input, cred *Credential, out *OutputOwners) error

VerifyCredentials ensures that the output can be spent by the input with the credential. SLH-DSA signatures are verified directly against the public key stored in OutputOwners.Addrs.

func (*Fx) VerifyOperation 

func (fx *Fx) VerifyOperation(txIntf, opIntf, credIntf interface{}, utxosIntf []interface{}) error

func (*Fx) VerifyPermission 

func (fx *Fx) VerifyPermission(txIntf, inIntf, credIntf, ownerIntf interface{}) error

VerifyPermission returns nil iff [credIntf] proves that [ownerIntf] assents to [txIntf]

func (*Fx) VerifySpend 

func (fx *Fx) VerifySpend(utx UnsignedTx, in *TransferInput, cred *Credential, utxo *TransferOutput) error

VerifySpend ensures that the utxo can be sent to any address

func (*Fx) VerifyTransfer 

func (fx *Fx) VerifyTransfer(txIntf, inIntf, credIntf, utxoIntf interface{}) error

type Input 

type Input struct {
	SigIndices []uint32 `serialize:"true" json:"signatureIndices"`
}

Input references signature indices into the credential for spending.

func (*Input) Cost 

func (in *Input) Cost() (uint64, error)

func (*Input) Verify 

func (in *Input) Verify() error

Verify this input is syntactically valid

type Keychain 

type Keychain struct {
	Addrs set.Set[ids.ShortID]
	Keys  []*slhdsa.PrivateKey
	// contains filtered or unexported fields
}

Keychain is a collection of SLH-DSA keys that can be used to spend outputs

func NewKeychain 

func NewKeychain(keys ...*slhdsa.PrivateKey) *Keychain

NewKeychain returns a new keychain containing [keys]

func (*Keychain) Add 

func (kc *Keychain) Add(key *slhdsa.PrivateKey)

Add a new key to the key chain

func (Keychain) Addresses 

func (kc Keychain) Addresses() set.Set[ids.ShortID]

Addresses returns the set of addresses this keychain manages

func (Keychain) Get 

func (kc Keychain) Get(id ids.ShortID) (keychain.Signer, bool)

Get a key from the keychain. Returns keychain.Signer.

func (*Keychain) Match 

func (kc *Keychain) Match(owners *OutputOwners, time uint64) ([]uint32, []*slhdsa.PrivateKey, bool)

Match attempts to match a list of addresses up to the provided threshold

func (*Keychain) New 

func (kc *Keychain) New() (*slhdsa.PrivateKey, error)

New generates a new SLH-DSA-SHA2-192f key pair and adds it to the keychain

func (*Keychain) Spend 

func (kc *Keychain) Spend(out verify.Verifiable, time uint64) (verify.Verifiable, []*slhdsa.PrivateKey, error)

Spend attempts to create an input for the given output

type MintOperation 

type MintOperation struct {
	MintInput      Input          `serialize:"true" json:"mintInput"`
	MintOutput     MintOutput     `serialize:"true" json:"mintOutput"`
	TransferOutput TransferOutput `serialize:"true" json:"transferOutput"`
}

func (*MintOperation) Cost 

func (op *MintOperation) Cost() (uint64, error)

func (*MintOperation) Outs 

func (op *MintOperation) Outs() []verify.State

func (*MintOperation) Verify 

func (op *MintOperation) Verify() error

type MintOutput 

type MintOutput struct {
	verify.IsState `serialize:"-" json:"-"`

	OutputOwners `serialize:"true"`
}

func (*MintOutput) Verify 

func (out *MintOutput) Verify() error

type OutputOwners 

type OutputOwners struct {
	// Level indicates the SLH-DSA parameter set for all addresses
	Level SecurityLevel `serialize:"true" json:"securityLevel"`
	// Locktime is the Unix timestamp after which this output can be spent
	Locktime uint64 `serialize:"true" json:"locktime"`
	// Threshold is the number of signatures required to spend
	Threshold uint32 `serialize:"true" json:"threshold"`
	// Addrs are the SLH-DSA public keys that can sign to spend
	Addrs [][]byte `serialize:"true" json:"addresses"`
}

OutputOwners describes who can spend an output locked with SLH-DSA keys.

func (*OutputOwners) Addresses 

func (out *OutputOwners) Addresses() []ids.ShortID

Addresses returns short IDs derived from the SLH-DSA public keys. Public keys are hashed via SHA256+RIPEMD160 to produce 20-byte addresses.

func (*OutputOwners) Equals 

func (out *OutputOwners) Equals(other *OutputOwners) bool

Equals returns true if the provided owners create the same condition

func (*OutputOwners) MarshalJSON 

func (out *OutputOwners) MarshalJSON() ([]byte, error)

MarshalJSON marshals the output owners to JSON

func (*OutputOwners) Verify 

func (out *OutputOwners) Verify() error

Verify validates the output owners structure

type SecurityLevel 

type SecurityLevel uint8

SecurityLevel indicates the SLH-DSA parameter set 

const (
	// SecLevelSLH128f is 128-bit security with fast signing
	SecLevelSLH128f SecurityLevel = iota
	// SecLevelSLH192f is 192-bit security with fast signing (recommended default)
	SecLevelSLH192f
	// SecLevelSLH256f is 256-bit security with fast signing
	SecLevelSLH256f
)

func (SecurityLevel) PubKeyLen 

func (s SecurityLevel) PubKeyLen() int

PubKeyLen returns the public key length for this security level

func (SecurityLevel) SignatureLen 

func (s SecurityLevel) SignatureLen() int

SignatureLen returns the signature length for this security level

func (SecurityLevel) String 

func (s SecurityLevel) String() string

String returns the human-readable name

type TestTx 

type TestTx struct{ UnsignedBytes []byte }

TestTx is a minimal implementation of a Tx

func (*TestTx) Bytes 

func (tx *TestTx) Bytes() []byte

Bytes returns UnsignedBytes

type TestVM 

type TestVM struct {
	Clk   mockable.Clock
	Codec codec.Registry
	Log   log.Logger
}

TestVM is a minimal implementation of a VM

func (*TestVM) Clock 

func (vm *TestVM) Clock() *mockable.Clock

func (*TestVM) CodecRegistry 

func (vm *TestVM) CodecRegistry() codec.Registry

func (*TestVM) Logger 

func (vm *TestVM) Logger() log.Logger

type TransferInput 

type TransferInput struct {
	Amt   uint64 `serialize:"true" json:"amount"`
	Input `serialize:"true"`
}

func (*TransferInput) Amount 

func (in *TransferInput) Amount() uint64

Amount returns the quantity of the asset this input produces

func (*TransferInput) InitRuntime 

func (*TransferInput) InitRuntime(*runtime.Runtime)

func (*TransferInput) Verify 

func (in *TransferInput) Verify() error

Verify this input is syntactically valid

type TransferOutput 

type TransferOutput struct {
	verify.IsState `serialize:"-" json:"-"`

	Amt          uint64 `serialize:"true" json:"amount"`
	OutputOwners `serialize:"true"`
}

func (*TransferOutput) Amount 

func (out *TransferOutput) Amount() uint64

Amount returns the quantity of the asset this output consumes

func (*TransferOutput) Owners 

func (out *TransferOutput) Owners() interface{}

func (*TransferOutput) Verify 

func (out *TransferOutput) Verify() error

type UnsignedTx 

type UnsignedTx interface {
	Bytes() []byte
}

UnsignedTx that this Fx is supporting

type VM 

type VM interface {
	CodecRegistry() codec.Registry
	Clock() *mockable.Clock
	Logger() log.Logger
}

VM that this Fx must be run by

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.