@payvol/core

Build, read and validate Canton payment requests. A canton: URI, canonical JSON (JCS, RFC 8785), and validation with named reason codes. Pure and side-effect free, so it runs in a browser, in Node and in a worker without touching a network.

A Payvol request is a portable, session-less artifact that any conforming wallet can read, present for review, and settle as a Canton Token Standard transfer, with no live connection between the application and the wallet.

Three version numbers, and what each one versions

They are not the same number and they do not move together.

• The npm version (0.3.0) versions this package: its API, its exports, its behaviour. It follows semver, and while it is 0.x a breaking change bumps the minor.
• The data profile (version: '0.1' inside an artifact) versions the artifact format. 0.1 is the default and is deprecated but still read and written; 0.2-draft is the profile under development and may change without a package major, because a draft that could not change would not be a draft.
• SPEC.md's own revision versions the normative text, which can gain a clarification without either of the above moving.

A package at 0.3.0 writing an artifact that declares 0.1 is therefore normal, not a mismatch. What conforms is decided by the profile in the artifact, not by the version of the library that produced it.

One thing the numbers do not tell you: signatureVerified: 'not-checked' means the signature's shape was accepted and nothing was verified. It is not a pass, and no version number changes that.

Install

npm i @payvol/core

Tested on Node 20. The engines field records the supported range. ESM, with type declarations; require() works on Node versions that support requiring an ES module.

What a party id and an instrument id are

A Canton party id is name::fingerprint, where the fingerprint is 68 hex characters beginning 1220 (a multihash prefix: sha2-256 over 32 bytes). You get yours from the validator or wallet that hosts the party: it is shown when the party is allocated, and any wallet connected to it will display it. A shorter string is a placeholder, not a party.

An instrument id is admin/id. admin is the party id of the registry that issues the asset and id is its symbol within that registry. On Canton DevNet, Canton Coin is DSO::1220be58c29e65de40bf273be1dc2b266d43a9a002ea5b18955aeef7aac881bb471a/Amulet, where the DSO admin comes from the network's own registry metadata endpoint and is captured in this repository's fixtures rather than typed by hand.

A valid request is not a settleable one. validate() answers whether the artifact is the right shape. It returns warnings when the recipient is not a full party id, or the instrument names no registry admin, because those are well formed and unpayable. What settles a request is a wallet: the payer opens it, the wallet builds a Canton Token Standard transfer, and the payer signs it.

Example

import { encode, decode, validate, toCanonical } from '@payvol/core';

const uri = encode({
  version: '0.1',
  type: 'transfer',
  recipient: 'payvol-demo-recipient::122013babe3c9a7ed315a3e8f8181bbcf85aaa0bfd0e3efbaf2e166f31ab80e4f9f5',
  instrument: 'DSO::1220be58c29e65de40bf273be1dc2b266d43a9a002ea5b18955aeef7aac881bb471a/Amulet',
  amount: '1.50',
  reference: 'INV-2026-0042',
});

const request = decode(uri);
const result = validate(request);
result.valid;           // true
result.warnings;        // [] when the party and registry admin are full ids
result.signatureVerified; // 'absent'
toCanonical(request);   // the JCS bytes an identifier is derived from

encode(decode(uri)) returns the same string, and the round trip is pinned by conformance vector rather than by assertion.

The 0.2 draft profile

A different profile, on its own entry point, so a consumer of 0.1 never loads it. A 0.1 request and a 0.2-draft payload are different shapes: the 0.1 fields are flat, and 0.2-draft uses structured payee, requestedReceive and executionScope objects. Do not pass one to the other's functions.

validateArtifact takes an artifact, which wraps the payload. payloadDigest and reconcile take the payload itself.

import { validateArtifact, payloadDigest, reconcile } from '@payvol/core/draft02';

const DSO = 'DSO::1220be58c29e65de40bf273be1dc2b266d43a9a002ea5b18955aeef7aac881bb471a';
const PAYEE = 'payvol-demo-recipient::122013babe3c9a7ed315a3e8f8181bbcf85aaa0bfd0e3efbaf2e166f31ab80e4f9f5';

const payload = {
  version: '0.2-draft',
  type: 'transfer',
  executionScope: { network: 'canton-devnet', synchronizerPolicy: 'any' },
  payee: { party: PAYEE },
  requestedReceive: {
    instrument: { admin: DSO, id: 'Amulet' },
    amount: '1.50',
    destination: { owner: PAYEE, provider: DSO, id: '' },
  },
  securityRequirement: { mode: 'unsignedAllowed', allowedSuites: ['ed25519-raw'] },
  expiry: '2027-07-01T00:00:00Z',
};

// the ARTIFACT wraps the payload
validateArtifact({ payload });   // { valid: true, artifact: { ... } }

// the identifier is DERIVED from the payload bytes, never assigned
const digest = payloadDigest(payload);

// what arrived, against what was asked, on five independent axes
const record = reconcile(payload, digest, [], { allowPartial: false });
record.closureReadiness;   // 'not-satisfied' with nothing observed yet

payloadDigest is domain separated, so it cannot collide with a digest computed under another profile over the same bytes. It will hash anything you pass it, so handing it a 0.1 request returns a digest of the wrong thing rather than an error.

reconcile classifies and stops. It never closes anything: closure belongs to whichever system is accountable for the accounts.

Signatures

validate() reports signatureVerified as 'absent' or 'not-checked', and never as verified. The bytes a signature must cover are pinned by conformance vector, but the Canton external party key and signature scheme is an open question, so no implementation can verify one yet.

Now what: getting a request paid

A valid request is paid by a wallet that implements the Payvol transfer. Today that is through PartyLayer, with Console, Loop and Nightly on Canton DevNet. To try one without writing wallet code, paste a request into payvol.xyz/app/pay.

The specification

SPEC.md ships in this package and is normative for this implementation. Behaviour is pinned by the vectors in @payvol/conformance. The repository at github.com/cayvox/Payvol-CPR carries the same document and its history; those links resolve once the repository is public.

Apache-2.0. The specification text is CC0-1.0.