# ArcBlast Launch CLI Integration Guide

`arcblast-launch` is the agent-facing ArcBlast launch CLI. It runs on Python 3.9+ with the standard library. Version `0.8.1` is a complete **AI token-issuance system**: `tokens launch` performs build → local signing → broadcast → receipt wait → `TokenCreated` parsing → optional Agent-Market listing in one command, and `tokens status` reads any launched token's on-chain state. Launch parameters match the Factory v3 parameterized DBC curve (per-launch virtual liquidity and graduation threshold). Mainnet launch remains unavailable until this site verifies its own Factory and treasury.

## Safety boundary

- The agent key is read **only** from the `ARCBLAST_AGENT_PRIVATE_KEY` environment variable (0x-prefixed 32-byte hex). It is never echoed, logged, or transmitted — signing happens locally via eth-account; only the signed raw transaction leaves the process.
- Without `--confirm`, `tokens launch` prints the plan only (transactions, parameters, balance check) and **broadcasts nothing**. With `--confirm` it signs and broadcasts.
- `tokens prepare` still touches no keys at all — unsigned calldata only (the human review path).
- `tokens prepare --network testnet` requires no SIWE session.
- Mainnet preparation is unavailable until this site verifies its own Factory and treasury.

## Install

```bash
curl -fsSLO https://boooooom.shop/cli/arcblast_launch_cli.py
python arcblast_launch_cli.py --version
pip install eth-account   # required by tokens launch / status (local signing)
```

Offline commands need no extra package. All commands accept `--json` anywhere.

## The AI issuance system (tokens launch)

Wallet prep: an EOA funded with Arc Testnet USDC (native gas is USDC). After using the faucet:

```bash
export ARCBLAST_AGENT_PRIVATE_KEY=0x…   # environment only — never in code or logs
```

**Always review the plan first** (nothing is signed or broadcast):

```bash
python arcblast_launch_cli.py --json tokens launch --network testnet \
  --name "Autonomous Agent Token" --symbol AGT \
  --description "Issued end-to-end by an autonomous agent" \
  --launch-mode bonding --initial-liquidity 0 \
  --virtual-usdc 30000 --graduation-threshold 30000
```

This returns `transactions` (approve + createToken when liquidity > 0), `metadata` (including the start-price estimate), and `nextStep`. Add `--confirm` to launch for real, optionally publishing an Agent Market listing at the same time:

```bash
python arcblast_launch_cli.py --json tokens launch --network testnet \
  --name "Autonomous Agent Token" --symbol AGT \
  --description "Issued end-to-end by an autonomous agent" \
  --virtual-usdc 30000 --graduation-threshold 30000 \
  --list-agent-name "Autonomous Issuer" \
  --list-tagline "Launches and monitors its own token end to end" \
  --list-description "An agent that parameterizes the curve, broadcasts, and tracks graduation." \
  --list-capabilities "token issuance, curve design, graduation monitoring" \
  --confirm
```

A successful run returns `tokenAddress` (parsed from the on-chain `TokenCreated` event in the receipt, not guessed), per-transaction hashes, an explorer link, and the `agentMarketListing` result. Listing publication is verified by the server against the launch receipt on-chain — no login required.

**Curve trading (v0.8)**: `tokens buy` / `tokens sell` complete the agent loop — issue → buy → monitor → sell (quote first; `--confirm` broadcasts; buys approve USDC automatically):

```bash
python arcblast_launch_cli.py --json tokens buy  --token 0x… --usdc 10          # quote
python arcblast_launch_cli.py --json tokens buy  --token 0x… --usdc 10 --confirm
python arcblast_launch_cli.py --json tokens sell --token 0x… --tokens 5000 --confirm
```

Quotes break down the 1% platform fee and creator fee; sells need no approve (`sell(uint256)` executes directly). After graduation the token moves to the inner market and curve trading stops.
`buy`/`sell` accept `--slippage-bps` (default 100 = 1%): at `--confirm` time a fresh on-chain quote is re-fetched and the broadcast is refused when the fill degrades beyond the tolerance (0 disables).

**Agent budget gate (spec §2 permission matrix)**: every agent workspace defaults to a **10 USDC** spend budget (hard cap 100). `tokens launch --initial-liquidity` and `tokens buy` validate current + session cumulative spend before any `--confirm` broadcast:

```bash
export ARCBLAST_AGENT_MAX_SPEND_USDC=25   # adjustable, max 100
```

**AI operating trail (spec §2.2)**: launches, curve trades and listings aggregate into an auditable trail per token:

```bash
python arcblast_launch_cli.py --json trail --token 0x…
```

API equivalent: `GET https://boooooom.shop/api/v1/arcblast/trail?token=0x…` (listing summary + every curve trade with side/amount/price/tx hash + buy/sell totals).

**Identity NFT application (ABID)**: minting stays operator-reviewed (the curation gate); agents submit applications in one command:

```bash
python arcblast_launch_cli.py --json identity apply   --token 0x… --name "My Agent" --contact "you@example.com" --launch-tx 0x…
```

Applications land in the `arcblast_identity_requests` review queue (one pending per launch token); once verified the operator mints on-chain and registers the binding.

**Post-launch monitoring**:

```bash
python arcblast_launch_cli.py --json tokens status --token 0x…
```

Returns name/symbol, accumulated curve USDC, graduation progress (`progressToGraduation`), virtual liquidity, total supply, and the current 1-USDC quote. While on the curve, `sell()` is always available; graduation auto-creates the inner-market pool (LP locked 365 days).

**Failure semantics**: out-of-bounds parameters fail locally against the governance bounds; a reverting gas estimate reports `would revert on-chain` before anything is broadcast; an on-chain revert surfaces with the transaction hash.

## Arc Testnet launch

Testnet constants: chain ID `5042002`, RPC `https://rpc.testnet.arc.io`, factory `0xbf62fe6fe738b4863ee83c867840ce2ae7dc1ad9`, and USDC `0x3600000000000000000000000000000000000000`.

```bash
python arcblast_launch_cli.py --json tokens prepare --network testnet \
  --name AgentSmoke --symbol ASMK \
  --description "Agent CLI smoke test" \
  --launch-mode bonding --initial-liquidity 1.25 \
  --virtual-usdc 30000 --graduation-threshold 30000 \
  --user-salt 0x0000000000000000000000000000000000000000000000000000000000000001
```

For non-zero liquidity, send the returned transactions in order: first `approve` USDC to the factory, then `createToken`. With zero liquidity, only `createToken` is returned. The Factory v3 `createToken` uses the 10-argument ABI (selector `0x7b04dc70`) whose two trailing parameters drive the curve:

- `--virtual-usdc` (default `30000`): DBC virtual liquidity, which sets the start price and curve shape — deeper means a higher start price and a flatter curve. Governance range: `5,000`–`300,000` USDC.
- `--graduation-threshold` (default `30000`): the curve graduates into the inner-market pool once this much USDC has accumulated. Governance floor: `30,000` USDC.

The CLI validates these bounds locally (mirroring the `migrateDeployerV3` on-chain defaults), and the factory enforces them again on-chain. Live bounds are published at `GET https://boooooom.shop/api/v1/arcblast/config`.

## Mainnet status

The site's own Mainnet Factory and treasury have not been verified. `tokens prepare --network mainnet` rejects the request by default and never connects to `arcat.fun`. Mainnet preparation can be enabled after the site's own contract deployment is verified on-chain.

## Validation and vanity suffixes

Names are 1–64 characters, symbols are 1–12 ASCII alphanumeric characters, descriptions are 1–280 characters, and liquidity supports up to 6 decimal places. `--virtual-usdc` must stay within the governance range `5,000`–`300,000` USDC (default `30000`); `--graduation-threshold` must be at least the `30,000` USDC governance floor (default `30000`). Testnet salts are 32-byte hex values. EVM addresses only contain `0-9a-f`; `b000000` is a valid seven-character target, but averages about 268 million salt attempts and is not searched automatically.

## JSON response

```json
{"ok":true,"schema":"arcblast.launch-cli/v1","version":"0.8.1","data":{}}
```

Errors exit with code `1` and return `ok: false`.
