alkahest-user

# Alkahest User Skill

## What is Alkahest?

Alkahest is an EAS-based (Ethereum Attestation Service) escrow protocol for trustless exchanges on EVM chains. It enables:

- **Token escrow** with programmable release conditions (ERC20, ERC721, ERC1155, native tokens, bundles)
- **Arbiter-based validation** — release conditions are defined by arbiter contracts that check fulfillment
- **Composable demands** — combine multiple conditions with AND/OR logic
- **Oracle arbitration** — off-chain validation with on-chain decision submission
- **Commit-reveal** — frontrunning protection for self-contained fulfillment data

Supported chains: Base Sepolia, Sepolia, Ethereum mainnet.

## Roles

| Role | Description |
|------|-------------|
| **Buyer** | Creates escrow with assets + demand (what they want in return) |
| **Seller** | Fulfills the demand to collect escrowed assets |
| **Oracle** | Validates fulfillment and submits on-chain decisions (for TrustedOracleArbiter) |

## CLI Setup

Install globally via `npm install -g alkahest-cli`, then run commands with:

```bash
alkahest [global-flags] <command> <subcommand> [options]
```

### Authentication

Provide a wallet via one of (in priority order):

| Method | Flag / Env Var |
|--------|---------------|
| Private key flag | `--private-key 0x...` |
| Mnemonic flag | `--mnemonic "word1 word2 ..."` |
| Ledger USB | `--ledger [--ledger-path <path>]` |
| Private key env | `ALKAHEST_PRIVATE_KEY=0x...` |
| Mnemonic env | `ALKAHEST_MNEMONIC="word1 word2 ..."` |
| Compat env | `PRIVATE_KEY=0x...` |

### Global Flags

```
--chain <name>          base-sepolia (default) | sepolia | ethereum
--rpc-url <url>         Custom RPC URL (overrides chain default)
--human                 Human-readable output (default: JSON)
```

### Output Format

JSON by default (ideal for programmatic/agent use). All BigInts are serialized as strings.

```json
{ "success": true, "data": { "hash": "0x...", "uid": "0x..." } }
{ "success": false, "error": { "code": "ESCROW_CREATE_FAILED", "message": "..." } }
```

Use `--human` for labeled, indented output.

## Buyer Workflow: Create Escrow

### 1. Encode the demand

First, encode the demand data that specifies your release condition:

```bash
# Trusted oracle demand — oracle must approve fulfillment
alkahest arbiter encode-demand \
  --type trusted-oracle \
  --oracle 0xORACLE_ADDRESS \
  --data 0x
# Returns: { "success": true, "data": { "encoded": "0x..." } }
```

### 2. Create the escrow

Use the `--arbiter` address and the encoded `--demand` hex from step 1:

```bash
# ERC20 escrow with auto-approve
alkahest --private-key 0xKEY escrow create \
  --erc20 \
  --token 0xTOKEN_ADDRESS \
  --amount 1000000000000000000 \
  --arbiter 0xARBITER_ADDRESS \
  --demand 0xENCODED_DEMAND \
  --expiration 1735689600 \
  --approve

# ERC721 escrow
alkahest --private-key 0xKEY escrow create \
  --erc721 \
  --token 0xNFT_ADDRESS \
  --token-id 42 \
  --amount 0 \
  --arbiter 0xARBITER_ADDRESS \
  --demand 0xENCODED_DEMAND \
  --expiration 1735689600 \
  --approve

# Native token (ETH) escrow — no approve needed
alkahest --private-key 0xKEY escrow create \
  --native \
  --token 0x0000000000000000000000000000000000000000 \
  --amount 500000000000000000 \
  --arbiter 0xARBITER_ADDRESS \
  --demand 0xENCODED_DEMAND \
  --expiration 1735689600
```

Returns `{ "success": true, "data": { "hash": "0x...", "uid": "0x...", ... } }`. Save the `uid` — this is the escrow UID.

### 3. Wait for fulfillment

```bash
alkahest --private-key 0xKEY escrow wait \
  --erc20 --uid 0xESCROW_UID
# Blocks until fulfilled. Returns: { payment, fulfillment, fulfiller }
```

### 4. Reclaim expired escrow (if unfulfilled)

```bash
alkahest --private-key 0xKEY escrow reclaim \
  --erc20 --uid 0xESCROW_UID
```

### 5. Get escrow details

```bash
alkahest --private-key 0xKEY escrow get \
  --erc20 --uid 0xESCROW_UID
```

## Seller Workflow: Fulfill Escrow

### Using StringObligation (off-chain validated work)

```bash
# 1. Create fulfillment referencing the escrow
alkahest --private-key 0xKEY string create \
  --item "Here is my completed deliverable" \
  --ref-uid 0xESCROW_UID
# Returns: { uid: "0xFULFILLMENT_UID", ... }

# 2. If escrow uses TrustedOracleArbiter, oracle arbitrates
alkahest --private-key 0xORACLE_KEY arbiter arbitrate \
  --obligation 0xFULFILLMENT_UID \
  --demand 0xDEMAND_HEX \
  --decision true

# 3. Collect the escrow
alkahest --private-key 0xSELLER_KEY escrow collect \
  --erc20 \
  --escrow-uid 0xESCROW_UID \
  --fulfillment-uid 0xFULFILLMENT_UID
```

### Using barter (token-for-token swap)

```bash
# Create a barter offer: bid ERC20 for ERC20
alkahest --private-key 0xKEY barter create \
  --bid-type erc20 --ask-type erc20 \
  --bid-token 0xBID_TOKEN --bid-amount 1000000000000000000 \
  --ask-token 0xASK_TOKEN --ask-amount 2000000000000000000 \
  --expiration 1735689600 \
  --approve

# Counterparty fulfills the barter
alkahest --private-key 0xCOUNTERPARTY_KEY barter fulfill \
  --uid 0xBARTER_UID \
  --bid-type erc20 --ask-type erc20 \
  --approve
```

Supported barter pairs: `erc20/erc20`, `erc20/erc721`, `erc20/erc1155`. `--permit` is only supported when fulfilling an ERC20 ask.

## Oracle Workflow: Arbitrate

```bash
# Approve a fulfillment
alkahest --private-key 0xORACLE_KEY arbiter arbitrate \
  --obligation 0xFULFILLMENT_UID \
  --demand 0xDEMAND_HEX \
  --decision true

# Reject a fulfillment
alkahest --private-key 0xORACLE_KEY arbiter arbitrate \
  --obligation 0xFULFILLMENT_UID \
  --demand 0xDEMAND_HEX \
  --decision false
```

For auto-arbitration (listening for requests and auto-deciding), use the TypeScript SDK directly — see `references/typescript-sdk.md`.

## Commit-Reveal Workflow

Use commit-reveal when fulfillment data is self-contained (e.g., a string answer) to prevent frontrunning.

```bash
# 1. Compute commitment hash
alkahest --private-key 0xKEY commit-reveal compute-commitment \
  --ref-uid 0xESCROW_UID \
  --claimer 0xSELLER_ADDRESS