Modes and package formats

A mode controls which forward transitions can be accepted. A package codec controls how the origin or witness is encoded. Its export representation controls whether that package is returned as text or bytes.

Choose S or X

Mode	Forward gap	Behavior
S · Skippable	1 through N − 1	Accepts a bounded skip over intermediate witnesses.
X · Adjacent-only	Exactly 1	Requires the immediately following transition.

Core defaults to S. With N = 5, S accepts gaps up to four and rejects a gap of five or more. X rejects a gap of two.

Run this complete example with ulda-core@1.0.1 installed:

compare-modes.mjs

import UldaSign from 'ulda-core';

async function checkTwoStepGap(mode) {
  const core = new UldaSign({ sign: { mode } });
  const origin0 = core.New();
  const origin2 = core.stepUp(core.stepUp(origin0));

  return core.verify(
    await core.sign(origin0),
    await core.sign(origin2),
  );
}

const skippable = await checkTwoStepGap('S');
const adjacentOnly = await checkTwoStepGap('X');
console.log({ skippable, adjacentOnly });
// { skippable: true, adjacentOnly: false }

Mode S does not reorder writes, merge competing branches or retain an unlimited history. The five-block illustration in Core Concepts shows S construction; X uses a different witness construction.

Use a consistent profile

The defaults can be written explicitly:

const core = new UldaSign({
  fmt: { export: 'hex' },
  sign: {
    N: 5,
    mode: 'S',
    hash: 'SHA-256',
    originSize: 256,
    pack: 'compactV1',
    ageBytes: 4,
  },
});

Participants in a stream must agree on the codec, mode, height, hash implementation and origin block size. originSize is measured in bits, not bytes.

The configuration layer does not validate every protocol policy constraint. Non-default X profiles require separate review in the current release, particularly when origin-block and digest lengths differ.

The Auth SDK uses a fixed compatible profile around Core. It defaults to X for content and always uses X for its master; changing standalone Core settings does not reconfigure an SDK resource.

compactV1

The default codec carries or implies the height, mode, hash identifier and unsigned state age. At age zero the age field is omitted; nonzero ages use a four-byte unsigned big-endian value, up to 4294967295.

The format does not encode package kind, origin block size, stream identity or payload identity. Canonical v1 packages leave reserved backup and future-mode flags unused.

See the compact header specification when implementing format tooling.

Hex, Base64 and bytes

Choose a representation with fmt.export:

Value	Returned representation
'hex'	Hexadecimal string; the default.
'base64'	Base64 string.
'bytes'	Uint8Array.

Representations do not change the underlying package codec or turn a private origin into public data.

Legacy packages

simpleSig is a compatibility codec that must be selected explicitly with sign.pack. The identifier 'v1' is its alias.

compactV1 and simpleSig have different headers. Core does not auto-detect them. A runtime configured for one codec must not be expected to decode the other.

The current SDK/server profile uses compactV1. Keep legacy compatibility experiments separate from that application protocol.

Hash implementations

Core delegates SHA-256, SHA-384 and SHA-512 to Web Crypto. SHA-1 remains available for compatibility and should not be chosen for new security designs.

Identifiers for SHA3, BLAKE3 and WHIRLPOOL do not imply bundled implementations. These require an external hasher and agreement between participants. See the hasher configuration before introducing one.