@jamscript/client 0.1.0-rc.1

package/dist/state-provider.js

@@ -0,0 +1,173 @@
+import { verifyManagedStateProof } from "./proof.js";
+import { parseHex } from "./crypto.js";
+export class StateProviderError extends Error {
+    kind;
+    cause;
+    constructor(kind, message, cause) {
+        super(message);
+        this.kind = kind;
+        this.cause = cause;
+        this.name = "StateProviderError";
+    }
+}
+/** Legacy explicit-root proof provider retained for compatibility. */
+export class RpcStateProvider {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async get(request) {
+        let response;
+        try {
+            response = await this.transport.call("minijam_getManagedStateV1", {
+                serviceId: request.serviceId,
+                stateRoot: request.stateRoot,
+                keyBase64: toBase64(request.key),
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? ": " + error.message : "";
+            throw new StateProviderError(classifyRpcFailure(error), "managed-state provider request failed" + detail, error);
+        }
+        try {
+            return {
+                serviceId: response.serviceId,
+                stateRoot: response.managedStateRoot ?? response.stateRoot ?? "",
+                key: fromBase64(response.keyBase64),
+                value: response.valueBase64 === null ? null : fromBase64(response.valueBase64),
+                proof: response.proofBase64.map(fromBase64),
+            };
+        }
+        catch (error) {
+            throw new StateProviderError("MalformedResponse", "managed-state provider response is malformed", error);
+        }
+    }
+}
+/**
+ * The v0.1 default provider. The backend owns canonical-root discovery and
+ * returns only the trusted value; proof validation remains available through
+ * RpcStateProvider when an application explicitly opts into proof mode.
+ */
+export class TrustedStateProvider {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async get(request) {
+        let response;
+        try {
+            response = await this.transport.call("jamscript_getStateV1", {
+                serviceId: request.serviceId,
+                keyBase64: toBase64(request.key),
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? ": " + error.message : "";
+            throw new StateProviderError(classifyRpcFailure(error), "trusted managed-state request failed" + detail, error);
+        }
+        try {
+            return {
+                serviceId: response.serviceId,
+                stateRoot: response.managedStateRoot ?? response.stateRoot ?? "",
+                key: fromBase64(response.keyBase64),
+                value: response.valueBase64 === null ? null : fromBase64(response.valueBase64),
+                proof: [],
+            };
+        }
+        catch (error) {
+            throw new StateProviderError("MalformedResponse", "trusted managed-state response is malformed", error);
+        }
+    }
+}
+/** Requests the v1 proof endpoint and leaves verification to the client. */
+export class ProofStateProvider {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async get(request) {
+        let response;
+        try {
+            response = await this.transport.call("jamscript_getStateProofV1", {
+                serviceId: request.serviceId,
+                keyBase64: toBase64(request.key),
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? ": " + error.message : "";
+            throw new StateProviderError(classifyRpcFailure(error), "proof managed-state request failed" + detail, error);
+        }
+        try {
+            return {
+                serviceId: response.serviceId,
+                stateRoot: response.managedStateRoot ?? response.stateRoot ?? "",
+                key: fromBase64(response.keyBase64),
+                value: response.valueBase64 === null ? null : fromBase64(response.valueBase64),
+                proof: response.proofBase64.map(fromBase64),
+            };
+        }
+        catch (error) {
+            throw new StateProviderError("MalformedResponse", "proof managed-state response is malformed", error);
+        }
+    }
+}
+/** Tries providers in order and only accepts a response with a valid proof. */
+export class FallbackStateProvider {
+    providers;
+    constructor(providers) {
+        this.providers = providers;
+        if (providers.length === 0)
+            throw new Error("at least one state provider is required");
+    }
+    async get(request) {
+        let lastError;
+        for (const provider of this.providers) {
+            try {
+                const response = await provider.get(request);
+                assertResponseIdentity(request, response);
+                verifyManagedStateProof(parseHex(request.stateRoot, 32), request.key, response.value, response.proof);
+                return response;
+            }
+            catch (error) {
+                lastError = error instanceof StateProviderError
+                    ? error
+                    : new StateProviderError("InvalidProof", "state provider proof verification failed", error);
+            }
+        }
+        throw lastError ?? new StateProviderError("Unavailable", "no state provider is available");
+    }
+}
+function assertResponseIdentity(request, response) {
+    if (response.serviceId !== request.serviceId
+        || !sameHex(response.stateRoot, request.stateRoot)
+        || !sameBytes(response.key, request.key)) {
+        throw new StateProviderError("InconsistentResponse", "managed-state provider response does not match the request");
+    }
+}
+function classifyRpcFailure(error) {
+    const code = typeof error === "object" && error !== null && "code" in error
+        ? error.code
+        : undefined;
+    if (code === -32030 || code === -32601)
+        return "RootUnavailable";
+    return "Unavailable";
+}
+function sameHex(left, right) {
+    return left.toLowerCase().replace(/^0x/, "") === right.toLowerCase().replace(/^0x/, "");
+}
+function sameBytes(left, right) {
+    return left.length === right.length && left.every((byte, index) => byte === right[index]);
+}
+function toBase64(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function fromBase64(value) {
+    const binary = atob(value);
+    const output = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        output[index] = binary.charCodeAt(index);
+    return output;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@jamscript/client",
+  "version": "0.1.0-rc.1",
+  "description": "TypeScript client for JamScript services, managed state and Ownership.",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "test:network": "node tests/minijam-network.e2e.mjs",
+    "test:transaction-closure": "node tests/minijam-transaction-closure.e2e.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@polkadot-api/substrate-bindings": "^0.21.0",
+    "@polkadot/util": "^14.0.1",
+    "@polkadot/util-crypto": "^14.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArcheLabs/JamScript.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://github.com/ArcheLabs/JamScript",
+  "bugs": {
+    "url": "https://github.com/ArcheLabs/JamScript/issues"
+  },
+  "keywords": [
+    "jamscript",
+    "jam",
+    "ownership",
+    "polkadot"
+  ],
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}