Alkahest Developer

---
name: alkahest-developer
description: Help developers write code that interacts with Alkahest escrow contracts using the TypeScript, Rust, or Python SDK
---

# Alkahest Developer Skill

## When to Use

Use this skill when a developer wants to write code that interacts with Alkahest escrow contracts. This covers:

- Integrating Alkahest into an application
- Writing bots/agents that create escrows, fulfill obligations, or arbitrate
- Building custom arbiters or obligation contracts
- Understanding SDK patterns and APIs

## SDK Overview

| SDK | Language | Package | Foundation |
|-----|----------|---------|------------|
| TypeScript | TypeScript/JavaScript | `@alkahest/ts-sdk` | viem |
| Rust | Rust | `alkahest-rs` | alloy |
| Python | Python | `alkahest-py` | PyO3 wrapper around Rust SDK |

## Client Setup

### TypeScript

```typescript
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia } from "viem/chains";
import { makeClient } from "@alkahest/ts-sdk";

const walletClient = createWalletClient({
  account: privateKeyToAccount("0xPRIVATE_KEY"),
  chain: baseSepolia,
  transport: http("https://rpc-url"),
});

// Full client with all extensions
const client = makeClient(walletClient);

// Custom addresses (optional)
const client = makeClient(walletClient, customAddresses);

// Minimal client for custom extension patterns
const minimal = makeMinimalClient(walletClient);
const extended = minimal.extend((base) => ({
  custom: makeErc20Client(base.viemClient, pickErc20Addresses(base.contractAddresses)),
}));
```

### Rust

```rust
use alkahest_rs::AlkahestClient;

// Full client with all extensions (Base Sepolia default)
let client = AlkahestClient::with_base_extensions(
    "0xPRIVATE_KEY",
    "https://rpc-url",
    None, // uses Base Sepolia addresses
).await?;

// Custom addresses
use alkahest_rs::{DefaultExtensionConfig, ETHEREUM_SEPOLIA_ADDRESSES};
let client = AlkahestClient::with_base_extensions(
    "0xPRIVATE_KEY",
    "https://rpc-url",
    Some(ETHEREUM_SEPOLIA_ADDRESSES),
).await?;

// Bare client + custom extensions
let bare = AlkahestClient::new("0xPRIVATE_KEY", "https://rpc-url").await?;
let extended = bare.extend::<Erc20Module>(Some(erc20_config)).await?;
```

### Python

```python
from alkahest_py import PyAlkahestClient

# Full client with all extensions (Base Sepolia default)
client = PyAlkahestClient("0xPRIVATE_KEY", "https://rpc-url")

# Custom addresses
from alkahest_py import DefaultExtensionConfig, PyErc20Addresses, ...
config = DefaultExtensionConfig(erc20_addresses=..., ...)
client = PyAlkahestClient("0xPRIVATE_KEY", "https://rpc-url", config)
```

## Core Patterns

### Creating an Escrow

**TypeScript:**
```typescript
// 1. Approve token
await client.erc20.util.approve({ address: TOKEN, value: amount }, "escrow");

// 2. Create escrow
const { hash, attested } = await client.erc20.escrow.nonTierable.doObligation(
  client.erc20.escrow.nonTierable.encodeObligationRaw({
    token: TOKEN, amount, arbiter: ARBITER, demand: DEMAND_BYTES,
  }),
);
const escrowUid = attested.uid;
```

**Rust:**
```rust
// 1. Approve
client.erc20().approve(&Erc20Data { address: token, value: amount }, ApprovalPurpose::Escrow).await?;

// 2. Create escrow
let receipt = client.erc20().escrow().non_tierable().make_statement(
    token, amount, arbiter, demand_bytes, expiration,
).await?;
let attested = client.get_attested_event(receipt)?;
```

**Python:**
```python
# 1. Approve
await client.erc20.util.approve(token_address, amount, "escrow")

# 2. Create escrow
uid = await client.erc20.escrow.non_tierable.create(
    token=token_address, amount=amount,
    arbiter=arbiter_address, demand=demand_bytes,
    expiration=expiration,
)
```

### Fulfilling with StringObligation

**TypeScript:**
```typescript
const { attested } = await client.stringObligation.doObligation(
  "fulfillment content",
  undefined,  // schema
  escrowUid,  // refUID
);
```

**Rust:**
```rust
let receipt = client.string_obligation().do_obligation(
    "fulfillment content", None, Some(escrow_uid),
).await?;
```

**Python:**
```python
uid = await client.string_obligation.do_obligation(
    "fulfillment content",
    ref_uid=escrow_uid,
)
```

### Collecting Escrow

**TypeScript:**
```typescript
const { hash } = await client.erc20.escrow.nonTierable.collectObligation(
  escrowUid,
  fulfillmentUid,
);
```

**Rust:**
```rust
let receipt = client.erc20().escrow().non_tierable().collect_payment(
    escrow_uid, fulfillment_uid,
).await?;
```

**Python:**
```python
tx_hash = await client.erc20.escrow.non_tierable.collect(escrow_uid, fulfillment_uid)
```

### Waiting for Fulfillment

**TypeScript:**
```typescript
const result = await client.waitForFulfillment(
  client.contractAddresses.erc20EscrowObligation,
  escrowUid,
);
```

**Rust:**
```rust
let log = client.wait_for_fulfillment(
    client.erc20_address(Erc20Contract::EscrowObligation),
    escrow_uid,
    None, // from_block
).await?;
```

**Python:**
```python
result = await client.wait_for_fulfillment(
    escrow_contract_address,
    escrow_uid,
)
```

### Encoding Demands

**TypeScript:**
```typescript
// Trusted oracle
const demand = client.arbiters.general.trustedOracle.encodeDemand({
  oracle: ORACLE, data: "0x",
});

// Logical composition
const demand = client.arbiters.logical.all.encodeDemand({
  arbiters: [ARBITER_A, ARBITER_B],
  demands: [DEMAND_A, DEMAND_B],
});

// Attestation properties
const demand = client.arbiters.attestationProperties.attester.encodeDemand({
  attester: REQUIRED_ATTESTER,
});
```

**Rust:**
```rust
// Trusted oracle (ABI encoding)
use alloy::sol_types::SolValue;
let demand = TrustedOracleArbiter::DemandData { oracle, data: Bytes::new() }.abi_encode();

// Decode arbiter demand (auto-detects)
let decoded = client.arbiters().decode_arbiter_demand(arbiter_addr, &demand_bytes)?;
```

**Python:**
```python
# Trusted oracle
demand = client.arbiters.trusted_oracle.encode_demand(oracle=ORACLE, data=b"")

# Logical composition
demand = client.arbiters.logical.all.encode(
    arbiters=[ARBITER_A, ARBITER_B],
    demands=[DEMAND_A, DEMAND_B],
)
```

### Commit-Reveal Pattern

**TypeScript:**
```typescript
// 1. Compute commitment
const commitment = await client.commitReveal.computeCommitment(
  escrowUid, claimerAddress, { payload, salt, schema },
);
// 2. Commit (sends bond as ETH)
await client.commitReveal.commit(commitment);
// 3. Wait 1+ blocks, then reveal
const { attested } = await client.commitReveal.doObligation(
  { payload, salt, schema }, escrowUid,
);
// 4. Reclaim bond
await client.commitReveal.reclaimBond(attested.uid);
```

**Rust:**
```rust
let commitment = client.commit_reveal().compute_commitment(
    escrow_uid, claimer, &obligation_data,
).await?;
client.commit_reveal().commit(commitment).await?;
// wait 1+ blocks
let receipt = client.commit_reveal().do_obligation(&obligation_data, Some(escrow_uid)).await?;
client.commit_reveal().reclaim_bond(obligation_uid).await?;
```

**Python:**
```python
commitment = await client.commit_reveal.compute_commitment(
    escrow_uid, claimer, payload, salt, schema,
)
await client.commit_reveal.commit(commitment)
# wait 1+ blocks
uid = await client.commit_reveal.do_obligation(payload, salt, schema, ref_uid=escrow_uid)
await client.commit_reveal.reclaim_bond(uid)
```

## Barter Utilities

Barter utils provide atomic single-transaction token swaps:

**TypeScript:**
```typescript
await client.erc20.barter.buyErc20ForErc20(
  { address: BID_TOKEN, value: bidAmount },
  { address: ASK_TOKEN, value: askAmount },
  BigInt(Math.floor(Date.now() / 1000) + 3600),
);
```

**Rust:**
```rust
client.erc20().barter().buy_erc20_for_erc20(
    &bid_token, &ask_token, expiration,
).await?;
```

## Key Type Differences

| Concept | TypeScript | Rust | Python |
|---------|-----------|------|--------|
| Addresses | `` `0x${string}` `` | `Address` | `str` (hex) |
| Big integers | `bigint` | `U256` | `str` (decimal) |
| Bytes | `` `0x${string}` `` | `Bytes` / `FixedBytes<32>` | `bytes` / `str` (hex) |
| Receipts | `{ hash, attested }` | `TransactionReceipt` | `str` (tx hash or uid) |
| Attestations | `Attestation` object | `IEAS::Attestation` | `PyAttestation` |

## Reference Documentation

- `references/typescript-api.md` — full TS SDK API tree
- `references/rust-api.md` — full Rust SDK API tree
- `references/python-api.md` — full Python SDK API tree
- `references/contracts.md` — contract addresses and data schemas
- `docs/Escrow Flow (pt 1).md` — token trading walkthrough
- `docs/Escrow Flow (pt 2).md` — oracle arbitration walkthrough
- `docs/Escrow Flow (pt 2b).md` — commit-reveal frontrunning protection
- `docs/Escrow Flow (pt 3).md` — composing demands with logical arbiters
- `docs/Writing Arbiters/` — custom arbiter development
- `docs/Writing Contracts/` — custom escrow/obligation development
- `docs/mcp-server/` — MCP server for looking up contract details