Chapter 02 · Foundations

Version, type, key, data

Every VDXF object is the same four-part shape. The interesting part is that type means two different things depending on whether the registry recognises it.

FIGURE 2.1 · OrdinalVDXFObject and its key routes.

Everything is a buffer with a version

VDXFObject is the base class: it carries a vdxfkey and implements the serialisation contract. OrdinalVDXFObject extends the idea for the wire format with an explicit version, type, optional key, and a data payload.

The type field is doing two jobs at once, and this is the first thing to get straight: for recognised objects it is a reserved ordinal (AUTHENTICATION_REQUEST_VDXF_ORDINAL, IDENTITY_UPDATE_REQUEST_VDXF_ORDINAL, …) that maps to a class via OrdinalVDXFObjectOrdinalMap; for everything else it is one of three reserved marker bytes saying "the key is an i-address", "the key is a text VDXF key name", or "the key is an identity/currency FQN".

If a parser throws "Unrecognized vdxf ordinal object type", you are looking at a type byte the registry has never seen — usually a newer family than your library version.

The key registry

src/vdxf/keys.ts is a list of plain objects: vdxfid, hash160result, qualifiedname, optional bounddata and indexid. The qualifiedname is the human name (veruspay.vrsc::invoice); the vdxfid is the i-address the daemon resolves to; the hash160result is the 20-byte key that actually lands in the bytes.

export const VERUSPAY_INVOICE_VDXF_KEY = {
  qualifiedname: { name: "veruspay.vrsc::invoice", namespace: "iAisVse…" },
  vdxfid: "iEETy7La3FTN2Sd2hNRgepek5S8x8eeUeQ",
  hash160result: "628efc28c2e2d40050e1a9de7a93e7ddf2aa0076",
}

Flags are bitmasks, not enums

Almost every class carries a flags field built from powers of two, with a setFlags() method that derives the bits from the optional fields actually present, and a family of hasX() predicates. Two consequences follow, and both matter when debugging:

The bytes are self-describing — the reader knows what is present before it reads it.
Field order is fixed by the code, not by the flags. Setting a flag without setting the field is how you get a buffer that parses into nonsense.

Reading the code

src/vdxf/classes/ordinals/OrdinalVDXFObject.ts   # version, type, key, data
src/vdxf/classes/ordinals/OrdinalVDXFObjectOrdinalMap.ts
src/vdxf/keys.ts                                 # every VDXF key constant
src/utils/types/SerializableEntityBase.ts        # the toBuffer/fromBuffer contract