/protocol/docs

Run it yourself

Clone, configure, deploy to testnet. Full details live in the README and the DEPLOY guide.

1Get the code

shell

git clone --recurse-submodules https://github.com/ketutezraugm/kulaya
cd kulaya

2Setup & test

shell

# 1. contracts
cd contracts
cp .env.example .env     # PRIVATE_KEY (throwaway testnet wallet), AGENT_ADDRESS
forge test               # 33 tests
bash redeploy.sh         # deploy, adapter, seed demo shop, one real loan cycle (writes app/.env.local)

# 2. app + API + bot
cd ../app && npm install
cp .env.example .env.local
npm test                 # 32 tests
npm run dev              # http://localhost:3000 (API under /api)

3Environment (names only)

.env

# secrets (server only, never NEXT_PUBLIC_)
TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET, SESSION_SECRET
UNDERWRITER_PRIVATE_KEY, RELAYER_PRIVATE_KEY
# at least one LLM provider (free tiers, tried in this order)
GROQ_API_KEY, CEREBRAS_API_KEY, MISTRAL_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY
# chain
RPC_URL, WARUNG_ADDRESS, IDRX_ADDRESS, REPUTATION_ADAPTER, ERC8004_REPUTATION_REGISTRY, AGENT_ID, DEPLOY_BLOCK, CHAIN_ID
# app
APP_URL, REDTEAM_MERCHANT, REDTEAM_RATE_LIMIT, KV_REST_API_URL, KV_REST_API_TOKEN
# public (shipped to browsers)
NEXT_PUBLIC_TELEGRAM_BOT, NEXT_PUBLIC_WC_PROJECT_ID, NEXT_PUBLIC_SITE_URL

Repository layout

contracts/	Foundry: Warung.sol, ReputationAdapter.sol, MockIDRX.sol, redeploy.sh
app/app/	owner site (Bahasa) and /protocol (English); app/api/ holds the serverless routes
app/server/	agent, policy layer, reply guard, LLM provider chain, relayer, keeper, Telegram
app/components/art/	the designer's SVG artwork, generated by scripts/build-art.mjs
app/scripts/	seed the demo shop, full loan cycle, gasless and feature end-to-end checks
app/e2e/	Playwright journeys (scripted wallet)

README.md DEPLOY.md github.com/ketutezraugm/kulaya