metered-protocol 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The metered authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# metered
+
+**A payment protocol for work whose size is only known once it has been delivered.**
+
+You cannot price a language model's answer before it writes one. Today that is settled by the
+seller reporting what it used, against a cap the buyer set in advance — the buyer never verifies
+anything, and for a fifth of a cent, disputing it is not worth anyone's time.
+
+`metered` replaces the invoice with an agreement. The buyer authorises one slice at a time, both
+sides count what was actually delivered, and a small program on Kaspa releases the money whether or
+not either party cooperates at the end.
+
+**The buyer counts what it was given — not what it was told about.** Everything else here is
+bookkeeping around that sentence.
+
+- **[Read the explainer](https://kaspahttp402.github.io/metered-protocol/)** — the idea, in plain
+  terms, for people who are not going to read a specification.
+- **[Read the specification](spec/SPEC.md)** — normative.
+- **[Implement it](spec/CONFORMANCE.md)** — inputs and exact outputs, in a form no implementation
+  can pass by accident.
+
+---
+
+## The two ideas
+
+**One babel at a time.** A *babel* is one reserved slice of delivered work. The buyer authorises a
+babel, receives it, counts it, agrees it, and only then authorises the next. The babel is the
+exposure bound: the most either side can lose if the other turns dishonest mid-session, fixed
+before anything is spent.
+
+**Both sides count.** After each babel the buyer measures it too, with the same *meter* the seller
+named up front. The seller's figure stops being an invoice and becomes a claim standing next
+to the buyer's. If they agree within tolerance, the lower figure is billed. If they do not, the
+session stops — there is no arbiter, because an arbiter would have to be trusted.
+
+Neither party is trusted for anything. The arithmetic does not leave room.
+
+## What is here
+
+| | |
+|---|---|
+| `spec/SPEC.md` | the protocol, normatively |
+| `spec/CONFORMANCE.md` | how to check an implementation, and the four traps that catch people |
+| `spec/conformance-vectors.json` | 36 cases: canonical bytes, the settlement preimage, signatures, reconciliation, settlement, meters |
+| `spec/worked-example.txt` | a complete session, generated, with real signatures |
+| `src/` | reference implementation, TypeScript |
+| `impl-py/` | a second implementation, Python, written from the specification alone |
+| `contracts/` | the covenant, twice: hand-written SilverScript and an Argent port |
+| `evidence/` | the measurements behind every number in the specification |
+| `tools/` | chain tooling — settle, close, anchor, and an end-to-end demo |
+
+## Verifying it yourself
+
+```bash
+npm install
+npm test                 # 193 tests
+npm run conformance      # regenerate the vectors
+npm run conformance:py   # the second implementation, against the same file
+```
+
+`impl-py/` shares no code with `src/`. It was written from `spec/SPEC.md` and implements BIP340
+verification from the BIP rather than importing it, so the two agree on the specification rather
+than on a shared library. All 69 assertions pass.
+
+The covenant suites need [SilverScript](https://github.com/kaspanet/silverscript) and a patched
+debugger; the chain tooling additionally needs a rusty-kaspa WASM build (`METERED_KASPA_SDK`) and a
+funded key. Neither is required to read the specification or run the conformance vectors.
+
+## Status
+
+Both covenants and the full session flow run on **Kaspa testnet-10**. The protocol has not been
+deployed to mainnet: SilverScript is unaudited and Argent is pre-release, and the covenant holds
+funds.
+
+What has been exercised end to end:
+
+- A language model metered through a complete session and settled on chain, with the model's own
+  usage figure, the seller's count and the buyer's count agreeing exactly.
+- Both covenants executing under consensus — a claim posted, a stale claim refused by the network,
+  a newer claim superseding it, the balance split between the parties, and a full refund where no
+  claim was made.
+- Two implementations agreeing on every conformance vector.
+- The tokeniser pinned across languages, token boundary by token boundary, against Python
+  `tiktoken` over mixed scripts, emoji, combining marks and pathological whitespace.
+- Two different units settled through the same unchanged protocol — tokens and delivered bytes —
+  which is what distinguishes a unit-agnostic design from one that merely uses abstract field names.
+
+Figures: the covenant is **504 bytes** of a 520-byte script limit; a State is **72 bytes** signed;
+a checkpoint costs **0.002 KAS**; the response window is **600 blocks, about 60 seconds** at the
+roughly 10 blocks per second Kaspa produces. The same 600-block window is over four days at
+ten-minute block times, which is why the settlement layer is a blockDAG.
+
+## Prior art
+
+`metered` adds the two pieces [x402](https://github.com/coinbase/x402) names as out of scope:
+reservation in chunks so a session can span many settlements, and two-sided measurement so the
+buyer's own count is part of what settles. The chunked-quota idea is older still — telephone
+networks standardised it in RFC 4006 for the same reason, that metering every unit is too expensive
+and trusting the total is too risky. See [PRIOR-ART.md](PRIOR-ART.md).
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

package/contracts/metered.ag

@@ -0,0 +1,135 @@
+// The metered session covenant, in Argent.
+//
+// A port of contracts/metered_session.sil, which is hand-written SilverScript at 520 of 520 bytes
+// with zero spare. Argent compiles to SilverScript, so this does not replace that toolchain --
+// it sits above it. The reason to move is not novelty:
+//
+//   TWO OF THE FIVE FUND-LOSING BUGS FOUND IN THE HAND-WRITTEN VERSION CANNOT BE WRITTEN HERE.
+//
+//   Finding H  a one-output close constrained only outputs[0] and left the rest to fee, so a
+//              provider could burn the buyer's refund. `emits` declares the COMPLETE output
+//              shape, and Argent requires every declared output's value to be disposed of.
+//   Finding J  two covenant inputs could satisfy one payout, destroying the other's balance.
+//              Input-group accounting is what the leader/delegate rules exist for, and
+//              `emits {}` lowers to a consensus-level `OpAuthOutputCount(...) == 0`.
+//
+// WHAT DOES NOT CHANGE. Argent proves the actor, template and successor-state relationships.
+// Application rules stay explicit `require(...)` conditions, so every measured constant below --
+// the 400,000 fee allowance, the 2,000,000 dust floor, the 2,400,000 fold threshold -- is the
+// same number for the same reason, each measured rather than chosen.
+
+state SessionState {
+    // Immutable for the life of the session; carried forward unchanged by every `become`.
+    // In the SilverScript version these were constructor constants outside the state span.
+    // Here they are state, which means the compiler CHECKS that a continuation preserves them
+    // rather than trusting the author to re-emit them correctly.
+    byte[32] parties;
+    byte[16] session_id;
+    int window;
+
+    // The pending claim. SPEC.md 7.4: integers only.
+    int pending_seq;
+    int pending_sompi;
+}
+
+actor MeteredSession owns SessionState {
+    // POST A CLAIM (SPEC.md 7.2 `settle`). Pays nobody: it hands the funds back to this same
+    // actor carrying the agreed State, and restarts the response window. Supersede is the seq
+    // guard, not a separate entry.
+    entry settle(
+        pubkey buyer,
+        pubkey provider,
+        datasig buyer_sig,
+        datasig provider_sig,
+        int seq,
+        int cumulative_units,
+        int cumulative_sompi,
+        byte[32] prev_state
+    ) emits next: MeteredSession {
+        require(blake3(byte[](buyer) + byte[](provider)) == parties);
+
+        // Strictly higher, so a stale State cannot replace a fresher one. pending_seq starts at
+        // -1, so this also implies seq >= 0 on every reachable path.
+        require(seq > pending_seq);
+
+        // cumulative_sompi is load-bearing: it becomes pending_sompi, whose value decides the
+        // close shape, and it is the amount actually paid out. The other two need no lower bound
+        // -- each omission below is argued rather than assumed.
+        require(cumulative_sompi >= 0);
+
+        // SPEC.md 3.4.1: sessionId(16) + seq(8) + cumUnits(8) + cumSompi(8) + prevState(32) = 72.
+        byte[32] digest = blake3(
+            byte[](session_id)
+            + OpNum2Bin(seq, 8)
+            + OpNum2Bin(cumulative_units, 8)
+            + OpNum2Bin(cumulative_sompi, 8)
+            + byte[](prev_state)
+        );
+        require(checkMsgSig(buyer_sig, digest, buyer));
+        require(checkMsgSig(provider_sig, digest, provider));
+
+        SessionState next_state = {
+            parties: parties,
+            session_id: session_id,
+            window: window,
+            pending_seq: seq,
+            pending_sompi: cumulative_sompi,
+        };
+
+        // Written as an addition, never `self.value - fee`: subtraction can underflow, underflow
+        // is undefined, and SilverScript's undefined behaviour is fail-OPEN.
+        require(next.value + 400000 >= self.value);
+        become next <- MeteredSession(next_state);
+    }
+
+    // FINALISE (SPEC.md 7.2 `expire`). No successor: the session ends and the money is paid to
+    // the parties' own keys. `emits {}` is what says so, and lowers to a consensus check that
+    // this input authorises no continuation output at all.
+    entry expire(pubkey buyer, pubkey provider, sig party_sig) emits {} {
+        require(blake3(byte[](buyer) + byte[](provider)) == parties);
+
+        // SPEC.md 7.3: the window is RELATIVE, so ageDaa lowers to OpCheckSequenceVerify and
+        // reads the spending input's sequence field.
+        require(this.ageDaa >= window);
+        require(checkSig(party_sig, buyer) || checkSig(party_sig, provider));
+
+        // SPEC.md 7.2a, Finding J. This covenant accounts for exactly one input -- its own -- and
+        // the payouts below go to plain keys that carry no session identifier, so two sessions
+        // between the same parties would otherwise share one payout and destroy the other's
+        // balance. Measured before the rule existed: 10,400,000 sompi burned.
+        require(tx.inputs.length == 1);
+
+        byte[36] buyer_lock = new ScriptPubKeyP2PK(buyer);
+
+        // DUST (SPEC.md 7.4a). KIP-9 prices an output by its reciprocal, so MEASURED: see tools/dust-map.ts. Whichever side's share is dust, the other
+        // takes the lot: folding costs that party at most 0.02 KAS, and the alternative is
+        // locking the whole balance forever, which is what Finding G actually did.
+        // DUST (SPEC.md 7.4a), measured by tools/dust-map.ts rather than reasoned: the KIP-9
+        // floor is not a constant, and 2,000,000 left an unclosable window at every balance.
+        if (pending_sompi < 2600000) {
+            // The provider earned dust, which includes earning nothing. SPEC.md 7.2: expire
+            // "refunds the buyer entirely if none".
+            require(tx.outputs.length == 1);
+            require(tx.outputs[0].scriptPubKey == byte[](buyer_lock));
+            require(tx.outputs[0].value + 400000 >= self.value);
+        } else {
+            byte[36] provider_lock = new ScriptPubKeyP2PK(provider);
+            require(tx.outputs[0].value == pending_sompi);
+            require(tx.outputs[0].scriptPubKey == byte[](provider_lock));
+            if (tx.outputs.length == 1) {
+                // The buyer's refund is dust, so it goes to fee. The threshold is 2,400,000 and
+                // not 2,000,000 because the refund is self.value - pending_sompi - fee: the
+                // smaller bound would leave 1,600,000..2,000,000 with no legal shape at all.
+                require(pending_sompi + 3000000 >= self.value);
+            } else {
+                require(tx.outputs.length == 2);
+                require(tx.outputs[1].scriptPubKey == byte[](buyer_lock));
+                require(tx.outputs[1].value + pending_sompi + 400000 >= self.value);
+            }
+        }
+    }
+}
+
+app Metered {
+    actor MeteredSession;
+}