Advanced utilities and types

Use lower-level address, tag, timestamp, result, logging, and request utilities for custom integrations.

These are the small pieces the rest of the SDK is built from, exported because integrations need them too. None of them talks to the protocol on its own; they convert between the shapes the contracts use and the shapes an application shows — a Date to the Unix-seconds bigint every on-chain timestamp is expressed in, a typed string to a resolved address, an address to its ENS name or to a shortened form for display.

Tags are the largest group here. A V3 LOC may carry up to 512 bytes of reference data, recorded in its creation event so an integration can tie the LOC to an order or an account of its own. assembleTag builds one from named fields, getFixedTagBytes and TAG_MAX_BYTES say how much room the user-entered segments have left, and getTagByteLength and isTagAscii check a single value. Beyond tags, Result is the tagged union the single-value validators return, safeStringify is JSON.stringify that survives bigints, and Logger is the sink SDKContext writes diagnostics to.

Where a tag is stored, and why a direct chain read cannot return it, is in Where data comes from.

Building a tag from one fixed and one user-supplied field:

// A partner pins the first segment; the customer fills in the rest.
const fields: TagField[] = [
  { name: 'campaign', value: 'SPRING24' },
  { name: 'orderId' },
];

// Bytes left for user-entered segments: 512 minus fixed values and
// delimiters.
const remaining = TAG_MAX_BYTES - getFixedTagBytes(fields);
if (remaining < 0) {
  throw new Error('fixed segments alone exceed 512 bytes');
}

// "SPRING24|ORD-88213" -> raw dynamic bytes; pass as `tag` on V3
// CreateStaticLOCParams / CreateDynamicLOCParams.
const tag = assembleTag(fields, { orderId: 'ORD-88213' });

Primary APIs

Functions

• assembleTag — Assembles tag fields into a raw dynamic-bytes hex value.
• dateToEthereumTimestamp — Converts a JavaScript Date to the Unix-seconds bigint the protocol uses for every on-chain timestamp (expirationTimestampSeconds,…
• shortenAddress — Shortens a string to a maxLength by replacing the middle of it with ....

Supporting types and functions in this group are not listed here; each has its own page, listed with the group in the sidebar.