Payvol Route
Say how a payment settles. Let somebody else run it.
Route describes the path a request will take on Canton, in a shape every module downstream already understands. It does not price, hold liquidity, or execute anything.
@payvol/coreexpresses, never executesdirect today In development
The code exists and runs in this repository. It is not published yet, so there is nothing to install.
One source of truth
Owning execution is how a standard turns into a product you cannot leave.
The moment a payment layer runs its own matching engine, everyone downstream depends on that engine being up, being fair, and staying in business. Route takes the opposite side: it expresses the settlement path precisely enough that anyone can execute it, and then gets out of the way.
The amount lives in exactly one place
One truth
What the payee must receive is stated once, on the request. Every settlement option derives from it. A second copy on the option would be a second truth, and the two would drift the first time somebody edited one.
Declared once, referenced per option
No repetition
The conditions a payment depends on are defined at the top of the request and referenced by the options that need them. Different paths need different conditions, and none of them repeat the definition.
We describe, providers execute
Where the line sits
Payvol never quotes a price, never holds inventory, never guarantees atomicity. Those belong to whoever runs the settlement, along with the responsibility when one of them fails.
Every route returns the same five things
One shape back
Whatever path a payment took, the record that comes back has the same shape. That is what lets a reconciliation engine treat a direct transfer and a future conversion identically.
How it works
Read, resolve, prepare.
01
Read
- Take the settlement options off the request
- Read what the payer actually holds
- Filter to the options that can run today
02
Resolve
- Check the conditions each option references
- Drop any option whose conditions cannot be met
- Present what is left, with the reasons for what was dropped
03
Prepare
- Build the Token Standard transfer for the chosen option
- Attach the identifier to the settlement metadata
- Hand the prepared transaction to the wallet's signing flow
Where the line sits
Three ways a payment layer can treat settlement.
01
Run the engine
the layer executes
The payment layer matches, prices and settles. Integration is easy on day one, and every participant now depends on one operator staying online, neutral and solvent.
Convenience bought with dependency
02
Say nothing
settlement left undefined
The format carries an amount and a payee and stops. Every integrator invents their own answer for how the payment actually runs, and no two of them agree.
Interoperability that ends at the transfer
03
Describe the path
Payvol Route
The route is expressed in the request, precisely enough to execute and neutral enough that anyone can. The engine is somebody else, and replacing it changes nothing upstream.
Precision without a dependency
Boundaries
What Route deliberately does not do.
This is the module where saying no matters most, because everything it refuses is something a vendor would happily sell you.
For integrators
The route object is small on purpose.
It names the option, the conditions it depends on, and the references that come back after settlement. Everything else is the executor business.
import { validateArtifact } from '@payvol/core/draft02'
// the options a request declares, and the conditions each needs
const result = validateArtifact(artifact)
const { options, requirementDefs } = result.artifact.payload
// an option a payer could not evaluate is refused, never ignored
result.valid // false
result.code // 'UNRESOLVED_REQUIREMENT_REF'Where it is used
1 of the six situations reach Route.
Direct today. The shape is ready for the rest.
Build against it now and the day conversion arrives, your integration does not move.