Crate nectar_postage_issuer 

Postage stamp issuing and signing for Ethereum Swarm.

This crate provides the issuing and signing functionality for postage stamps, designed for use by CLI tools (like dipper) that create and sign stamps.

For verification-only use cases (like vertex nodes), use nectar-postage directly.

Immutable and mutable issuance

Immutable batches are fill-only: every slot is written at most once and a full bucket is refused. Use MemoryIssuer (or ShardedIssuer for parallel stamping). Their from_batch constructors deliberately refuse a mutable batch with IssuerError::MutableNotSupported, so a ring is never produced by accident from the generic constructor.

Mutable batches are overwrite-aware: a later chunk may reuse the slot held by an older one. This is the ring issuance in RingIssuer (and ShardedRingIssuer for parallel stamping), and it must be requested by name. A ring carries its reservation policy in a type parameter so a reserved-blind ring can never be used in a self-hosting context:

• RingIssuer::external builds a RingIssuer<Unreserved> for external tracking: the caller keeps usage state outside the batch and nothing in the batch is protected.
• RingIssuer::reserved builds a RingIssuer<Reserved> for self-hosting: the protected slots come from nectar-postage-usage, and the ring never re-emits one even after it wraps.

There is no public conversion from Unreserved to Reserved, so a self-hosting context that demands a RingIssuer<Reserved> cannot be handed a reserved-blind ring. The following does not compile:

use nectar_postage_issuer::{RingIssuer, Reserved, Unreserved};
use nectar_postage::Batch;
use alloy_primitives::B256;

fn self_hosting_sink(_ring: RingIssuer<Reserved>) {}

let batch = Batch::new(B256::ZERO, 0, 0, Default::default(), 20, 16, false);
let unreserved: RingIssuer<Unreserved> = RingIssuer::external(&batch).unwrap();
// A reserved-blind ring is not a Reserved ring, and there is no conversion.
self_hosting_sink(unreserved);

Features

• std (default) - Enables standard library support
• serde - Enables serialization/deserialization
• local-signer - Enables local key signing with alloy-signer-local
• parallel - Enables parallel signing with rayon

Example

use nectar_postage_issuer::{BatchStamper, MemoryIssuer, Stamper};
use nectar_primitives::SwarmAddress;
use alloy_primitives::B256;
use alloy_signer_local::PrivateKeySigner;

// Create an issuer for a batch
let issuer = MemoryIssuer::new(B256::ZERO, 20, 16);

// Combine with any SignerSync implementation to create a stamper
let signer = PrivateKeySigner::random();
let mut stamper = BatchStamper::new(issuer, signer);

// Stamp chunks
let stamp = stamper.stamp(&chunk_address)?;

Structs

Batch

A postage batch represents a prepaid storage allocation in the Swarm network.

BatchParams

Parameters for creating a new batch.

BatchStamper

A stamper that combines an issuer (for bucket tracking) with a signer.

CounterTable

Per-bucket slot counters in the [0, capacity] deferred-wrap representation.

CreateResult

The result of creating a batch.

IssuerRegistry

A registry of dilutable issuers keyed by BatchId.

MemoryBatchFactory

An in-memory batch factory for testing.

MemoryIssuer

An in-memory stamp issuer that tracks bucket utilization.

PostageContext

Context for postage validation.

Reserved

A reservation policy that protects a fixed set of (bucket, index) slots.

RingIssuer

A mutable (ring) stamp issuer.

ShardedIssuer

A sharded stamp issuer for high-throughput parallel stamping.

ShardedRingIssuer

A sharded mutable (ring) stamp issuer for high-throughput parallel stamping.

Stamp

A postage stamp represents proof of payment for storing a chunk.

StampDigest

The digest that must be signed to create a valid stamp.

StampIndex

A stamp index representing the position of a chunk within a batch.

StampResult

Result of a parallel stamp operation.

StampedChunk

A chunk together with its postage stamp.

StoreValidator

A validator that uses a BatchStore for validation.

Unreserved

A reservation policy that protects nothing.

Enums

BatchEvent

Events emitted by the postage stamp contract.

BatchStoreError

Errors that can occur when working with a batch store.

CounterError

An error advancing or constructing a CounterTable.

CounterMode

Whether a CounterTable fills each bucket once or wraps it as a ring.

IssuerError

Errors that can occur when constructing a stamp issuer.

SigningError

Errors that can occur when signing stamps.

StampError

Errors that can occur when working with stamps.

Constants

STAMP_SIZE

The size of a serialized stamp in bytes.

Traits

BatchEventHandler

A handler for batch events.

BatchFactory

A trait for creating postage batches.

BatchStore

A trait for storing and retrieving batches.

BatchStoreExt

Extension methods for BatchStore.

Dilutable

An issuer whose per-bucket capacity can be grown by an on-chain dilution.

Reservation

A reservation policy: answers whether a given (bucket, index) slot is protected and must never be emitted by a ring.

SnapshotStore

A cache for recovered issuer snapshot state, keyed by BatchId.

StampIssuer

A trait for managing stamp issuance within a batch.

StampValidator

A trait for validating postage stamps.

Stamper

A trait for entities that can stamp chunks.

Functions

calculate_bucket

Calculates which collision bucket a chunk belongs to based on its address.

current_timestamp

Returns the current timestamp in nanoseconds since the Unix epoch.

sign_stamps_parallel

Signs multiple chunks in parallel using the provided signer.

Type Aliases

BatchId

A 32-byte batch identifier.

StampBytes

A serialized postage stamp as a fixed-size byte array.

VerifyingKey

ECDSA/secp256k1 verification key (i.e. public key)