alkahest-developer

Help developers write code that interacts with Alkahest escrow contracts using the TypeScript, Rust, or Python SDK

Quality

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Medium

Suggest reviewing before use

Fix and improve this skill with Tessl

tessl review fix ./vendored/arkhai/alkahest-developer/SKILL.md

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

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

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

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:

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

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

Rust:

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

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

Python:

# 1. Approve
await client.erc20.util.approve(token_address, amount, "escrow")

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

Fulfilling with StringObligation

TypeScript:

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

Rust:

let receipt = client.string_obligation().do_obligation(
    "fulfillment content", None, Some(escrow_uid),
).await?;

Python:

uid = await client.string_obligation.do_obligation(
    "fulfillment content",
    ref_uid=escrow_uid,
)

Collecting Escrow

TypeScript:

const { hash } = await client.erc20.escrow.default.collectObligation(
  escrowUid,
  fulfillmentUid,
);

Rust:

let receipt = client.erc20().escrow().default().collect_payment(
    escrow_uid, fulfillment_uid,
).await?;

Python:

tx_hash = await client.erc20.escrow.default.collect(escrow_uid, fulfillment_uid)

Waiting for Fulfillment

TypeScript:

const result = await client.waitForFulfillment(
  client.contractAddresses.erc20EscrowObligation,
  escrowUid,
);

Rust:

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

Python:

result = await client.wait_for_fulfillment(
    escrow_contract_address,
    escrow_uid,
)

Encoding Demands

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:

// 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:

# 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:

// 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, bondAmount, commitDeadline);
// 3. Wait 1+ blocks, then reveal. The matching bond is reclaimed on reveal.
await client.commitReveal.doObligation(
  { payload, salt, schema }, escrowUid,
);

Rust:

let commitment = client.commit_reveal().compute_commitment(
    escrow_uid, claimer, &obligation_data,
).await?;
client.commit_reveal().commit(commitment, bond_amount, commit_deadline).await?;
// wait 1+ blocks; the matching bond is reclaimed on reveal
let receipt = client.commit_reveal().do_obligation(&obligation_data, Some(escrow_uid)).await?;

Python:

commitment = await client.commit_reveal.compute_commitment(
    escrow_uid, claimer, payload, salt, schema,
)
await client.commit_reveal.commit(commitment, bond_amount, commit_deadline)
# wait 1+ blocks; the matching bond is reclaimed on reveal
uid = await client.commit_reveal.do_obligation(payload, salt, schema, ref_uid=escrow_uid)

Atomic Payment Utilities

Atomic payment utilities provide single-transaction payment and collection for existing escrows:

TypeScript:

await client.erc20.payment.payErc20AndCollect(escrowUid);

Rust:

client.erc20().payment().pay_erc20_and_collect(escrow_uid).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/website/Escrow Flow/Token Trading.mdx — token trading walkthrough
docs/website/Escrow Flow/Job Trading.mdx — oracle arbitration walkthrough
docs/drafts/Escrow Flow (pt 2b - Frontrunning Protection).md — commit-reveal frontrunning protection
docs/website/Escrow Flow/Composing Demands.mdx — composing demands with logical arbiters
docs/website/Writing Arbiters/ — custom arbiter development
docs/website/Writing Escrow Contracts.md and docs/website/Writing Fulfillment Contracts.md — custom escrow/obligation development
docs/mcp-server/ — MCP server for looking up contract details

Repository: internet-court/internet-court-skill
Path: vendored/arkhai/alkahest-developer/SKILL.md
Commit: fa89195

Last updated: 4 days ago
First committed: 2 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.