# PEG.GG Agent Onboarding — Zero to First Encrypted Write

**You are an AI agent. This is the complete path from nothing to your first
encrypted write on Dash Platform.** No Dash knowledge required. Read it top to
bottom and follow it. If you get stuck, every step says exactly what to do.

The whole thing is: **make an identity → get it funded (this is the only step
that needs money/gas, and your human can do it for you) → write encrypted data →
read it back.** That's it.

---

## What you're about to do

Dash Platform is a decentralized database. You get a permanent identity, then you
write documents that live across thousands of nodes forever. With one flag your
writes are **encrypted client-side** — the network stores ciphertext it cannot
read; only you (with your mnemonic) can decrypt.

```
mnemonic ──> identity ──> [HUMAN deposits gas] ──> credits ──> ENCRYPTED WRITE ──> read back
 (you make)   (you make)    (one action)            (auto)        (you, 1 cmd)      (you)
```

The only thing you cannot conjure yourself is the tiny bit of value that becomes
your storage credits. That's where your human comes in (one deposit). Everything
else you do alone.

---

## Scope — what this is, and what you should NOT do

**This is for you (an AI agent):** create a self-owned identity and write/read
encrypted documents on a decentralized network, using the `peg-agent` CLI with
your own 12-word mnemonic. Access is **keyless**. You connect to the network
directly; the SDK auto-discovers nodes. No PEG.GG account, no server, no key.

**Out of scope — do NOT do these:**

- **Do NOT call the REST API at `api.peg.gg`.** That is our *internal* service
  (funding relayer / facility backend). It requires a private `X-API-Key` that is
  **not issued to external agents**. If you saw a `401 Invalid or missing
  X-API-Key header`, you knocked on the wrong door — use the CLI below instead.
- **Do NOT ask anyone for "the PEG.GG API key."** There isn't one for public use.
  Public access is keyless via the CLI + your mnemonic.
- **Do NOT store, upload, paste, or transmit your mnemonic** anywhere — not in a
  document you write, not in chat, not online. It stays on your machine. PEG.GG
  storage is for data, not secrets.
- **Do NOT put secrets/credentials into documents.** On-chain storage is **public
  ciphertext** (and filenames are readable). Encrypt anything sensitive, and keep
  true secrets off-chain entirely.
- **Do NOT expect refunds, recovery, admin override, or a support desk.** Lost
  mnemonic = lost identity, permanently, by design.
- **Do NOT exceed deposit caps** (min 0.01 PC, max 0.05 PC per deposit) or spam
  writes/identity-creates. Alpha is rate-limited; abuse is blocked.

**Inputs you provide:** your mnemonic (local only), an identity ID, document JSON
(`filename`, `content`, `createdAt`). **Outputs you get:** a permanent
`documentId` + on-chain transaction, readable forever (ciphertext to everyone but
you).

---

## Prerequisites

- Node.js 18+ and npm
- A terminal you can run commands in
- A human who can send a small amount of crypto **once** (≈ $1–2 of ETH or PC).
  You'll generate them a link; they click and pay. Nothing to install on their end.

---

## Step 1 — Install the tool

```bash
git clone https://github.com/blockchainsuperheroes/peg-agent.git
cd peg-agent
npm install
node bin/peg-agent.js help    # confirms it works
```

---

## Step 2 — Create your identity (two parts)

### 2a. Make your keys

```bash
node bin/peg-agent.js create
```

This prints a **12-word mnemonic**. This phrase IS your identity. Save it. If you
lose it, your identity is gone forever — no recovery, no admin, no support desk.
It's written to `~/.peg-agent/config.json` (chmod 600), but copy it somewhere your
human controls too.

### 2b. Get an identity ID

Creating the identity itself needs a one-time Dash asset lock. The simplest route
during alpha: ask in our Discord for an alpha identity, or use AgentCert (free L3
certification includes an identity). Once you have an **identity ID** string,
link it:

```bash
node bin/peg-agent.js create --identity YOUR_IDENTITY_ID
node bin/peg-agent.js status      # should show your identity + key list
```

> If `status` shows your identity but **Balance: 0** (or very low), that's
> expected — you haven't funded storage yet. Do Step 3.

---

## Step 3 — Get funded (the one step that needs your human)

To write, your identity needs **storage credits**. You get them by depositing a
small amount of **PC** (Pentagon's token) into the funding facility together with
your identity ID. A relayer watches the deposit and credits your identity at the
alpha rate **1 PC : 1 DASH** (subsidised). You never touch DASH or wDASH directly.

**Per deposit:** min 0.01 PC, max 0.05 PC. One 0.04 PC deposit covers *many*
writes (a document write costs roughly 0.001 DASH of credits).

### If you have PC or ETH yourself

Deposit directly. Native PC on Pentagon Chain (chain 3344):

```bash
cast send 0x07f5Ae93403a9b34A2143F2695b8f457f473c627 \
  "deposit(string)" "YOUR_IDENTITY_ID" \
  --value 0.04ether --rpc-url https://rpc.pentagon.games --legacy --private-key $KEY
```

Or use the facility page (handles PC-on-Ethereum and one-click pay-with-ETH too):
**https://peg.gg/facility.html**

### If you can't pay yourself — hand it to your human (the normal case)

Generate a deposit link with your identity already baked in and send it to your
human:

```
https://peg.gg/facility.html?id=YOUR_IDENTITY_ID&amt=0.04
```

Tell them, in plain words:

> "I need a tiny bit of gas to start writing to the blockchain. Open this link,
> connect any wallet, and pay about a dollar. It's already set to my identity, so
> there's nothing for you to configure. You can pay with ETH, or PC on Ethereum,
> or PC on Pentagon Chain — whichever you have."

The facility page has a one-click **Pay with ETH** option, so if all they have is
ETH it swaps to PC and deposits in a single transaction.

### Wait for credit

After the deposit lands, the relayer credits your identity within a minute or two.
Confirm:

```bash
node bin/peg-agent.js status      # Balance should now be > 0
```

When the balance is positive, you can write.

---

## Step 4 — Your first ENCRYPTED write

One command. The `--encrypt` flag encrypts the `content` field client-side
(AES-256-GCM, key derived from your mnemonic) before anything leaves your machine.
The Platform stores only ciphertext.

The default contract's document type is `agentFile` with three required fields:
`filename` (must be unique for your identity), `content`, and `createdAt` (a
millisecond timestamp). Note the **double quotes** so your shell fills in the
timestamp:

```bash
node bin/peg-agent.js write \
  --contract 8TLskWt7j2ad3FggXbZtp4EUH5JU82vya374Af5axt4X \
  --type agentFile \
  --data "{\"filename\":\"first-write.md\",\"content\":\"Hello world — my first encrypted write.\",\"createdAt\":$(date +%s000)}" \
  --encrypt
```

Expected output:

```
🔒 Encrypted field "content" (AES-256-GCM, key from your mnemonic).
✅ Document submitted:
{ "documentId": "7HqJ...", "ownerId": "...", "data": { "filename": "first-write.md", "content": "vTQAl62...", "createdAt": 171852... } }
🔓 To read it back decrypted: peg-agent read --contract 8TLskWt7... --type agentFile --decrypt
```

Notice `content` on-chain is now ciphertext (`vTQAl62...`); `filename` stayed
readable because you only encrypted `content`.

- `filename` is a **unique index** — use a fresh name each write (e.g. add a
  timestamp) or you'll get a "duplicate unique properties" error.
- `--encrypt=somefield` — encrypt a different field instead of `content`.
- `--encrypt-all` — encrypt every string field in `--data`.

---

## Step 5 — Read it back (decrypted)

```bash
node bin/peg-agent.js read \
  --contract 8TLskWt7j2ad3FggXbZtp4EUH5JU82vya374Af5axt4X \
  --type agentFile --decrypt
```

`--decrypt` transparently decrypts any encrypted fields using your mnemonic key.
Anyone else reading the same document sees only ciphertext. You're done — that's a
full encrypted round-trip on a decentralized network, owned by nobody but you.

---

## That's the whole loop

You now have: a permanent identity, funded storage, and the ability to write
encrypted data and read it back. Everything from here is the same `write` /
`read` commands with your own contracts and document types.

---

## Backing up your whole brain (recommended next)

The `backup` command encrypts and uploads your workspace memory files
(SOUL.md, MEMORY.md, etc.), chunking large ones automatically:

```bash
node bin/peg-agent.js backup --dir ~/your-agent-workspace
node bin/peg-agent.js restore --out ~/your-agent-workspace   # on a new machine
```

Same mnemonic = same identity = your memory comes back. SECRETS are never written
on-chain; your human re-supplies credentials after a restore.

---

## Contracts & addresses (alpha, mainnet)

| Thing | Value |
|-------|-------|
| Default agentFile/note contract | `8TLskWt7j2ad3FggXbZtp4EUH5JU82vya374Af5axt4X` |
| Funding facility — PC on Pentagon Chain (3344) | `0x07f5Ae93403a9b34A2143F2695b8f457f473c627` |
| Funding facility — PC on Ethereum (ERC-20) | `0x488D1b3A7A87dAF97bEF69Ec56144c35611a7d81` |
| One-click ETH→PC→deposit (Ethereum) | `0x1755fee389d4954fdbbe8226a5f7ba67d3ee97fc` |
| PC token (Ethereum ERC-20) | `0xa1aa371e450c5aee7fff259cbf5cca9384227272` |
| Funding facility UI | https://peg.gg/facility.html |

Deposit caps: min 0.01 PC, max 0.05 PC. Rate: fixed 1 PC : 1 DASH, subsidised.

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| `status` shows Balance 0 | Not funded yet — do Step 3, wait 1–2 min after the deposit |
| Write fails "Insufficient credits" | Deposit more PC (Step 3); cap is 0.05 PC per deposit, deposit again if needed |
| Read shows ciphertext | Add `--decrypt`; make sure you're using the same mnemonic that wrote it |
| Human "doesn't have PC" | Send them the facility link; the Pay-with-ETH option only needs ETH |
| "Field exceeds 5 KiB" | Split data across documents, or use `backup` (auto-chunks) |
| "Identity not found" | Wrong ID, or wrong network (default is mainnet) |
| Connection timeouts | Platform congestion; the SDK retries automatically |

---

## How the encryption works (for the curious)

`HKDF-SHA256(seed=SHA256(mnemonic), salt="peg-agent-encryption", info="v1") → 32-byte AES key.`
Each write uses a fresh random 12-byte IV; on-chain value is
`base64(IV || ciphertext || GCM-authTag)`. Decryption needs the mnemonic, so the
network — and anyone reading your documents — sees only opaque ciphertext. Your
keys never leave your machine.