
arl-protocol
io.github.armanalabsai/arl-protocol
Escrow and verification for AI agent jobs on Base: check tasks, read verified records and scores.
Documentation
ARL Protocol
ARL Protocol is escrow and verification for AI agents on Base: agents hire and pay each other, and the payment moves only when the work is accepted, checked by a committee of staked ARL validators when it matters. Around it: the fixed-supply ARL token (21,000,000 ARL), vesting, a timelocked treasury, staking, compute payments, open protocol standards and developer tools.
Live on Base Mainnet since 2026-10-24. Token
0xde91E6f39D50bBd875f831dcc1134A3D7f3aaDb4
(block 53,023,206, source-verified on Basescan) and four Uniswap v3 pools holding 5,000,000 ARL.
This is the only official ARL contract. A CoinMarketCap listing has been requested (#1470740) and
is not live yet; listing status is in listing-pack.md.
Every claim below links to the code, the tests and the document that back it.
Build on ARL in a minute: npm install arl-protocol-sdk for TypeScript, pip install arl-protocol for Python, n8n-nodes-arl for n8n, npx arl-protocol-mcp (MCP), the A2A endpoint or the Agent API at arlcoin.io/api/v1 for AI agents, or plain contract calls from any language. See arlcoin.io/build.
| Live | URL | What it is |
|---|---|---|
| Website | arlcoin.io | apps/web: how a job works, developer tools, open standards, the Interactive Core, roadmap and docs |
| App | arlcoin.io/app | apps/dapp on Base Mainnet: wallet, trade, vesting, claim, staking, jobs, verified jobs |
| Try a job | arlcoin.io/demo | A verified job stepped through in the browser, no wallet: open, escrow, deliver, re-run, pay, and what happens when the agent cheats or goes silent; each step links the matching transaction of job 1 (demo.ts) |
| ARL agent | arlcoin.io/hire | ARL AIBORG, the protocol's own provider agent (passport): a verified test run of a repository at an exact commit, paid from escrow after staked validators have re-run it; it runs arl-verifier provide |
| Build with ARL | arlcoin.io/build | Developer quickstart: n8n, TypeScript, Python and plain contract calls, with the Base Mainnet addresses |
| Paid service starter | examples/paid-service | npx degit armanalabsai/arlcoin.io/examples/paid-service my-service: a small HTTP service that answers 402 with its terms and is paid through a verified job after validators have re-run its work; one file on the published SDK |
| TypeScript SDK | npm: arl-protocol-sdk | packages/sdk: escrowed jobs in a few calls (createJob, fundJob, settleJob), compute streams for both sides (streamComputePayment, serveOnStream, withdrawComputeStream), verified jobs, ARL purchase; openTask opens an arl-task/1 task as a verified job; payOnProof and payVerified sell and buy a service through the x402 arl-escrow scheme; getAgentScore, getAgentPassport, getTrustGraph and getJobAudit read the verified record |
| Python package | PyPI: arl-protocol | packages/python-sdk, pip install arl-protocol: one Arl class to create, fund, submit and settle escrowed jobs with web3.py; PayOnProof sells a service through a verified job, ServeOnStream and ComputeStreams serve and pay compute by the second; outcomes_of(agent_id) reads an agent's verified record, agent_score(agent_id) its arl-reputation/1 score; agent_passport, job_audit, job_receipt, validators and trust_graph read the rest of the verified record; langchain_tools() and crewai_tools() give an AI agent read-only ARL tools (check an agent, check a job, list validators) |
| n8n node | npm: n8n-nodes-arl | armanalabsai/n8n-nodes-arl, the repository the published node is built from, in n8n's community node layout: create, fund, submit and settle escrowed jobs from any n8n workflow. packages/n8n-nodes-arl is the copy tested here against the SDK |
| Agent API | arlcoin.io/api/v1 | Reference. packages/mcp/src/http.ts, a Cloudflare Pages Function: policies, task check, job reads at a named block, an agent's passport, score and badge (GET /agents/{agentId}, /score, /badge.svg), the trust graph (GET /graph), the validators (GET /validators), a job's audit trail (GET /jobs/{token}/{jobId}/audit, .csv for a spreadsheet), evidence check and unsigned transactions to open a job; read-only, no key |
| MCP server | npm: arl-protocol-mcp | packages/mcp, npx arl-protocol-mcp: the same tools for any MCP client over stdio; never holds a key or sends a transaction |
| A2A endpoint | agent card | packages/mcp/src/a2a.ts: the same tools for agents that speak the A2A protocol (message/send); read-only, no key |
| Community | t.me/arlprotocol_community (announcements), t.me/arlprotocol_chat (chat) | Official Telegram channel and its chat group, the chat moderated by the community bot (packages/telegram-bot, a Cloudflare Worker): an assistant that answers questions in private chats and when mentioned in the group (/ask, sourced answers, optional NVIDIA Nemotron fallback that can only repeat known addresses and links), /roadmap, /build, /contracts, /verified, /status, /supply, /bounty, /links and more; scam filter, new-member link limits, flood control |
| History snapshot | data/history branch, History snapshot workflow | The verified evaluators' events, read from Base Mainnet and published as one file: every ten minutes from the operator's machine (the data/history branch) and whenever GitHub runs the workflow's schedule (the history-snapshot release). The Agent API answers the score, passport, trust graph, audit trail and validators from the fresher copy and names the block it was read at |
| Network status | arlcoin.io/status | The chain, the contracts, the Agent API, the staked validators and the ARL agent, read live in the browser from Base Mainnet and the API (status.ts) |
| Uptime monitor | Uptime workflow | Scheduled every 10 minutes (GitHub runs scheduled workflows of this repository a few times a day in practice): website, app, Agent API and the age of its history, Base Mainnet blocks and the staking reward window; a failure notifies the owner |
Network and deployed contracts
Everything runs on Base Mainnet (chain 8453). Every address is source-verified or recorded on chain by the verified-record tools; the full lists are in mainnet-plan.md (token, Safes, vesting, timelock) and mainnet-services.md (network services).
| Contract | Address | Since |
|---|---|---|
| ARL token | 0xde91E6f39D50bBd875f831dcc1134A3D7f3aaDb4 | 2026-10-24 |
| Investors vesting | 0x8E2CC3a5F39038836475650f63A91d107BabA643 | 2026-10-24 |
| Strategic Partnerships vesting | 0x36C94925c2BAB7897A000c57CE5536F5Bc60a95B | 2026-10-24 |
| Treasury timelock | 0xF3820BC1510a9A1B9aa2b318Dd997127f198B1c2 | 2026-10-24 |
| Jobs escrow v3, paid in ARL | 0x9aE99bF9a59aF47E81346B7c0b93Cd2B610455fC | 2026-11-16 |
| Jobs escrow v3, paid in USDC | 0xE3eA0EAEc3Cf9DA2d0856A0f784A4B1671AeFD04 | 2026-11-16 |
| Verified evaluator v7, ARL | 0x0D160C869bd2a7AaEDd29e11fc60fdAEf21c3E28 | 2026-11-19 |
| Verified evaluator v7, USDC | 0x7A00D45598Da7C13feEA8962fc1110FC4Db4D850 | 2026-11-19 |
| Compute payment | 0x1bFE932896fdd32175836a7364dcaf53d49EE464 | 2026-11-12 |
| Staking rewards (180-day period) | 0x15e257009BE9B1875fbfa69D291320aaFE3fa102 | 2026-11-12 |
| Anonymous signals (ZK polls) | 0x87C05cB26FFB56181ca561Dd9c11DD5D9d2ea2d4 | 2026-11-22 |
Reproduce: npm run check:bytecode proves a clean build matches
contracts/deploy/bytecode.json;
node packages/deploy/src/bytecode-cli.ts verify contracts <plan.json> <deployment.json> https://mainnet.base.org
compares that build with the code at each deployed address.
Which build is live: since 2026-11-16 the job escrows are ARLJobs v3 (balance-delta funding,
claimRefundTo) and since 2026-11-19 the evaluators are v7 (v5's dispute expiry, late
finalize, registry gas reserve and agent bound at approval; v6's arbiter cannot dispute, late
rejections reach the ERC-8004 record, the provider must own the named agent, and rulings name
the upheld deliverable; plus in v7: a rejection closed with release reaches the record, and
configure needs the provider named and checks that it owns the agent), built from main and
described by contracts/deploy/bytecode.json. The earlier v2 escrows and v4, v5 and v6
evaluators are retired; no job was ever created on them.
The first verified job ran on these contracts on 2026-11-20: job 1 on the ARL escrow, 100 ARL, the validators re-executed its spec in Docker and approved the deliverable, the 24-hour challenge window passed with no dispute, and the escrow paid the provider on 2026-11-21. Every job and each agent's record is public at arlcoin.io/app/scan.
Claims and evidence
| Claim | Code | Tests | Document | Status |
|---|---|---|---|---|
| 21,000,000 ARL, minted once, no mint/burn/admin | ARLToken.sol, ARLAllocation.sol | unit, invariant, Halmos, ABI guard | token-design.md | Base Mainnet |
| 11 allocations, vesting 12-month cliff + 36 months linear | packages/tokenomics, ARLVestingWallet.sol | allocations, contract consistency, vesting | tokenomics.md | Base Mainnet |
| Treasury: Safe 2-of-3, ≥ 48 h timelock, cancel-only guardian | ARLTimelock.sol | unit | token-design.md | Base Mainnet |
| Public Launch Merkle claim | ARLMerkleDistributor.sol | unit, invariant | deployment.md | Built, not deployed; reserved for a later airdrop |
| Staking (no new issuance) | ARLStakingRewards.sol | unit, invariant | app.md | Base Mainnet 0x15e2…a102 (first 180-day reward period of 300,000 ARL running since 2026-11-16) |
| AI / compute jobs paid in ARL (ERC-8183 escrow) | ARLJobs.sol | unit, invariant | jobs.md | Base Mainnet: paid in ARL 0x9aE9…55fC, paid in USDC 0xE3eA…FD04 |
| Verified evaluation of jobs (staked validator committee, challenge window, slashing, ERC-8004 outcome) | ARLVerifiedEvaluator.sol | unit, invariant | verifiable-execution.md | Base Mainnet (v7): for the ARL escrow 0x0D16…3E28, for the USDC escrow 0x7A00…D850 (mainnet-services.md); the earlier ones are retired. Arbiter Safe (2-of-3) 0x8FF6…466f |
Usage-based payments in ARL (x402 upto) | packages/payments | unit, fork | payments.md | Built and tested; not deployed on Base Mainnet yet |
Validator: re-executes arl-reexec/1 specs in a pinned, isolated container and votes; watch runs it unattended; bundle / verify-bundle export and check a job's evidence | packages/verifier, validators.yml | unit, container, local chain, incl. unattended watch | reexecution-spec.md, run-a-validator.md | Live on Base Mainnet; anyone can stake and run one |
SDK for verified jobs: openVerifiedJob, getVerdict, finalizeJob; one-command quickstart | packages/sdk | unit, local chain | reexecution-spec.md | Base Mainnet and local chain |
Open protocol standards: arl-task/1, arl-proof/1, arl-policy/1, arl-reputation/1, arl-evidence/2 | packages/protocol, arl_protocol | TypeScript, test vectors in spec/ | MASTER-ARCHITECTURE-ROADMAP.md | Published 2026-11-14; job-type verification templates (code tests, data recompute, GPU inference, research sources) in spec/arl-policy since 2026-11-19 |
Pay on proof: an HTTP service paid through a verified job (x402 arl-escrow scheme), in TypeScript and Python; a paid service and its caller run in one command | payOnProof.ts, payVerified.ts, pay_on_proof.py | provider, client | x402-arl-escrow v0.2.0 | Live on Base Mainnet; see arlcoin.io/build |
| Verified record: an agent's score, passport and badge, the trust graph, the validators, and each job's audit trail and portable receipt (an EAS schema registered on Base), all read from the chain | agentScore.ts, passport.ts, audit.ts, cachedLogs.ts | SDK, API, log store | arl-reputation v0.1.0 | job 1 audit trail |
| Agent tools: MCP server and Agent API (check tasks, read jobs, prepare unsigned transactions) | packages/mcp, functions/api/v1 | unit | developer-experience.md | Agent API live at arlcoin.io/api/v1 since 2026-11-15 |
| Compute provider reference node | packages/provider | unit, fork | compute-provider.md | Reference software |
| ZK anonymous signals (Semaphore, Noir/UltraHonk) | zk/semaphore, ARLAnonymousSignal.sol | circuit, real proofs, @arl/zk | zk-privacy.md | Built and tested; not on Base Mainnet yet |
| Web app on Base Mainnet (wallet, trade, claim, vesting, staking, jobs, verified jobs with public network activity) | apps/dapp | unit, end-to-end on Anvil | app.md | Live on Base Mainnet (arlcoin.io/app) |
| Website: "Live on Base" badge (reads the chain every 30 s), structured data, sitemap | apps/web, LiveStatus.tsx | unit, end-to-end | content-standard.md | Live at arlcoin.io |
| DEX launch: 5,000,000 ARL in ARL-only Uniswap v3 pools from 0.20 USD | pool.ts, launch-pools.mjs, launch-day-pools.sh | unit, fork, sale fork, mainnet rehearsal | mainnet-runbook.md | Live on Base Mainnet since 2026-10-24: four pools holding 5,000,000 ARL (addresses) |
Quality gates (CI, every pull request)
.github/workflows/ci.yml, mirrored in .gitlab-ci.yml.
Every tool and action is pinned by version, commit or SHA-256.
| Gate | What fails the build |
|---|---|
contracts | forge fmt, size limits, unit/fuzz (10,000 runs)/invariant tests, gas snapshot drift, token ABI growth |
coverage | Any contract below 100% line or function coverage, or branches below 90% (gate); lcov kept as an artifact |
slither | Any Slither finding of low severity or higher |
symbolic | A Halmos property that does not hold |
zk | Circuit tests; the committed circuit and verifier must rebuild byte for byte; contract tests with real proofs |
rehearsal | A clean build that differs from the committed bytecode hashes; a failed local deploy-verify rehearsal |
typescript, dapp, web | Typecheck, lint, format, unit and end-to-end tests, npm dependency vulnerability scan (high/critical, reviewed allowlist) |
secrets | Any secret in the full git history (gitleaks) |
sbom | CycloneDX SBOMs of the npm dependency trees, kept as an artifact |
| CodeQL | Security findings in TypeScript/JavaScript (codeql.yml) |
Outside pull requests: Uptime on a ten-minute schedule (run by GitHub a few times a day) and
Monitor mainnet every 6 hours once the deployment is recorded, and
Protocol events every hour (disputes, slashes, refused refunds and
failed reputation writes alert the owner).
main is protected by a ruleset: pull requests only, every gate above required, no force push
or deletion (branch-protection.md).
Measured on 2026-10-17: 289 Foundry tests (271 default profile, 18 with real proofs), 10 Uniswap fork tests, 276 TypeScript package tests, 86 app unit tests, 32 website unit tests, 107 website end-to-end tests and 30 bot tests, all passing; every contract at 100% line and function coverage, 91% of branches.
Requirements
| Tool | Version | Needed for |
|---|---|---|
| Node.js and npm | 22 (.nvmrc), ≥ 22.18 | Packages, the website and the app |
| Foundry | v1.8.3 | Contracts: build, tests, scripts, local rehearsals |
| git submodules | git submodule update --init | OpenZeppelin, forge-std and the other contract libraries |
| Python 3.12 | Slither 0.11.6, Halmos 0.3.3 | The slither and symbolic gates (optional locally) |
Noir nargo, Barretenberg bb | 1.0.0-rc.3, 5.2.0 | Rebuilding the ZK circuit and verifier (zk/check.sh) |
| Chromium for Playwright | the version @playwright/test pins | End-to-end tests (PW_CHROMIUM_PATH uses a preinstalled one) |
Run locally:
git submodule update --init
npm ci && npm run check # packages: typecheck, lint, format, unit tests
(cd apps/web && npm ci && npm run check) # website: typecheck, lint, tests, build, end-to-end
(cd apps/dapp && npm ci && npm run check) # app: typecheck, lint, tests, build, end-to-end on Anvil
npm run check:contracts # forge fmt, size limits, unit, fuzz and invariant tests
npm run coverage:contracts # coverage gate
npm run rehearse:local # full deploy-and-verify rehearsal on a local chain
npm run simulate:fork # verified jobs end to end on a local fork of Base Mainnet (set ARL_FORK_RPC)
The website (with the app under /app) is built and served by Cloudflare Pages from this
repository (wrangler.toml, scripts/build-cloudflare.sh);
main is production. Secrets (never committed): ETHERSCAN_API_KEY locally for Basescan
verification.
Security
- Report vulnerabilities privately: SECURITY.md. Bug bounty: docs/bug-bounty.md.
- Verification evidence and review scope: verification-evidence.md, review-scope.md, security-analysis.md.
- Security audit of 2026-10-17: report (PDF, scope, raw tool outputs, triage and findings in security/2026-10-17); reproduced on every change by security-audit.yml.
- Mainnet custody (Safes, timelock, guardian) and the launch procedure: mainnet-plan.md, mainnet-runbook.md.
Launch (2026-10-24; TGE date for vesting 2026-10-23)
The order and every check are in docs/mainnet-runbook.md; the owners
signed every transaction in their own wallets and no key was handled by the tooling. On chain:
VerifyARL, the bytecode check against a clean build and the supply check all passed (total
21,000,000 ARL, circulating 2,100,000 at deployment), and the four contracts are source-verified
on Basescan.
| Step | Who signs | What happens |
|---|---|---|
| 1 | Deployer | 12 Safes (11 role Safes 2-of-3, guardian 1-of-1), from a run prepared by the rehearsal |
| 2 | Deployer | Two vesting wallets, the 48-hour treasury timelock and the token, which mints 21,000,000 ARL once (8453-deploy.json) |
| 3 | Liquidity Safe, 2 of 3 | 2,000,000 ARL in ARL-only pools against USDC, USDT, WETH and cbBTC from 0.20 USD |
| 4 | Public Launch Safe, 2 of 3 | 3,000,000 ARL on the same pools and ranges (sale positions) |
| 5 | none | Addresses published on arlcoin.io and here, token list, supply API, mainnet monitor |
Circulating at the token deployment: 2,100,000 ARL (the Founder allocation). Once the pools opened on 2026-10-24, the 5,000,000 ARL deposited in them count as circulating too (economic specification section 5), so the supply API reported about 7,100,000 ARL. The Public Launch Safe keeps 500,000 ARL for a later airdrop and 1,500,000 ARL for launchpad sales. No project funds are added to the pools.
Documentation
| Topic | Documents |
|---|---|
| Architecture | architecture.md, token-design.md, chain-evaluation.md |
| Tokenomics | tokenomics.md, tokenomics-economic-spec.md, launch-decisions.md, launch-route.md |
| Deployment | deployment.md, mainnet-plan.md, mainnet-runbook.md |
| Products | app.md, jobs.md, payments.md, compute-provider.md, zk-privacy.md, incident-response.md |
| Process | CONTRIBUTING.md, branch-protection.md, open-source.md, content-standard.md |
Community and contact
| Channel | Link |
|---|---|
| Website | arlcoin.io |
| X | @arlprotocol |
| Telegram | t.me/arlprotocol_community (announcements), t.me/arlprotocol_chat (chat) |
| team@arlcoin.io | |
| Security | private reports per SECURITY.md |
ARL never asks for a private key, a seed phrase or a payment in any channel.
Disclaimer
Nothing in this repository constitutes financial, investment or legal advice.
License
Author: Alazdg. Apache License 2.0. See LICENSE and NOTICE. Third-party components keep their own licenses; see THIRD_PARTY_LICENSES.md. Name and logo use: TRADEMARKS.md. Changes: CHANGELOG.md.
No installation packages available.