@payvol/cli

Build, read and check Canton payment requests from the command line, and run the conformance vectors. No account, no key, and no network call at any step.

Install

npm i -g @payvol/cli
# or without installing
npx @payvol/cli conformance

Tested on Node 20; the engines field records the supported range.

payvol --help lists every command and payvol --version prints the version.

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

# build a request from fields
payvol encode \
  --recipient 'payvol-demo-recipient::122013babe3c9a7ed315a3e8f8181bbcf85aaa0bfd0e3efbaf2e166f31ab80e4f9f5' \
  --instrument 'DSO::1220be58c29e65de40bf273be1dc2b266d43a9a002ea5b18955aeef7aac881bb471a/Amulet' \
  --amount 1.50 --reference INV-2026-0042

# read one back
payvol decode 'canton:alice%3A%3A1220ab?instrument=DSO%3A%3A1220be%2FAmulet&amount=1.50'

# validate, and print the canonical form and its sha256
payvol inspect 'canton:alice%3A%3A1220ab?instrument=DSO%3A%3A1220be%2FAmulet&amount=1.50'

# run the vectors
payvol conformance

encode also accepts a whole request as JSON on stdin or through --json. inspect exits non-zero when the request is invalid, so it drops into a script or a CI step without extra glue.

The specification

SPEC.md ships in @payvol/core and is normative. The repository at github.com/cayvox/Payvol-CPR carries the vector format document; those links resolve once the repository is public.

Apache-2.0.