protocol

Documentation

Index

• Constants
• Variables
• func ComputeItemID(item StoredItem) string
• func DeleteReceiptSigningBytes(receipt DeleteReceipt) []byte
• func HasLeadingZeroBits(sum []byte, difficulty uint8) bool
• func ItemCommitment(item StoredItem) []byte
• func ProofSigningBytes(proof StorageProof) []byte
• func ReceiptSigningBytes(receipt StorageReceipt) []byte
• func ValidRouteTag(routeTag string) bool
• func ValidateItem(item StoredItem, now time.Time, maxBytes int) error
• func ValidateNodeParameters(parameters NodeParameters) error
• func VerifyWork(item StoredItem, now time.Time, epochSeconds int64, minimumDifficulty uint8) error
• func WorkDigest(item StoredItem, proof WorkProof) [sha256.Size]byte
• type DeleteReceipt
• type DeleteRequest
• type DeviceDescriptor
• type DeviceSyncEnvelope
• type DirectCiphertext
• type FetchRequest
• type FetchResponse
• type FileChunk
• type FileManifest
• type HybridSignature
• type NodeParameters
• type NodePublicIdentity
• type ProofRequest
• type StorageProof
• type StorageReceipt
• type StoredItem
• type WorkProof
  • func SolveWork(ctx context.Context, item StoredItem, epochSeconds int64, difficulty uint8) (WorkProof, error)

Constants

const (
	ProtocolVersion = 1
	// FixedItemRetention is the protocol-wide storage window. Every stored
	// item expires exactly this long after creation; nodes reject any other
	// expiry. Earlier removal is only possible through the delete capability.
	FixedItemRetention   = 60 * 24 * time.Hour
	DefaultMaxItemBytes  = 320 * 1024
	DefaultMaxFileBytes  = 64 * 1024 * 1024
	DefaultFileChunkSize = 256 * 1024
	CapabilityBytes      = 32
	MaxRouteTagsPerFetch = 256
	DefaultMaxFetchItems = 512
	DefaultMaxFetchBytes = 8 * 1024 * 1024
	MinWorkEpochSeconds  = 60
	MaxWorkEpochSeconds  = 24 * 60 * 60
	MaxWorkDifficulty    = 24
	MaxProofSampleBytes  = 16 * 1024
)

Variables

var (
	ErrInvalidItem      = errors.New("invalid stored item")
	ErrInvalidRetention = errors.New("item expiry must equal the fixed retention window")
	ErrItemTooLarge     = errors.New("item exceeds node maximum")
)

var ErrInvalidWork = errors.New("invalid proof of work")

Functions

func ComputeItemID

func ComputeItemID(item StoredItem) string

func DeleteReceiptSigningBytes

func DeleteReceiptSigningBytes(receipt DeleteReceipt) []byte

func HasLeadingZeroBits

func HasLeadingZeroBits(sum []byte, difficulty uint8) bool

func ItemCommitment

func ItemCommitment(item StoredItem) []byte

func ProofSigningBytes

func ProofSigningBytes(proof StorageProof) []byte

func ReceiptSigningBytes

func ReceiptSigningBytes(receipt StorageReceipt) []byte

func ValidRouteTag

func ValidRouteTag(routeTag string) bool

func ValidateItem

func ValidateItem(item StoredItem, now time.Time, maxBytes int) error

func ValidateNodeParameters

func ValidateNodeParameters(parameters NodeParameters) error

func VerifyWork

func VerifyWork(item StoredItem, now time.Time, epochSeconds int64, minimumDifficulty uint8) error

func WorkDigest

func WorkDigest(item StoredItem, proof WorkProof) [sha256.Size]byte

Types

type DeleteReceipt

type DeleteReceipt struct {
	NodeID    string          `json:"node_id"`
	ItemID    string          `json:"item_id"`
	DeletedAt time.Time       `json:"deleted_at"`
	Signature HybridSignature `json:"signature"`
}

type DeleteRequest

type DeleteRequest struct {
	ItemID      string `json:"item_id"`
	DeleteToken []byte `json:"delete_token"`
}

type DeviceDescriptor

type DeviceDescriptor struct {
	DeviceID      string             `json:"device_id"`
	AccountID     string             `json:"account_id"`
	HPKEPublicKey []byte             `json:"hpke_public_key"`
	SigningKey    NodePublicIdentity `json:"signing_key"`
}

type DeviceSyncEnvelope

type DeviceSyncEnvelope struct {
	DeviceID string           `json:"device_id"`
	Payload  DirectCiphertext `json:"payload"`
}

type DirectCiphertext

type DirectCiphertext struct {
	Suite         string `json:"suite"`
	Encapsulation []byte `json:"encapsulation"`
	Ciphertext    []byte `json:"ciphertext"`
}

type FetchRequest

type FetchRequest struct {
	RouteTags []string `json:"route_tags"`
}

type FetchResponse

type FetchResponse struct {
	Items []StoredItem `json:"items"`
}

type FileChunk

type FileChunk struct {
	Index      int    `json:"index"`
	RouteTag   string `json:"route_tag"`
	CipherHash []byte `json:"cipher_hash"`
	CipherSize int    `json:"cipher_size"`
}

type FileManifest

type FileManifest struct {
	Version        uint8       `json:"version"`
	FileID         string      `json:"file_id"`
	Name           string      `json:"name"`
	MediaType      string      `json:"media_type"`
	PlaintextBytes int64       `json:"plaintext_bytes"`
	ChunkSize      int         `json:"chunk_size"`
	Chunks         []FileChunk `json:"chunks"`
}

type HybridSignature

type HybridSignature struct {
	Ed25519 []byte `json:"ed25519"`
	MLDSA65 []byte `json:"ml_dsa_65"`
}

type NodeParameters

type NodeParameters struct {
	ProtocolVersion uint8 `json:"protocol_version"`
	Difficulty      uint8 `json:"difficulty"`
	EpochSeconds    int64 `json:"epoch_seconds"`
	MaxItemBytes    int   `json:"max_item_bytes"`
	StorageUsed     int64 `json:"storage_used"`
	StorageCapacity int64 `json:"storage_capacity"`
}

NodeParameters intentionally carries no retention field: the storage window is a fixed protocol constant, not a negotiable node parameter.

type NodePublicIdentity

type NodePublicIdentity struct {
	NodeID          string `json:"node_id"`
	Ed25519Public   []byte `json:"ed25519_public"`
	MLDSA65Public   []byte `json:"ml_dsa_65_public"`
	ProtocolVersion uint8  `json:"protocol_version"`
}

type ProofRequest

type ProofRequest struct {
	ItemID string `json:"item_id"`
	Nonce  []byte `json:"nonce"`
	Offset int64  `json:"offset"`
	Length int    `json:"length"`
}

type StorageProof

type StorageProof struct {
	NodeID      string          `json:"node_id"`
	ItemID      string          `json:"item_id"`
	Nonce       []byte          `json:"nonce"`
	Offset      int64           `json:"offset"`
	Sample      []byte          `json:"sample"`
	PayloadHash []byte          `json:"payload_hash"`
	ProvedAt    time.Time       `json:"proved_at"`
	Signature   HybridSignature `json:"signature"`
}

type StorageReceipt

type StorageReceipt struct {
	NodeID      string          `json:"node_id"`
	ItemID      string          `json:"item_id"`
	PayloadHash []byte          `json:"payload_hash"`
	StoredAt    time.Time       `json:"stored_at"`
	ExpiresAt   time.Time       `json:"expires_at"`
	Signature   HybridSignature `json:"signature"`
}

type StoredItem

type StoredItem struct {
	Version         uint8     `json:"version"`
	ItemID          string    `json:"item_id"`
	RouteTag        string    `json:"route_tag"`
	CreatedAt       time.Time `json:"created_at"`
	ExpiresAt       time.Time `json:"expires_at"`
	DeleteTokenHash []byte    `json:"delete_token_hash"`
	Payload         []byte    `json:"payload"`
	Work            WorkProof `json:"work"`
}

StoredItem contains opaque ciphertext. RouteTag is a one-time capability, not an account or user identifier. DeleteTokenHash authorizes deletion without disclosing an identity to the node.

type WorkProof

type WorkProof struct {
	Epoch      int64  `json:"epoch"`
	Nonce      uint64 `json:"nonce"`
	Difficulty uint8  `json:"difficulty"`
}

func SolveWork

func SolveWork(ctx context.Context, item StoredItem, epochSeconds int64, difficulty uint8) (WorkProof, error)