@buildaureon/sdk 0.1.8 → 0.1.9

package/docs/receipt-validation.md

@@ -1,66 +1,66 @@
-# Receipt validation
-
-Phase 2 receipts must follow honest settlement rules. Use the SDK validator after every restore or when ingesting receipts from logs.
-
----
-
-## Quick example
-
-```ts
-import {
-  createAureonClient,
-  resolveAureonNetworkFromEnv,
-  validateExecutionReceipt,
-  assertValidExecutionReceipt,
-} from "@buildaureon/sdk";
-
-const resolved = resolveAureonNetworkFromEnv();
-const client = createAureonClient({
-  network: resolved.network,
-  baseUrl: resolved.baseUrl,
-  apiKey: process.env.AUREON_API_KEY!,
-});
-
-const receipt = await client.restoreObjective("obj_abc123");
-
-const check = validateExecutionReceipt(receipt);
-if (!check.valid) {
-  for (const issue of check.issues) {
-    console.error(issue.code, issue.path, issue.message);
-  }
-  throw new Error("Receipt failed validation");
-}
-
-// Or throw in one step:
-assertValidExecutionReceipt(receipt);
-```
-
-List recent receipts and validate each:
-
-```ts
-for (const receipt of await client.listExecutions()) {
-  assertValidExecutionReceipt(receipt);
-}
-```
-
----
-
-## What gets checked
-
-| Rule | Fail code (examples) |
-|------|----------------------|
-| Required fields present | `MISSING_FIELD` |
-| `settlement` is `vault` or `staged` | `INVALID_SETTLEMENT` |
-| Staged: no explorer, not verified | `STAGED_WITH_EXPLORER`, `STAGED_VERIFIED_ON_CHAIN` |
-| Vault with real `0x` tx: explorer required | `VAULT_MISSING_EXPLORER` |
-| `verifiedOnChain: true` needs matching record | `VERIFIED_WITHOUT_RECORD` |
-| Registry ref hex shape | `INVALID_REGISTRY_REF` |
-
-The validator does **not** re-query the chain — it checks shape and honesty only.
-
----
-
-## Related
-
-- [Data contracts](./data-contracts.md) — receipt and settlement fields
-- [Integration guide](./integration-guide.md) — agent restore loop
+# Receipt validation
+
+Phase 2 receipts must follow honest settlement rules. Use the SDK validator after every restore or when ingesting receipts from logs.
+
+---
+
+## Quick example
+
+```ts
+import {
+  createAureonClient,
+  resolveAureonNetworkFromEnv,
+  validateExecutionReceipt,
+  assertValidExecutionReceipt,
+} from "@buildaureon/sdk";
+
+const resolved = resolveAureonNetworkFromEnv();
+const client = createAureonClient({
+  network: resolved.network,
+  baseUrl: resolved.baseUrl,
+  apiKey: process.env.AUREON_API_KEY!,
+});
+
+const receipt = await client.restoreObjective("obj_abc123");
+
+const check = validateExecutionReceipt(receipt);
+if (!check.valid) {
+  for (const issue of check.issues) {
+    console.error(issue.code, issue.path, issue.message);
+  }
+  throw new Error("Receipt failed validation");
+}
+
+// Or throw in one step:
+assertValidExecutionReceipt(receipt);
+```
+
+List recent receipts and validate each:
+
+```ts
+for (const receipt of await client.listExecutions()) {
+  assertValidExecutionReceipt(receipt);
+}
+```
+
+---
+
+## What gets checked
+
+| Rule | Fail code (examples) |
+|------|----------------------|
+| Required fields present | `MISSING_FIELD` |
+| `settlement` is `vault` or `staged` | `INVALID_SETTLEMENT` |
+| Staged: no explorer, not verified | `STAGED_WITH_EXPLORER`, `STAGED_VERIFIED_ON_CHAIN` |
+| Vault with real `0x` tx: explorer required | `VAULT_MISSING_EXPLORER` |
+| `verifiedOnChain: true` needs matching record | `VERIFIED_WITHOUT_RECORD` |
+| Registry ref hex shape | `INVALID_REGISTRY_REF` |
+
+The validator does **not** re-query the chain — it checks shape and honesty only.
+
+---
+
+## Related
+
+- [Data contracts](./data-contracts.md) — receipt and settlement fields
+- [Integration guide](./integration-guide.md) — agent restore loop

package/docs/security.md

@@ -1,120 +1,120 @@
-# Security Model and Practices
-
-Security architecture for `@buildaureon/sdk`: trust boundaries, credentials, vault signing, and production checklist.
-
-**Automation note:** SDK agents should run **Automatic** objectives only. Manual Approve flows are utility concerns, not SDK security surface.
-
----
-
-## 1. Gateway trust boundaries
-
-AUREON is non-custodial. The API is a policy engine, price indexer, and coordinator. It does not hold private keys and does not broadcast owner withdrawals for you.
-
-```mermaid
-flowchart TD
-  Host[Host_application] -->|1_request_calldata| Gateway[Aureon_API]
-  Gateway -->|2_unsigned_steps| Host
-  Host -->|3_sign_locally| Wallet[Private_key_or_KMS]
-  Wallet -->|4_broadcast| Chain[Robinhood_Chain_RPC]
-
-  subgraph OnChain [Smart_contract_controls]
-    Vault[Smart_Vault]
-    DX[Allowlisted_DEX_routes]
-    Vault -->|keeper_swaps_only| DX
-  end
-  Wallet -.->|owner_deposit_withdraw| Vault
-```
-
-### 1.1 Private key isolation
-
-The SDK never loads, stores, or transmits private keys or mnemonics. Signing stays in the host (viem, ethers, HSM, KMS). A gateway breach cannot drain vaults by itself.
-
-### 1.2 Issued API keys are wallet credentials
-
-An **issued** developer key identifies the bound wallet for control-plane operations (sync, objectives, health, restore, prepare). Treat it like a password:
-
-- Create in utility **Developers**
-- Store in env / secret manager
-- Pause or revoke on leak
-- Prefer one key per agent host
-
-Env bootstrap keys on the server unlock product access only. They do **not** identify a wallet and must not be used as agent identity.
-
-### 1.3 Unsigned calldata
-
-`prepareVaultDeposit` / `prepareVaultWithdraw` return structured steps. Decode against published ABIs before signing. Broadcast is always host-side.
-
----
-
-## 2. What a compromised API key can and cannot do
-
-| Can | Cannot |
-| --- | --- |
-| Read portfolio, vault, health, timeline | Sign owner deposit/withdraw txs |
-| Create / update / pause Auto objectives | Withdraw vault funds to arbitrary addresses |
-| Request restore plans and trigger Automatic restore coordination | Bypass vault keeper allowlists |
-| Create additional developer keys under the same wallet | Recover a private key |
-
-Keeper-driven Automatic restores execute allowlisted vault swaps. Keepers cannot send vault assets to arbitrary third parties.
-
----
-
-## 3. Smart vault access control
-
-- **Owner path:** deposits and withdrawals require owner-signed txs from prepare steps.
-- **Keeper path:** Automatic restores use registered keepers on allowlisted routes only.
-- **Slippage / limits:** vault and planner enforce execution bounds to reduce bad fills.
-
----
-
-## 4. Settlement honesty
-
-Every execution receipt includes `settlement`:
-
-| Value | Meaning | UI rule |
-| --- | --- | --- |
-| `vault` | On-chain vault / keeper settlement with verifiable hash | May show as on-chain |
-| `staged` | Ledger-local / rehearsal — not a chain settlement | Must **not** be labeled as on-chain |
-
-Never collapse staged into “confirmed on Robinhood Chain.”
-
----
-
-## 5. Transport and logging hygiene
-
-- Default omitted client is local mainnet `http://127.0.0.1:8788` (4663). Use `network: "testnet"` for the public host (still 46630). Do not call that host production.
-- Do not log raw `Authorization` or `X-Aureon-Api-Key`.
-- Redact prepare step calldata in public logs if it includes sensitive amounts in your threat model.
-- Set `timeoutMs` / `maxRetries` deliberately for agent loops (see [transport.md](./transport.md)).
-
----
-
-## 6. Frontend vs agent hosts
-
-| Host | Guidance |
-| --- | --- |
-| Server agent / cron | Issued API key in secret store; private key in KMS if broadcasting deposits |
-| Browser SPA | Do **not** embed issued API keys in public bundles; proxy through your backend |
-| Operator utility | Wallet Bearer only — separate from SDK agent auth |
-
----
-
-## 7. Production checklist
-
-- [ ] Issued developer key (not a shared env bootstrap key) in secrets
-- [ ] Private keys isolated from the API key and never logged
-- [ ] Deposit/withdraw broadcast path reviewed and ABI-checked
-- [ ] Automatic objectives only in SDK loops
-- [ ] UI / agent summaries honor `settlement: vault | staged`
-- [ ] Gas reserve on the signing wallet for owner txs
-- [ ] Key rotation plan (pause/revoke in Developers)
-- [ ] Error handling branches on `error.code` (see [error-model.md](./error-model.md))
-
----
-
-## 8. Related docs
-
-- [Auth](./auth.md)
-- [Architecture](./architecture.md)
-- [Integration guide](./integration-guide.md)
-- [Error model](./error-model.md)
+# Security Model and Practices
+
+Security architecture for `@buildaureon/sdk`: trust boundaries, credentials, vault signing, and production checklist.
+
+**Automation note:** SDK agents should run **Automatic** objectives only. Manual Approve flows are utility concerns, not SDK security surface.
+
+---
+
+## 1. Gateway trust boundaries
+
+AUREON is non-custodial. The API is a policy engine, price indexer, and coordinator. It does not hold private keys and does not broadcast owner withdrawals for you.
+
+```mermaid
+flowchart TD
+  Host[Host_application] -->|1_request_calldata| Gateway[Aureon_API]
+  Gateway -->|2_unsigned_steps| Host
+  Host -->|3_sign_locally| Wallet[Private_key_or_KMS]
+  Wallet -->|4_broadcast| Chain[Robinhood_Chain_RPC]
+
+  subgraph OnChain [Smart_contract_controls]
+    Vault[Smart_Vault]
+    DX[Allowlisted_DEX_routes]
+    Vault -->|keeper_swaps_only| DX
+  end
+  Wallet -.->|owner_deposit_withdraw| Vault
+```
+
+### 1.1 Private key isolation
+
+The SDK never loads, stores, or transmits private keys or mnemonics. Signing stays in the host (viem, ethers, HSM, KMS). A gateway breach cannot drain vaults by itself.
+
+### 1.2 Issued API keys are wallet credentials
+
+An **issued** developer key identifies the bound wallet for control-plane operations (sync, objectives, health, restore, prepare). Treat it like a password:
+
+- Create in utility **Developers**
+- Store in env / secret manager
+- Pause or revoke on leak
+- Prefer one key per agent host
+
+Env bootstrap keys on the server unlock product access only. They do **not** identify a wallet and must not be used as agent identity.
+
+### 1.3 Unsigned calldata
+
+`prepareVaultDeposit` / `prepareVaultWithdraw` return structured steps. Decode against published ABIs before signing. Broadcast is always host-side.
+
+---
+
+## 2. What a compromised API key can and cannot do
+
+| Can | Cannot |
+| --- | --- |
+| Read portfolio, vault, health, timeline | Sign owner deposit/withdraw txs |
+| Create / update / pause Auto objectives | Withdraw vault funds to arbitrary addresses |
+| Request restore plans and trigger Automatic restore coordination | Bypass vault keeper allowlists |
+| Create additional developer keys under the same wallet | Recover a private key |
+
+Keeper-driven Automatic restores execute allowlisted vault swaps. Keepers cannot send vault assets to arbitrary third parties.
+
+---
+
+## 3. Smart vault access control
+
+- **Owner path:** deposits and withdrawals require owner-signed txs from prepare steps.
+- **Keeper path:** Automatic restores use registered keepers on allowlisted routes only.
+- **Slippage / limits:** vault and planner enforce execution bounds to reduce bad fills.
+
+---
+
+## 4. Settlement honesty
+
+Every execution receipt includes `settlement`:
+
+| Value | Meaning | UI rule |
+| --- | --- | --- |
+| `vault` | On-chain vault / keeper settlement with verifiable hash | May show as on-chain |
+| `staged` | Ledger-local / rehearsal — not a chain settlement | Must **not** be labeled as on-chain |
+
+Never collapse staged into “confirmed on Robinhood Chain.”
+
+---
+
+## 5. Transport and logging hygiene
+
+- Default omitted client is the official API `https://api.aureonlabs.network` (currently testnet 46630). Use `network: "mainnet"` for chain 4663 on the same host. Do not call that host production until it is cut over.
+- Do not log raw `Authorization` or `X-Aureon-Api-Key`.
+- Redact prepare step calldata in public logs if it includes sensitive amounts in your threat model.
+- Set `timeoutMs` / `maxRetries` deliberately for agent loops (see [transport.md](./transport.md)).
+
+---
+
+## 6. Frontend vs agent hosts
+
+| Host | Guidance |
+| --- | --- |
+| Server agent / cron | Issued API key in secret store; private key in KMS if broadcasting deposits |
+| Browser SPA | Do **not** embed issued API keys in public bundles; proxy through your backend |
+| Operator utility | Wallet Bearer only — separate from SDK agent auth |
+
+---
+
+## 7. Production checklist
+
+- [ ] Issued developer key (not a shared env bootstrap key) in secrets
+- [ ] Private keys isolated from the API key and never logged
+- [ ] Deposit/withdraw broadcast path reviewed and ABI-checked
+- [ ] Automatic objectives only in SDK loops
+- [ ] UI / agent summaries honor `settlement: vault | staged`
+- [ ] Gas reserve on the signing wallet for owner txs
+- [ ] Key rotation plan (pause/revoke in Developers)
+- [ ] Error handling branches on `error.code` (see [error-model.md](./error-model.md))
+
+---
+
+## 8. Related docs
+
+- [Auth](./auth.md)
+- [Architecture](./architecture.md)
+- [Integration guide](./integration-guide.md)
+- [Error model](./error-model.md)

package/docs/transport.md

@@ -1,143 +1,143 @@
-# Transport Layer Reference
-
-HTTP transport for `@buildaureon/sdk` (`src/transport/http.ts`): headers, timeouts, retries, URL helpers, and logging.
-
----
-
-## 1. Request lifecycle
-
-```mermaid
-flowchart TD
-  Call[Client_method] --> Prep[Join_URL_and_headers]
-  Prep --> Auth[Resolve_API_key_and_Bearer]
-  Auth --> Abort[AbortController_timeout]
-  Abort --> Fetch[fetch_implementation]
-  Fetch --> Ok{HTTP_OK?}
-  Ok -->|Yes| Parse[Parse_JSON]
-  Ok -->|No| Map[Map_to_AureonError]
-  Map --> Retry{Retryable_and_budget?}
-  Retry -->|Yes| Sleep[retryDelayMs]
-  Sleep --> Fetch
-  Retry -->|No| Throw[Throw]
-```
-
-1. Join `baseUrl` + path; attach query string when needed.
-2. Resolve `X-Aureon-Api-Key` from `apiKey` / `getApiKey`.
-3. Resolve `Authorization: Bearer …` from `getAccessToken` / `authToken` (optional).
-4. Apply timeout via `AbortController` (default 30s).
-5. On failure, map status → typed error; retry only if configured and retryable.
-
----
-
-## 2. Headers
-
-| Header | When | Purpose |
-| --- | --- | --- |
-| `Accept` | Always | `application/json` |
-| `Content-Type` | Body present | `application/json` |
-| `X-Aureon-SDK` | Always | Package identity / version |
-| `X-Aureon-Api-Key` | Key configured | Product access + issued-key identity |
-| `Authorization` | Token configured | Optional Bearer session |
-| Custom `headers` | If set on client | Merged into every request |
-
-Issued developer keys in `X-Aureon-Api-Key` are enough for control-plane identity on the live API. Bearer is optional and wins when both are present.
-
----
-
-## 3. Client transport options
-
-```ts
-createAureonClient({
-  // omit network → local mainnet 8788 / 4663
-  // network: "testnet" → public host (still 46630)
-  apiKey: process.env.AUREON_API_KEY!,
-  timeoutMs: 30_000,   // per attempt
-  maxRetries: 2,        // extra attempts after first failure
-  retryDelayMs: 500,    // fixed delay between attempts
-  fetch: customFetch,   // optional
-  headers: { "X-Debug": "1" },
-  logger: myLogger,
-});
-```
-
-| Option | Default | Notes |
-| --- | --- | --- |
-| `timeoutMs` | `30000` | Must be positive finite |
-| `maxRetries` | `0` | Extra tries after the first failure |
-| `retryDelayMs` | `250` | Fixed sleep between tries |
-| `fetch` | `globalThis.fetch` | Inject for tests / unusual runtimes |
-
----
-
-## 4. Retry policy
-
-**Retryable:** network failures, timeouts, HTTP 429, HTTP 5xx (when mapped as retryable).
-
-**Not retryable:** 400 validation, 401/403 auth, 404, most 409 conflicts (operator must change state).
-
-Total attempts = `1 + maxRetries`.
-
----
-
-## 5. URL helpers
-
-### `joinUrl`
-
-Prevents double slashes when combining base + path.
-
-### `withQuery`
-
-Serializes defined query params with `encodeURIComponent`. Omits `null` / `undefined`.
-
----
-
-## 6. Timeouts and aborts
-
-```ts
-const controller = new AbortController();
-const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-try {
-  return await fetchImpl(url, { ...init, signal: controller.signal });
-} catch (error) {
-  if (error instanceof Error && error.name === "AbortError") {
-    throw /* AureonTimeoutError */;
-  }
-  throw /* AureonNetworkError */;
-} finally {
-  clearTimeout(timeoutId);
-}
-```
-
-For agent loops that call restore + sync, prefer slightly higher `timeoutMs` under load rather than disabling timeouts.
-
----
-
-## 7. Logger interface
-
-```ts
-interface AureonLogger {
-  debug(message: string, context?: Record<string, unknown>): void;
-  info(message: string, context?: Record<string, unknown>): void;
-  warn(message: string, context?: Record<string, unknown>): void;
-  error(message: string, context?: Record<string, unknown>): void;
-}
-```
-
-Helpers may include console / silent adapters depending on package exports. Never log secrets from context.
-
----
-
-## 8. Testing transport
-
-- Inject a fake `fetch` that returns controlled status/body.
-- Assert header presence of `X-Aureon-Api-Key` for SDK clients.
-- Assert retries by counting fetch invocations with `maxRetries > 0` and 503 responses.
-
----
-
-## 9. Related docs
-
-- [Error model](./error-model.md)
-- [Auth](./auth.md)
-- [Client API](./client-api.md)
-- [Security](./security.md)
+# Transport Layer Reference
+
+HTTP transport for `@buildaureon/sdk` (`src/transport/http.ts`): headers, timeouts, retries, URL helpers, and logging.
+
+---
+
+## 1. Request lifecycle
+
+```mermaid
+flowchart TD
+  Call[Client_method] --> Prep[Join_URL_and_headers]
+  Prep --> Auth[Resolve_API_key_and_Bearer]
+  Auth --> Abort[AbortController_timeout]
+  Abort --> Fetch[fetch_implementation]
+  Fetch --> Ok{HTTP_OK?}
+  Ok -->|Yes| Parse[Parse_JSON]
+  Ok -->|No| Map[Map_to_AureonError]
+  Map --> Retry{Retryable_and_budget?}
+  Retry -->|Yes| Sleep[retryDelayMs]
+  Sleep --> Fetch
+  Retry -->|No| Throw[Throw]
+```
+
+1. Join `baseUrl` + path; attach query string when needed.
+2. Resolve `X-Aureon-Api-Key` from `apiKey` / `getApiKey`.
+3. Resolve `Authorization: Bearer …` from `getAccessToken` / `authToken` (optional).
+4. Apply timeout via `AbortController` (default 30s).
+5. On failure, map status → typed error; retry only if configured and retryable.
+
+---
+
+## 2. Headers
+
+| Header | When | Purpose |
+| --- | --- | --- |
+| `Accept` | Always | `application/json` |
+| `Content-Type` | Body present | `application/json` |
+| `X-Aureon-SDK` | Always | Package identity / version |
+| `X-Aureon-Api-Key` | Key configured | Product access + issued-key identity |
+| `Authorization` | Token configured | Optional Bearer session |
+| Custom `headers` | If set on client | Merged into every request |
+
+Issued developer keys in `X-Aureon-Api-Key` are enough for control-plane identity on the live API. Bearer is optional and wins when both are present.
+
+---
+
+## 3. Client transport options
+
+```ts
+createAureonClient({
+  // omit network → official API / testnet 46630
+  // network: "mainnet" → chain 4663 on the same official host
+  apiKey: process.env.AUREON_API_KEY!,
+  timeoutMs: 30_000,   // per attempt
+  maxRetries: 2,        // extra attempts after first failure
+  retryDelayMs: 500,    // fixed delay between attempts
+  fetch: customFetch,   // optional
+  headers: { "X-Debug": "1" },
+  logger: myLogger,
+});
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `timeoutMs` | `30000` | Must be positive finite |
+| `maxRetries` | `0` | Extra tries after the first failure |
+| `retryDelayMs` | `250` | Fixed sleep between tries |
+| `fetch` | `globalThis.fetch` | Inject for tests / unusual runtimes |
+
+---
+
+## 4. Retry policy
+
+**Retryable:** network failures, timeouts, HTTP 429, HTTP 5xx (when mapped as retryable).
+
+**Not retryable:** 400 validation, 401/403 auth, 404, most 409 conflicts (operator must change state).
+
+Total attempts = `1 + maxRetries`.
+
+---
+
+## 5. URL helpers
+
+### `joinUrl`
+
+Prevents double slashes when combining base + path.
+
+### `withQuery`
+
+Serializes defined query params with `encodeURIComponent`. Omits `null` / `undefined`.
+
+---
+
+## 6. Timeouts and aborts
+
+```ts
+const controller = new AbortController();
+const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+try {
+  return await fetchImpl(url, { ...init, signal: controller.signal });
+} catch (error) {
+  if (error instanceof Error && error.name === "AbortError") {
+    throw /* AureonTimeoutError */;
+  }
+  throw /* AureonNetworkError */;
+} finally {
+  clearTimeout(timeoutId);
+}
+```
+
+For agent loops that call restore + sync, prefer slightly higher `timeoutMs` under load rather than disabling timeouts.
+
+---
+
+## 7. Logger interface
+
+```ts
+interface AureonLogger {
+  debug(message: string, context?: Record<string, unknown>): void;
+  info(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>): void;
+}
+```
+
+Helpers may include console / silent adapters depending on package exports. Never log secrets from context.
+
+---
+
+## 8. Testing transport
+
+- Inject a test `fetch` that returns a controlled status and body.
+- Assert header presence of `X-Aureon-Api-Key` for SDK clients.
+- Assert retries by counting fetch invocations with `maxRetries > 0` and 503 responses.
+
+---
+
+## 9. Related docs
+
+- [Error model](./error-model.md)
+- [Auth](./auth.md)
+- [Client API](./client-api.md)
+- [Security](./security.md)

package/examples/ai-to-objective-to-portfolio/main.ts

@@ -3,7 +3,7 @@
  *
  * Env:
  *   AUREON_API_KEY  issued developer key (required)
- *   AUREON_NETWORK  optional; omit for mainnet (4663 / 8788); set testnet for public host (still 46630)
+ *   AUREON_NETWORK  optional; omit for official API / testnet 46630; set mainnet for chain 4663
  *   AUREON_API_URL  optional override (must match network if both set)
  *
  *   pnpm example:ai-to-objective-to-portfolio