Calvin Routes: Smart Execution Routing
Status: conceptual, last checked 2026-11-02. No Calvin code is on Dial-SDK main yet. No live route exists.
Calvin finds a permitted way to fund and execute a program. It takes what the payer can pay with and what the recipient requires, applies the signed policy, and returns a quote with an exact route and its costs. It can only choose among options the authorization allows, and it can’t widen them.
Calvin selects routes, SPAWN derives destinations
A route can end at a deterministic destination, and that pairing is what makes “pay the program” possible. The two jobs stay separate: SPAWN adapters derive the destination, and Calvin decides how value and execution get there. A destination that can be computed but has no valid route is not usable.
Terms
| Term | Meaning |
|---|---|
| Intent | The desired outcome, such as “pay this invoice” |
| Funding capability | What the payer can use, such as a token balance on a network or a payment provider |
| Settlement constraint | What the recipient accepts: asset, network, deadline, finality |
| Quote | A priced, expiring offer for one route, including all fees |
| Route | The specific permitted path a quote describes |
| Action | The concrete execution resolved from an intent and an accepted quote |
| Settlement | The final state of the value, as evidenced by the network or provider |
Inputs and output
Rules a route has to follow
- Quotes expire. A changed fee or an expired quote needs a new authorization. An adapter can’t quietly apply a new price.
- Adapters can’t broaden authority. Amount, recipient, asset, duration and contract version stay inside what was signed.
- Failover stays in bounds. Falling back to another route is allowed only if that route satisfies the same signed limits. If its fees are higher than authorized, the payer has to approve again.
- Costs are complete. A quote shows principal, protocol fee, route fees and network fees separately, and states who pays each.
- Finality is explicit. A route states what it counts as final and how long that takes.
Failure cases a route has to handle
| Case | Required behavior |
|---|---|
| Quote expires mid-flow | Stop and re-quote |
| Provider fails after accepting funds | Report an unresolved state. Don’t report success |
| Partial execution across steps | Report each step, and state who is responsible for recovery |
| Duplicate payment or message | No second side effect |
| Reorg or rollback | Hold the state until finality is reached |
Cross-network routes don’t get atomic settlement or automatic refunds from this protocol. See cross-network settlement.
Fees
The planned DNN Payments profile charges a 25 bps protocol fee on principal, and the creator chooses whether the payer or the payee covers it. That fee belongs to that one profile. It is not a SPORE, SPAWN or network-wide rule. A public invoice format can’t force third-party wallets to pay it, so the fee only applies on routes that actually enforce it.
Explore invoicing: Programmable Invoicing