@envolvr/sdk 0.1.0 → 0.2.0

package/README.md

@@ -11,17 +11,19 @@ the account with USDG, runs inference, keeps every receipt, and verifies it.
 npm install @envolvr/sdk        # Node 20+
 ```
 
-## From zero to a verified receipt (testnet)
+## From zero to a verified receipt
 
 ```bash
-export ENVOLVR_PRIVATE_KEY=0x…   # a wallet with a little Robinhood testnet ETH for gas
-npx envolvr signin --save        # sign a message, get an API key
-npx envolvr testnet-mint 20      # test USDG (testnet only)
-npx envolvr deposit 10           # credited net of the deposit fee, within seconds
-npx envolvr chat "Reply with the single word: sealed"
-npx envolvr verify --last        # signature, billing, payer, on-chain anchor
+export ENVOLVR_PRIVATE_KEY=0x…            # a wallet with USDG and a little ETH on Robinhood Chain
+npx @envolvr/sdk signin --save            # sign a message, get an API key
+npx @envolvr/sdk deposit 10               # credited net of the deposit fee, within seconds
+npx @envolvr/sdk chat "Reply with the single word: sealed"
+npx @envolvr/sdk verify --last            # signature, billing, payer, on-chain anchor
 ```
 
+Or `npm install -g @envolvr/sdk` and run `envolvr …`. Always name the scoped
+package with npx: `npx envolvr` alone would fetch an unrelated package.
+
 `verify` prints what the receipt proves: the gateway's TDX attestation and the
 receipt signature (checked by `private-ai-proxy`), what was billed and that it
 was billed to your key, and the batch and transaction that anchor it. A receipt
@@ -30,9 +32,9 @@ is anchored at the end of its 10-minute slot (UTC).
 ## In code
 
 ```ts
-import { Envolvr, privateKeySigner, signIn, depositUsdg, TESTNET, toMicros } from '@envolvr/sdk';
+import { Envolvr, privateKeySigner, signIn, depositUsdg, MAINNET, toMicros } from '@envolvr/sdk';
 
-const wallet = privateKeySigner(process.env.KEY!, { rpcUrl: TESTNET.rpcUrl, chainId: TESTNET.chainId });
+const wallet = privateKeySigner(process.env.KEY!, { rpcUrl: MAINNET.rpcUrl, chainId: MAINNET.chainId });
 const { apiKey } = await signIn(wallet);                          // keep it: shown once
 await depositUsdg({ signer: wallet, amountMicros: toMicros('10') });
 
@@ -52,6 +54,26 @@ sending and checks every receipt, run the local verifying proxy
 `npx private-ai-proxy serve https://api.envolvr.xyz` and point the client at
 `http://127.0.0.1:4180/v1`.
 
+### Automatic top-up
+
+Keep an agent funded without watching its balance. When the balance falls below
+`below`, the client deposits `amount` from `signer` and
+waits until it is credited; a request refused for insufficient credit is topped
+up and retried once. `maxPerDay` caps the deposits per UTC day (default: one
+top-up). The signer can be the agent's own wallet or another one, which then
+deposits for the agent's account.
+
+```ts
+const envolvr = new Envolvr({
+  apiKey,
+  autoTopUp: { signer: wallet, below: '5', amount: '20', maxPerDay: '100', onEvent: console.log },
+});
+```
+
+The cap is counted per process. `onEvent` hears every top-up (`topped-up`),
+every day the cap stops one (`capped`) and every failure (`failed`); a failed
+top-up never fails the request on its own.
+
 Any wallet works for sign-in and deposits: implement `Signer` (`address`,
 `signMessage`, and `sendTransaction` for deposits) around viem, ethers or a
 hardware wallet.

package/dist/api.js

@@ -1,7 +1,7 @@
 // envolvr's HTTP surface for an agent: sign in with a wallet, read the account
 // and the pricing, and move USDG into the credit vault.
 import { decodeWords, encodeCall, Rpc } from "./evm.js";
-import { TESTNET } from "./network.js";
+import { assertContracts, MAINNET, TESTNET } from "./network.js";
 async function json(res) {
     const body = (await res.json().catch(() => ({})));
     if (!res.ok)
@@ -17,7 +17,7 @@ export function signInMessage(wallet, nonce, issuedAt) {
  * Sign in with a wallet and get an API key. The key is shown once; keep it.
  * Each sign-in issues a new key; earlier keys keep working.
  */
-export async function signIn(signer, network = TESTNET) {
+export async function signIn(signer, network = MAINNET) {
     const n = await json(await fetch(`${network.control}/auth/nonce?wallet=${signer.address}`));
     const expected = signInMessage(signer.address, n.nonce, n.issuedAt);
     if (n.message !== expected)
@@ -41,7 +41,7 @@ export function closeAccountMessage(wallet, refundTo, nonce, issuedAt) {
  * credit vault shortly after.
  */
 export async function closeAccount(signer, opts = {}) {
-    const network = opts.network ?? TESTNET;
+    const network = opts.network ?? MAINNET;
     const refundTo = opts.refundTo ?? signer.address;
     const n = await json(await fetch(`${network.control}/account/close/nonce?wallet=${signer.address}&refundTo=${refundTo}`));
     const expected = closeAccountMessage(signer.address, refundTo, n.nonce, n.issuedAt);
@@ -54,10 +54,10 @@ export async function closeAccount(signer, opts = {}) {
         body: JSON.stringify({ wallet: signer.address, refundTo, nonce: n.nonce, issuedAt: n.issuedAt, signature }),
     }));
 }
-export async function getAccount(apiKey, network = TESTNET) {
+export async function getAccount(apiKey, network = MAINNET) {
     return json(await fetch(`${network.control}/account`, { headers: { authorization: `Bearer ${apiKey}` } }));
 }
-export async function getPricing(network = TESTNET) {
+export async function getPricing(network = MAINNET) {
     return json(await fetch(`${network.control}/pricing`));
 }
 /** What a deposit of `amountMicros` credits at `feeBps` (the fee rounds down). */
@@ -72,12 +72,13 @@ export function netCredit(amountMicros, feeBps) {
  * vault is not credited.
  */
 export async function depositUsdg(opts) {
-    const network = opts.network ?? TESTNET;
+    const network = opts.network ?? MAINNET;
     const { signer, amountMicros } = opts;
     if (!signer.sendTransaction)
         throw new Error('this signer cannot send transactions');
     if (amountMicros <= 0n)
         throw new Error('the amount must be positive');
+    assertContracts(network);
     const rpc = new Rpc(network.rpcUrl);
     const view = async (to, sig, args) => BigInt(decodeWords(await rpc.call('eth_call', [{ to, data: encodeCall(sig, args) }, 'latest']))[0]);
     const balance = await view(network.usdg, 'balanceOf(address)', [signer.address]);

package/dist/cli.js

@@ -1,22 +1,21 @@
 #!/usr/bin/env node
 // envolvr: sign in, fund, run private inference, and verify its receipts.
 //
-//   ENVOLVR_PRIVATE_KEY  wallet key, for signin, deposit and testnet-mint
+//   ENVOLVR_PRIVATE_KEY  wallet key, for signin and deposit
 //   ENVOLVR_API_KEY      API key, for everything else (or ~/.envolvr/credentials.json)
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { closeAccount, depositUsdg, getPricing, mintTestUsdg, signIn } from "./api.js";
+import { closeAccount, depositUsdg, getPricing, signIn } from "./api.js";
 import { AUDIT_CHECKS, verifyGateway } from "./attest.js";
 import { Envolvr, savedReceipts, verifySaved } from "./client.js";
-import { fromMicros, TESTNET, toMicros } from "./network.js";
+import { fromMicros, MAINNET, toMicros } from "./network.js";
 import { privateKeySigner } from "./wallet.js";
 const HELP = `envolvr: private inference your agent can prove
 
   envolvr signin [--save]             sign in with ENVOLVR_PRIVATE_KEY, print a new API key
-  envolvr testnet-mint <usd>          mint test USDG to the wallet (testnet)
   envolvr deposit <usd> [--for 0x…]   deposit USDG (net of the deposit fee) to your balance
-  envolvr account                     balance and today's staking allowance
+  envolvr account                     your balance
   envolvr pricing                     the deposit fee and how token prices are set
   envolvr models                      models and per-token prices
   envolvr chat <prompt> [--model m] [--provider '{"only":["near-ai"]}']
@@ -36,7 +35,7 @@ const flag = (name) => {
     const i = args.indexOf(`--${name}`);
     return i > 0 ? args[i + 1] : undefined;
 };
-const network = TESTNET;
+const network = MAINNET;
 const receiptDir = process.env.ENVOLVR_RECEIPTS ?? 'envolvr-receipts';
 const credentialsPath = join(homedir(), '.envolvr', 'credentials.json');
 function wallet() {
@@ -69,11 +68,6 @@ async function main() {
             }
             return;
         }
-        case 'testnet-mint': {
-            const tx = await mintTestUsdg({ signer: wallet(), amountMicros: toMicros(args[1]), network });
-            console.log(`minted ${args[1]} test USDG: ${network.explorer}/tx/${tx}`);
-            return;
-        }
         case 'deposit': {
             const r = await depositUsdg({ signer: wallet(), amountMicros: toMicros(args[1]), account: flag('for'), network });
             console.log(`deposited ${usd(r.amountMicros)} for ${r.account}: ${network.explorer}/tx/${r.depositTx}`);
@@ -82,7 +76,8 @@ async function main() {
         }
         case 'account': {
             const a = await new Envolvr({ apiKey: apiKey(), network }).account();
-            console.log(`${a.wallet}\nbalance ${usd(a.balanceMicros)} | allowance today ${usd(a.allowanceTodayMicros)}, left ${usd(a.allowanceLeftMicros)}`);
+            const allowance = BigInt(a.allowanceTodayMicros) > 0n ? ` | allowance today ${usd(a.allowanceTodayMicros)}, left ${usd(a.allowanceLeftMicros)}` : '';
+            console.log(`${a.wallet}\nbalance ${usd(a.balanceMicros)}${allowance}`);
             return;
         }
         case 'pricing': {

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import { type AuditSummary, type PapResult } from './attest.ts';
 import { type Network } from './network.ts';
+import { type AutoTopUpOptions } from './topup.ts';
 import { type Anchor, type Billing, type Receipt } from './receipts.ts';
 export interface SavedReceipt {
     id: string;
@@ -25,10 +26,16 @@ export declare class Envolvr {
     readonly network: Network;
     private apiKey;
     private receiptDir;
+    private topUp;
+    /**
+     * `autoTopUp` keeps the account funded from a wallet: see AutoTopUpOptions.
+     * It covers chat(); a client built from `openai` handles its own 402s.
+     */
     constructor(opts: {
         apiKey: string;
         network?: Network;
         receiptDir?: string;
+        autoTopUp?: AutoTopUpOptions;
     });
     /** Settings for the OpenAI SDK: `new OpenAI(envolvr.openai)`. Receipts are then yours to fetch. */
     get openai(): {
@@ -49,6 +56,7 @@ export declare class Envolvr {
         receiptId: string | null;
         saved?: SavedReceipt;
     }>;
+    private chatOnce;
     /**
      * Fetch a receipt (within an hour of the response) and save it. With
      * `receiptDir`, the request and response bytes and the signing keyset's

package/dist/client.js

@@ -7,16 +7,24 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import { join } from 'node:path';
 import { getAccount, getPricing } from "./api.js";
 import { auditReceipt, fetchAttestationReport, summarizeAudit } from "./attest.js";
-import { TESTNET } from "./network.js";
+import { MAINNET } from "./network.js";
+import { AutoTopUp } from "./topup.js";
 import { billingOf, chargedTo, verifyAnchor } from "./receipts.js";
 export class Envolvr {
     network;
     apiKey;
     receiptDir;
+    topUp;
+    /**
+     * `autoTopUp` keeps the account funded from a wallet: see AutoTopUpOptions.
+     * It covers chat(); a client built from `openai` handles its own 402s.
+     */
     constructor(opts) {
         this.apiKey = opts.apiKey;
-        this.network = opts.network ?? TESTNET;
+        this.network = opts.network ?? MAINNET;
         this.receiptDir = opts.receiptDir;
+        if (opts.autoTopUp)
+            this.topUp = new AutoTopUp(opts.autoTopUp, this.apiKey, this.network);
     }
     /** Settings for the OpenAI SDK: `new OpenAI(envolvr.openai)`. Receipts are then yours to fetch. */
     get openai() {
@@ -41,6 +49,19 @@ export class Envolvr {
      * to pin providers.
      */
     async chat(body) {
+        await this.topUp?.beforeRequest();
+        try {
+            return await this.chatOnce(body);
+        }
+        catch (err) {
+            // Out of credit: top up once and retry, when auto top-up is on and could add funds.
+            if (err.status === 402 && this.topUp && (await this.topUp.afterInsufficientCredit())) {
+                return this.chatOnce(body);
+            }
+            throw err;
+        }
+    }
+    async chatOnce(body) {
         const request = JSON.stringify({ ...body, stream: false });
         const res = await fetch(`${this.network.gateway}/v1/chat/completions`, {
             method: 'POST', headers: { authorization: `Bearer ${this.apiKey}`, 'content-type': 'application/json' }, body: request,
@@ -122,7 +143,7 @@ export class Envolvr {
 }
 /** Verify a receipt saved by Envolvr.receipt (a directory with receipt.json). */
 export async function verifySaved(dir, opts) {
-    const network = opts.network ?? TESTNET;
+    const network = opts.network ?? MAINNET;
     const receiptPath = join(dir, 'receipt.json');
     const receipt = JSON.parse(readFileSync(receiptPath, 'utf8'));
     const reports = join(opts.receiptDir ?? join(dir, '..'), 'attestation');

package/dist/index.d.ts

@@ -4,7 +4,8 @@ export { auditReceipt, fetchAttestationReport, runPap, verifyGateway } from './a
 export type { PapResult } from './attest.ts';
 export { Envolvr, savedReceipts, verifySaved } from './client.ts';
 export type { SavedReceipt, Verification } from './client.ts';
-export { fromMicros, TESTNET, toMicros } from './network.ts';
+export { fromMicros, MAINNET, TESTNET, toMicros } from './network.ts';
+export type { AutoTopUpOptions, TopUpEvent } from './topup.ts';
 export type { Network } from './network.ts';
 export { billingOf, chargedTo, payerCommitment, proofLeadsToRoot, receiptDigest, verifyAnchor } from './receipts.ts';
 export type { Anchor, Billing, Receipt } from './receipts.ts';

package/dist/index.js

@@ -2,6 +2,6 @@
 export { closeAccount, closeAccountMessage, depositUsdg, getAccount, getPricing, mintTestUsdg, netCredit, signIn, signInMessage, } from "./api.js";
 export { auditReceipt, fetchAttestationReport, runPap, verifyGateway } from "./attest.js";
 export { Envolvr, savedReceipts, verifySaved } from "./client.js";
-export { fromMicros, TESTNET, toMicros } from "./network.js";
+export { fromMicros, MAINNET, TESTNET, toMicros } from "./network.js";
 export { billingOf, chargedTo, payerCommitment, proofLeadsToRoot, receiptDigest, verifyAnchor } from "./receipts.js";
 export { privateKeySigner } from "./wallet.js";

package/dist/network.d.ts

@@ -14,6 +14,11 @@ export interface Network {
     providerId: string;
 }
 export declare const TESTNET: Network;
+/** The mainnet contract addresses are published at launch; until then they are this placeholder. */
+export declare const PENDING_ADDRESS = "0x0000000000000000000000000000000000000000";
+export declare const MAINNET: Network;
+/** Throws before any on-chain step on a network whose contracts are not published yet. */
+export declare function assertContracts(network: Network): void;
 /** USDG and envolvr balances have 6 decimals: "1.5" -> 1500000n. */
 export declare function toMicros(amount: string | number): bigint;
 export declare function fromMicros(micros: bigint | string): string;

package/dist/network.js

@@ -1,4 +1,4 @@
-// Where envolvr runs. Robinhood Chain testnet until mainnet.
+// Where envolvr runs: Robinhood Chain mainnet, and the testnet.
 export const TESTNET = {
     gateway: 'https://api.envolvr.xyz',
     control: 'https://auth.envolvr.xyz',
@@ -10,6 +10,25 @@ export const TESTNET = {
     receiptAnchor: '0xff179938C830134D8E2922dAe7e16Ee4F0E33853',
     providerId: '0x86b99987cd8f8ebddc2dd0efa61ed52b5db594430f12446db424da0d9c4b831f',
 };
+/** The mainnet contract addresses are published at launch; until then they are this placeholder. */
+export const PENDING_ADDRESS = '0x0000000000000000000000000000000000000000';
+export const MAINNET = {
+    gateway: 'https://api.envolvr.xyz',
+    control: 'https://auth.envolvr.xyz',
+    chainId: 4663,
+    rpcUrl: 'https://rpc.mainnet.chain.robinhood.com',
+    explorer: 'https://robin.etherscan.io',
+    usdg: '0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168',
+    creditVault: '0x24DbbBd7d5eE9674D8A8B19a492E87A4957B1261',
+    receiptAnchor: '0x591fadf9d2D9d0A0fedEEd95d74321694797AF60',
+    providerId: '0x86b99987cd8f8ebddc2dd0efa61ed52b5db594430f12446db424da0d9c4b831f',
+};
+/** Throws before any on-chain step on a network whose contracts are not published yet. */
+export function assertContracts(network) {
+    if ([network.usdg, network.creditVault].includes(PENDING_ADDRESS)) {
+        throw new Error(`the contracts on chain ${network.chainId} are published at launch: see https://envolvr.xyz/token/#contracts`);
+    }
+}
 /** USDG and envolvr balances have 6 decimals: "1.5" -> 1500000n. */
 export function toMicros(amount) {
     const s = String(amount).trim();

package/dist/receipts.js

@@ -1,8 +1,9 @@
 // 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';
+// against the contract itself. No Node built-ins, so the site's in-browser
+// verifier bundles this same file.
+import { sha256 } from '@noble/hashes/sha2';
 import { keccak_256 } from '@noble/hashes/sha3';
 import { bytesToHex, concatBytes, hexToBytes, utf8ToBytes } from '@noble/hashes/utils';
 import canonicalize from 'canonicalize';
@@ -11,7 +12,7 @@ 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')}`;
+    return `0x${bytesToHex(sha256(utf8ToBytes(jcs)))}`;
 }
 /** The receipt's billing.charged event, or undefined for an unpriced request. */
 export function billingOf(receipt) {
@@ -26,8 +27,8 @@ export function billingOf(receipt) {
 }
 /** 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')}`;
+    const keyHash = bytesToHex(sha256(utf8ToBytes(apiKey)));
+    return `sha256:${bytesToHex(sha256(utf8ToBytes(`billing.payer.v1:${keyHash}:${receiptId}`)))}`;
 }
 export function chargedTo(receipt, apiKey) {
     return billingOf(receipt)?.payer === payerCommitment(apiKey, receipt.receipt_id);

package/dist/topup.d.ts

@@ -0,0 +1,61 @@
+import { type Network } from './network.ts';
+import type { Signer } from './wallet.ts';
+export interface AutoTopUpOptions {
+    /** The wallet that pays: it needs USDG, and a little ETH for gas. */
+    signer: Signer;
+    /** Top up when allowance left plus balance falls below this, USD (for example '5'). */
+    below: string;
+    /** How much to deposit each time, USD. The account is credited net of the deposit fee. */
+    amount: string;
+    /** Most to deposit per UTC day, USD. Defaults to `amount`: one top-up a day. */
+    maxPerDay?: string;
+    /** How often to read the account before a request, ms. Default 30 000. */
+    checkEveryMs?: number;
+    /** How long to wait for a mined deposit to be credited, ms. Default 120 000. */
+    creditTimeoutMs?: number;
+    /** Told about every top-up, skip and failure. */
+    onEvent?: (event: TopUpEvent) => void;
+}
+export type TopUpEvent = {
+    type: 'topped-up';
+    amountMicros: bigint;
+    depositTx: string;
+    creditedMicros: bigint;
+} | {
+    type: 'capped';
+    availableMicros: bigint;
+    spentTodayMicros: bigint;
+    maxPerDayMicros: bigint;
+} | {
+    type: 'failed';
+    error: Error;
+};
+export declare class AutoTopUp {
+    private readonly opts;
+    private readonly below;
+    private readonly amount;
+    private readonly maxPerDay;
+    private lastCheck;
+    private running;
+    private day;
+    private spentToday;
+    private cappedNoticeDay;
+    private toppedUp;
+    private readonly apiKey;
+    private readonly network;
+    private readonly now;
+    private readonly sleep;
+    constructor(opts: AutoTopUpOptions, apiKey: string, network: Network, clock?: {
+        now?: () => number;
+        sleep?: (ms: number) => Promise<unknown>;
+    });
+    /** Before a request: read the account at most every `checkEveryMs`, top up if it is low. */
+    beforeRequest(): Promise<void>;
+    /**
+     * After a 402: read the account now, whatever the interval, and top up if it is
+     * low. True when a top-up was credited, so the request can be retried.
+     */
+    afterInsufficientCredit(): Promise<boolean>;
+    private ensure;
+    private run;
+}

package/dist/topup.js

@@ -0,0 +1,109 @@
+// Automatic top-up: keep an account funded from a wallet, within a daily cap.
+//
+// Before a request (at most every `checkEveryMs`), and whenever the gateway
+// answers 402 insufficient credit, the client reads the account. When the
+// staking allowance left plus the USDG balance is below `below`, it deposits
+// `amount` from `signer` (for the account's own wallet, or with depositFor when
+// the signer is another wallet, such as the person funding an agent) and waits
+// until the control plane has credited it. Concurrent requests share one
+// top-up. Deposits per UTC day stop at `maxPerDay` (default: one top-up), as
+// counted by this process.
+import { depositUsdg, getAccount } from "./api.js";
+import { fromMicros, toMicros } from "./network.js";
+const DAY_MS = 86_400_000;
+const available = (a) => BigInt(a.balanceMicros) + BigInt(a.allowanceLeftMicros);
+export class AutoTopUp {
+    opts;
+    below;
+    amount;
+    maxPerDay;
+    lastCheck = 0;
+    running;
+    day = -1;
+    spentToday = 0n;
+    cappedNoticeDay = -1;
+    toppedUp = 0;
+    apiKey;
+    network;
+    now;
+    sleep;
+    constructor(opts, apiKey, network, clock = {}) {
+        this.opts = opts;
+        this.apiKey = apiKey;
+        this.network = network;
+        this.now = clock.now ?? Date.now;
+        this.sleep = clock.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        this.below = toMicros(opts.below);
+        this.amount = toMicros(opts.amount);
+        this.maxPerDay = toMicros(opts.maxPerDay ?? opts.amount);
+        if (this.amount <= 0n)
+            throw new Error('autoTopUp.amount must be positive');
+        if (this.maxPerDay < this.amount)
+            throw new Error('autoTopUp.maxPerDay must be at least autoTopUp.amount');
+    }
+    /** Before a request: read the account at most every `checkEveryMs`, top up if it is low. */
+    async beforeRequest() {
+        if (this.running)
+            return this.running;
+        if (this.now() - this.lastCheck < (this.opts.checkEveryMs ?? 30_000))
+            return;
+        return this.ensure();
+    }
+    /**
+     * After a 402: read the account now, whatever the interval, and top up if it is
+     * low. True when a top-up was credited, so the request can be retried.
+     */
+    async afterInsufficientCredit() {
+        const toppedUp = this.toppedUp;
+        await this.ensure();
+        return this.toppedUp > toppedUp;
+    }
+    ensure() {
+        this.running ??= this.run().finally(() => { this.running = undefined; });
+        return this.running;
+    }
+    async run() {
+        try {
+            this.lastCheck = this.now();
+            const account = await getAccount(this.apiKey, this.network);
+            const have = available(account);
+            if (have >= this.below)
+                return;
+            const day = Math.floor(this.now() / DAY_MS);
+            if (day !== this.day) {
+                this.day = day;
+                this.spentToday = 0n;
+            }
+            if (this.spentToday + this.amount > this.maxPerDay) {
+                if (this.cappedNoticeDay !== day) {
+                    this.cappedNoticeDay = day;
+                    this.opts.onEvent?.({ type: 'capped', availableMicros: have, spentTodayMicros: this.spentToday, maxPerDayMicros: this.maxPerDay });
+                }
+                return;
+            }
+            const { depositTx, expectedCreditMicros } = await depositUsdg({
+                signer: this.opts.signer, amountMicros: this.amount, account: account.wallet, network: this.network,
+            });
+            this.spentToday += this.amount;
+            // The deposit is mined; wait until the control plane has credited it.
+            const target = BigInt(account.balanceMicros) + expectedCreditMicros;
+            const deadline = this.now() + (this.opts.creditTimeoutMs ?? 120_000);
+            let credited = 0n;
+            while (this.now() < deadline) {
+                const a = await getAccount(this.apiKey, this.network);
+                credited = BigInt(a.balanceMicros) - BigInt(account.balanceMicros);
+                if (BigInt(a.balanceMicros) >= target)
+                    break;
+                await this.sleep(3_000);
+            }
+            if (credited < expectedCreditMicros) {
+                throw new Error(`deposit ${depositTx} was mined but ${fromMicros(expectedCreditMicros)} USD was not credited within the timeout`);
+            }
+            this.toppedUp++;
+            this.opts.onEvent?.({ type: 'topped-up', amountMicros: this.amount, depositTx, creditedMicros: credited });
+        }
+        catch (err) {
+            this.opts.onEvent?.({ type: 'failed', error: err instanceof Error ? err : new Error(String(err)) });
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envolvr/sdk",
-  "version": "0.1.0",
+  "version": "0.2.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",