> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/prd-shared/devenv-integration.md).

# Devenv Integration

> **Last Updated**: 2026-02-21 | **Referenced by**: devenv/01-overview\.md, vault/05-local-dev.md
>
> Cross-package integration contract between `@gotts.ai/devenv` (protocol layer) and `@gotts.ai/vault` (application layer). This document defines the shared types, state files, command hierarchy, and env file conventions that both packages depend on.

***

## Command Hierarchy

```
pnpm devenv                    # Protocol layer only (Anvil + Uniswap stack + debug UI)
    │                            Package: packages/devenv
    │                            Ports: 8545 (Anvil), 3001 (debug UI), 5100 (Otterscan)
    │
    ▼
pnpm testnet                   # Protocol + vault layer (adds factory, agents, vaults)
    │                            Package: packages/vault
    │                            Calls: deployUniswapStack() from @gotts.ai/devenv
    │                            Additional ports: 8080 (vault MCP), 3000 (vault UI)
    │
    ▼
pnpm testnet:swarm             # Protocol + vault + 5 autonomous agents
                                 Package: packages/vault
                                 Adds: 5 MCP server instances, agent prompt profiles
```

Each command is a superset of the one above. `pnpm testnet` implicitly runs `pnpm devenv` as its first step.

***

## Shared Types

### `UniswapDeployment`

Produced by `@gotts.ai/devenv`, consumed by `@gotts.ai/vault` and `@gotts.ai/safe`.

```typescript
interface UniswapDeployment {
  mode: "from-scratch" | "fork";
  chainId: number;
  rpcUrl: string;
  addresses: {
    weth9: Address;
    permit2: Address;
    v2Factory: Address;
    v2Router: Address;
    v3Factory: Address;
    v3PositionManager: Address;
    v3SwapRouter: Address;
    v4PoolManager: Address;
    v4PositionManager: Address;
    universalRouter: Address;
    exclusiveDutchReactor: Address;
    v2DutchReactor: Address;
    priorityReactor: Address;
    limitReactor: Address;
    erc8004IdentityRegistry: Address;
    erc8004ReputationRegistry: Address;
    usdc: Address;
    usdt: Address;
    dai: Address;
    wbtc: Address;
  };
  testAccounts: TestAccount[];
}
```

### `GottsDeployment`

Produced by `@gotts.ai/vault` testnet scripts, consumed by vault tests and debug UI.

```typescript
interface GottsDeployment {
  uniswap: UniswapDeployment; // From devenv
  vaultFactory: Address; // AgentVaultFactory (CREATE2)
  identityRegistry: Address; // Mock or real ERC-8004
  reputationRegistry: Address; // Mock or real
  vaults: {
    alice: Address; // CCA Hunter vault
    bob: Address; // Simple Yield vault
    eve: Address; // Meta-Vault
  };
  agents: {
    alice: { id: 1; address: Address; reputation: 120 };
    bob: { id: 2; address: Address; reputation: 60 };
    carol: { id: 3; address: Address; reputation: 15 };
    dave: { id: 4; address: Address; reputation: 0 };
    eve: { id: 5; address: Address; reputation: 600 };
  };
}
```

***

## State File Inventory

| File                            | Owner       | Consumer        | Format                      | Persists Across Restarts      |
| ------------------------------- | ----------- | --------------- | --------------------------- | ----------------------------- |
| `.devenv/deployment.json`       | devenv      | vault, safe     | `UniswapDeployment` JSON    | Yes (until Anvil reset)       |
| `.devenv/anvil-state.json`      | devenv      | devenv          | Anvil state dump            | Yes (optional, via `--state`) |
| `.devenv/gotts-deployment.json` | vault       | vault tests, UI | `GottsDeployment` JSON      | Yes (until Anvil reset)       |
| `logs/agents/*.jsonl`           | vault swarm | vault debug UI  | JSONL (one action per line) | No (cleared on restart)       |

***

## Environment File Mapping

| File          | Package           | Purpose                                                        |
| ------------- | ----------------- | -------------------------------------------------------------- |
| `.env.devenv` | `packages/devenv` | Devenv-specific config (fork URL, block number, mode)          |
| `.env`        | `packages/vault`  | Vault-specific config (wallet keys, factory address, MCP port) |
| `.env.test`   | Both              | Test-only overrides (CI, deterministic seeds)                  |

These files MUST NOT be merged. The devenv layer reads `.env.devenv`; the vault layer reads `.env`. This prevents variable collision (e.g., both defining `RPC_URL` with different values).

***

## Integration Contract

1. `@gotts.ai/devenv` exports `deployUniswapStack(): Promise<UniswapDeployment>` as its primary API
2. `@gotts.ai/vault` calls `deployUniswapStack()` and layers vault contracts on top
3. The `UniswapDeployment` type is the sole interface between the two packages
4. Neither package reads the other's `.env` file
5. Both packages write state to `.devenv/` (devenv creates the directory; vault appends to it)
6. Port allocation follows `prd/shared/port-allocation.md`

***

## Zero-Dependency Mode

The install wizard's `--zero` flag (`npx @gotts.ai setup --zero`) does **NOT** use `@gotts.ai/devenv`. It connects to public RPCs (Ethereum, Base, Arbitrum, etc.) and runs the MCP server with the `data` profile (28 read-only tools). No Anvil, no local fork, no contract deployment.

This is useful for evaluating the MCP data layer (pool info, token prices, trade history) without any local blockchain infrastructure. However, it cannot be used for contract testing, vault deployment, or any write operations that require a local Anvil instance.

For local contract testing and development, use `pnpm devenv` or `pnpm testnet` instead. See [mcp-server/15-install-wizard.md](/docs/gotts-safe-mcp-server/mcp-server/15-install-wizard.md) for the zero-dependency specification.