@envolvr/sdk 0.1.0

package/dist/receipts.d.ts

@@ -0,0 +1,46 @@
+import type { Network } from './network.ts';
+export type Receipt = Record<string, unknown> & {
+    receipt_id: string;
+    event_log: Array<Record<string, unknown>>;
+};
+/** SHA-256 of the receipt's JCS bytes (RFC 8785): the value that is anchored. */
+export declare function receiptDigest(receipt: unknown): `0x${string}`;
+export interface Billing {
+    currency: string;
+    /** Exact cost as a decimal string, e.g. "0.00014". */
+    cost: string;
+    /** What was debited: the cost rounded up to the next micro-USD. */
+    billedMicroUsd: number;
+    rates: Record<string, string>;
+    tokens: {
+        prompt: number;
+        completion: number;
+        cache_read: number;
+        cache_creation: number;
+    };
+    payer?: string;
+}
+/** The receipt's billing.charged event, or undefined for an unpriced request. */
+export declare function billingOf(receipt: Receipt): Billing | undefined;
+/** The payer commitment a receipt charged to `apiKey` carries. */
+export declare function payerCommitment(apiKey: string, receiptId: string): string;
+export declare function chargedTo(receipt: Receipt, apiKey: string): boolean;
+/** Check an inclusion proof against a root (OpenZeppelin sorted-pair Merkle tree). */
+export declare function proofLeadsToRoot(digest: string, proof: string[], root: string): boolean;
+export interface Anchor {
+    status: 'anchored' | 'pending' | 'unknown';
+    digest: string;
+    batchIndex?: number;
+    leafIndex?: number;
+    count?: number;
+    root?: string;
+    txHash?: string | null;
+    /** Unix seconds, read from the contract. */
+    anchoredAt?: number;
+}
+/**
+ * Is this receipt anchored? The proof comes from envolvr's proof service as
+ * data only; the chain, contract and provider come from `network`, and the
+ * contract itself is asked.
+ */
+export declare function verifyAnchor(receipt: unknown, network: Network, fetchImpl?: typeof fetch): Promise<Anchor>;

package/dist/receipts.js

@@ -0,0 +1,100 @@
+// Receipts: what each one says about billing, whether it was charged to you,
+// and whether it is anchored on Robinhood Chain. Nothing here trusts envolvr:
+// digests and commitments are computed locally, and the anchor is checked
+// against the contract itself.
+import { createHash } from 'node:crypto';
+import { keccak_256 } from '@noble/hashes/sha3';
+import { bytesToHex, concatBytes, hexToBytes, utf8ToBytes } from '@noble/hashes/utils';
+import canonicalize from 'canonicalize';
+/** SHA-256 of the receipt's JCS bytes (RFC 8785): the value that is anchored. */
+export function receiptDigest(receipt) {
+    const jcs = canonicalize(receipt);
+    if (jcs === undefined)
+        throw new Error('receipt is not JSON');
+    return `0x${createHash('sha256').update(jcs).digest('hex')}`;
+}
+/** The receipt's billing.charged event, or undefined for an unpriced request. */
+export function billingOf(receipt) {
+    const e = receipt.event_log.find((x) => x.type === 'billing.charged');
+    if (!e)
+        return undefined;
+    return {
+        currency: String(e.currency), cost: String(e.cost), billedMicroUsd: Number(e.billed_micro_usd),
+        rates: e.rates, tokens: e.tokens,
+        payer: e.payer === undefined ? undefined : String(e.payer),
+    };
+}
+/** The payer commitment a receipt charged to `apiKey` carries. */
+export function payerCommitment(apiKey, receiptId) {
+    const keyHash = createHash('sha256').update(apiKey, 'utf8').digest('hex');
+    return `sha256:${createHash('sha256').update(`billing.payer.v1:${keyHash}:${receiptId}`).digest('hex')}`;
+}
+export function chargedTo(receipt, apiKey) {
+    return billingOf(receipt)?.payer === payerCommitment(apiKey, receipt.receipt_id);
+}
+// ---- anchoring ----
+const leafOf = (digest) => keccak_256(keccak_256(hexToBytes(digest.replace(/^0x/, ''))));
+function hashPair(a, b) {
+    for (let i = 0; i < 32; i++) {
+        if (a[i] !== b[i])
+            return a[i] < b[i] ? keccak_256(concatBytes(a, b)) : keccak_256(concatBytes(b, a));
+    }
+    return keccak_256(concatBytes(a, b));
+}
+/** Check an inclusion proof against a root (OpenZeppelin sorted-pair Merkle tree). */
+export function proofLeadsToRoot(digest, proof, root) {
+    let node = leafOf(digest);
+    for (const sibling of proof)
+        node = hashPair(node, hexToBytes(sibling.replace(/^0x/, '')));
+    return `0x${bytesToHex(node)}` === root.toLowerCase();
+}
+const selector = (sig) => bytesToHex(keccak_256(utf8ToBytes(sig))).slice(0, 8);
+const word = (v) => (typeof v === 'bigint' ? v.toString(16) : v.replace(/^0x/, '').toLowerCase()).padStart(64, '0');
+/**
+ * Is this receipt anchored? The proof comes from envolvr's proof service as
+ * data only; the chain, contract and provider come from `network`, and the
+ * contract itself is asked.
+ */
+export async function verifyAnchor(receipt, network, fetchImpl = fetch) {
+    const digest = receiptDigest(receipt);
+    const url = `${network.control}/receipts/${digest}/proof`;
+    const res = await fetchImpl(url).catch((err) => {
+        throw new Error(`proof service unreachable (${new URL(url).origin}): ${err.message}`);
+    });
+    if (res.status === 404)
+        return { status: 'unknown', digest };
+    if (!res.ok)
+        throw new Error(`proof service answered HTTP ${res.status}`);
+    const p = await res.json();
+    if (p.status !== 'anchored')
+        return { status: 'pending', digest };
+    if (!proofLeadsToRoot(digest, p.proof, p.root))
+        throw new Error('the proof does not lead to its root');
+    const rpc = async (method, params) => {
+        const r = await fetchImpl(network.rpcUrl, {
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+        });
+        const body = await r.json();
+        if (body.error || body.result === undefined)
+            throw new Error(`${method}: ${body.error?.message ?? `HTTP ${r.status}`}`);
+        return body.result;
+    };
+    const chainId = Number(BigInt(await rpc('eth_chainId', [])));
+    if (chainId !== network.chainId)
+        throw new Error(`RPC is on chain ${chainId}, expected ${network.chainId}`);
+    const call = (data) => rpc('eth_call', [{ to: network.receiptAnchor, data }, 'latest']);
+    const batch = await call(`0x${selector('batch(bytes32,uint256)')}${word(network.providerId)}${word(BigInt(p.batchIndex))}`);
+    const onChainRoot = `0x${batch.slice(2, 66)}`;
+    if (onChainRoot.toLowerCase() !== p.root.toLowerCase()) {
+        throw new Error(`batch ${p.batchIndex} on chain has root ${onChainRoot}, the proof claims ${p.root}`);
+    }
+    const verified = await call(`0x${selector('verifyReceipt(bytes32,uint256,bytes32,bytes32[])')}${word(network.providerId)}`
+        + `${word(BigInt(p.batchIndex))}${word(digest)}${word(128n)}${word(BigInt(p.proof.length))}${p.proof.map(word).join('')}`);
+    if (BigInt(verified) !== 1n)
+        throw new Error('ReceiptAnchor.verifyReceipt returned false');
+    return {
+        status: 'anchored', digest, batchIndex: p.batchIndex, leafIndex: p.leafIndex, count: p.count, root: p.root,
+        txHash: p.txHash ?? null, anchoredAt: Number(BigInt(`0x${batch.slice(194, 258)}`)),
+    };
+}

package/dist/wallet.d.ts

@@ -0,0 +1,14 @@
+export interface Signer {
+    address: string;
+    /** EIP-191 personal_sign of a UTF-8 message: 65 bytes as 0x hex. */
+    signMessage(message: string): Promise<string>;
+    /** Send a transaction and resolve once it is mined; returns its hash. Needed for deposits only. */
+    sendTransaction?(tx: {
+        to: string;
+        data: string;
+    }): Promise<string>;
+}
+export declare function privateKeySigner(privateKey: string, opts: {
+    rpcUrl: string;
+    chainId: number;
+}): Signer;

package/dist/wallet.js

@@ -0,0 +1,47 @@
+// Wallets. envolvr needs a wallet for two things: signing the sign-in message
+// (EIP-191) and, to deposit USDG, sending two transactions. Bring your own by
+// implementing Signer (for example around viem or ethers), or use
+// privateKeySigner for a plain key.
+import { hexToBytes } from '@noble/hashes/utils';
+import { addressOfKey, personalSign, Rpc, signTx } from "./evm.js";
+export function privateKeySigner(privateKey, opts) {
+    const key = hexToBytes(privateKey.replace(/^0x/, ''));
+    if (key.length !== 32)
+        throw new Error('a private key is 32 bytes of hex');
+    const address = addressOfKey(key);
+    const rpc = new Rpc(opts.rpcUrl);
+    return {
+        address,
+        async signMessage(message) {
+            return personalSign(message, key);
+        },
+        async sendTransaction({ to, data }) {
+            const chainId = BigInt(await rpc.call('eth_chainId', []));
+            if (chainId !== BigInt(opts.chainId))
+                throw new Error(`RPC is on chain ${chainId}, expected ${opts.chainId}`);
+            const call = { from: address, to, data };
+            const [nonce, gas, block] = await Promise.all([
+                rpc.call('eth_getTransactionCount', [address, 'pending']),
+                rpc.call('eth_estimateGas', [call]),
+                rpc.call('eth_getBlockByNumber', ['latest', false]),
+            ]);
+            const priority = await rpc.call('eth_maxPriorityFeePerGas', []).then(BigInt, () => 0n);
+            const baseFee = BigInt(block.baseFeePerGas ?? (await rpc.call('eth_gasPrice', [])));
+            const { raw, hash } = signTx({
+                chainId, nonce: BigInt(nonce), maxPriorityFeePerGas: priority, maxFeePerGas: baseFee * 2n + priority,
+                gas: (BigInt(gas) * 13n) / 10n, to, value: 0n, data,
+            }, key);
+            await rpc.call('eth_sendRawTransaction', [raw]);
+            for (let i = 0; i < 90; i++) {
+                const r = await rpc.call('eth_getTransactionReceipt', [hash]);
+                if (r) {
+                    if (BigInt(r.status) !== 1n)
+                        throw new Error(`transaction ${hash} reverted`);
+                    return hash;
+                }
+                await new Promise((res) => setTimeout(res, 2_000));
+            }
+            throw new Error(`transaction ${hash} not mined after 3 minutes`);
+        },
+    };
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@envolvr/sdk",
+  "version": "0.1.0",
+  "description": "envolvr client: wallet sign-in, USDG deposits, private inference with signed receipts, and receipt verification (signature, billing, on-chain anchor).",
+  "license": "Apache-2.0",
+  "author": "envolvr",
+  "homepage": "https://envolvr.xyz/docs/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/envolvr/envolvr.git",
+    "directory": "sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/envolvr/envolvr/issues"
+  },
+  "keywords": [
+    "ai",
+    "inference",
+    "private",
+    "verifiable",
+    "tee",
+    "tdx",
+    "attestation",
+    "receipts",
+    "agents",
+    "openai",
+    "robinhood-chain",
+    "usdg"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "envolvr": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --disable-warning=ExperimentalWarning --test test/*.test.ts",
+    "prepublishOnly": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "^1.8.0",
+    "canonicalize": "^5.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}