natural-language-agreements

Natural Language Agreement Oracle - Create and manage blockchain escrows using natural language demands powered by AI.

Public Demo

A public demo oracle is deployed on Ethereum Sepolia at 0xc5c132B69f57dAAAb75d9ebA86cab504b272Ccbc. You can use this oracle to test escrow creation and fulfillment on the Sepolia testnet without deploying your own oracle.

Table of Contents

• Prerequisites
• Installation
• Quick Start
• CLI Commands
• LLM Providers
• Deployment
• Examples
• Agent Skills

Prerequisites

• Node.js >= 18.0.0 (or Bun)
• Foundry - Ethereum development toolkit (includes Anvil)
• API key for at least one LLM provider (OpenAI, Anthropic, or OpenRouter)

Installation

Option 1: Install from npm (Recommended)

Install the nla CLI globally:

npm install -g nla

Verify installation:

nla help

Option 2: Install from source

# Clone the repository
git clone https://github.com/arkhai-io/natural-language-agreements.git
cd natural-language-agreements

# Install dependencies
bun install  # or: npm install

# Link the CLI globally
bun link     # or: npm link

# Verify installation
nla help

Quick Start

1. Configure API Keys

Create a .env file or export environment variables:

# Required: At least one LLM provider
export OPENAI_API_KEY=sk-your-openai-key
# or
export ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
# or
export OPENROUTER_API_KEY=sk-or-your-openrouter-key

# Optional: Private key for deploying/signing transactions
export PRIVATE_KEY=0x...

2. Start Development Environment

Run the all-in-one setup command:

nla dev

This automatically:

• ✅ Starts Anvil (local blockchain)
• ✅ Deploys all contracts
• ✅ Creates mock ERC20 tokens
• ✅ Starts the oracle listener
• ✅ Displays contract addresses

3. Create Your First Escrow

nla escrow:create \
  --demand "The sky is blue" \
  --amount 10 \
  --token 0xa513e6e4b8f2a923d98304ec87f64353c4d5c853 \
  --oracle 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266

4. Stop Services

nla stop

CLI Commands

Core Commands

Command	Description
nla dev	Start complete local development environment
nla deploy [network] [rpc]	Deploy contracts to a network
nla start-oracle [options]	Start the oracle service
nla stop	Stop all running services
nla help	Display help information

Wallet Management

Command	Description
nla wallet:set --private-key <key>	Save private key to config
nla wallet:show	Show current wallet address
nla wallet:clear	Remove private key from config

Escrow Operations

Command	Description
nla escrow:create [options]	Create a new escrow
nla escrow:fulfill [options]	Submit fulfillment for an escrow
nla escrow:collect [options]	Collect approved escrow funds
nla escrow:status --escrow-uid <uid>	Check escrow status
nla escrow:arbitrate [options]	Manually arbitrate escrow fulfillments

Environment Management

Command	Description
nla switch <env>	Switch between environments
nla network	Show current environment

Available environments: anvil, sepolia, base-sepolia, mainnet

Global Options

Most commands support these options:

Option	Description
--private-key <key>	Private key for signing transactions
--rpc-url <url>	Custom RPC endpoint URL
--deployment <file>	Path to deployment JSON file
--env <file>	Path to .env file
--help, -h	Show command help

Oracle-Specific Options

When starting the oracle:

nla start-oracle [options]

Option	Description
--rpc-url <url>	RPC URL (overrides deployment file)
--private-key <key>	Oracle operator private key
--deployment <file>	Deployment file path
--polling-interval <ms>	Polling interval (default: 5000ms)
--openai-api-key <key>	OpenAI API key
--anthropic-api-key <key>	Anthropic API key
--openrouter-api-key <key>	OpenRouter API key
--perplexity-api-key <key>	Perplexity API key

Example with custom RPC:

nla start-oracle --rpc-url https://eth-mainnet.g.alchemy.com/v2/YOUR-KEY

Escrow Creation Options

nla escrow:create \
  --demand <text> \
  --amount <number> \
  --token <address> \
  --oracle <address> \
  [--arbitration-provider <provider>] \
  [--arbitration-model <model>] \
  [--arbitration-prompt <prompt>] \
  [--private-key <key>]

Option	Required	Description
--demand	Yes	Natural language demand
--amount	Yes	Token amount to escrow
--token	Yes	ERC20 token contract address
--oracle	Yes	Oracle address
--arbitration-provider	No	AI provider (default: OpenAI)
--arbitration-model	No	Model name (default: gpt-4o-mini)
--arbitration-prompt	No	Custom prompt template
--private-key	No	Signer private key

NPM Scripts

If installed from source, you can use npm/bun scripts:

bun run setup              # Same as: nla dev
bun run deploy             # Same as: nla deploy
bun run oracle             # Same as: nla start-oracle
bun run stop               # Same as: nla stop
bun run escrow:create      # Same as: nla escrow:create
bun run escrow:fulfill     # Same as: nla escrow:fulfill
bun run escrow:collect     # Same as: nla escrow:collect

LLM Providers

Supported LLM Providers

The oracle supports multiple AI providers for arbitration:

1. OpenAI (default)

   • Models: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo
   • API Key: Get from OpenAI Platform
   • Environment Variable: OPENAI_API_KEY

2. Anthropic (Claude)

   • Models: claude-3-5-sonnet-20241022, claude-3-opus-20240229, claude-3-sonnet-20240229
   • API Key: Get from Anthropic Console
   • Environment Variable: ANTHROPIC_API_KEY

3. OpenRouter

   • Models: Any model available on OpenRouter (e.g., openai/gpt-4, anthropic/claude-3-opus)
   • API Key: Get from OpenRouter
   • Environment Variable: OPENROUTER_API_KEY

4. Perplexity (for enhanced search)

   • Optional: Enhances LLM responses with real-time search
   • API Key: Get from Perplexity
   • Environment Variable: PERPLEXITY_API_KEY

Examples

Basic Escrow Workflow

# 1. Start development environment
nla dev

# 2. Create an escrow
nla escrow:create \
  --demand "The sky is blue" \
  --amount 10 \
  --token 0xa513e6e4b8f2a923d98304ec87f64353c4d5c853 \
  --oracle 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266

# 3. Fulfill the escrow
nla escrow:fulfill \
  --escrow-uid 0x... \
  --fulfillment "The sky appears blue today" \
  --oracle 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266

# 4. Check status
nla escrow:status --escrow-uid 0x...

# 5. Collect funds (if approved)
nla escrow:collect \
  --escrow-uid 0x... \
  --fulfillment-uid 0x...

Using Different AI Providers

# Create escrow with Anthropic Claude
nla escrow:create \
  --demand "Deliver package by Friday" \
  --amount 100 \
  --token 0xa513e6e4b8f2a923d98304ec87f64353c4d5c853 \
  --oracle 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 \
  --arbitration-provider "Anthropic" \
  --arbitration-model "claude-3-5-sonnet-20241022"

# Create escrow with OpenRouter
nla escrow:create \
  --demand "Write a 1000-word article" \
  --amount 50 \
  --token 0xa513e6e4b8f2a923d98304ec87f64353c4d5c853 \
  --oracle 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 \
  --arbitration-provider "OpenRouter" \
  --arbitration-model "anthropic/claude-3-opus"

Custom RPC and Deployment

# Deploy to custom network
nla deploy \
  --network sepolia \
  --rpc-url https://sepolia.infura.io/v3/YOUR-KEY \
  --private-key 0x...

# Start oracle with custom RPC
nla start-oracle \
  --rpc-url https://eth-mainnet.g.alchemy.com/v2/YOUR-KEY \
  --private-key 0x...

# Use specific deployment file
nla start-oracle --deployment ./my-deployment.json

Wallet Management

# Save private key globally
nla wallet:set --private-key 0x...

# Check current wallet
nla wallet:show

# Clear saved key
nla wallet:clear

Deployment to Other Networks

Sepolia Testnet

# 1. Get Sepolia ETH from faucet
# 2. Set your keys
export PRIVATE_KEY=0x...
export OPENAI_API_KEY=sk-...

# 3. Deploy
nla deploy sepolia https://sepolia.infura.io/v3/YOUR-KEY

# 4. Start oracle
nla start-oracle sepolia

Mainnet

# ⚠️ PRODUCTION - Be careful!
export PRIVATE_KEY=0x...
export OPENAI_API_KEY=sk-...

# Deploy contracts
nla deploy mainnet https://mainnet.infura.io/v3/YOUR-KEY

# Start oracle (consider running as a service)
nla start-oracle --rpc-url https://mainnet.infura.io/v3/YOUR-KEY

Environment Configuration

The CLI uses environment files and a config directory for storing settings:

Environment Variables

Create a .env file in your project root:

# Private Keys
PRIVATE_KEY=0x...                    # For signing transactions

# RPC URLs
RPC_URL=http://localhost:8545        # Default RPC endpoint

# LLM Provider API Keys (at least one required)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
OPENROUTER_API_KEY=sk-or-...
PERPLEXITY_API_KEY=pplx-...          # Optional for search

Config Directory

The CLI stores configuration in ~/.nla/:

• ~/.nla/config.json - Saved wallet private key (via nla wallet:set)
• ~/.nla/environment - Current active environment

Advanced Usage

Using Custom Deployment Files

Create a custom deployment file:

{
  "network": "custom",
  "chainId": 1,
  "rpcUrl": "https://your-rpc.example.com",
  "addresses": {
    "eas": "0x...",
    "trustedOracleArbiter": "0x...",
    "erc20EscrowObligation": "0x..."
  }
}

Use it with commands:

nla start-oracle --deployment ./my-deployment.json
nla escrow:create --deployment ./my-deployment.json ...

Running Oracle as a Service

For production deployments, run the oracle as a systemd service:

[Unit]
Description=NLA Oracle Service
After=network.target

[Service]
Type=simple
User=nla
WorkingDirectory=/home/nla
ExecStart=/usr/bin/nla start-oracle --rpc-url https://mainnet.infura.io/v3/YOUR-KEY
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Multiple Environments

Switch between different networks:

# Switch to sepolia
nla switch sepolia

# Check current environment
nla network

# Switch to mainnet
nla switch mainnet

# Back to local development
nla switch anvil

Troubleshooting

Common Issues

"Private key is required" error:

# Option 1: Set globally
nla wallet:set --private-key 0x...

# Option 2: Export environment variable
export PRIVATE_KEY=0x...

# Option 3: Pass with command
nla deploy --private-key 0x...

"RPC URL not found" error:

# Option 1: Pass RPC URL
nla start-oracle --rpc-url https://...

# Option 2: Set in environment
export RPC_URL=https://...

# Option 3: Use deployment file with rpcUrl
nla start-oracle --deployment ./deployment.json

"No LLM provider API key" error:

# Set at least one provider key
export OPENAI_API_KEY=sk-...
# or
export ANTHROPIC_API_KEY=sk-ant-...

Documentation

For more detailed documentation:

• CLI Documentation - Complete CLI reference
• API Documentation - GitHub repository
• Alkahest SDK - Underlying SDK

Project Structure

natural-language-agreements/
├── cli/                          # CLI tools and server components
│   ├── index.ts                  # Main CLI entry point (nla command)
│   ├── README.md                 # CLI documentation
│   ├── client/                   # User-facing escrow tools
│   │   ├── create-escrow.ts      # Create escrow CLI with arbitration config
│   │   ├── fulfill-escrow.ts     # Fulfill escrow CLI
│   │   └── collect-escrow.ts     # Collect escrow CLI
│   ├── server/                   # Server-side components
│   │   ├── deploy.ts             # Contract deployment script
│   │   └── oracle.ts             # Multi-provider oracle service
│   ├── commands/                 # CLI command implementations
│   │   ├── dev.ts                # Development environment setup
│   │   ├── stop.ts               # Stop services
│   │   ├── switch.ts             # Switch environments
│   │   └── wallet.ts             # Wallet management
│   └── deployments/              # Deployment addresses (generated)
│       ├── anvil.json
│       ├── sepolia.json
│       ├── base-sepolia.json
│       └── mainnet.json
├── skills/                       # Agent skills for AI coding assistants
│   ├── nla-create/               # Escrow creation skill
│   ├── nla-fulfill/              # Escrow fulfillment skill
│   └── nla-arbitrate/            # Manual arbitration skill
├── nla.ts                        # Natural Language Agreement client library
├── tests/                        # Test files
│   ├── nla.test.ts
│   └── nlaOracle.test.ts
├── index.ts                      # Main exports
└── package.json                  # Package configuration

Agent Skills

The skills/ directory contains agent skills for AI coding assistants (Claude Code, OpenClaw, etc.) that can create, fulfill, and arbitrate NLA escrows conversationally.

Available Skills

Skill	Description
nla-create	Create an escrow with a natural language demand
nla-fulfill	Submit fulfillment for an escrow and collect tokens
nla-arbitrate	Manually arbitrate pending escrow fulfillments

Installation

Claude Code (via plugin marketplace)

/plugin marketplace add arkhai-io/claude-plugins
/plugin install nla-plugin@arkhai-plugins

See the arkhai-plugins marketplace for all available plugins.

OpenClaw (via ClawHub)

clawhub install nla-create
clawhub install nla-fulfill
clawhub install nla-arbitrate

Manual

Each skill is a directory under skills/ containing a SKILL.md file. Any agent that supports SKILL.md-based skill definitions can use them directly.

Usage

Once installed, you can ask your agent things like:

• "Create an escrow for 100 tokens with the demand 'Prove the Riemann hypothesis'"
• "Fulfill escrow 0xabc123... with this proof: ..."
• "Check for pending arbitration requests and review them"

The skills require the nla CLI to be installed (npm install -g nla) and a configured wallet.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions:

• GitHub Issues: https://github.com/arkhai-io/natural-language-agreements/issues
• Documentation: CLI README