One wallet core. Three surfaces. No plaintext on our servers.

// On app.html, open DevTools and try the page's own provider
await myhelix.request({ method: 'mh_chainId' });                 // '0x48454c58'
const [did] = await myhelix.request({ method: 'mh_requestAccounts' });   // approval sheet appears in the app
await myhelix.request({ method: 'mh_getPublicKeys' });
await myhelix.request({ method: 'mh_signMessage', params: { message: 'hello from the console' } });
myhelix.on('grantRevoked', (e) => console.log('revoked', e.grantId));

// did:key for a P-256 public key
const raw = new Uint8Array(await subtle.exportKey('raw', signingPublicKey));   // 0x04 || X || Y (65 bytes)
const compressed = new Uint8Array([raw[64] & 1 ? 0x03 : 0x02, ...raw.slice(1, 33)]);
const did = 'did:key:z' + base58btc(new Uint8Array([0x80, 0x24, ...compressed])); // 0x1200 as unsigned varint
// => did:key:zDnae...

// Demo account address (stands in for the counterfactual ERC-4337 smart-account address)
const address = '0x' + toHex((await sha256(raw)).slice(12));                   // last 20 bytes

// Passphrase -> KEK_pass (wraps MK)
const salt = crypto.getRandomValues(new Uint8Array(16));        // stored next to the wrapped MK
const base = await subtle.importKey('raw', utf8(passphrase.normalize('NFKC')), 'PBKDF2', false, ['deriveBits']);
const kekPass = await subtle.importKey('raw',
  await subtle.deriveBits({ name: 'PBKDF2', hash: 'SHA-256', salt, iterations: 600_000 }, base, 256),
  'AES-GCM', false, ['encrypt', 'decrypt']);

// BIP-39 recovery phrase -> KEK_recovery (wraps the same MK)
const seedBase = await subtle.importKey('raw', utf8(mnemonic.normalize('NFKD')), 'PBKDF2', false, ['deriveBits']);
const seed = await subtle.deriveBits({ name: 'PBKDF2', hash: 'SHA-512', salt: utf8('mnemonic'), iterations: 2048 }, seedBase, 512);
const hk = await subtle.importKey('raw', seed, 'HKDF', false, ['deriveBits']);
const kekRecovery = await subtle.importKey('raw',
  await subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: utf8('myhelix'), info: utf8('myhelix/recovery/v1') }, hk, 256),
  'AES-GCM', false, ['encrypt', 'decrypt']);

{
  "kind": "lab_panel",
  "date": "2026-08-02",
  "label": "Blood 100 panel",
  "source": "Binary Helix Lab Network · kit BH-7Q2D-9X",
  "payload": {
    "resourceType": "DiagnosticReport",
    "org": "Binary Helix Lab Network",
    "collected": "2026-08-02",
    "results": [
      {
        "key": "ldl",
        "code": "13457-7",
        "name": "LDL-C",
        "value": 138,
        "unit": "mg/dL",
        "ref": [
          0,
          130
        ],
        "optimal": [
          0,
          100
        ]
      }
    ]
  }
}

// Mirrors addRecord() + persist() in js/app/vault.js (MH.C = Web Crypto helpers)
async function addRecord(rec /* {kind, date, label, source, payload} */) {
  const id = 'rec_' + C.toHex(C.rand(6));

  // 1. Fresh 256-bit DEK; payload JSON -> AES-GCM with a random 12-byte IV
  const dekRaw = C.rand(32);
  const box = await C.aesEncrypt(await C.aesKeyFromRaw(dekRaw), JSON.stringify(rec.payload));   // {iv, ct} base64

  // 2. Wrap the DEK under the Vault Master Key
  const wdek = await C.aesEncrypt(S.mk, dekRaw);

  // 3. Integrity hash over the CIPHERTEXT bytes (random IV + DEK => unlinkable)
  const hash = await C.sha256hex(C.fromB64(box.ct));

  // 4. The stored envelope carries no metadata at all
  S.vault.records.push({ id, v: 1, iv: box.iv, ct: box.ct, wdek, hash, size: box.ct.length, createdAt: Date.now(), anchor: null });

  // 5. kind / date / label / source go into the sealed index instead
  S.sealed.index[id] = { kind: rec.kind, date: rec.date, label: rec.label, source: rec.source, addedAt: Date.now(), via: null };

  S.vault.pending.push({ hash, kind: 'record', ref: id });     // next Merkle batch
  await audit('Record encrypted & added', rec.label + ' · ' + rec.date);
  await persist();
}

// persist(): the whole sealed index is re-encrypted under MK on every change
async function persist() {
  S.vault.sealed = await C.aesEncrypt(S.mk, JSON.stringify(S.sealed));   // AES-256-GCM, fresh IV each time
  S.vault.rev += 1;
  localStorage.setItem('mh:vault:v1', JSON.stringify(S.vault));          // ciphertext-only vault blob
}

{
  "id": "rec_3f9a1c7e2b4d",
  "v": 1,
  "iv": "e6+MRDPaDCKvjZLd",
  "ct": "fVkwTzh3tvlpnsL+rZNlZ3+xCAQQNbOYtUTn3Vsj6rrrb2cyfEP6vnJ5UXGExxohBuk3MPSgoEGKkBLlJ8faufQMTHCqOP49YnY0f/Ilea7th8TsTrXV0eCEM7oTdZFZfWV/tpubchTDOU03m92zGEdYcpDlBJ4UiE/e5vSM8skXcACAY9xg2RTKXoI412QGmyaGBP1U1TIkqcHuRgWd7K+XnCYtkAi/EWmKlGUPBfOkS1nyZrpaHjFPT4TT7kMJC3nyG4syUnPu3qgexMGqc+7tj2YMbTl5YXxj0VUnZYgNmPv2/aEyyVJAN20=",
  "wdek": {
    "iv": "pQ2mY7cVxK0rTa4L",
    "ct": "0m5Q7Jb3yTqQn2d1bS0mJ8eYc6oZ3uVwq4P7lXf2s9kR1aHdG0nE5tBv8yWc3xMz"
  },
  "hash": "0x1d02aa809eb2afde290f8cf7fc92c3e3262660de0779c74d2997d242bba386f8",
  "size": 316,
  "createdAt": 1785657600000,
  "anchor": {
    "root": "0x0c5c259de9a3ae81fd3f7f310e8942f70c460faa12d52daae71382e6e278cc25",
    "proof": [
      {
        "sibling": "0x6fd68459f58bc44c7e22d3491cd964e2f0c8ec2dc59de2dcede8b52fed4cd3e6",
        "position": "R"
      },
      {
        "sibling": "0x423a032124d082bbc8e0ccc3e117c27ecdfbb8eaa63c7ac7f802a61d79640fca",
        "position": "L"
      },
      {
        "sibling": "0x13ea166dc116ed48f958a335444d36c178948c4bbdac9ca32f52ab9650f91616",
        "position": "R"
      }
    ],
    "txHash": "0x53ba41ed400e4e38fea31c8a817c88e11695a73ae10e4cebe9fd48a1f4bdaf48",
    "block": 1842,
    "at": 1785657612000
  }
}

{
  "profile": {
    "name": "…",
    "birthYear": 1982,
    "sex": "…"
  },
  "index": {
    "rec_3f9a1c7e2b4d": {
      "kind": "lab_panel",
      "date": "2026-08-02",
      "label": "Blood 100 panel",
      "source": "Binary Helix Lab Network · kit BH-7Q2D-9X",
      "addedAt": 1785657600000,
      "via": "kit BH-7Q2D-9X"
    }
  },
  "grants": [
    "…receipts, signatures, scopes, tx hashes…"
  ],
  "kits": [
    "…anonymous barcodes and status history…"
  ],
  "connections": [
    {
      "origin": "portal.helixcare.clinic",
      "name": "HelixCare Clinics portal",
      "permissions": [
        "accounts",
        "requestAccess",
        "submitRecord"
      ],
      "connectedAt": 1785657600000
    }
  ],
  "settings": {},
  "audit": [
    "…hash-chained entries…"
  ],
  "mnemonic": "… (demo only) …",
  "backup": {
    "phraseConfirmed": true,
    "guardians": [
      "…"
    ],
    "shares": [
      "mhs1-1-…",
      "mhs1-2-…",
      "mhs1-3-…"
    ],
    "passkey": false
  },
  "dismissed": []
}

{
  "v": 1,
  "app": "myhelix",
  "createdAt": 1706775120000,
  "did": "did:key:zDnaeTgKt9wNwDUyrTEu7pEEubn4mJAwcZCCWfe8pLEkJcfHs",
  "address": "0x5bd27019df04102da4d187be16d1af5aba6cad7f",
  "signPub": "<base64 raw P-256>",
  "encPub": "<base64 raw P-256>",
  "kdf": {
    "alg": "PBKDF2-SHA256",
    "iters": 600000,
    "salt": "<base64 16 bytes>"
  },
  "wrap": {
    "pass": {
      "iv": "…",
      "ct": "…"
    },
    "recovery": {
      "iv": "…",
      "ct": "…"
    },
    "passkeys": [
      {
        "credId": "…",
        "salt": "…",
        "box": {
          "iv": "…",
          "ct": "…"
        }
      }
    ]
  },
  "identity": {
    "signPriv": {
      "iv": "…",
      "ct": "<PKCS#8 under MK>"
    },
    "encPriv": {
      "iv": "…",
      "ct": "<PKCS#8 under MK>"
    }
  },
  "sealed": {
    "iv": "…",
    "ct": "<sealed index under MK>"
  },
  "records": [
    "<envelopes>"
  ],
  "pending": [
    "<hashes awaiting a batch>"
  ],
  "rev": 42
}

// Mirrors unlockWithPasskey() in js/app/vault.js - no secret to remember
const pk = vault.wrap.passkeys[0];                           // { credId, salt (32 random bytes, b64), box: wrapped MK }
const cred = await navigator.credentials.get({
  publicKey: {
    challenge: C.rand(32),
    allowCredentials: [{ type: 'public-key', id: C.fromB64(pk.credId) }],
    userVerification: 'required',
    extensions: { prf: { eval: { first: C.fromB64(pk.salt) } } }
  }
});
const prf = cred.getClientExtensionResults().prf?.results?.first;   // 32 bytes
if (!prf) throw new Error('This passkey provider does not support the PRF extension - use the passphrase');
const kekPasskey = await C.aesKeyFromRaw(await C.hkdf(new Uint8Array(prf), 'myhelix/passkey/v1'));   // HKDF-SHA256, salt "myhelix"
const mkRaw = await C.aesDecrypt(kekPasskey, pk.box);

// 2-of-3 split of the 32-byte MK over GF(2^8), reduction polynomial x^8+x^4+x^3+x+1 (0x11b)
const shares = shamirSplit(mkRaw, /* n */ 3, /* k */ 2);
// [ 'mhs1-1-<64 hex chars>', 'mhs1-2-<64 hex chars>', 'mhs1-3-<64 hex chars>' ]

// Production: never hand a guardian a plaintext share - encrypt it to their ECDH key
const sealed = await eciesEncrypt(guardian.encryptionKeyRaw, utf8(shares[1]));   // { epk, iv, ct }

// Recovery: any two shares reconstruct MK (Lagrange interpolation at x = 0)
const mkRaw2 = shamirCombine(['mhs1-1-…', 'mhs1-3-…']);

// Lab side (browser or Node 20+). Mirrors eciesEncrypt() in js/app/crypto.js
const subtle = globalThis.crypto.subtle;
const utf8 = (s) => new TextEncoder().encode(s);
const toB64 = (b) => btoa(String.fromCharCode(...new Uint8Array(b)));

async function hkdf(secret, info) {
  const base = await subtle.importKey('raw', secret, 'HKDF', false, ['deriveBits']);
  return new Uint8Array(await subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: utf8('myhelix'), info: utf8(info) }, base, 256));
}

async function eciesEncrypt(recipientRaw /* 65-byte uncompressed P-256 point */, plaintext /* string */) {
  const eph = await subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits']);
  const recipient = await subtle.importKey('raw', recipientRaw, { name: 'ECDH', namedCurve: 'P-256' }, false, []);
  const shared = new Uint8Array(await subtle.deriveBits({ name: 'ECDH', public: recipient }, eph.privateKey, 256));
  const key = await subtle.importKey('raw', await hkdf(shared, 'myhelix/ecies/v1'), 'AES-GCM', false, ['encrypt']);
  const iv = crypto.getRandomValues(new Uint8Array(12));
  const ct = await subtle.encrypt({ name: 'AES-GCM', iv }, key, utf8(plaintext));
  return { epk: toB64(await subtle.exportKey('raw', eph.publicKey)), iv: toB64(iv), ct: toB64(ct) };
}

// Demo plaintext: the record the wallet will seal (production: a FHIR R4 Bundle)
const result = { kind: 'lab_panel', date: '2026-09-14', label: 'Pulse Kit · 8 markers',
                 source: 'Binary Helix Lab Network · kit BH-7Q2D-9X', payload: diagnosticReport };
const envelope = await eciesEncrypt(walletEncRaw /* from mh_getPublicKeys().encryption.raw */, JSON.stringify(result));

// Sign canonical(envelope) with the lab's ECDSA P-256 key; the wallet verifies BEFORE decrypting
const sig = await subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, labSigningKey, utf8(canonical(envelope)));
const signature = '0x' + [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, '0')).join('');   // raw r||s

await myhelix.request({
  method: 'mh_submitRecord',
  params: { envelope, source: 'Binary Helix Lab Network', kitId: 'BH-7Q2D-9X', signature, signerPublicKey: labSignRawB64 }
});
// ...or post the same {env, labSig, labSignPub} to the relay inbox for that kit (no name, no DOB, no email).

{
  "kinds": [
    "lab_panel"
  ],
  "markers": [
    "apob",
    "ldl",
    "a1c"
  ],
  "from": "2025-01-01"
}

// Mirrors createGrant() in js/app/vault.js - runs after the patient approves (and possibly narrows) the request
async function createGrant({ granteeId, scope, purpose, hours, shareName }) {
  const cp = counterparty(granteeId);                                  // verified directory entry: did, encPub
  const pkg = await buildPackage(scope);                               // decrypts matching records, filters markers
  const grantId = await C.sha256hex(C.rand(32));
  const grantKeyRaw = C.rand(32);                                      // fresh per grant

  // Package plaintext (demo JSON; production can emit a FHIR R4 Bundle)
  const box = await C.aesEncrypt(await C.aesKeyFromRaw(grantKeyRaw), JSON.stringify({
    patient: shareName ? S.sealed.profile.name : 'MyHelix member',
    scope,
    items: pkg.items                                                   // [{kind, date, label, source, hash, data}]
  }));
  const wrapped = await C.eciesEncrypt(C.fromB64(cp.encPub), grantKeyRaw);   // {epk, iv, ct}

  const now = Math.floor(Date.now() / 1000);
  const receipt = {
    type: 'MyHelixConsent', version: '1', chainId: '0x48454c58', verifyingContract: CONSENT_REGISTRY,
    grantId, grantor: S.vault.did, grantee: cp.did, scopeHash: await C.sha256hex(C.canonical(scope)),
    purpose, issuedAt: now, expiresAt: now + hours * 3600, nonce: C.toHex(C.rand(8))
  };
  const signature   = await C.sign(S.signPriv, C.canonical(receipt));          // "0x" + raw r||s
  const receiptHash = await C.sha256hex(C.canonical(receipt));
  const granteeCommitment = await C.sha256hex(cp.did + receipt.nonce);         // SHA-256(UTF-8(did + nonce))

  const { tx } = await ledger.submit('ConsentRegistry', 'grant',
    { grantId, grantee: granteeCommitment, receiptHash, expiresAt: receipt.expiresAt });
  relay.grants[grantId] = { receipt, signature, grantorSignPub: S.vault.signPub, wrappedKey: wrapped, box };
  S.vault.pending.push({ hash: receiptHash, kind: 'receipt', ref: grantId });  // also Merkle-anchored
  await audit('Access granted', cp.name + ' · ' + pkg.count + ' records · ' + purpose);
  await persist();

  // Provider result: package = { epk: wrapped.epk, wiv: wrapped.iv, wct: wrapped.ct, iv: box.iv, ct: box.ct }
}

{
  "type": "MyHelixConsent",
  "version": "1",
  "chainId": "0x48454c58",
  "verifyingContract": "0xc0a5e7b1d9f3a2c64e8b7d1f0a9c3e5b2d6f8a17",
  "grantId": "0x5c1fa0d3e7b24c9a86f1d2e3b4a5968778695a4b3c2d1e0f9a8b7c6d5e4f3a2b",
  "grantor": "did:key:zDnaeTgKt9wNwDUyrTEu7pEEubn4mJAwcZCCWfe8pLEkJcfHs",
  "grantee": "did:key:zDnaerx9CtbPJ1q36T5Ln5wYt3MQYeGRG5ehnPAmxcf5mDZpv",
  "scopeHash": "0xe17d862d61e2f77cade7c0a16aa946f9faf765b575a4d3fa8857edb9a6d0ce9e",
  "purpose": "Treatment",
  "issuedAt": 1789560000,
  "expiresAt": 1789819200,
  "nonce": "8e2b4f6a1c3d5e7f"
}

{
  "domain": {
    "name": "MyHelix",
    "version": "1",
    "chainId": "0x48454c58",
    "verifyingContract": "0xc0a5e7b1d9f3a2c64e8b7d1f0a9c3e5b2d6f8a17"
  },
  "primaryType": "MyHelixConsent",
  "types": {
    "MyHelixConsent": [
      {
        "name": "grantId",
        "type": "bytes32"
      },
      {
        "name": "grantor",
        "type": "string"
      },
      {
        "name": "grantee",
        "type": "string"
      },
      {
        "name": "scopeHash",
        "type": "bytes32"
      },
      {
        "name": "purpose",
        "type": "string"
      },
      {
        "name": "issuedAt",
        "type": "uint64"
      },
      {
        "name": "expiresAt",
        "type": "uint64"
      },
      {
        "name": "nonce",
        "type": "string"
      }
    ]
  },
  "message": "<receipt fields other than type / version / chainId / verifyingContract>"
}

// Mirrors audit() / verifyAudit() in js/app/vault.js
const GENESIS = '0x' + '0'.repeat(64);

async function audit(action, detail, actor = 'You') {
  const log = S.sealed.audit;                                       // lives inside the sealed index
  const prev = log.length ? log[log.length - 1].hash : GENESIS;
  const e = { i: log.length, ts: Date.now(), actor, action, detail, prev };
  e.hash = await C.sha256hex(prev + C.canonical(e));                // SHA-256(UTF-8(prevHash + canonical(entry-without-hash)))
  log.push(e);
}

async function verifyAudit(log) {
  let prev = GENESIS;
  for (const { hash, ...body } of log) {
    if (body.prev !== prev || await C.sha256hex(prev + C.canonical(body)) !== hash) return { ok: false, at: body.i };
    prev = hash;
  }
  return { ok: true, head: prev };                                  // head is added as a leaf to every anchor batch
}

// Mirrors merkle() / verifyProof() in js/app/crypto.js and anchorPending() in js/app/vault.js
const leafHash = (h) => C.sha256hex(C.concat(new Uint8Array([0x00]), C.fromHex(h)));
const nodeHash = (l, r) => C.sha256hex(C.concat(new Uint8Array([0x01]), C.fromHex(l), C.fromHex(r)));

async function merkle(hashes) {
  let level = await Promise.all(hashes.map(leafHash));
  const proofs = hashes.map(() => []), pos = hashes.map((_, i) => i);
  while (level.length > 1) {
    const next = [];
    for (let i = 0; i < level.length; i += 2) {
      next.push(i + 1 < level.length ? await nodeHash(level[i], level[i + 1]) : level[i]);   // odd node promoted
    }
    pos.forEach((p, leaf) => {
      const sib = p ^ 1;
      if (sib < level.length) proofs[leaf].push({ sibling: level[sib], position: sib < p ? 'L' : 'R' });
      pos[leaf] = p >> 1;
    });
    level = next;
  }
  return { root: level[0], proofs };
}

// One batch = pending record hashes + receipt hashes + the CURRENT AUDIT-LOG HEAD as an extra leaf
async function anchorPending() {
  const items = S.vault.pending.slice();
  const log = S.sealed.audit;
  if (log.length) items.push({ hash: log[log.length - 1].hash, kind: 'audit', ref: 'audit:' + (log.length - 1) });
  const tree = await merkle(items.map((x) => x.hash));
  const { tx, block } = await ledger.submit('HelixAnchor', 'anchor', { root: tree.root, leafCount: items.length, batchId });
  items.forEach((it, i) => attachAnchor(it, { root: tree.root, proof: tree.proofs[i], txHash: tx.hash, block: block.number, at: block.timestamp }));
  S.vault.pending = [];
}

// Verify one record end-to-end
async function verifyRecord(r) {
  const h = await C.sha256hex(C.fromB64(r.ct));                              // 1. recompute from ciphertext
  if (h !== r.hash) return false;                                            //    flipped bit => fails here
  let acc = await leafHash(h);                                               // 2. fold the proof
  for (const { sibling, position } of r.anchor.proof) acc = position === 'L' ? await nodeHash(sibling, acc) : await nodeHash(acc, sibling);
  if (acc !== r.anchor.root) return false;
  return (await helixAnchor.roots(r.anchor.root)) > 0n;                      // 3. root known on chain
}

// On-chain equivalent: HelixAnchor.verifyProof(hash, proof.map(p => p.sibling), proof.map(p => p.position === 'L'), root)

// Sponsored consent registration from the patient's smart account (ERC-4337)
const callData = smartAccount.encodeExecute({
  to: CONSENT_REGISTRY,
  data: encodeFunctionData({ abi: consentRegistryAbi, functionName: 'grant',
                             args: [grantId, granteeCommitment, receiptHash, BigInt(expiresAt)] })
});
const userOp = await bundler.prepareUserOperation({
  sender: smartAccount.address,
  callData,
  paymaster: BINARY_HELIX_PAYMASTER          // policy: only HelixAnchor / ConsentRegistry calls, rate limited
});
// Owner signature is P-256 (wallet signing key or passkey), checked on-chain by the RIP-7212 precompile (0x…0100)
userOp.signature = await smartAccount.signUserOperation(userOp);
const txHash = await bundler.sendUserOperation(userOp);

type DID = `did:key:z${string}`;
type Hex = `0x${string}`;
type B64 = string;                                   // standard base64
type RawP256Key = { kty: 'EC'; crv: 'P-256'; alg: 'ES256' | 'ECDH-ES'; raw: B64 };   // raw = 65-byte uncompressed point

interface MyHelixProvider {
  readonly isMyHelix: true;
  request<M extends keyof Methods>(args: { method: M; params?: Methods[M]['params'] }): Promise<Methods[M]['result']>;
  on<E extends keyof Events>(event: E, listener: (payload: Events[E]) => void): void;
  removeListener<E extends keyof Events>(event: E, listener: (payload: Events[E]) => void): void;
}

interface Methods {
  mh_requestAccounts: { params?: { name?: string }; result: [DID] };                // connect prompt
  mh_accounts:        { params?: undefined; result: [DID] | [] };
  mh_chainId:         { params?: undefined; result: '0x48454c58' };
  mh_getPublicKeys:   { params?: undefined; result: { did: DID; address: Hex; signing: RawP256Key; encryption: RawP256Key } };
  mh_requestAccess:   { params: AccessRequest; result: AccessResult };             // approval UI (user may narrow)
  mh_revokeAccess:    { params: { grantId: Hex }; result: { txHash: Hex } };
  mh_submitRecord:    { params: { envelope: { epk: B64; iv: B64; ct: B64 }; source: string; kitId?: string;
                                  signature?: Hex; signerPublicKey?: B64 };         // ECDSA P-256 over canonical(envelope)
                        result: { recordId: string; hash: Hex } };                 // approval UI
  mh_signMessage:     { params: { message: string }; result: { signature: Hex; did: DID } }; // approval UI
  mh_verifyRecord:    { params: { hash: Hex };
                        result: { anchored: boolean; valid: boolean; root?: Hex; proof?: ProofStep[]; txHash?: Hex; block?: number } };
}

interface AccessRequest {
  grantee: { did: DID; name: string; encryptionKey?: B64 };   // resolved by did against the verified directory; unknown => 4100
  scope: { kinds: string[]; markers: string[]; from?: string; to?: string; includeSensitive?: boolean };
  purpose: string;
  durationHours: number;                                                           // e.g. 24, 72, 168, 720
}

interface AccessResult {
  grantId: Hex;
  receipt: ConsentReceipt;                  // reflects what the patient APPROVED, which may be narrower than requested
  signature: Hex;                           // ECDSA P-256 over UTF-8(canonical(receipt)), raw r||s
  package: { epk: B64; wiv: B64; wct: B64; iv: B64; ct: B64 };
  expiresAt: number;                        // unix seconds
  txHash: Hex;                              // ConsentRegistry.grant
}

interface ConsentReceipt {
  type: 'MyHelixConsent'; version: '1'; chainId: '0x48454c58'; verifyingContract: Hex;
  grantId: Hex; grantor: DID; grantee: DID; scopeHash: Hex;
  purpose: string; issuedAt: number; expiresAt: number; nonce: string;             // nonce: 16 hex chars
}

type ProofStep = { sibling: Hex; position: 'L' | 'R' };

interface Events {
  connect: { chainId: '0x48454c58' };
  disconnect: { code: number; message: string };
  accountsChanged: DID[];
  lock: void;
  unlock: void;
  grantRevoked: { grantId: Hex };
}

// Discover MyHelix without relying on a global (EIP-6963 style)
function discoverMyHelix(timeoutMs = 800) {
  return new Promise((resolve, reject) => {
    const onAnnounce = (event) => {
      window.removeEventListener('myhelix:announceProvider', onAnnounce);
      clearTimeout(timer);
      resolve(event.detail);                  // { info: { uuid, name, icon, rdns: 'bio.binaryhelix.myhelix' }, provider }
    };
    const timer = setTimeout(() => {
      window.removeEventListener('myhelix:announceProvider', onAnnounce);
      reject(new Error('MyHelix wallet not found'));
    }, timeoutMs);
    window.addEventListener('myhelix:announceProvider', onAnnounce);
    window.dispatchEvent(new Event('myhelix:requestProvider'));
  });
}

page                     inpage.js (MAIN)          content.js (ISOLATED)       background.js (SW)            approval window
 │ request({method})  ──▶ postMessage(target:      ──▶ port.postMessage      ──▶ origin = port.sender.origin
 │                        'myhelix-contentscript')                               permission? unlocked?
 │                                                                              chrome.windows.create(popup) ──▶ shows origin + scope
 │                                                                                                       ◀── approve / reject / close
 │                                                                              vault op (packages/core)
 │ Promise resolves  ◀──  postMessage(target:      ◀── port.onMessage        ◀── { type:'response', id, result | error }
 │                        'myhelix-inpage')
 │ on('lock')        ◀──  event                    ◀── event                 ◀── chrome.alarms / chrome.idle -> lock()

extension/
├── manifest.json      MV3: service worker, MAIN-world provider script, isolated bridge, popup
├── inpage.js          window.myhelix  +  myhelix:requestProvider / myhelix:announceProvider
├── content.js         window.postMessage  <->  chrome.runtime.connect Port
├── background.js      vault session · per-origin permissions · RPC dispatch · approvals · auto-lock
├── popup.html/.js     create / unlock / lock · connected sites · Open MyHelix
├── approval.html/.js  chrome.windows.create({ type: 'popup' }) approval window
├── popup.css
└── README.md          load unpacked · what works · what remains

forge init contracts && cp HelixAnchor.sol ConsentRegistry.sol contracts/src/
cd contracts
forge build                                   # solc 0.8.24+
forge test -vvv                               # include a test that folds proofs produced by packages/core
forge script script/Deploy.s.sol --rpc-url base_sepolia --broadcast --verify

// payload is ECIES-encrypted to mh_getPublicKeys().encryption before sending
await myhelix.request({ method: 'mh_submitRecord', params: {
  envelope,                         // { epk, iv, ct } of the JSON below
  source: 'HelixCare Clinics',
  signature, signerPublicKey        // ECDSA P-256 over canonical(envelope)
}});
// plaintext inside the envelope
{ "kind": "prescription", "date": "2026-09-21", "label": "e-Prescription · Ezetimibe 10 mg",
  "payload": { "catId": "ezetimibe", "name": "Ezetimibe", "dose": 10, "unit": "mg", "route": "oral",
               "sched": { "type": "daily", "times": ["08:00"] }, "prescriber": "Dr. Amara Okafor, MD", "refills": 3 } }

myhelix/
├── packages/
│   ├── core/                 TypeScript, zero UI. One implementation for every surface.
│   │   ├── src/crypto/       aes-gcm · kdf (PBKDF2/HKDF) · ecies · bip39 · shamir · did · canonical-json
│   │   ├── src/vault/        master key, wrapping, unlock factors, storage adapters (IndexedDB / chrome.storage / Keychain)
│   │   ├── src/records/      envelopes, FHIR normalisation, import pipelines
│   │   ├── src/grants/       scopes, packages, receipts, revocation
│   │   ├── src/ledger/       Merkle batching, proofs, HelixAnchor / ConsentRegistry client, ERC-4337 UserOps
│   │   ├── src/provider/     RPC schema, errors, permission model (shared by extension + mobile pairing)
│   │   └── test/vectors/     JSON test vectors: BIP-39, HKDF, ECIES, Shamir, Merkle, receipts
│   └── ui/                   React components + shell layouts (web / extension / mobile-web)
├── apps/
│   ├── web/                  PWA (app.html in this demo)
│   ├── extension/            MV3 (extension/ skeleton in this demo)
│   └── mobile/               Expo / React Native
├── contracts/                Foundry: src/HelixAnchor.sol, src/ConsentRegistry.sol, test/, script/
└── services/                 suggested: relay (ciphertext + grant mailboxes), batcher, paymaster policy