@cardanowall/sdk-ts 0.0.0 → 0.2.0

package/README.md

@@ -1,13 +1,13 @@
-# @cardanowall/sdk-ts — the TypeScript SDK for CIP-309 Proof-of-Existence
+# @cardanowall/sdk-ts — the TypeScript SDK for Label 309 Proof-of-Existence
 
-The browser + Node TypeScript SDK for [CIP-309](https://cips.cardano.org/) Proof-of-Existence on Cardano: a **standalone verifier** (three roles), a **gateway-agnostic HTTP client**, **off-host signing** helpers, and **seed-derived identity** helpers.
+The browser + Node TypeScript SDK for [Label 309](https://cips.cardano.org/) Proof-of-Existence on Cardano: a **standalone verifier** (three roles), a **gateway-agnostic HTTP client**, **off-host signing** helpers, and **seed-derived identity** helpers.
 
 ## What it is
 
-CIP-309 anchors a content hash on Cardano under metadata label 309 so that anyone can later prove "this content existed on or before block time T" — without trusting any server, domain, or issuer identity. This package is the high-level TypeScript surface over that standard:
+Label 309 anchors a content hash on Cardano under metadata label 309 so that anyone can later prove "this content existed on or before block time T" — without trusting any server, domain, or issuer identity. This package is the high-level TypeScript surface over that standard:
 
-- **Verify** any CIP-309 transaction from chain metadata alone — no issuer server in the trust path.
-- **Publish, read, and decrypt** records against **any** CIP-309 gateway (you supply the base URL and an opaque key).
+- **Verify** any Label 309 transaction from chain metadata alone — no issuer server in the trust path.
+- **Publish, read, and decrypt** records against **any** Label 309 gateway (you supply the base URL and an opaque key).
 - **Sign** records off-host (AWS KMS, GCP HSM, YubiHSM, air-gapped) — the private key never touches the SDK.
 - **Derive identity** keypairs, recipient strings, signers, and sealed-PoE decryption from a single 32-byte seed.
 
@@ -42,9 +42,9 @@ const report = await verifyTx({
   cardanoGatewayChain: ['https://api.koios.rest/api/v1'], // tried in order
 });
 
-console.log(report.verdict);   // 'valid' | 'pending' | 'failed'
+console.log(report.verdict); // 'valid' | 'pending' | 'failed'
 console.log(report.exit_code); // 0 valid · 1 integrity fail · 2 network fail · 3 pending
-console.log(report.record);    // the decoded CIP-309 PoeRecord
+console.log(report.record); // the decoded Label 309 PoeRecord
 ```
 
 To decrypt a sealed PoE addressed to you, run at the **recipient-sealed** profile and supply your X25519 private key per item index:
@@ -68,11 +68,11 @@ When you already hold the metadata bytes from an indexer mirror, skip the chain
 `baseUrl` is **required** — the client binds to no particular deployment. `apiKey`, when present, is an **opaque** bearer token forwarded verbatim as `Authorization: Bearer <apiKey>`; the SDK never parses or assumes its format. Omit it for anonymous read-only use.
 
 ```ts
-import { CardanowallClient } from '@cardanowall/sdk-ts';
+import { Label309Client } from '@cardanowall/sdk-ts';
 
-const client = new CardanowallClient({
-  baseUrl: 'https://gateway.example.com', // any CIP-309 gateway
-  apiKey: process.env.CIP309_API_KEY,     // opaque; omit for anonymous reads
+const client = new Label309Client({
+  baseUrl: 'https://gateway.example.com', // any Label 309 gateway
+  apiKey: process.env.LABEL309_API_KEY, // opaque; omit for anonymous reads
 });
 
 // Read surface — no auth required for public records.
@@ -94,7 +94,7 @@ const quote = await client.poe.quote({
 
 // Hash-only PoE: hash the content, build the record, submit. One HTTP call.
 const result = await client.poe.publishContent({
-  content: 'hello world',        // string (UTF-8) or Uint8Array
+  content: 'hello world', // string (UTF-8) or Uint8Array
   quoteId: quote.quote_id,
   // signer is optional; omit to publish unsigned (profile=core)
 });
@@ -132,9 +132,9 @@ import {
   decryptSealedFromSeed,
 } from '@cardanowall/sdk-ts';
 
-const keys = deriveKeysFromSeed(seed);        // { ed25519, x25519, mlkem768x25519 }
-const me = recipientsFromSeed(seed);          // { age: 'age1…', age1pqc: 'age1pqc…' }
-const signer = signerFromSeed(seed);          // a path-1 Signer for the publish helpers
+const keys = deriveKeysFromSeed(seed); // { ed25519, x25519, mlkem768x25519 }
+const me = recipientsFromSeed(seed); // { age: 'age1…', age1pqc: 'age1pqc…' }
+const signer = signerFromSeed(seed); // a path-1 Signer for the publish helpers
 
 // Decrypt a sealed PoE addressed to this seed — works for both classical
 // (x25519) and hybrid post-quantum (mlkem768x25519 / X-Wing) records.
@@ -149,6 +149,7 @@ if (result.matched) {
 Everything is reachable from the package root; submodule entry points (`/verifier`, `/client`, `/identity`, `/merkle`, `/hash`, `/fetch`) exist for tree-shaking.
 
 **Verifier** (`@cardanowall/sdk-ts` or `/verifier`)
+
 - `verifyTx(input)` / `verifyResolved(input)` — the full pipeline; returns a `VerifyReport`.
 - `verifyRecordSignatures`, `verifyMerkleCommitments`, `tryDecryptions` — individual stages.
 - `DEFAULT_PROFILE`, `profileImplements`, `planProfileSkips` — the four conformance profiles (`core` → `signed` → `sealed` → `recipient-sealed`).
@@ -156,18 +157,21 @@ Everything is reachable from the package root; submodule entry points (`/verifie
 - `resolveCardanoTx`, `extractLabel309Metadata`, `decodeTxWitnesses`, `decodeTxSummary` — resolution + transaction-level description.
 
 **Client** (`/client`)
-- `CardanowallClient({ baseUrl, apiKey?, fetch? })` — `baseUrl` required, key opaque.
+
+- `Label309Client({ baseUrl, apiKey?, fetch? })` — `baseUrl` required, key opaque.
 - `client.poe.{quote, publishContent, publishPrehashed, publishSealed, publishMerkle, uploads, publish, publishBatch}`.
 - `client.records.{get, verify}`, `client.inbox.{list, get}`, `client.account.balance()`.
 - Off-host signing: `prepareSigStructure`, `assembleCoseSign1`, plus the CIP-8 hashed-mode pair `prepareSigStructureHashed` / `assembleCoseSign1Hashed`.
-- Typed errors extending `CardanowallHttpError`: `InsufficientFundsError`, `QuoteExpiredError`, `QuoteAlreadyConsumedError`, `FxStaleError`, `RateLimitedError`, `UnauthorizedError`, `ValidationFailedError`, `MalformedCborError`, `InvalidClientConfigError`, and more.
+- Typed errors extending `Label309HttpError`: `InsufficientFundsError`, `QuoteExpiredError`, `QuoteAlreadyConsumedError`, `FxStaleError`, `RateLimitedError`, `UnauthorizedError`, `ValidationFailedError`, `MalformedCborError`, `InvalidClientConfigError`, and more.
 
 **Identity** (`/identity`)
+
 - `deriveKeysFromSeed`, `recipientsFromSeed`, `signerFromSeed`, `recipientKeyBundleFromSeed`, `decryptSealedFromSeed`.
 - Recipient codecs `encodeAgeX25519Recipient`, `encodeAgeXWingRecipient`, `parseAgeRecipient`.
 - Low-level derive primitives `deriveEd25519KeypairFromSeed`, `deriveX25519KeypairFromSeed`, `deriveMlKem768X25519KeypairFromSeed`.
 
 **Wire format & primitives** (re-exported for convenience)
+
 - From `@cardanowall/poe-standard`: `validatePoeRecord`, `encodePoeRecord`, `encodeRecordBodyForSigning`, the error-code catalogues (`STRUCTURAL_ERROR_CODES`, `VERIFIER_ERROR_CODES`, `ERROR_CODES`), `severityOf`, `PoeRecordSchema`.
 - From `@cardanowall/crypto-core`: `eciesSealedPoeWrap` / `eciesSealedPoeUnwrap` (sealed PoE), `hash.*` (digests), `merkle.*` (`merkleSha2256Root`, `merkleSha2256InclusionProof`, `merkleSha2256VerifyInclusion`, leaves-list codecs).
 
@@ -193,12 +197,12 @@ The verifier, the structural validator, the sealed-PoE construction, the off-hos
 
 ## Standard & service independence
 
-A CIP-309 proof verifies from three inputs only: the **transaction metadata**, optionally the **content bytes**, and a **public blockchain explorer**. No issuer server sits in the trust path. `verifyTx` reaches only the gateway chains you pass it, routes every outbound request through a single auditable egress point (every call lands in `VerifyReport.http_calls`), and enforces a deny-host policy — so the standalone verifier can be pointed at any infrastructure and still produce a trustworthy verdict.
+A Label 309 proof verifies from three inputs only: the **transaction metadata**, optionally the **content bytes**, and a **public blockchain explorer**. No issuer server sits in the trust path. `verifyTx` reaches only the gateway chains you pass it, routes every outbound request through a single auditable egress point (every call lands in `VerifyReport.http_calls`), and enforces a deny-host policy — so the standalone verifier can be pointed at any infrastructure and still produce a trustworthy verdict.
 
 ## Relation to the other packages
 
 - **`@cardanowall/crypto-core`** — closed-catalogue cryptographic primitives (hash, KDF, signature, KEM, AEAD, CBOR, COSE, sealed-PoE, Merkle, recipient encoding, seed derivation). The building blocks this SDK is built on.
-- **`@cardanowall/poe-standard`** — the CIP-309 wire-format library: record schema, canonical-CBOR encoder, pure structural validator, error-code catalogue.
+- **`@cardanowall/poe-standard`** — the Label 309 wire-format library: record schema, canonical-CBOR encoder, pure structural validator, error-code catalogue.
 - **`@cardanowall/sdk-py`** — the Python SDK: a byte-identical parity twin of this package, validated against the same canonical-CBOR vectors.
 - **`cardanowall`** (Rust crate) — the Rust SDK: the byte-parity twin in Rust, blocking HTTP, secure-by-default egress. The `cardanowall` CLI is built on it.
 

package/dist/client/index.cjs

@@ -78,7 +78,7 @@ function buildSigStructure(args) {
     args.payload
   ]);
 }
-function buildCip309SigStructure(args) {
+function buildLabel309SigStructure(args) {
   const toSign = new Uint8Array(
     CARDANO_POE_SIG_DOMAIN_PREFIX_BYTES.length + args.recordBodyCbor.length
   );
@@ -406,7 +406,7 @@ function prepareSigStructure(args) {
   }
   const { protectedHeaderBytes } = encodePath1ProtectedHeader(args.signerPubkey);
   const recordBodyCbor = encodeRecordBodyForSigning(args.record);
-  const sigStructureBytes = buildCip309SigStructure({
+  const sigStructureBytes = buildLabel309SigStructure({
     bodyProtectedBytes: protectedHeaderBytes,
     recordBodyCbor
   });
@@ -500,7 +500,7 @@ function extractProblemExtensions(problem) {
   }
   return out;
 }
-var Cip309HttpError = class extends Error {
+var Label309HttpError = class extends Error {
   problem;
   code;
   httpStatus;
@@ -515,7 +515,7 @@ var Cip309HttpError = class extends Error {
   retryAfterSeconds;
   constructor(init) {
     super(init.problem.detail || `${init.problem.title} (HTTP ${init.problem.status})`);
-    this.name = "Cip309HttpError";
+    this.name = "Label309HttpError";
     this.problem = init.problem;
     this.code = init.problem.code;
     this.httpStatus = init.problem.status;
@@ -532,7 +532,7 @@ var Cip309HttpError = class extends Error {
 };
 
 // src/client/batch-empty-error.ts
-var BatchEmptyError = class extends Cip309HttpError {
+var BatchEmptyError = class extends Label309HttpError {
   constructor(init) {
     super(init);
     this.name = "BatchEmptyError";
@@ -543,7 +543,7 @@ var BatchEmptyError = class extends Cip309HttpError {
 function readInt(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
-var BatchTooLargeError = class extends Cip309HttpError {
+var BatchTooLargeError = class extends Label309HttpError {
   max;
   got;
   constructor(init) {
@@ -555,7 +555,7 @@ var BatchTooLargeError = class extends Cip309HttpError {
 };
 
 // src/client/forbidden-error.ts
-var ForbiddenError = class extends Cip309HttpError {
+var ForbiddenError = class extends Label309HttpError {
   constructor(init) {
     super(init);
     this.name = "ForbiddenError";
@@ -563,7 +563,7 @@ var ForbiddenError = class extends Cip309HttpError {
 };
 
 // src/client/idempotency-conflict-error.ts
-var IdempotencyConflictError = class extends Cip309HttpError {
+var IdempotencyConflictError = class extends Label309HttpError {
   constructor(init) {
     super(init);
     this.name = "IdempotencyConflictError";
@@ -583,7 +583,7 @@ function readBigIntString(value) {
 function readString(value) {
   return typeof value === "string" ? value : void 0;
 }
-var InsufficientFundsError = class extends Cip309HttpError {
+var InsufficientFundsError = class extends Label309HttpError {
   balanceUsdMicros;
   requiredUsdMicros;
   topUpUrl;
@@ -601,7 +601,7 @@ function readScopeArray(value) {
   if (!Array.isArray(value)) return [];
   return value.filter((entry) => typeof entry === "string");
 }
-var InsufficientScopeError = class extends Cip309HttpError {
+var InsufficientScopeError = class extends Label309HttpError {
   requiredScopes;
   grantedScopes;
   constructor(init) {
@@ -617,7 +617,7 @@ var InsufficientScopeError = class extends Cip309HttpError {
 };
 
 // src/client/internal-server-error.ts
-var InternalServerError = class extends Cip309HttpError {
+var InternalServerError = class extends Label309HttpError {
   constructor(init) {
     super(init);
     this.name = "InternalServerError";
@@ -625,7 +625,7 @@ var InternalServerError = class extends Cip309HttpError {
 };
 
 // src/client/invalid-body-error.ts
-var InvalidBodyError = class extends Cip309HttpError {
+var InvalidBodyError = class extends Label309HttpError {
   constructor(init) {
     super(init);
     this.name = "InvalidBodyError";
@@ -633,7 +633,7 @@ var InvalidBodyError = class extends Cip309HttpError {
 };
 
 // src/client/malformed-cbor-error.ts
-var MalformedCborError = class extends Cip309HttpError {
+var MalformedCborError = class extends Label309HttpError {
   constructor(init) {
     super(init);
     this.name = "MalformedCborError";
@@ -641,7 +641,7 @@ var MalformedCborError = class extends Cip309HttpError {
 };
 
 // src/client/not-found-error.ts
-var NotFoundError = class extends Cip309HttpError {
+var NotFoundError = class extends Label309HttpError {
   constructor(init) {
     super(init);
     this.name = "NotFoundError";
@@ -652,7 +652,7 @@ var NotFoundError = class extends Cip309HttpError {
 function readString2(value) {
   return typeof value === "string" ? value : void 0;
 }
-var QuoteAlreadyConsumedError = class extends Cip309HttpError {
+var QuoteAlreadyConsumedError = class extends Label309HttpError {
   quoteId;
   constructor(init) {
     super(init);
@@ -665,7 +665,7 @@ var QuoteAlreadyConsumedError = class extends Cip309HttpError {
 function readString3(value) {
   return typeof value === "string" ? value : void 0;
 }
-var QuoteExpiredError = class extends Cip309HttpError {
+var QuoteExpiredError = class extends Label309HttpError {
   quoteId;
   constructor(init) {
     super(init);
@@ -678,7 +678,7 @@ var QuoteExpiredError = class extends Cip309HttpError {
 function readString4(value) {
   return typeof value === "string" ? value : void 0;
 }
-var QuoteNotFoundError = class extends Cip309HttpError {
+var QuoteNotFoundError = class extends Label309HttpError {
   quoteId;
   constructor(init) {
     super(init);
@@ -688,7 +688,7 @@ var QuoteNotFoundError = class extends Cip309HttpError {
 };
 
 // src/client/rate-limited-error.ts
-var RateLimitedError = class extends Cip309HttpError {
+var RateLimitedError = class extends Label309HttpError {
   constructor(init) {
     super(init);
     this.name = "RateLimitedError";
@@ -696,7 +696,7 @@ var RateLimitedError = class extends Cip309HttpError {
 };
 
 // src/client/record-not-found-error.ts
-var RecordNotFoundError = class extends Cip309HttpError {
+var RecordNotFoundError = class extends Label309HttpError {
   constructor(init) {
     super(init);
     this.name = "RecordNotFoundError";
@@ -704,7 +704,7 @@ var RecordNotFoundError = class extends Cip309HttpError {
 };
 
 // src/client/service-unavailable-error.ts
-var ServiceUnavailableError = class extends Cip309HttpError {
+var ServiceUnavailableError = class extends Label309HttpError {
   constructor(init) {
     super(init);
     this.name = "ServiceUnavailableError";
@@ -712,7 +712,7 @@ var ServiceUnavailableError = class extends Cip309HttpError {
 };
 
 // src/client/unauthorized-error.ts
-var UnauthorizedError = class extends Cip309HttpError {
+var UnauthorizedError = class extends Label309HttpError {
   constructor(init) {
     super(init);
     this.name = "UnauthorizedError";
@@ -720,7 +720,7 @@ var UnauthorizedError = class extends Cip309HttpError {
 };
 
 // src/client/validation-failed-error.ts
-var ValidationFailedError = class extends Cip309HttpError {
+var ValidationFailedError = class extends Label309HttpError {
   constructor(init) {
     super(init);
     this.name = "ValidationFailedError";
@@ -838,7 +838,7 @@ function parseHttpError(args) {
     case "fx-stale":
       return new ServiceUnavailableError(init);
     default:
-      return new Cip309HttpError(init);
+      return new Label309HttpError(init);
   }
 }
 
@@ -2382,7 +2382,7 @@ var PoeNamespace = class {
    * publish time against the locked price snapshot.
    *
    * On HTTP-level failure (auth, rate limit, malformed request) this throws
-   * a typed `Cip309HttpError` subclass. Per-file failures inside a 200
+   * a typed `Label309HttpError` subclass. Per-file failures inside a 200
    * response are NOT thrown by `uploads()` itself — the response body is
    * returned verbatim so the caller can decide how to react. The
    * higher-level helpers (`publishSealed`, `publishMerkle`) treat any failed
@@ -2467,7 +2467,7 @@ var PoeNamespace = class {
   }
   /**
    * High-level hash-only publish: hash the supplied content, build a
-   * single-item CIP-309 record, optionally sign it with the caller-supplied
+   * single-item Label 309 record, optionally sign it with the caller-supplied
    * signer, and submit. No Arweave, no storage round-trip — anchors the
    * digest only.
    */
@@ -2485,7 +2485,7 @@ var PoeNamespace = class {
   /**
    * Sealed-PoE: encrypt the supplied content to the recipient X25519 public
    * keys (age-style sealed envelope), upload the ciphertext to Arweave via
-   * /uploads, build a CIP-309 record with the resulting `ar://` URI, sign
+   * /uploads, build a Label 309 record with the resulting `ar://` URI, sign
    * it (optional), and submit via /publish.
    *
    * The sender SHOULD include their own X25519 public key in `recipients`
@@ -2583,7 +2583,7 @@ var RecordsNamespace = class {
     return await readJson(response);
   }
   /**
-   * Run the canonical CIP-309 verifier against the record at `txHash`.
+   * Run the canonical Label 309 verifier against the record at `txHash`.
    * Returns the same `VerifyReport` shape the standalone verifier emits —
    * `VerifyReport` IS the wire body of this endpoint, with no transformer in
    * between.
@@ -2606,31 +2606,31 @@ var RecordsNamespace = class {
   }
 };
 
-// src/client/cip309-client.ts
+// src/client/label-309-client.ts
 function resolveFetch(provided) {
   if (provided !== void 0) return provided;
   if (typeof globalThis.fetch === "function") {
     return globalThis.fetch.bind(globalThis);
   }
   throw new Error(
-    "Cip309Client: no fetch implementation available. Pass `fetch` in the config or run on a platform with globalThis.fetch."
+    "Label309Client: no fetch implementation available. Pass `fetch` in the config or run on a platform with globalThis.fetch."
   );
 }
 function resolveBaseUrl(config) {
   const baseUrl = config.baseUrl?.trim();
   if (baseUrl === void 0 || baseUrl === "") {
     throw new InvalidClientConfigError(
-      "Cip309Client: baseUrl is required. Pass the base URL of the CIP-309 gateway you are targeting (e.g. https://gateway.example.com)."
+      "Label309Client: baseUrl is required. Pass the base URL of the Label 309 gateway you are targeting (e.g. https://gateway.example.com)."
     );
   }
   return baseUrl.replace(/\/$/, "");
 }
-var Cip309Client = class {
+var Label309Client = class {
   poe;
   records;
   account;
   /**
-   * Construct a client against a CIP-309 gateway.
+   * Construct a client against a Label 309 gateway.
    *
    * `config.baseUrl` is required — there is no default deployment. The
    * `config.apiKey`, when supplied, is an opaque bearer token sent verbatim as
@@ -2661,8 +2661,6 @@ var Cip309Client = class {
 exports.AccountNamespace = AccountNamespace;
 exports.BatchEmptyError = BatchEmptyError;
 exports.BatchTooLargeError = BatchTooLargeError;
-exports.Cip309Client = Cip309Client;
-exports.Cip309HttpError = Cip309HttpError;
 exports.ForbiddenError = ForbiddenError;
 exports.IdempotencyConflictError = IdempotencyConflictError;
 exports.InsufficientFundsError = InsufficientFundsError;
@@ -2670,6 +2668,8 @@ exports.InsufficientScopeError = InsufficientScopeError;
 exports.InternalServerError = InternalServerError;
 exports.InvalidBodyError = InvalidBodyError;
 exports.InvalidClientConfigError = InvalidClientConfigError;
+exports.Label309Client = Label309Client;
+exports.Label309HttpError = Label309HttpError;
 exports.MalformedCborError = MalformedCborError;
 exports.NotFoundError = NotFoundError;
 exports.OffHostSignError = OffHostSignError;