Chio/Docs
LOGIN · JOIN

Revenue Splits

Declare who shares a tool’s revenue in its signed price, then settle each share as its own commitment on its own schedule.

Concept chio@5f63e6e

On this page

The revenue from one tool rarely belongs to one party. The operator who serves it, the partner who fixed its code, and a reserve that backs its refunds each have a claim, and a single payout to the operator turns their shares into private bookkeeping no one else can check. A revenue split moves the division into the tool’s signed price. Settlement then produces one commitment per beneficiary, so each party’s share is a record of its own that can be verified and paid without trusting the others’ ledgers.

Your pricing service sells quote at USD 0.01 a call. Half of the revenue is yours, a third goes to your partner for the refund() fix in issue #417 and vests over the winter, and the rest funds a reserve.

Settlement writes one commitment per beneficiary

A share is a number of basis points of the settled total, and 10,000 is the whole. Each commitment takes the floor of its share in integer minor units, and whatever the floors leave becomes one more commitment, to the settling operator.

Revenue splitDrag t across the schedule.
payeeSplit10,000 bps5000you3333your partner1667reservefloors leave USD 0.01 residual to the operatoryouUSD 5.00USD 5.00your partnerUSD 3.33cliffAtvestEndAtUSD 1.66reserveUSD 1.66USD 1.66residualUSD 0.01USD 0.01Oct 1Nov 1Dec 1Jan 1Feb 1t = Dec 16payeeSplit, 10,000 bps of USD 10.005000you3333your partner1667reservefloors leave USD 0.01 residual to the operatoryou USD 5.00USD 5.00your partner USD 3.33, vests Nov 1 to Jan 30USD 1.66reserve USD 1.66USD 1.66residual USD 0.01USD 0.01Oct 1Dec 1Feb 1t = Dec 16
ui=⌊U⋅bpsi10 000⌋,r=U−∑iuivi(t)=⌊ui⋅min⁡ ⁣(1,max⁡ ⁣(0,t−tclifftend−tcliff))⌋\begin{aligned} &u_i = \left\lfloor \frac{U \cdot \mathrm{bps}_i}{10\,000} \right\rfloor, \qquad r = U - \textstyle\sum_i u_i \\[6pt] &v_i(t) = \left\lfloor u_i \cdot \min\!\left(1, \max\!\left(0, \tfrac{t - t_{\mathrm{cliff}}}{t_{\mathrm{end}} - t_{\mathrm{cliff}}}\right)\right) \right\rfloor \end{aligned}

Between cliff and end, the share vests linearly

On Dec 16 your partner has USD 1.66 of its USD 3.33 commitment vested, with USD 1.67 still held until Jan 30. The other commitments vest in full at settlement, so USD 8.33 of USD 10.00 is vested in all.

One USD 10.00 settlement under a three-way payeeSplit, the commitments it produces, and your partner’s vesting schedule on an October to February axis. Amounts and dates are illustrative; cosignature checks and the settlement rail are left out.

A day of quotes settles USD 10.00. The floors give USD 5.00, USD 3.33, and USD 1.66, and the remaining cent becomes a residual commitment whose reference hashes the URN urn:chio:operator:split-residual, so no rounding is silently absorbed into anyone’s share. Each commitment’s receipt reference is the first 32 hex characters of SHA-256 over the receipt id and the beneficiary, joined by a colon, which makes every share traceable to the receipt that earned it.

A split is part of the tool’s signed price

Declare the split where you declare the price. Your kernel writes it into the tool manifest and signs the manifest again:

pricing.tspricing.pysrc/main.rs · in main
import { Computer, USD } from "@chio-protocol/sdk";

const project = await Computer.open("quickstart");
const pricing = await project.service("pricing", { tools: { quote: "src/pricing.py:quote" } });

const priced = await pricing.price("quote", {
  amount: USD("0.01"),
  economy: "urn:chio:economy:pricing",
  split: [
    { to: "did:chio:z6Mkf3…Qp9", bps: 5000 },
    {
      to: "did:chio:z6MkpA7…c2T",
      bps: 3333,
      vest: { cliff: "2026-11-01", end: "2027-01-30" },
      cosigners: ["did:chio:z6Mkf3…Qp9"],
    },
    { to: "urn:chio:economy:pricing:reserve", bps: 1667 },
  ],
});
console.log(priced.describe());
Output
price      pricing.quote USD 0.01 per call, economy urn:chio:economy:pricing
split      5000  did:chio:z6Mkf3…Qp9
           3333  did:chio:z6MkpA7…c2T, vests 2026-11-01 to 2027-01-30, cosigned by you
           1667  urn:chio:economy:pricing:reserve
manifest   re-signed, payee_split sums to 10000 bps

The manifest carries the split as payee_split on the tool’s ToolPricing. Each entry names a beneficiary by DID or URN, its basis points, an optional vesting window in Unix seconds, and the cosigners who must sign the split:

pricing manifest · tools.quote.pricingjson
"pricing": {
  "pricing_model": "per_invocation",
  "base_price": { "units": 1, "currency": "USD" },
  "economy": "urn:chio:economy:pricing",
  "payee_split": [
    { "beneficiary": "did:chio:z6Mkf3…Qp9", "bps": 5000 },
    {
      "beneficiary": "did:chio:z6MkpA7…c2T",
      "bps": 3333,
      "vesting": { "cliffAt": 1793491200, "vestEndAt": 1801267200 },
      "cosigners": ["did:chio:z6Mkf3…Qp9"]
    },
    { "beneficiary": "urn:chio:economy:pricing:reserve", "bps": 1667 }
  ]
}

A split that does not sum to 10,000 is refused

Manifest validation runs validate_payee_split on every split. A split must have at least one entry and sum to exactly 10,000; a sum of 9,999 fails with sum of bps was 9999; expected exactly 10_000. Beneficiaries must be nonempty and distinct, a cosigner may not appear twice or cosign its own entry, and a vesting window must end at or after its cliff, with nonzero timestamps in range.

Every failure reports urn:chio:error:manifest:payee-split-invalid with the specific reason, and the manifest is refused. A cliff equal to its end is valid: the share is held until that moment and then vests whole.

Vesting holds a share until its cliff

A share with a vesting window is held until cliffAt, vests linearly until vestEndAt, and is fully vested after it. A share without one is claimable at settlement. Read the commitments for a settled receipt as they stand on a given day:

Terminalbash
chio settle split rcpt-01b9…e4a0 --at 2026-12-16
Output
receipt     rcpt-01b9…e4a0, USD 10.00 on eip155:8453, economy urn:chio:economy:pricing
commitment  did:chio:z6Mkf3…Qp9               USD 5.00   vested
commitment  did:chio:z6MkpA7…c2T              USD 3.33   USD 1.66 vested, USD 1.67 held
commitment  urn:chio:economy:pricing:reserve  USD 1.66   vested
residual    did:chio:z6Mkf3…Qp9               USD 0.01   urn:chio:operator:split-residual

On December 16 your partner’s USD 3.33 is half vested: 45 of the 90 days between the cliff and the end have passed. Cosigners sign the canonical JSON of the split itself, and verify_payee_split_cosignatures returns the set of signers whose signatures verify. The quorum that set must meet is the consumer’s policy; the empty list means the beneficiary alone governs its entry.

An EconomyId keeps one economy’s money together

An EconomyId is an opaque string, such as urn:chio:economy:pricing, that names the economy a price and its money belong to. The same optional economy field appears on a tool’s ToolPricing, on each SettlementCommitment, on a CreditFacilityArtifact, and on a BudgetNode, so a tool’s receipts, the commitments they settle into, and the credit and budgets that fund them can be selected as one ledger.

Chio derives nothing from the string. Choose one per economy and keep it stable across its tools, budgets, and credit facilities.

Next: net the commitments

Clearing RoundsSettle many parties’ commitments with few transfers.Signed Tool ManifestsRead the manifest that carries the price and the split.
PreviousClearing RoundsNextPassports
Revenue Splits · Chio Docs