DraftUP/0.1 spec and reference interpreter

The contract layer every system can verify.

Universal Paper is an open language for agreements between GPOs, suppliers and members. Every agreement, signature and change is plain JSON that any system can check for itself, offline.

up validate examples/conventional/bundle.json
7primitives
16standard Terms
13axioms
0servers required
Built on open standards · reuses the identifiers you already have
RFC 8785Canonical JSONSHA-256Content hashesRFC 8032Ed25519 signaturesRFC 3339TimestampsISO 4217CurrenciesGS1GTIN itemsGS1GLN locationsHIBCCHINFDANDCASC X12845 · 844 · 849 · 867 mappingCC BY 4.0Spec licenseApache-2.0Reference code

The problem

Three systems. Three copies. One deal.

The GPO's contract system, the supplier's ERP and the member's spreadsheet each hold their own version of the same agreement. Teams spend weeks reconciling them. Universal Paper gives all three the same record, with a fingerprint that proves they match.

Aggregator CLMv4 (final)
Admin fee ........ 2.0% net Billing .......... monthly Terms ............ Net 30
sha256:616dac2f…8623
Supplier ERPrev 7
ADM_FEE_PCT = 2.00 ADM_FEE_FREQ = M ADM_FEE_DUE_D = 30
sha256:616dac2f…8623
Member sheetcopy (2)
| Fee rate | Period | Due | | 0.02 | 1 mo | 30 d |
sha256:616dac2f…8623
Each system keeps its own format. All three compute the same agreement hash:sha256:616dac2fd52f336580dec71a1d1f00ccabed5b3ef0e14b15bb0761a453218623

How it works

One agreement, from draft to proof.

Scroll to follow the admin-fee clause from the repo's conventional example. Every hash below is computed live in your browser.

agreement.json · clause "fee"draft
"term": "UP:Admin-Fee",
"payer": "supplier", "payee": "aggregator",
"rate": "0.02",
"due": { "count": 30, "unit": "day" }
fingerprint · JCS + SHA-256
signatures · Ed25519GPOSupplier
January report · hypotheticalUSD 3,050.00 × 2% → USD 61.00 due 2027-03-03
  1. 01 · Write it once

    Three systems, one form

    The GPO's contract system, the supplier's ERP and the member's spreadsheet each describe the same deal. Universal Paper gives it one shape: plain JSON built from standard Terms, with the parties' own numbers.

  2. 02 · Fingerprint it

    A name computed from the content

    Canonical JSON (RFC 8785) plus SHA-256 turns the agreement into 64 characters. Any system, in any language, computes the same ones.

  3. 03 · Sign the fingerprint

    Signatures cover exactly this text

    Each party signs the hash with Ed25519. The signature covers these Terms and these numbers, nothing more and nothing less.

  4. 04 · Let the data do the math

    Everyone derives the same fee

    When January's sales report arrives, every party's software computes the same fee and due date from the signed clause. Nobody re-keys a number.

  5. 05 · Catch any change

    One digit breaks the proof

    Change the rate after signing and the fingerprint no longer matches. Every party's software rejects the copy, offline, without asking anyone.

  6. 06 · Keep private terms private

    Sealed values still verify

    A Seal hides a value from parties who shouldn't see it (A10). They still check the signatures and reach the same verdicts.

Try it

Edit a signed clause. Watch the proof react.

Change the rate, the due period or the rounding. The fingerprint, the contract text and the fee recompute in your browser, exactly as the Python reference does.

  • Hashes match the reference interpreter digit for digit
  • Contract text rendered from the same data (A8)
  • Exact decimal rounding, four modes
Open the full Playground
runs in your browser
// examples/conventional · master agreement · clause "fee"
{ "term": "UP:Admin-Fee", "def": "sha256:7794f787…",
"params": { "payer": "supplier", "payee": "aggregator",
"rate": "",
"due": { "count": , "unit": "day" },
"period": { "count": 1, "unit": "month" },
"rounding": { "mode": , "scale": 2 } } }
Agreement hash · JCS + SHA-256matches the signed hashsha256:616dac2fd52f336580dec71a1d1f00ccabed5b3ef0e14b15bb0761a453218623
Contract text · up render (A8)

Fee owed · Jan 2027USD 61.00on USD 3,050.00 reported · hypothetical
Due2027-03-03January period ends 2027-02-01

Start where you work

Four ways into the same language

From signature to first invoice

Watch a deal go live, one signed event at a time

This is the conventional example from the repo: a GPO and supplier sign a tiered agreement, a hospital joins, its tier is confirmed, and the first report and fee settle. Every date and number below comes from the example chains. The parties and values are hypothetical

2026-12-01 · propose

The GPO sends a proposal

Business development composes the agreement from standard Terms: renewal, three price tiers, monthly sales reporting, a 2% admin fee, audit and exit. The proposal is signed and becomes the first event of the chain.

2026-12-05 · accept

The supplier signs. No redline round.

The supplier accepts the exact agreement hash it reviewed. Both required signers now agree, so the agreement is executed and goes into force on 2027-01-01.

2027-01-04 · 09:00 → 16:00

A hospital joins in one afternoon

The participation is its own small agreement linked to the master. The GPO proposes at 09:00, and the hospital and supplier accept by 16:00. It starts on tier C until a tier is confirmed.

2027-01-07 · attest + accept

Tier confirmed, contract prices live

The hospital attests tier B and the supplier acknowledges it the same day. Every system derives the same contract prices from the chain. Nobody had to send or load a price file.

2027-02-10 · attest

The first sales report lands

The supplier reports January's sales against each participation. The fee owed follows by itself: 2% of USD 3,050.00 reported, which is USD 61.00, due 30 days after the period ends.

2027-02-15 → 02-16

An upgrade reprices on acknowledgment

The hospital's purchases now qualify for tier A. It attests, the supplier acknowledges, and the derived prices change for everyone at once.

2027-02-20 → 02-21

The fee settles, with proof on both sides

The supplier attests payment of USD 61.00 and the GPO acknowledges it. The obligation is discharged in every copy, with no true-up spreadsheet.

Deal room · derived from the chain2026-12-01
Master agreement
Hypothetical Health Purchasing Alliance × Example Medical Supply Co.proposed
aggregator ✓supplier
Member · participation
No members yetnone
tier —
Contract prices for this member
GTIN …0017—
GTIN …0024—
GTIN …0031—
Obligations · January 2027
Sales report, supplier → aggregatornot yet due
Admin fee not yet due
propose aggregator · Master agreement · ChainId sha256:47b4b79c…

What changes for each team

Less reconciling. More time on the deal.

When every party works from the same verifiable record, most of the work between "signed" and "paid" stops being manual. Here's what that could look like for the people who live in it today.

Today

  • Every counterparty starts from different paper, so each deal opens with a redline cycle.
  • Approved language drifts between versions and has to be re-checked.
  • "Which version did they sign?" is a real question.

On Universal Paper

  • Proposals are assembled from standard Terms. Only the parameters are negotiated.
  • The counterparty reviews a short list of values, not a 40-page diff.
  • The signed hash settles which version is binding.

Built on

proposeacceptTerm libraryA8 rendering

Value-neutral by design: the library never suggests a price, rate or period.

These describe possibilities the design allows. They are not measured results from a deployment.

Time to first invoice

Fewer hand-offs between the signature and the first invoice

Illustrative only. Bar lengths show the shape of the work, not a measurement.

A typical path todaymany hand-offs
RedlinesLegal reviewKey into CLMPrice file to ERPRoster & eligibilityTier confirmationReconcileInvoice
On Universal Papereach step is a signed event
ParametersSignJoinTierInvoice
signaturefirst invoice at contract price
Version reconciliation

One hash per agreement

Copies either match the signed hash or are rejected. There's nothing to compare by hand.

Price file loads

Prices are derived

Contract price follows from the tier schedule and the member's acknowledged tier.

Fee true-ups

Fees are computed

The fee follows from the reported sales and the signed rate, with rounding defined in the spec.

"Who changed this?"

Every change is signed

Corrections are new events. The past can't be edited, only added to.

At a glance

The whole language fits on one page.

Each count below is fixed in the spec. Every new construct is a permanent commitment, so the language stays small enough for any engineer to implement and any lawyer to read.

7PrimitivesAgreement, Party, Role, Term, Event, State, Mandate
3Event kindspropose accept attest
6Clause formsWindow, Exit, Selection, Valuation, Duty, Link
16Standard TermsFrom admin fees to governing law, in spec/06-terms
13AxiomsConsensus rules, each checkable by hand
0Servers requiredAny party verifies any copy, offline

Content-addressed RFC 8785

Every object is named by the SHA-256 of its canonical JSON. Same content, same name, on every machine.

Deterministic A4

State is computed from the chain, never stored. Two evaluators with the same events always agree.

Value-neutral A6

Terms define meaning, never numbers. The library can't suggest a price, rate or period.

Ricardian A8

The signed contract text is generated from the data, under the same hash. They can't drift.

Bounded delegation A9

Agents act under Mandates. Anything outside the bounds is invalid for every evaluator.

Confidential by construction A10

Seals hide private values while hashes, signatures and states still verify.

The language

Small enough to check by hand. Complete enough to run a contract.

Seven primitives, two value types and six clause forms. Each primitive does one thing, and the list is short on purpose because every primitive is a permanent commitment.

Primitive

Agreement

The cover page: Parties in Roles, plus Clauses that apply standard Terms with values. Its hash is what everyone signs.

{"type": "Agreement", "spec": "UP/0.1-draft", "parties": […], "clauses": […]}
Primitive

Party

Anything that can sign. A Party is its Ed25519 key.

"ed25519:315acb5c…"
Primitive

Role

What a Party does in one Agreement.

aggregator · supplier · member
Primitive

Term

Standard meaning with a stable id, pinned by hash.

"UP:Admin-Fee"
Primitive

Event

A signed change. Only three kinds exist.

propose · accept · attest
Primitive

State

Where an Agreement stands. Never written, always computed from its chain, so every evaluator gets the same answer.

"status": "executed", "height": 9, "last": "sha256:68b6d6b8…"
Primitive

Mandate

Bounded authority for an agent.

"rate": {"max": "0.03"}
Value type

Identifier

Reuses GTIN, GLN, HIN, NDC. Never mints IDs.

{"scheme": "GTIN", "id": "…"}
Value type

Seal

A salted hash in place of a private value.

{"seal": "sha256:41135ba3…"}
Clause forms

Six building blocks

Every Term is built from these. A new Term never needs new code.

WindowExitSelectionValuationDutyLink

Term library

Sixteen standard Terms. Each one hashed live in your browser.

These are the real definitions from spec/06-terms. A clause pins a Term by its content hash, and this page recomputes each one so you can check it against the agreements that use it. All are drafts that counsel hasn't reviewed yet.

Terms as data

Scroll to watch a clause become data

The real UP:Admin-Fee Term. Its prose and its machine meaning share one hash, so they can't drift apart.

1 · The prose

It starts as contract language

The rendering template has a slot for each value the parties choose. There are no numbers in it.

2 · Parameters

Every slot is a typed parameter

Name, type and description, and nothing else. There's no field for a default value, so the library can't suggest a price or rate (axiom A6).

3 · Machine meaning

The meaning is a Duty form

Who owes whom, how often, by when, how the amount is computed, and what discharges it.

4 · A clause

The Agreement binds values

The clause pins the exact Term definition by hash in def and supplies every parameter.

5 · Back to prose

The signed text is generated

up render fills the template. Everyone gets the same sentence, byte for byte (axiom A8).

UP-Admin-Fee.json → rendertemplate
For each period of {{period|period}}, {{payer|role}} pays {{payee|role}} an administrative fee equal to {{rate|rate}} of the net sales reported for that period, rounded {{rounding|rounding}}, within {{due|period}} after the period ends. The fee is fixed at that rate for the term of this Agreement unless the Agreement is amended.
UP-Admin-Fee.json → paramsno defaults (A6)
nametypedoc
payerRoleRole that pays the fee.
payeeRoleRole that receives the fee.
rateRateFee as a fraction of reported net sales.
report_clausestringName of the Sales-Reporting clause whose reports form the base.
periodPeriodFee period.
duePeriodTime after each period's end by which the fee is due.
roundingRoundingRounding applied to each period's fee.
UP-Admin-Fee.json → formsDuty
{
  "form": "Duty", "duty": "pay",
  "obligor": {"param": "payer"},
  "obligee": {"param": "payee"},
  "trigger": {"every": {"param": "period"}, "anchor": "window-start"},
  "due": {"param": "due"},
  "discharge": {"claim": "UP:Admin-Fee/paid", "ack": [{"param": "payee"}]},
  "amount": {
    "rate": {"param": "rate"},
    "base": {"claim": "UP:Sales-Reporting/report",
             "clause": {"param": "report_clause"}, "field": "total_net"},
    "rounding": {"param": "rounding"}
  }
}
master agreement · clause "fee"hypothetical values
{
  "n": "fee",
  "term": "UP:Admin-Fee",
  "def": "sha256:7794f7872d6cef305839b2fdc7b7e9f2916e71f20cde4bdac95321848e21a85e",
  "params": {
    "due": {"count": 30, "unit": "day"},
    "payee": "aggregator", "payer": "supplier",
    "period": {"count": 1, "unit": "month"},
    "rate": "0.02",
    "report_clause": "reporting",
    "rounding": {"mode": "half-even", "scale": 2}
  }
}
$ up render … --chain 0output

### 4. Administrative fee (UP:Admin-Fee, clause "fee")

For each period of 1 calendar month, the Supplier pays the Aggregator an administrative fee equal to 2% of the net sales reported for that period, rounded to 2 decimal places, rounding half to even, within 30 days after the period ends. The fee is fixed at that rate for the term of this Agreement unless the Agreement is amended.

Agreement hash: sha256:616dac2fd52f336580dec71a1d1f00ccabed5b3ef0e14b15bb0761a453218623

Proof, not trust

Every object has a fingerprint. Try to change one.

Every Term, Agreement, Event and State is identified by the SHA-256 hash of its canonical JSON (RFC 8785). The same content gives the same hash on any machine, in any language.

1 · Agreement object
↓ canonicalize: sorted keys, no whitespace, decimals as strings, no "sigs"
2 · Canonical bytes · … bytes
↓ SHA-256
3 · Content hash

Live · computed in your browser

Edit the signed fee rate

This is the full master agreement from examples/conventional. The page hashes it with the same algorithm the Python interpreter uses.

"rate":

Agreement hash

sha256:616dac2fd52f336580dec71a1d1f00ccabed5b3ef0e14b15bb0761a453218623
Matches the hash both parties signed. Their signatures still verify.

Signatures and chains

History is a single signed line. Tampering breaks it.

Each Event is signed over its hash and names the State before it. This is the real master chain, then the repo's fault example.

genesis

The proposal starts the chain

Its hash becomes the ChainId, the agreement's permanent identity, even through later amendments.

prev → state

Each event commits to what came before

The supplier's accept names the State it saw in prev. Two events can't both follow the same State, so there's never a fork to argue over.

nine events

Every evaluator lands on the same State

After nine events, every copy reaches sha256:f7ca8ea5…. What's owed comes from up derive, never from a stored balance.

fault example

Change one number in one copy

In the supplier ERP's copy, the fee rate was changed from 2% to 1.5% after signing. The genesis event's hash changes, the aggregator's signature fails, and that copy stops at event #0.

Supplier ERP copy · rejected at event #0
A9 · Signature by ed25519:315acb5c… does not verify: the event was altered after signing, or the signature is missing or forged.
From conventional.tamper-supplier-fee.trace.json

Confidential by construction

Hide the prices. Keep the proof.

A Seal is a salted SHA-256 commitment that stands in for a private value. Hashes and signatures cover the sealed form, so a holder who sees nothing reaches the same verdicts and the same State hashes (axiom A10).

With disclosures · confidential/bundle.json
Fee rate"0.02" hypothetical
Fee, Jan 2027USD 61.00 · discharged
Master statesha256:99d9a009f537e31f7b925b1f…
Hashes only · bundle.hashes-only.json
Fee rate{"seal": "sha256:41135ba3df21…"}
Fee, Jan 2027sealed · due 2027-03-03
Master statesha256:99d9a009f537e31f7b925b1f…

Agents under Mandates

Let software negotiate, inside limits everyone can check

A Mandate gives an agent its own key and bounds on every value it may set. Out-of-bounds actions are invalid on arrival (axiom A9). From the generative example, where one GPO is run entirely by an agent:

cooperative's Mandate (excerpt)hypothetical bounds
"scope": {
  "kinds": ["propose", "accept", "attest"],
  "roles": ["aggregator"],
  "terms": { "UP:Admin-Fee": {
    "payer": {"in": ["supplier"]},
    "rate": {"max": "0.03"}, … } }
}
Rejected · propose · 2027-01-25Agent ed25519:0b2edec9… is out of bounds: UP:Admin-Fee parameter 'rate': 0.035 is above the maximum 0.03.
Rejected · attest · 2027-01-20Agent ed25519:0a8109e4… is out of bounds: claim field 'option': 'C' is not in the allowed set.

Build on it

A foundation, not a platform

The spec is the language. The Python interpreter is a reference you can use, port or replace. If your code produces the same hashes and verdicts, it speaks Universal Paper. Nobody has to grant you access.

$ up validate examples/conventional/bundle.json
chain 0: Master agreement (hypothetical)
  id sha256:47b4b79c2b8e07588427250c27c170241a171cd1e86dded047828518e31d78be
  [ok      ] #0 propose 2026-12-01T15:00:00Z
  [ok      ] #1 accept  2026-12-05T10:00:00Z
  …
  state sha256:f7ca8ea5183a39b1e6a1388dcc33cf0b66e9eb1b91b00df8972bca6548a95144  status at latest event: active
Every event is valid.

$ up derive   examples/conventional/bundle.json --at 2027-04-30T00:00:00Z   # status, tiers, prices, obligations
$ up simulate examples/conventional/bundle.json my-hypothetical-events.json # what-if; Mandate limits still apply
$ up render   examples/confidential/bundle.json --chain 0 --hashes-only     # the contract text, sealed values hidden
$ up trace    examples/conventional/bundle.json -o conventional.trace.json  # every check, as a trace file

The JS tab is the exact code this page runs for the fingerprint lab. It matches the Python interpreter's hashes for the example agreement.

Conformance

Reproduce these results and your code speaks Universal Paper

There's no certification program and nobody to ask for permission. The example traces are the test vectors: every evaluator has to reach the same verdict on every event and the same State hash at every step.

Python · referenceApache-2.0

universal_paper

The complete reference interpreter and CLI used to generate every trace on this page.

  • hash
  • verify
  • derive
  • simulate
  • render
  • trace
JavaScript · this page~60 lines

Hashing only

Canonical JSON plus SHA-256. It reproduces the example agreement and all 16 Term hashes, but it doesn't verify signatures.

  • hash
  • verify
  • derive
  • render
Your languageopen

Your implementation

Port it to Go, Rust, Java or TypeScript, or into a CLM or ERP. If your verdicts and hashes match the traces, every counterparty can rely on them.

Test vectorScenarioEvery evaluator must conclude
conventional.trace.jsonTiered master, two members joining, monthly reports, fees and a tier changeAll events valid. Master reaches state f7ca8ea5…
conventional.tamper-supplier-feeThe supplier's copy had its fee rate changed after signingRejected at event #0. The aggregator's signature doesn't verify
conventional.tamper-aggregator-missing-signatureThe supplier's signature on its acceptance is missing from one copyThe acceptance carries no signatures. The master stays proposed
conventional.tamper-member-backdateA tier attestation was re-signed with an earlier dateRejected as backdated. Past states can't be altered
generative.trace.jsonA GPO run entirely by an agent under a MandateTwo out-of-bounds agent actions rejected (A9). Everything else valid
overlay.trace.jsonA 2024 contract described by its document hash, without renegotiationValid. Duties start only from the overlay's signing
confidential.trace.jsonEvery price, rate and amount sealed. The observer has no disclosuresSame verdicts and same State hash at every step (A10)

Verified agreement in four commands

  1. Install Python 3.11+ and the cryptography package
    cd universal-paper
    pip install -e '.[test]'      # or: export PYTHONPATH=src
  2. Validate an example
    up validate examples/conventional/bundle.json
  3. Ask what's owed on a date
    up derive examples/conventional/bundle.json --at 2027-04-30T00:00:00Z
  4. Read it as a contract, run the tests
    up render examples/conventional/bundle.json --chain 0
    python -m pytest

Specification

A public, versioned spec, with its open questions listed

Universal Paper is a working draft. Here's exactly where it stands, what the documents cover and what is still undecided. Nothing on this page is final until the steward's review closes these questions.

Version
UP/0.1-draft
Maturity
Working draft
Created by
Uppercentile, offered free to everyone
Steward
Uppercentile provisional
Licenses
Spec CC BY 4.0 · Code Apache-2.0 · Examples CC0
Changes
Public changelog and RFC process provisional
Repository
Not public yet
  1. Working draft
  2. Public review
  3. Candidate
  4. 1.0

An illustrative path. No stages or dates have been set.

00Overview: thesis, properties and document map00-overview.md
01Domain: objects, canonical JSON and hashing01-domain.md
02Predicates and functions02-predicates-functions.md
03Axioms A1 to A1303-axioms.md
04Inference: how State is computed04-inference.md
05Lifecycle05-lifecycle.md
06Initial Term library (16 Terms)06-terms/
07Mapping guide: rosters, eligibility and X1207-mapping-guide.md
08Neutrality charter08-neutrality-charter.md

Open questions for the steward

  1. Library emphasis. Aggregator–supplier Terms, member participation, or both? Currently both.
  2. Publishing name. Uppercentile as steward and "Universal Paper" as the project name, for now.
  3. Change process. A public changelog and RFCs, with comment periods and decision rules still to set.
  4. Roles. Fixed at three in v0. The mapping guide suggests a distributor Role will be needed.

From DESIGN_NOTES.md §6

Questions

What teams ask first

Short answers, with the part of the spec that backs each one.

Is this a blockchain?

No. There's no ledger, token, mining or global network. Each agreement has its own short chain of signed events, held by the parties to it. Hashes link the events and Ed25519 signatures authorize them, so any copy can be checked offline.

spec/04-inference.md · axiom A3

Where do our agreements live?

With the parties. A bundle is plain JSON that you can store in your CLM, ERP or a file share. Hosted services can store and route bundles for you, but nobody needs one to verify, because every evaluator recomputes the same verdicts from the same events.

spec/08-neutrality-charter.md: products built on the language may not claim to be required to use it.

Does the language set or suggest prices?

Never. Terms have typed parameters with no default values, so the library can't suggest a price, rate or period. The parties supply every number. The language standardizes process, not economics.

axiom A6 · spec/08-neutrality-charter.md

Do we have to renegotiate existing contracts?

No. UP:Overlay describes a contract you already have by its document hash, so you get computed obligations on day one while the signed PDF stays the governing document.

spec/06-terms/UP-Overlay.md · examples/overlay

How do confidential prices stay private?

A private value can be replaced by a Seal, a salted SHA-256 commitment. Hashes and signatures cover the sealed form, so a holder who sees nothing still reaches the same verdicts and State hashes. You disclose values only to the parties who need them.

axiom A10 · examples/confidential

Can AI agents sign on our behalf?

Yes, within limits. A Mandate gives an agent its own key and bounds on the kinds, Roles, Terms and values it may use. An out-of-bounds event is invalid on arrival for everyone.

axiom A9 · examples/generative

How does it fit with EDI?

Side by side. The mapping guide shows how rosters, eligibility files and the X12 845, 844, 849 and 867 sets correspond to events and projections. The main gap in v0 is the distributor Role, and it's documented.

spec/07-mapping-guide.md

Who governs the spec?

Uppercentile is the current steward provisional. The neutrality charter commits the steward to publish its affiliations, keep the language value-neutral, and transfer stewardship to a neutral body once the language has users across segments. Governance details are still open questions.

spec/08-neutrality-charter.md · DESIGN_NOTES.md §6

What's the license?

Universal Paper was created by Uppercentile, which offers it to everyone for free under open licenses: the specification and Term library are CC BY 4.0, the reference code and schemas are Apache-2.0, and the example agreements are CC0. No account, fee or license key is ever required. Anyone can implement it: if your code produces the same hashes and verdicts, it speaks Universal Paper. Licenses in detail.

Universal Paper

Same paper for everyone. Proof for every change.

Open language, open reference code, no gatekeeper. Pick an example, run the validator, and build the first app your team wishes it had.