Class BatchExpiryPolicy

Namespace

NArk.Core.Batches

Assembly

NArk.Core.dll

Bounds the batch expiry an Arkade server declares when it opens a batch, before the client commits to it.

public sealed record BatchExpiryPolicy : IEquatable<BatchExpiryPolicy>

Inheritance

object

BatchExpiryPolicy

Implements

IEquatable<BatchExpiryPolicy>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The expiry becomes the timelock of the sweep leaf — the operator's only unilateral path out of the batch output. Tree validation cannot vouch for it, because the sweep root it checks against is derived from that same expiry, so this policy is the only check on the value. See the "Batch Expiry Validation" article for the attack it prevents.

Constructors

BatchExpiryPolicy(bool, TimeSpan, int)

Builds a policy.

public BatchExpiryPolicy(bool allowBlockTypedExpiry, TimeSpan minimumExpiry, int minimumExpiryBlocks)

Parameters

allowBlockTypedExpiry bool

Whether a block-typed expiry is acceptable.

minimumExpiry TimeSpan

Shortest acceptable seconds-typed expiry. Must be at least one BIP-68 granularity unit (SecondsGranularity seconds).

minimumExpiryBlocks int

Shortest acceptable block-typed expiry, in blocks.

Exceptions

ArgumentOutOfRangeException

minimumExpiryBlocks is zero or negative, or minimumExpiry is below one granularity unit. The floors can be lowered but not disabled.

Fields

SecondsGranularity

BIP-68 encodes seconds-typed relative timelocks in units of 512 seconds.

public const int SecondsGranularity = 512

Field Value

int

Properties

AllowBlockTypedExpiry

Whether a block-typed expiry is acceptable. Only regtest allows one by default.

public bool AllowBlockTypedExpiry { get; }

Property Value

bool

MinimumExpiry

Shortest acceptable seconds-typed expiry.

public TimeSpan MinimumExpiry { get; }

Property Value

TimeSpan

MinimumExpiryBlocks

Shortest acceptable block-typed expiry, in blocks.

public int MinimumExpiryBlocks { get; }

Property Value

int

Methods

Encode(long)

Applies the BIP-68 encoding the Arkade protocol uses for batch expiries: values below 512 are a block count, everything else is a number of seconds rounded down to a multiple of 512.

public static Sequence Encode(long declaredExpiry)

Parameters

declaredExpiry long

The expiry exactly as the server declared it.

Returns

Sequence

The encoded sequence.

Exceptions

InvalidBatchExpiryException

The value cannot be encoded as a relative timelock.

ForNetwork(Network, BatchExpiryOptions?)

Resolves the policy for a network, applying any caller overrides on top of the defaults.

public static BatchExpiryPolicy ForNetwork(Network network, BatchExpiryOptions? options = null)

Parameters

network Network

The network the Arkade server advertises.

options BatchExpiryOptions

Optional overrides; null properties keep the default.

Returns

BatchExpiryPolicy

The policy to enforce.

Remarks

Regtest allows a block-typed expiry with a 10-block floor, mirroring arkd, whose block-typed VTXO tree expiry is regtest-only; every other network requires a seconds-typed expiry of at least 24 hours. A server advertising "mutinynet" resolves to NBitcoin.Network.TestNet, so it gets the strict policy.

Exceptions

ArgumentOutOfRangeException

An override would disable rather than lower a floor. See the constructor for the bounds.

Validate(long, ILogger?)

Validates a declared batch expiry and returns the sequence to commit to the sweep leaf.

public Sequence Validate(long declaredExpiry, ILogger? logger = null)

Parameters

declaredExpiry long

The expiry exactly as the server declared it — RawBatchExpiry.

logger ILogger

Optional logger; receives a warning when the declared value is not encodable exactly.

Returns

Sequence

The encoded sequence, which is what the sweep leaf actually commits to.

Exceptions

InvalidBatchExpiryException

The expiry is not encodable, is block-typed where the policy forbids it, or falls below the floor.