Publish live @dotprotocol/* source (reproducibility gate)

packages/PROVENANCE.md

@@ -0,0 +1,65 @@
+# Live npm provenance — `@dotprotocol/*` packages
+
+This document records where the **live published** npm packages come from, so anyone
+can reproduce them. Resolved 2026-05-29 (Room "Mark III" reproducibility gate).
+
+## The two scopes
+
+There are two npm scopes, one hyphen apart:
+
+- **`@dotprotocol/*`** (NO hyphen) — the **live, published, in-use** packages on npm.
+- **`@dot-protocol/*`** (hyphen) — the namespace used inside this repo's source and in
+  the (unpublished) granular alpha packages.
+
+The live published packages keep their published **names, versions, and APIs** unchanged.
+This repo is the public, reproducible **source** for them.
+
+## Source map (live `@dotprotocol/*` → source in this repo)
+
+| Live npm package (v1.0.0) | How it ships | Source |
+|---|---|---|
+| `@dotprotocol/core`   | raw `src/index.ts` | `packages/core` (named `@dot-protocol/core` here; published under no-hyphen scope) |
+| `@dotprotocol/chain`  | raw `src/`         | `packages/chain` |
+| `@dotprotocol/mesh`   | raw `src/`         | `packages/mesh` |
+| `@dotprotocol/cli`    | —                  | `packages/cli` |
+| `@dotprotocol/lang`   | —                  | `packages/lang` |
+| `@dotprotocol/compression` | tsdown `dist/` | `packages/compression` |
+| `@dotprotocol/qr`     | tsdown `dist/`     | `packages/qr` |
+| `@dotprotocol/wrapper`| tsdown `dist/`     | `packages/wrapper` |
+| `@dotprotocol/arena`  | tsdown `dist/`     | `packages/arena` |
+| `@dotprotocol/relay`  | tsdown `dist/`     | `packages/relay` |
+| `@dotprotocol/identity`| tsdown `dist/`    | `packages/identity` |
+| `@dotprotocol/sdk`    | tsdown `dist/`     | `packages/sdk` |
+
+The 7 `dist`-shipped packages were originally cut at source version `0.3.0` and published
+to npm at `1.0.0` (a version bump, no API change). Their `src/` is committed here.
+
+## Build / reproduce
+
+`core`, `chain`, `mesh`, `cli`, `lang` publish their `src/` directly (the package `main`
+points at `src/index.ts`), so they are reproduced by `npm pack` of the package directory.
+
+The 7 `dist`-shipped packages build with `tsdown`:
+
+```bash
+pnpm install
+cd packages/<pkg> && pnpm exec tsdown   # emits dist/
+npm pack                                  # produces the publishable tarball
+```
+
+Note: the 7 packages declare `workspace:*` deps on `@dotprotocol/core` etc. When built
+standalone for publish, those resolve against the published `@dotprotocol/*` packages on
+the npm registry. Within this repo, the local core/chain are named `@dot-protocol/*`
+(hyphen) — this scope difference is intentional and preserved to avoid renaming live
+packages.
+
+## Acceptance test results (2026-05-29)
+
+`npm pack` of source vs the live npm tarball, per package:
+
+- `core`, `chain`, `mesh`: **file lists IDENTICAL**, `src/` contents byte-identical.
+  Only difference is the package.json `name` (`@dot-protocol/` here vs `@dotprotocol/`
+  published) — the publish step renames the scope.
+- `identity`, `qr`, `arena`, `sdk`: built `dist/` **export surface matches live exactly**
+  (same exported symbols). `dist` filenames carry tsdown content-hash suffixes which vary
+  with toolchain version, so they are functionally — not byte — identical.

packages/arena/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DOT Protocol contributors
+
+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.

packages/arena/README.md

@@ -0,0 +1,116 @@
+# @dotprotocol/arena
+
+Elo engine + blind prediction evaluation for DOT Protocol.
+
+[![npm](https://img.shields.io/npm/v/@dotprotocol/arena)](https://www.npmjs.com/package/@dotprotocol/arena)
+
+## Install
+
+```bash
+npm install @dotprotocol/arena
+```
+
+## Quick start
+
+```js
+import { resolveSession, rankLeaderboard } from '@dotprotocol/arena';
+
+// Resolve predictions against oracle outcome
+const { matches, ratings } = await resolveSession(session, resolutionDOT);
+
+// Rank by Elo
+const board = rankLeaderboard('prediction', entries);
+```
+
+## How blind evaluation works
+
+1. **Predictors submit** DOTs with sealed answers (commitment scheme)
+2. **Hash is published** before the oracle resolves — no retroactive changes
+3. **Oracle resolves** by emitting a resolution DOT
+4. **Session resolves** — correct predictions win Elo, incorrect ones lose it
+5. **Chain proves** the sequence — oracle cannot have seen predictions before resolving
+
+```js
+import { hashPredictionDOT, resolveSession, verifyPrediction } from '@dotprotocol/arena';
+
+// --- Predictor ---
+const predDOT    = await createDOT({ keypair, payload: myAnswer });
+const commitment = hashPredictionDOT(predDOT); // publish this hash
+
+// --- Oracle ---
+const resDOT = await createDOT({ keypair: oracleKeypair, payload: trueOutcome });
+
+// --- Resolution ---
+const session = { predictions: [predDOT], commitments: [commitment], domain: 'crypto' };
+const { matches, ratings } = await resolveSession(session, resDOT);
+```
+
+## API
+
+### `resolveSession(session, resolutionDOT)`
+
+Evaluate all predictions in a session against the oracle's resolution.
+
+```js
+const { matches, ratings } = await resolveSession({
+  predictions:  predictionDOTs,     // DOT[] — sealed predictions
+  commitments:  commitmentHashes,   // Uint8Array[] — published hashes
+  domain:       'crypto',           // string — Elo domain
+  initialRatings: new Map(),        // optional — Map<pubkey, number>
+}, resolutionDOT);
+
+// matches: [{ predictor: Uint8Array, correct: boolean, eloDelta: number }]
+// ratings: Map<pubkeyHex, number> — updated Elo ratings
+```
+
+### `verifyPrediction(predictionDOT, commitment)`
+
+Verify that a prediction DOT matches its published commitment.
+
+```js
+const ok = verifyPrediction(predictionDOT, commitment); // boolean
+```
+
+### `hashPredictionDOT(dot)`
+
+Compute the commitment hash for a prediction DOT.
+
+```js
+const hash = hashPredictionDOT(dot); // Uint8Array(32)
+```
+
+### `rankLeaderboard(domain, entries)`
+
+Sort leaderboard entries by Elo descending.
+
+```js
+const board = rankLeaderboard('crypto', [
+  { pubkey: aliceKey, elo: 1650 },
+  { pubkey: bobKey,   elo: 1720 },
+]);
+// [{ pubkey: bobKey, elo: 1720, rank: 1 }, ...]
+```
+
+### Elo utilities
+
+```js
+import { updateElo, computeEloFromMatches, computeEloPercentile } from '@dotprotocol/arena';
+
+// Single match
+const { newRating, delta } = updateElo({
+  rating:         1500,
+  opponentRating: 1600,
+  outcome:        'win',   // 'win' | 'draw' | 'loss'
+  K:              32,
+});
+
+// Bulk from history
+const rating = computeEloFromMatches(ELO_DEFAULT, matchHistory);
+
+// Where does this rating fall?
+const pct = computeEloPercentile(1720, allRatings); // 0.87 = top 13%
+```
+
+## License
+
+MIT

packages/arena/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@dotprotocol/arena",
+  "version": "0.3.0",
+  "description": "DOT Protocol Arena \u2014 Elo engine, blind evaluation, prediction resolution. DOT spreads like life, not like messages.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "dot-protocol",
+    "elo",
+    "prediction",
+    "blind-evaluation",
+    "arena"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0"
+  },
+  "dependencies": {
+    "@dotprotocol/core": "workspace:*",
+    "@dotprotocol/chain": "workspace:*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dot-protocol/dot.git",
+    "directory": "packages/arena"
+  },
+  "homepage": "https://github.com/dot-protocol/dot/tree/main/packages/arena#readme",
+  "bugs": {
+    "url": "https://github.com/dot-protocol/dot/issues"
+  }
+}

packages/arena/src/elo.ts

@@ -0,0 +1,54 @@
+/**
+ * DOT Protocol v0.3.0 — Arena Elo Engine
+ *
+ * Per-domain Elo ratings computed from prediction/resolution DOT pairs.
+ * Re-exports and extends the @dotprotocol/chain scoring utilities.
+ */
+
+import { updateElo, applyEloUpdates, ELO_DEFAULT } from '@dotprotocol/chain';
+import type { EloUpdate } from '@dotprotocol/chain';
+import type { ArenaMatch } from './types.js';
+
+export { updateElo, applyEloUpdates, ELO_DEFAULT };
+export type { EloUpdate };
+
+/**
+ * Compute Elo deltas for a batch of arena matches.
+ * Returns a map of domain → new Elo rating.
+ */
+export function computeEloFromMatches(
+  existingElo: Map<string, number>,
+  matches: ArenaMatch[]
+): Map<string, number> {
+  const updates: EloUpdate[] = matches.map((m) => ({
+    domain: m.prediction.domain,
+    correct: m.correct,
+  }));
+  return applyEloUpdates(existingElo, updates);
+}
+
+/**
+ * Compute Elo percentile of a given rating against a population.
+ * Returns 0–1 (1 = top of population).
+ */
+export function computeEloPercentile(rating: number, population: number[]): number {
+  if (population.length === 0) return 0.5;
+  const below = population.filter((r) => r < rating).length;
+  return below / population.length;
+}
+
+/**
+ * Produce a ranked leaderboard from a map of pubkey → Elo scores.
+ */
+export function rankLeaderboard(
+  domain: string,
+  entries: Array<{ pubkey: string; elo: number; totalPredictions: number; correctPredictions: number }>
+): import('./types.js').LeaderboardEntry[] {
+  const sorted = [...entries].sort((a, b) => b.elo - a.elo);
+  return sorted.map((e, i) => ({
+    ...e,
+    domain,
+    rank: i + 1,
+    accuracy: e.totalPredictions > 0 ? e.correctPredictions / e.totalPredictions : 0,
+  }));
+}

packages/arena/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @dotprotocol/arena — v0.3.0
+ *
+ * Elo engine, blind evaluation, prediction resolution.
+ * DOT spreads like life, not like messages.
+ *
+ * "DOT is a noun-verb. A state that records its own transition."
+ */
+
+// Elo engine
+export {
+  updateElo,
+  applyEloUpdates,
+  computeEloFromMatches,
+  computeEloPercentile,
+  rankLeaderboard,
+  ELO_DEFAULT,
+} from './elo.js';
+export type { EloUpdate } from './elo.js';
+
+// Resolution protocol
+export {
+  verifyResolution,
+  verifyPrediction,
+  resolveSession,
+  hashPredictionDOT,
+} from './resolution.js';
+
+// Types
+export type {
+  PredictionDOT,
+  ResolutionDOT,
+  ArenaMatch,
+  BlindEvalSession,
+  LeaderboardEntry,
+} from './types.js';