Help us shape the future of Go! Take the 2026 Go Developer Survey

keyvm

package
v1.24.29 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: 32 Imported by: 0

Documentation

Overview

Package kmsvm implements the KMS Virtual Machine (K-Chain) for distributed key management using ML-KEM post-quantum cryptography and threshold sharing.

Index

Constants

View Source 
const (
	TxTypeCreateKey     = 1
	TxTypeDeleteKey     = 2
	TxTypeDistributeKey = 3
	TxTypeReshareKey    = 4
	TxTypeUpdateKeyMeta = 5
	TxTypeRevokeKey     = 6
)

Transaction types

View Source 
const (
	// Version of the K-Chain VM
	Version = "1.0.0"

	// VMName is the human-readable name of K-Chain VM
	VMName = "keyvm"

	// MaxParallelOperations is the maximum number of concurrent crypto operations
	MaxParallelOperations = 100

	// SharePrefix is the database prefix for key shares
	SharePrefix = "share:"

	// KeyPrefix is the database prefix for key metadata
	KeyPrefix = "key:"
)

Variables

View Source 
var (
	ErrInvalidTxType    = errors.New("invalid transaction type")
	ErrInvalidTxData    = errors.New("invalid transaction data")
	ErrTxAlreadyExists  = errors.New("transaction already exists")
	ErrKeyNotFound      = errors.New("key not found")
	ErrKeyAlreadyExists = errors.New("key already exists")
	ErrUnauthorized     = errors.New("unauthorized operation")
)
View Source 
var VMID = ids.ID{'k', 'e', 'y', 'v', 'm'}

VMID is the unique identifier for KeyVM (K-Chain)

Functions

This section is empty.

Types

type AlgorithmInfo 

type AlgorithmInfo struct {
	Name             string   `json:"name"`
	Type             string   `json:"type"`
	SecurityLevel    int      `json:"securityLevel"`
	KeySize          int      `json:"keySize"`
	SignatureSize    int      `json:"signatureSize"`
	PostQuantum      bool     `json:"postQuantum"`
	ThresholdSupport bool     `json:"thresholdSupport"`
	Description      string   `json:"description"`
	Standards        []string `json:"standards"`
}

AlgorithmInfo describes a supported algorithm.

type Block 

type Block struct {
	// contains filtered or unexported fields
}

Block represents a K-Chain block containing key management transactions.

func (*Block) Accept 

func (b *Block) Accept(ctx context.Context) error

Accept accepts the block as final.

func (*Block) Bytes 

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

Bytes serializes the block to bytes.

func (*Block) Height 

func (b *Block) Height() uint64

Height returns the block's height.

func (*Block) ID 

func (b *Block) ID() ids.ID

ID returns the block's unique identifier.

func (*Block) Parent 

func (b *Block) Parent() ids.ID

Parent returns the parent block's ID (alias for ParentID).

func (*Block) ParentID 

func (b *Block) ParentID() ids.ID

ParentID returns the parent block's ID.

func (*Block) Reject 

func (b *Block) Reject(ctx context.Context) error

Reject rejects the block.

func (*Block) Status 

func (b *Block) Status() uint8

Status returns the block's status (0=Processing, 1=Accepted, 2=Rejected).

func (*Block) Timestamp 

func (b *Block) Timestamp() time.Time

Timestamp returns the block's timestamp.

func (*Block) Verify 

func (b *Block) Verify(ctx context.Context) error

Verify verifies the block is valid.

type CreateKeyArgs 

type CreateKeyArgs struct {
	Name        string   `json:"name"`
	Algorithm   string   `json:"algorithm"`
	Threshold   int      `json:"threshold"`
	TotalShares int      `json:"totalShares"`
	Tags        []string `json:"tags"`
}

CreateKeyArgs contains arguments for CreateKey.

type CreateKeyPayload 

type CreateKeyPayload struct {
	Name        string
	Algorithm   string
	Threshold   int
	TotalShares int
	Tags        []string
}

CreateKeyPayload represents the payload for a CreateKey transaction.

type CreateKeyReply 

type CreateKeyReply struct {
	Key       KeyMetadataReply `json:"key"`
	PublicKey string           `json:"publicKey"`
	ShareIDs  []string         `json:"shareIds"`
}

CreateKeyReply contains the response for CreateKey.

type DeleteKeyArgs 

type DeleteKeyArgs struct {
	ID    string `json:"id"`
	Force bool   `json:"force"`
}

DeleteKeyArgs contains arguments for DeleteKey.

type DeleteKeyPayload 

type DeleteKeyPayload struct {
	Force bool
}

DeleteKeyPayload represents the payload for a DeleteKey transaction.

type DeleteKeyReply 

type DeleteKeyReply struct {
	Success       bool     `json:"success"`
	DeletedShares []string `json:"deletedShares"`
}

DeleteKeyReply contains the response for DeleteKey.

type DistributeKeyPayload 

type DistributeKeyPayload struct {
	Validators []string
	Threshold  int
}

DistributeKeyPayload represents the payload for a DistributeKey transaction.

type EncryptArgs 

type EncryptArgs struct {
	KeyID     string `json:"keyId"`
	Plaintext string `json:"plaintext"` // Base64-encoded
}

EncryptArgs contains arguments for Encrypt.

type EncryptReply 

type EncryptReply struct {
	Ciphertext string `json:"ciphertext"` // Base64-encoded
	Nonce      string `json:"nonce"`
	Tag        string `json:"tag"`
}

EncryptReply contains the response for Encrypt.

type Factory 

type Factory struct {
	config.Config
}

Factory implements vms.Factory interface for creating K-Chain VM instances.

func NewDefaultFactory 

func NewDefaultFactory() *Factory

NewDefaultFactory creates a new K-Chain VM factory with default configuration.

func NewFactory 

func NewFactory(cfg config.Config) *Factory

NewFactory creates a new K-Chain VM factory with the given configuration.

func (*Factory) New 

func (f *Factory) New(logger log.Logger) (interface{}, error)

New creates a new K-Chain VM instance.

type Genesis 

type Genesis struct {
	Version   int    `json:"version"`
	Message   string `json:"message"`
	Timestamp int64  `json:"timestamp"`
}

Genesis represents the genesis state

type GetKeyByIDArgs 

type GetKeyByIDArgs struct {
	ID string `json:"id"`
}

GetKeyByIDArgs contains arguments for GetKeyByID.

type GetKeyByIDReply 

type GetKeyByIDReply struct {
	KeyMetadataReply
}

GetKeyByIDReply contains the response for GetKeyByID.

type GetKeyByNameArgs 

type GetKeyByNameArgs struct {
	Name string `json:"name"`
}

GetKeyByNameArgs contains arguments for GetKeyByName.

type GetKeyByNameReply 

type GetKeyByNameReply struct {
	KeyMetadataReply
}

GetKeyByNameReply contains the response for GetKeyByName.

type HealthArgs 

type HealthArgs struct{}

HealthArgs contains arguments for Health.

type HealthReply 

type HealthReply struct {
	Healthy    bool             `json:"healthy"`
	Version    string           `json:"version"`
	Validators map[string]bool  `json:"validators"`
	Latency    map[string]int64 `json:"latency"`
}

HealthReply contains the response for Health.

type KeyMetadata 

type KeyMetadata struct {
	ID          ids.ID            `json:"id"`
	Name        string            `json:"name"`
	Algorithm   string            `json:"algorithm"`
	KeyType     string            `json:"keyType"`
	PublicKey   []byte            `json:"publicKey"`
	Threshold   int               `json:"threshold"`
	TotalShares int               `json:"totalShares"`
	Validators  []string          `json:"validators"`
	CreatedAt   time.Time         `json:"createdAt"`
	UpdatedAt   time.Time         `json:"updatedAt"`
	Status      string            `json:"status"`
	Tags        []string          `json:"tags"`
	Metadata    map[string]string `json:"metadata"`
}

KeyMetadata stores information about a distributed key.

type KeyMetadataReply 

type KeyMetadataReply struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	Algorithm   string   `json:"algorithm"`
	KeyType     string   `json:"keyType"`
	PublicKey   string   `json:"publicKey"`
	Threshold   int      `json:"threshold"`
	TotalShares int      `json:"totalShares"`
	CreatedAt   string   `json:"createdAt"`
	UpdatedAt   string   `json:"updatedAt"`
	Status      string   `json:"status"`
	Tags        []string `json:"tags"`
}

KeyMetadataReply is the JSON representation of KeyMetadata.

type KeyShare 

type KeyShare struct {
	KeyID       ids.ID `json:"keyId"`
	ShareIndex  int    `json:"shareIndex"`
	ShareData   []byte `json:"shareData"` // Encrypted share
	ValidatorID string `json:"validatorId"`
	Timestamp   int64  `json:"timestamp"`
}

KeyShare represents a share of a distributed key.

type ListAlgorithmsArgs 

type ListAlgorithmsArgs struct{}

ListAlgorithmsArgs contains arguments for ListAlgorithms.

type ListAlgorithmsReply 

type ListAlgorithmsReply struct {
	Algorithms []AlgorithmInfo `json:"algorithms"`
}

ListAlgorithmsReply contains the response for ListAlgorithms.

type ListKeysArgs 

type ListKeysArgs struct {
	Offset    int    `json:"offset"`
	Limit     int    `json:"limit"`
	Algorithm string `json:"algorithm"`
	Status    string `json:"status"`
}

ListKeysArgs contains arguments for ListKeys.

type ListKeysReply 

type ListKeysReply struct {
	Keys  []KeyMetadataReply `json:"keys"`
	Total int                `json:"total"`
}

ListKeysReply contains the response for ListKeys.

type ReshareKeyPayload 

type ReshareKeyPayload struct {
	NewValidators []string
	NewThreshold  int
}

ReshareKeyPayload represents the payload for a ReshareKey transaction.

type RevokeKeyPayload 

type RevokeKeyPayload struct {
	Reason string
}

RevokeKeyPayload represents the payload for a RevokeKey transaction.

type Service 

type Service struct {
	// contains filtered or unexported fields
}

Service provides JSON-RPC endpoints for the K-Chain VM.

func (*Service) CreateKey 

func (s *Service) CreateKey(r *http.Request, args *CreateKeyArgs, reply *CreateKeyReply) error

CreateKey creates a new distributed key.

func (*Service) DeleteKey 

func (s *Service) DeleteKey(r *http.Request, args *DeleteKeyArgs, reply *DeleteKeyReply) error

DeleteKey deletes a key.

func (*Service) Encrypt 

func (s *Service) Encrypt(r *http.Request, args *EncryptArgs, reply *EncryptReply) error

Encrypt encrypts data.

func (*Service) GetKeyByID 

func (s *Service) GetKeyByID(r *http.Request, args *GetKeyByIDArgs, reply *GetKeyByIDReply) error

GetKeyByID retrieves a key by ID.

func (*Service) GetKeyByName 

func (s *Service) GetKeyByName(r *http.Request, args *GetKeyByNameArgs, reply *GetKeyByNameReply) error

GetKeyByName retrieves a key by name.

func (*Service) Health 

func (s *Service) Health(r *http.Request, args *HealthArgs, reply *HealthReply) error

Health checks service health.

func (*Service) ListAlgorithms 

func (s *Service) ListAlgorithms(r *http.Request, args *ListAlgorithmsArgs, reply *ListAlgorithmsReply) error

ListAlgorithms lists supported algorithms.

func (*Service) ListKeys 

func (s *Service) ListKeys(r *http.Request, args *ListKeysArgs, reply *ListKeysReply) error

ListKeys lists all keys.

type Transaction 

type Transaction struct {
	// contains filtered or unexported fields
}

Transaction represents a K-Chain transaction.

func NewTransaction 

func NewTransaction(txType uint8, keyID ids.ID, payload []byte, sender []byte) *Transaction

NewTransaction creates a new transaction.

func ParseTransaction 

func ParseTransaction(data []byte) (*Transaction, error)

ParseTransaction deserializes a transaction from bytes.

func (*Transaction) Bytes 

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

Bytes serializes the transaction to bytes.

func (*Transaction) Execute 

func (tx *Transaction) Execute(ctx context.Context, vm *VM) error

Execute executes the transaction against the VM state.

func (*Transaction) ID 

func (tx *Transaction) ID() ids.ID

ID returns the transaction's unique identifier.

func (*Transaction) KeyID 

func (tx *Transaction) KeyID() ids.ID

KeyID returns the key ID this transaction operates on.

func (*Transaction) Payload 

func (tx *Transaction) Payload() []byte

Payload returns the transaction payload.

func (*Transaction) Timestamp 

func (tx *Transaction) Timestamp() time.Time

Timestamp returns the transaction timestamp.

func (*Transaction) Type 

func (tx *Transaction) Type() uint8

Type returns the transaction type.

func (*Transaction) Verify 

func (tx *Transaction) Verify(ctx context.Context) error

Verify verifies the transaction is valid.

type UpdateKeyMetaPayload 

type UpdateKeyMetaPayload struct {
	Name   string
	Tags   []string
	Status string
}

UpdateKeyMetaPayload represents the payload for an UpdateKeyMeta transaction.

type VM 

type VM struct {
	config.Config
	// contains filtered or unexported fields
}

VM implements the K-Chain Virtual Machine.

func (*VM) BuildBlock 

func (vm *VM) BuildBlock(ctx context.Context) (chain.Block, error)

BuildBlock builds a new block from pending transactions.

func (*VM) Connected 

func (vm *VM) Connected(ctx context.Context, nodeID ids.NodeID, nodeVersion *chain.VersionInfo) error

Connected handles node connection events.

func (*VM) CreateHandlers 

func (vm *VM) CreateHandlers(ctx context.Context) (map[string]http.Handler, error)

CreateHandlers returns HTTP handlers for the VM.

func (*VM) CreateKey 

func (vm *VM) CreateKey(ctx context.Context, name, algorithm string, threshold, totalShares int) (*KeyMetadata, error)

CreateKey creates a new distributed key.

func (*VM) CreateStaticHandlers 

func (vm *VM) CreateStaticHandlers(ctx context.Context) (map[string]http.Handler, error)

CreateStaticHandlers returns static HTTP handlers.

func (*VM) DeleteKey 

func (vm *VM) DeleteKey(ctx context.Context, keyID ids.ID) error

DeleteKey deletes a key and its shares with secure zeroing of sensitive material.

func (*VM) Disconnected 

func (vm *VM) Disconnected(ctx context.Context, nodeID ids.NodeID) error

Disconnected handles node disconnection events.

func (*VM) Encrypt 

func (vm *VM) Encrypt(ctx context.Context, keyID ids.ID, plaintext []byte) ([]byte, []byte, error)

Encrypt encrypts data using the key's ML-KEM public key.

func (*VM) GetBlock 

func (vm *VM) GetBlock(ctx context.Context, blockID ids.ID) (chain.Block, error)

GetBlock retrieves a block by ID.

func (*VM) GetBlockIDAtHeight 

func (vm *VM) GetBlockIDAtHeight(ctx context.Context, height uint64) (ids.ID, error)

GetBlockIDAtHeight returns the block ID at a given height.

func (*VM) GetKey 

func (vm *VM) GetKey(ctx context.Context, keyID ids.ID) (*KeyMetadata, error)

GetKey retrieves key metadata by ID.

func (*VM) GetKeyByName 

func (vm *VM) GetKeyByName(ctx context.Context, name string) (*KeyMetadata, error)

GetKeyByName retrieves key metadata by name.

func (*VM) HealthCheck 

func (vm *VM) HealthCheck(ctx context.Context) (chain.HealthResult, error)

HealthCheck returns VM health status.

func (*VM) Initialize 

func (vm *VM) Initialize(ctx context.Context, init vmcore.Init) error

Initialize initializes the K-Chain VM with the unified Init struct.

func (*VM) LastAccepted 

func (vm *VM) LastAccepted(ctx context.Context) (ids.ID, error)

LastAccepted returns the last accepted block ID.

func (*VM) ListKeys 

func (vm *VM) ListKeys(ctx context.Context) ([]*KeyMetadata, error)

ListKeys lists all keys.

func (*VM) NewHTTPHandler 

func (vm *VM) NewHTTPHandler(ctx context.Context) (http.Handler, error)

NewHTTPHandler returns an HTTP handler for the VM.

func (*VM) ParseBlock 

func (vm *VM) ParseBlock(ctx context.Context, blockBytes []byte) (chain.Block, error)

ParseBlock parses a block from bytes.

func (*VM) SetPreference 

func (vm *VM) SetPreference(ctx context.Context, id ids.ID) error

SetPreference sets the preferred block tip.

func (*VM) SetState 

func (vm *VM) SetState(ctx context.Context, state uint32) error

SetState sets the VM state.

func (*VM) Shutdown 

func (vm *VM) Shutdown(ctx context.Context) error

Shutdown shuts down the VM with secure cleanup of sensitive key material.

func (*VM) Version 

func (vm *VM) Version(ctx context.Context) (string, error)

Version returns the VM version.

func (*VM) WaitForEvent 

func (vm *VM) WaitForEvent(ctx context.Context) (vmcore.Message, error)

WaitForEvent waits for a VM event.

Source Files

View all Source files

Directories

Path Synopsis

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.