← Book map

Chapter 07 · Families

Where the semantics live

Three families, three flag vocabularies. The envelope only knows a detail exists; these classes decide what asking actually means.

Three request families and their flags Authentication, identity update and invoice details each declare a different flag vocabulary: constraints and expiry, identity change and txid, amount and destination. AUTHENTICATION who is asking 1 requestID 2 recipient constraints 4 expiry time IDENTITY UPDATE what changes 1 signData 2 expiry height 4 requestID · 8 system · 16 txid INVOICE what is owed amount · destination currency id · expiry height accepted systems · tag Each family owns its own flags. The envelope only knows that a detail exists, never what it means.

FIGURE 7.1 · Detail classes are where the semantics live.

Authentication — login/AuthenticationRequestDetails.ts

The smallest family and the best one to read first. Flags: has request id, has recipient constraints, has expiry time. A recipient constraint narrows who is allowed to answer — typically an identity or a system — and the expiry stops a login challenge from being useful forever. 

new AuthenticationRequestDetails({
  requestID: CompactIAddressObject.fromAddress("i…"),
  recipientConstraints: [new RecipientConstraint({ type: …, identity: … })],
  expiryTime: new BN(unixSeconds),
})

Identity update — identity/IdentityUpdateRequestDetails.ts

The most consequential family, and the one with the most flags: signData (1), expires (2), contains request id (4), contains system (8), contains txid (16). The request can carry a full or partial identity, a system id, and a transaction id the update must spend.

Note what is not here: the request never says "apply this" — it says "here is a proposed identity state, valid until height H, to be applied on system S, provided txid T is spent". The wallet applies it as a normal identity-update transaction; the VDXF object is the instruction sheet.

Invoice — payment/VerusPayInvoiceDetails.ts

The invoice carries amount, destination (a TransferDestination or Sapling address), requested currency id, expiry height, maximum estimated slippage, accepted systems and an optional tag. Flags cover the choices that change the payment's meaning: accepts conversion, accepts non-Verus systems, accepts any amount, accepts any destination, excludes the Verus blockchain, testnet, preconvert, Sapling destination, tagged.

An invoice is consent to a conversion policy, not just a number. "Accepts any amount" and "accepts any destination" are the two flags most worth refusing in a wallet UI.

Reading the code

src/vdxf/classes/login/AuthenticationRequestDetails.ts
src/vdxf/classes/login/RecipientConstraint.ts
src/vdxf/classes/identity/IdentityUpdateRequestDetails.ts
src/vdxf/classes/payment/VerusPayInvoiceDetails.ts
src/vdxf/classes/payment/VerusPayInvoice.ts
← Book map

Next — Chapter 08 · Data, encryption, attestation