Skip to content
Payvol

Payvol Route

Say how a payment settles. Let somebody else run it.

Route lets a request list the ways it may be settled and the conditions each way depends on, in a shape every module downstream reads. It does not price, hold liquidity, or execute anything.

Read a route Install the packages

@payvol/core/draft02expresses, never executes

What it does

A route precise enough for anyone to execute.

A payment layer that runs its own matching engine makes everyone downstream depend on that engine being up, fair and in business. Route takes the other side: the request says how it may be settled, and whoever runs the settlement does the rest.

The amount lives in exactly one place

One truth

What the payee must receive is stated once, on the request. An option never carries an amount of its own, so there is no second copy to drift the first time somebody edits 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.

Payvol describes, 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 comes back in the same shape

One shape back

Whatever path a payment took, Reconcile answers it on the same five axes. A direct transfer and a conversion are read the same way downstream.

How it works

Declare, validate, execute elsewhere.

01

Declare

  • State once what the payee must receive
  • Define each condition once, with an id and a kind
  • List the settlement options, each referencing the conditions it needs

02

Validate

  • Options and conditions are checked against closed sets of fields
  • A repeated id is refused with DUPLICATE_REQUIREMENT_ID
  • A reference to an undefined condition is refused with UNRESOLVED_REQUIREMENT_REF

03

Execute elsewhere

  • A wallet or provider reads the options it can run
  • It checks the referenced conditions when the payer decides
  • Settlement runs through the Token Standard, outside Payvol

Scope

What Route leaves to the executor.

No pricing, ever Payvol does not quote a rate, imply a rate, or assume that two assets are worth the same. When a conversion happens, the provider's quote is the only number in play.
No liquidity, no inventory Nothing is held, pooled or fronted. Route describes a path that somebody else has the assets to walk.
No atomicity promise Where a path is atomic, it is atomic because the Token Standard and the provider make it so. Payvol reports that guarantee rather than issuing it.
No engine Route never matches, selects or submits. Whoever executes a route runs their own engine and carries the responsibility for it.

Who it is for

Wallets and settlement providers that need to know how a request may be paid, and anyone issuing requests that offer more than one way to pay.

Route is part of these situations.

Get started

Read the routes a request declares.

Install the package and validate the artifact. A valid result carries the options and the conditions they reference; a refusal names the rule it broke.

npm i @payvol/core version 0.4.0 TypeScript 
import { validateArtifact } from '@payvol/core/draft02';

const result = validateArtifact(artifact);

if (result.valid) {
  // the ways this request may be settled, and the conditions each one references
  const { options, requirementDefs } = result.artifact.payload;
  options;
  requirementDefs;
} else {
  // a route a payer could not evaluate is refused, for example
  // 'UNRESOLVED_REQUIREMENT_REF' or 'DUPLICATE_REQUIREMENT_ID'
  result.code;
}

Install the packages Reason codes What comes back after settlement