7.2 KiB
7.2 KiB
natural-language-agreements
Prerequisites
This project depends on the alkahest repository, which must be cloned in the same parent directory.
Setup Instructions
- Clone both repositories in the same parent directory:
# Navigate to your projects directory
cd ~/Desktop # or your preferred location
# Clone the alkahest repository
git clone https://github.com/arkhai-io/alkahest.git
# Clone this repository
git clone https://github.com/arkhai-io/natural-language-agreements.git
# Your directory structure should look like:
# parent-directory/
# ├── alkahest/
# │ └── sdks/
# │ └── ts/
# └── natural-language-agreements/
- Install alkahest dependencies:
cd alkahest
bun install
cd ..
- Install this project's dependencies:
cd natural-language-agreements
bun install
Quick Start
Option 1: Automated Setup (Easiest - 1 command!)
Set your OpenAI API key and run everything:
export OPENAI_API_KEY=sk-your-key-here
nla dev
This will:
- ✅ Check all prerequisites
- ✅ Start Anvil (local blockchain)
- ✅ Deploy all contracts
- ✅ Deploy and distribute mock ERC20 tokens
- ✅ Start the oracle
- ✅ Ready to test!
To stop everything:
nla stop
Note: If you haven't installed the CLI globally yet, run
bun linkfirst, or usebun run cli/index.ts devinstead.
Option 2: Manual Setup (Step by Step)
1. Start Local Blockchain
# Terminal 1: Start Anvil
anvil
2. Deploy Contracts
# Terminal 2: Deploy to localhost
export OPENAI_API_KEY=sk-your-key-here
nla deploy
This creates cli/deployments/localhost.json with all contract addresses.
3. Start Oracle
# Terminal 2 (or 3): Start oracle
nla start-oracle
Watch the oracle terminal - you'll see it process arbitration requests in real-time!
CLI Tools
For a complete guide to the CLI commands, see CLI Documentation.
Quick CLI Examples
# Create an escrow
nla escrow:create \
--demand "The sky is blue" \
--amount 10 \
--token 0xa513e6e4b8f2a923d98304ec87f64353c4d5c853 \
--oracle 0x70997970C51812dc3A010C7d01b50e0d17dc79C8
# Fulfill an escrow
nla escrow:fulfill \
--escrow-uid 0x... \
--fulfillment "The sky appears blue today" \
--oracle 0x70997970C51812dc3A010C7d01b50e0d17dc79C8
# Check escrow status
nla escrow:status --escrow-uid 0x...
# Collect approved escrow
nla escrow:collect \
--escrow-uid 0x... \
--fulfillment-uid 0x...
Deployment to Other Networks
Sepolia Testnet
# 1. Get Sepolia ETH from faucet
# 2. Set your keys
export DEPLOYER_PRIVATE_KEY=0x...
export ORACLE_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 DEPLOYER_PRIVATE_KEY=0x...
export ORACLE_PRIVATE_KEY=0x...
export OPENAI_API_KEY=sk-...
# Deploy
nla deploy mainnet https://mainnet.infura.io/v3/YOUR-KEY
# Start oracle (consider running as a service)
nla start-oracle mainnet
Available Commands
The nla CLI provides unified access to all functionality:
nla dev # Complete local setup (all-in-one)
nla deploy [network] [rpc] # Deploy contracts to network
nla start-oracle [network] # Start oracle for network
nla stop # Stop all services
nla escrow:create [options] # Create a new escrow
nla escrow:fulfill [options] # Fulfill an existing escrow
nla escrow:collect [options] # Collect an approved escrow
nla escrow:status [options] # Check escrow status
nla help # Show help
NPM Scripts (alternative):
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
Monitoring
View Oracle Logs
# If using systemd
sudo journalctl -u nla-oracle -f
# If using nohup
tail -f oracle.log
# If using Anvil
tail -f anvil.log
Check Oracle Status
# Check if oracle is running
ps aux | grep "bun run oracle"
# Check if Anvil is running
lsof -i :8545
Usage
Running Tests
bun test
Development Mode
To run:
bun run index.ts
Development
This project was created using bun init in bun v1.2.20. Bun is a fast all-in-one JavaScript runtime.
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
│ │ ├── fulfill-escrow.ts # Fulfill escrow CLI
│ │ └── collect-escrow.ts # Collect escrow CLI
│ ├── server/ # Server-side components
│ │ ├── deploy.ts # Contract deployment script
│ │ └── oracle.ts # Oracle service
│ ├── scripts/ # Shell scripts for orchestration
│ │ ├── dev.sh # Development environment setup
│ │ ├── deploy.sh # Deployment wrapper
│ │ ├── start-oracle.sh # Oracle starter
│ │ └── stop.sh # Cleanup script
│ └── deployments/ # Deployment addresses (generated)
│ ├── localhost.json
│ ├── sepolia.json
│ └── mainnet.json
├── clients/
│ └── nla.ts # Natural Language Agreement client library
├── tests/
│ ├── nla.test.ts # Basic tests
│ └── nlaOracle.test.ts # Oracle arbitration tests
├── index.ts # Development entry point
├── package.json
└── README.md
Troubleshooting
"Cannot find module 'alkahest-ts'"
- Ensure alkahest is cloned in the parent directory
- Run
bun installin both alkahest and this project
"Deployer has no ETH"
- Fund your deployer account before running deployment
- For testnets, use a faucet
"Oracle not detecting arbitration requests"
- Verify RPC URL is correct and accessible
- Check that EAS contract address matches deployment
- Ensure oracle has ETH for gas
- Check polling interval (try lowering it)
"OpenAI API errors"
- Verify API key is valid and active
- Check OpenAI usage limits and billing
- Ensure model name is correct (e.g., "gpt-4o")
Security Notes
⚠️ Important Security Considerations:
- Never commit your real private keys to version control
- Use environment variables or secure secret management for production
- The
.envfile is gitignored by default - The example private key in
.env.exampleis from Anvil and should NEVER be used in production - Ensure your OpenAI API key is kept secure and not exposed in logs or error messages
- Run the oracle in a secure environment with proper access controls