# Public SDK onboarding: V2 live and V3 source review

> **V3 IS MOCK / SOURCE-REVIEW ONLY AND CANNOT BROADCAST.**
>
> V2 is the live/default SDK surface. Current V3 exports are for local source
> review and fail-closed integration preparation. A future V3 deployment is a
> separate state that requires explicit verified addresses, runtime code
> hashes, authorization, activation, and availability evidence. Never infer a
> V3 address, substitute V2, or treat this sandbox as deployment evidence.

## Verified environment

The following was directly verified for this checkout on Linux x86_64:

```text
Node.js v20.20.1
npm 10.8.2
Linux x86_64
```

That Linux environment is the only environment claimed as verified here.
Current macOS and Windows releases are expected to work because the sandbox
uses Node built-ins and the SDK is TypeScript, but they were not verified in
this review. On Windows, use PowerShell equivalents for shell commands and path
syntax; WSL2 is expected to most closely match the verified Linux flow.

## Clean install, build, and test

From a clean checkout, verify the package lock rather than updating it:

```bash
cd repos/vaultfire-sdk
node --version
npm --version
npm ci
npm run build
npm test
```

Expected versions for this review are exactly `v20.20.1` and `10.8.2`.
`npm ci` removes any existing dependency tree and installs the checked-in lock.
Do not publish from this flow.

The local sandbox is separately dependency-free:

```bash
tar -xzf vaultfire-v3-partner-sandbox.tar.gz
cd vaultfire-v3-partner-sandbox
npm ci --offline --ignore-scripts --no-audit --no-fund
npm run build
npm test
```

## Minimal TypeScript source-review example

[`examples/minimal-sdk.ts`](./examples/minimal-sdk.ts) imports only the V3
review constants. It creates no provider or signer and sends no request or
transaction. The central guard is full ABI identity equality:

```typescript
import { V3_ABI_IDENTITIES, V3_NETWORK_PROFILES } from "@vaultfire/agent-sdk/v3";

const expected =
  "0x0c18d05c868716fad4bfc1fcfad2da51c83f247de06a7e3871dcece768a9526f";

if (V3_ABI_IDENTITIES.accountabilityBond !== expected) {
  throw new Error("VF3-IDENTITY-001: accountability ABI mismatch");
}

const profile = V3_NETWORK_PROFILES[8453];
if (profile.status !== "unconfigured" || profile.deployments.accountabilityBond.address !== null) {
  throw new Error("V3 must remain unavailable until explicitly verified");
}
```

The reviewed identities are:

| Module | Functions | Exact ABI identity |
| --- | ---: | --- |
| Accountability | 36 | `0x0c18d05c868716fad4bfc1fcfad2da51c83f247de06a7e3871dcece768a9526f` |
| Partnership | 55 | `0x954aeee609e92a621e726dcae77be193085651626941d582ca2f7f3b7c073d8c` |
| Governance | 45 | `0xcf81d69fed252f21bfd7661ff53868aa81b9ce1a4a1c89edbec9eaabffa7ad0a` |
| Mandate Registry | 24 | `0xe31e9d196bf5a37c328313f688b0d6eff881847e6c46437c1fc617faff8e80e3` |

Compare the complete identity, not an ABI subset or superset.

## OpenAPI client generation

The canonical generated OpenAPI document is read-only at
`pr7/generated/openapi.json`. This sandbox includes a deterministic,
dependency-free path-inventory generator so onboarding does not mutate the
canonical document or download a code generator:

```bash
cd pr7/partner-sandbox
npm run generate:openapi-client
```

Output is written to ignored `generated/vaultfire-api-paths.ts`. It is a typed
inventory, not a live client and not availability evidence. If a project needs
a full request client, pin and review its preferred OpenAPI generator in that
project, generate from the same document, and preserve the availability and
retirement gates below.

## 503 and retirement handling

Treat V3 availability as an explicit gate:

```typescript
async function readV3Status(baseUrl: string) {
  const response = await fetch(`${baseUrl}/api/v3/protocol/status`);
  if (response.status === 503) {
    return { available: false as const, reason: "V3 live readers are not configured" };
  }
  if (!response.ok) throw new Error(`V3 status failed: ${response.status}`);
  const body = await response.json();
  if (body.status !== "ok" || body.data == null) {
    return { available: false as const, reason: "V3 status is degraded" };
  }
  return { available: true as const, data: body.data };
}
```

An unavailable or degraded V3 response must not be converted to healthy zero
state and must not trigger a V2 fallback. Before a route call, inspect
`V3_ROUTE_METADATA`. If its disposition is `retired`, stop and surface
`retirement.retiredAt`, `reason`, and `replacement`. `taskEscrow` is retired;
the unversioned `latest` alias and `v2Fallback` are also explicitly retired.
Unavailable x402 routes remain unavailable until separately activated.

## Version separation checklist

| Surface | Current meaning | Permitted action |
| --- | --- | --- |
| V2 | Live/default deployed behavior | Use documented V2 reads/writes with normal production controls |
| V3 local sandbox | Deterministic educational source-review simulation | Run on loopback; use fixture units only; never broadcast |
| V3 SDK source | Review/build/test surface with null deployment addresses | Verify identities, types, gates, and generated unsigned intent locally |
| Future V3 | Not established by this checkout | Require explicit deployment, codehash, governance, audit, status, and activation evidence |

Do not mix receipts: sandbox receipts are local hash-linked records with
`mock: true` and `broadcast: false`; they are not chain transaction receipts,
x402 payment receipts, signatures, or proof of a future V3 deployment.