Six flows. The mechanic that enforces every commitment.

# the envelope OrangeCheck signs · class C session_creation
{
  "v": 1,
  "kind": "oc-me-event",
  "id": "oc-me-9k2x4f7p",
  "class": "C",
  "subtype": "session_creation",
  "identity": "bc1q...e3lr",         // your user's oc identity
  "site": "yourcompany.com",          // your project domain
  "session_duration_seconds": 604800, // 7 days
  "occurred_at": "2026-04-30T16:11:08Z",
  "gross_fee_sats": 64,               // funded by your project
  "platform_fee_sats": 13,            // round(64 × 0.20), to OC (charter §07)
  "user_earned_sats": 42,             // round(64 × 0.65), your user_share
  "site_rebate_sats": 9,              // your residual (64 − 13 − 42)
  "sig": "ed25519:2b:9pK4...rT8x"     // signed by OC on your behalf
}

# computeFees() · the canonical formula
//  in lib/events/types.ts (CI-tested, conformance-vector-locked)

const PLATFORM = 0.20;

function computeFees(cfg, payment_amount_sats?) {
  const gross = cfg.site_pays.kind === 'fixed_sats'
    ? cfg.site_pays.sats
    : Math.round(payment_amount_sats * cfg.site_pays.pct);

  const platform = Math.round(gross * PLATFORM);
  // user_share is a fraction of GROSS (clamped to 0.8), then capped
  // so platform + user never exceed gross.
  const share    = Math.min(0.8, Math.max(0, cfg.user_share_pct));
  const user     = Math.min(gross - platform, Math.round(gross * share));
  const rebate   = gross - platform - user;

  return { gross, platform, user, rebate };
}

// example · gross 1000, user_share 0.65
//   → platform 200, user 650, rebate 150

# the federation descriptor · the shape, once a federation is bound
{
  "v": 1,
  "identity": "bc1q...e3lr",
  "signing_method": "federation_threshold",
  "guardian_set_id": "fed11qgqrgvnhwd...",
  "threshold": "5-of-7",
  "graduation_path": [
    "stay-federation",
    "graduate-to-fedimint",
    "graduate-to-self-custody"
  ]
}

# after /me/graduate · once graduation opens · same identity, new method
{
  "v": 1,
  "identity": "bc1q...e3lr",        // unchanged
  "signing_method": "bip322",
  "graduated_at": "2026-05-15T09:21:00Z",
  "previous_method": "federation_threshold"
}

# oc_session JWT · what every consumer subdomain reads
{
  "alg": "EdDSA",
  "kid": "oc-auth-1",
  "sub": "did:btc:bc1q...e3lr",
  "addr": "bc1q...e3lr",
  "npub": "npub1...8q9w",
  "iat": 1714512000,
  "exp": 1715116800,
  "scope": ["identity", "payment"],
  "session_policy": {
    "duration_seconds": 604800,
    "refresh": "sliding"
  }
}

# JWKS published at ochk.io/.well-known/jwks.json
# verified locally · no ochk.io round-trip per request

# subtype → class mapping · in lib/events/types.ts
//  CI-tested · ratified · changeable only via spec PR

export const SUBTYPE_CLASS: Record<EventSubtype, EventClass> = {
  // Class A — state transitions
  account_creation:           'A',
  account_recovery:           'A',
  attest_bond_increased:      'A',
  payment_method_connected:   'A',
  agent_delegation_issued:    'A',
  recovery_method_updated:    'A',

  // Class B — action-bound
  payment_authorization:      'B',
  scoped_action_authorization:'B',
  attest_verification_at_gate:'B',
  stamp_signing:              'B',
  pledge_resolution:          'B',

  // Class C — sessions
  session_creation:           'C',
};

#!/usr/bin/env node
// Verify a me.ochk.io envelope with nothing but Node 18+.
//   node verify-envelope.mjs <envelope-id> [https://me.ochk.io]
import { createHash, createPublicKey, verify } from 'node:crypto';

const [id = 'oc-me-example-receipt', base = 'https://me.ochk.io'] = process.argv.slice(2);
const get = (path) => fetch(base + path).then((r) => r.json());

// 1. The envelope: its canonical bytes, and the signature over them.
const env = await get(`/api/envelope/${encodeURIComponent(id)}?format=wrapped`);
if (!env.ok || !env.signature) throw new Error(`no signed envelope at ${id}`);
const bytes = Buffer.from(env.canonical_b64, 'base64');

// 2. The key it names, from the published key set.
const jwks = await get('/.well-known/oc-envelope-jwks.json');
const jwk = jwks.keys.find((k) => k.kid === env.signature.kid);
if (!jwk) throw new Error(`key ${env.signature.kid} is not in the published set`);

// 3. Ed25519 over the canonical bytes themselves, not over a hash of them.
const ok = verify(
    null,
    bytes,
    createPublicKey({ key: jwk, format: 'jwk' }),
    Buffer.from(env.signature.sig_hex, 'hex')
);

// 4. The content address. A billable event's id is a routing id, so it is
//    reported, not compared; the other envelope kinds are named by it.
const sha256 = createHash('sha256').update(bytes).digest('hex');

// 5. The OpenTimestamps proof, when anchored, is over that digest:
//    save env.ots.proof_b64 and walk it with the `ots` client and your node.
console.log({ id, ok, kid: env.signature.kid, sha256, ots: env.ots?.status ?? 'not anchored' });
process.exit(ok ? 0 : 1);