From 40aca9e3f4af3f469f25c742de957d31a40fc22a Mon Sep 17 00:00:00 2001 From: Leonardo Custodio Date: Wed, 16 Sep 2026 09:41:43 -0700 Subject: [PATCH 1/2] Improvements to docs --- README.md | 29 ++++------------------------- 1 file changed, 4 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 695eb0c..dc191ea 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ **`bc-xid-ts`** implements eXtensible IDentifiers: stable, self-certifying decentralized identifiers whose keys, delegates, and permissions can evolve over time. -XIDs (eXtensible IDentity, _/zid/_) are unique 32-byte identifiers that represent any entities—real or abstract—such as a person, organization, or device. Generated from the SHA-256 hash of a specific public signing key known as the inception key, a XID provides a stable identity throughout its lifecycle, even as associated keys and permissions evolve. Leveraging Gordian Envelope for XID Documents, XIDs are recursively resolvable and extensible, allowing for detailed assertions about the entity, including key declarations, permissions, controllers, and endpoints. The integration of [provenance marks](https://provemark.com) ensures a verifiable chain of document revisions, enhancing security and authenticity in decentralized identity management. +XIDs (eXtensible IDentity, _/zid/_) are unique 32-byte identifiers that represent any entities-real or abstract-such as a person, organization, or device. Generated from the SHA-256 hash of a specific public signing key known as the inception key, a XID provides a stable identity throughout its lifecycle, even as associated keys and permissions evolve. Leveraging Gordian Envelope for XID Documents, XIDs are recursively resolvable and extensible, allowing for detailed assertions about the entity, including key declarations, permissions, controllers, and endpoints. The integration of [provenance marks](https://provemark.com) ensures a verifiable chain of document revisions, enhancing security and authenticity in decentralized identity management. ## Installation Instructions @@ -20,8 +20,6 @@ yarn add @blockchaincommons/xid bun add @blockchaincommons/xid ``` -**Requirements:** TypeScript >= 5.7 is required to consume the published types. Node >= 22.12 is required. - ## Usage Instructions ```typescript @@ -47,25 +45,6 @@ back.equals(doc); // true doc.toUR().toString(); // "ur:xid/…" ``` -Every failure is an `XIDError`: `code` names the condition with the -reference's variant names (`Duplicate`, `NotFound`, `EnvelopeParsing`, …), -`details` is typed by the code, and a sibling error wrapped inside a -decoder is `cause`. A caller's own faulty input (a `null` where private -keys go, an unknown option string, an invalid date) is a `TypeError`; a -constructor given text that is not a URI raises the components error. - -Reads are getters. Containers copy out (`keys`, `delegates`, `services`, -`resolutionMethods`, `endpoints`, `permissions.allow`); the values in them -are live, so `doc.keys[0].setNickname("x")` changes the document, and -`attachments` and `edges()` are the document's own containers. Options are -strings or small objects (`toEnvelope({ privateKeys: "include", sign: -"inception" })`). - -On the wire, a service's permissions are allow-only: `'deny'` assertions -are written but not read back, as the reference does (see ADR 0007 in -`docs/adr`). - - Runnable examples live in the [`examples/`](https://github.com/BlockchainCommons/bc-xid-ts/tree/master/examples) directory. ## Status - Beta @@ -74,7 +53,7 @@ Runnable examples live in the [`examples/`](https://github.com/BlockchainCommons ### Version History -- **1.0.0-beta.2 (September 16, 2026)** - Every decode failure is an `XIDError` with the reference's codes and messages; strict CBOR decoders (`fromCbor`, `fromUntaggedCbor`); typed error details; `addNickname`; options objects throughout; the JavaScript input domain checked; the Rust harness compares messages on every parser path. +- **1.0.0-beta.2 (September 16, 2026)** - Every decode failure is an `XIDError` with the reference's codes and messages; strict CBOR decoders (`fromCbor`, `fromUntaggedCbor`); typed error details; `addNickname`; options objects throughout; the JavaScript input domain checked. - **1.0.0-beta.1 (September 9, 2026)** - Initial beta implementation. ### Roadmap @@ -89,7 +68,7 @@ Runnable examples live in the [`examples/`](https://github.com/BlockchainCommons To build and work on this library, you'll need the following tools: - [Node.js](https://nodejs.org/) >= 22.12 - JavaScript runtime. -- [Bun](https://bun.sh/) - used in CI to install dependencies and run scripts (any Node-compatible package manager also works). +- [Bun](https://bun.sh/) - used to install dependencies and run scripts (any node package manager works). - [TypeScript](https://www.typescriptlang.org/) >= 5.7 - language and type checker. ### Derived from ... @@ -97,7 +76,7 @@ To build and work on this library, you'll need the following tools: This `bc-xid-ts` project is either derived from or was inspired by: - [BlockchainCommons/bc-xid-rust](https://github.com/BlockchainCommons/bc-xid-rust) - The reference Rust implementation, by [Wolf McNally](https://github.com/wolfmcnally). -- [paritytech/bcts](https://github.com/paritytech/bcts) - A TypeScript port covering many Blockchain Commons' implementations, by [Parity Technologies](https://github.com/paritytech). +- [paritytech/bcts](https://github.com/paritytech/bcts) - A TypeScript port of many Blockchain Commons' specs, by [Parity Technologies](https://github.com/paritytech). ## Financial Support From 5b737773fbb277de3952ea75cf47b896e01c9ea0 Mon Sep 17 00:00:00 2001 From: Leonardo Custodio Date: Wed, 16 Sep 2026 09:41:57 -0700 Subject: [PATCH 2/2] Delete bench directory --- bench/benchmark.mjs | 49 --------------------------------------------- 1 file changed, 49 deletions(-) delete mode 100644 bench/benchmark.mjs diff --git a/bench/benchmark.mjs b/bench/benchmark.mjs deleted file mode 100644 index 51e43d5..0000000 --- a/bench/benchmark.mjs +++ /dev/null @@ -1,49 +0,0 @@ -/** - * Baseline vs working tree micro-benchmarks. - * - * bun run build && bun bench/benchmark.mjs - */ -import * as baseline from "../tests/baseline/xid-baseline.mjs"; -import * as current from "../dist/index.mjs"; -import { PrivateKeyBase } from "@blockchaincommons/components"; - -const N = 200; -const seeds = Array.from({ length: 11 }, (_, i) => Uint8Array.from({ length: 32 }, (_, j) => (i * 31 + j * 7 + 1) & 0xff)); -const api = (m, current) => { - const pkb = (s) => (m.PrivateKeyBase ? m.PrivateKeyBase.fromData(s) : PrivateKeyBase.from(s)); - const build = () => { - const base = pkb(seeds[0]); - const doc = current - ? m.XIDDocument.from({ inceptionKey: base }) - : m.XIDDocument.new({ type: "privateKeyBase", privateKeyBase: base }, { type: "none" }); - for (let i = 1; i < 11; i++) { - const p = pkb(seeds[i]); - const key = current ? m.Key.from(p.ed25519PublicKeys(), { privateKeys: p.ed25519PrivateKeys() }) : m.Key.newWithPrivateKeys(p.ed25519PrivateKeys(), p.ed25519PublicKeys()); - doc.addKey(key); - } - return doc; - }; - const sign = (doc) => (current ? doc.toEnvelope({ sign: "inception" }) : doc.toEnvelope(m.XIDPrivateKeyOptions.Omit, m.XIDGeneratorOptions.Omit, { type: "inception" })); - const verify = (env) => (current ? m.XIDDocument.fromEnvelope(env, { verify: "inception" }) : m.XIDDocument.fromEnvelope(env, undefined, m.XIDVerifySignature.Inception)); - const parse = (env) => (current ? m.XIDDocument.fromEnvelope(env) : m.XIDDocument.fromEnvelope(env)); - return { build, sign, verify, parse }; -}; -const time = (fn, n) => { fn(); const t0 = performance.now(); for (let i = 0; i < n; i++) fn(); return (performance.now() - t0) / n; }; -const run = (m, current) => { - const a = api(m, current); - const doc = a.build(); - const signed = a.sign(doc); - return [ - ["build a 10-key document", time(() => a.build(), N)], - ["sign with the inception key", time(() => a.sign(doc), 50)], - ["parse and verify the signature", time(() => a.verify(signed), 50)], - ["parse (no verification)", time(() => a.parse(signed), N)], - ]; -}; -const before = run(baseline, false); -const after = run(current, typeof current.XIDDocument.from === "function"); -console.log(`${"operation".padEnd(34)} ${"baseline".padStart(10)} ${"current".padStart(10)} ${"ratio".padStart(7)}`); -for (let i = 0; i < before.length; i++) { - const [label, b] = before[i]; const c = after[i][1]; - console.log(`${label.padEnd(34)} ${b.toFixed(3).padStart(8)}ms ${c.toFixed(3).padStart(8)}ms ${(c / b).toFixed(2).padStart(6)}×`); -}