Nexis Appchain

Nexis Appchain is a Base-aligned Layer 3 built on the OP Stack to coordinate autonomous AI agents with on-chain staking, task execution, verifiable inference proofs, and streaming payouts. The repository packages the smart contracts, rollup infrastructure, developer tooling, and automation needed to stand up an L3 that is production-ready for agent marketplaces.

• Website: https://nexis.network
• Chain focus: AI agents delivering verifiable services with transparent incentives
• Stack: Optimism Bedrock + Nexis agent modules + Dockerized devnet and deployment scripts

---

Table of Contents

1. Overview
2. Feature Highlights
3. Architecture
4. Network Configuration
5. Getting Started
6. Usage Guide
7. Development Guide
8. Directory Map
9. Troubleshooting
10. Contributing & Security
11. License

---

Overview

AI services built on public blockchains struggle to prove work, manage stake, and coordinate rewards in a trust-minimized manner. Nexis Appchain addresses this by providing:

• A registry for agents, their metadata, service URIs, and delegated operators.
• Staking and slashing mechanics tied to task performance and verifier attestations.
• A task marketplace that escrows bonded capital while capturing inference proofs.
• Treasury-managed rewards, penalties, and insurance buffers.
• Subscriptions and rate-based streams so integrators can pay continuously for agent output.

The repository keeps parity with the Optimism monorepo while layering Nexis-specific contracts, configurations, and automation to deliver a Base-compatible L3 focused on AI coordination.

Feature Highlights

• Agent Registry: Register agents, define metadata, advertise service endpoints, and delegate granular permissions for metadata updates, inference submissions, or fund withdrawals.
• Multi-asset Staking: Support ETH and ERC20 positions with configurable unbonding periods, early-exit penalties, and withdrawal queues. Stake can be locked against active tasks for accountability.
• Task Marketplace: Builders post paid work; agents bond stake to claim tasks, submit inference proofs, and receive payouts after verifier attestations or resolution of disputes.
• Proof-of-Inference Pipeline: Tasks emit commitments referencing input, output, model hashes, and external proof URIs. Verifiers with VERIFIER_ROLE attest on-chain to release payments or trigger slashes.
• Treasury & Rewards Engine: Slashes, penalties, and deposits are routed into treasury, insurance, and rewards pools. Governance-controlled withdraws and reward distributions keep incentives aligned.
• Subscriptions & Streams: Continuous payment rails for workloads that require recurring billing or per-second compensation, built to integrate with Base-native partners.
• One-command Devnet: pnpm dev brings up sequencer, batcher, proposer, challenger, verifier, and supporting services via Docker, auto-deploying Nexis contracts against a deterministic chain configuration.
• Extensible Governance: All contracts are upgradeable (UUPS) with role-based access patterns tailored for decentralized operations and future governance handoff.

Architecture

Rollup Layer

Nexis Appchain operates as an L3 rollup that settles to Base, inheriting Ethereum security via Optimism Bedrock. Chain parameters (block time, fault proofs, governance roles) are defined in packages/contracts-bedrock/deploy-config/AgentsL3.json and consumed by the automated devnet and deployment scripts.

Core Smart Contracts (packages/contracts-bedrock/contracts)

Contract	Purpose
Agents.sol	Registry for agents with staking balances, reputation dimensions, delegate permissions, and inference records. Integrates with treasury and task modules.
Tasks.sol	Bonded task marketplace enabling posting, claiming, submission, dispute, and resolution flows. Escrows rewards and stake with the treasury on completion or slashing.
Treasury.sol	Routes inflows between treasury, insurance, and rewards pools; handles slashes and penalties; pays rewards under governance control.
Subscriptions.sol	Recurring (epoch-based) and streaming (per-second) payment contracts that wire funds to agent owners while supporting ETH or ERC20 assets.

Operational Services

• OP Stack Clients: Directories prefixed op- (e.g., op-node, op-batcher, op-proposer) mirror Optimism's Go services tuned via Base-aligned defaults.
• Devnet Orchestration: ops-bedrock/docker-compose.yml plus scripts/agents-devnet/up.sh run a local rollup, funding test accounts and deploying contracts.
• Bedrock Tooling: bedrock-devnet Python utilities manage deterministic network snapshots for repeatable development and CI.
• Indexing & Monitoring: indexer, op-heartbeat, and endpoint-monitor provide observability for chain health, RPC availability, and latency.

Developer Toolchain

• Node & pnpm: Monorepo management, TypeScript utilities, and orchestrated builds run through pnpm + Nx.
• Go 1.21: Core rollup clients and services are written in Go.
• Foundry & Hardhat: Contract tests cover both solidity unit tests (forge test) and integration checks against the live devnet (hardhat test).
• Docker: Required for local rollup orchestration.

Network Configuration

Key parameters for the Nexis Base L3 devnet (see deploy-config/AgentsL3.json):

Setting	Value
L2 Chain ID	84532
L2 Block Time	2 seconds
Sequencer Drift	600 seconds
Channel Timeout	300 seconds
Finalization Period	12 seconds
Governance Token	Symbol NZT, name Nexis
Fault Proofs	Enabled with max depth 73, max clock 600 seconds
Devnet RPC	http://127.0.0.1:9545
Deployment Scripts	pnpm --filter @eth-optimism/contracts-bedrock run deploy:agents --network agentsL3

When deploying to Base testnet or mainnet, adjust the configuration file and environment variables accordingly before running the deployment scripts.

Getting Started

Prerequisites

• Node.js ≥ 18 (monorepo enforces ≥ 16, recommended 18 LTS)
• pnpm ≥ 9 (corepack enable, then corepack prepare pnpm@latest --activate)
• Go ≥ 1.21
• Python ≥ 3.10 (for bedrock-devnet tooling)
• Docker Desktop or Docker Engine with Compose v2
• Foundry (pnpm install:foundry) and Hardhat (installed via pnpm) for Solidity workflows

Clone & Install

git clone https://github.com/Nexis-AI/nexis-appchain.git
cd nexis-appchain
pnpm install
pnpm build

pnpm build runs nx targets across the monorepo to compile Go binaries, TypeScript packages, and Solidity artifacts.

Start the Local Devnet

pnpm dev &
sleep 20

The helper script performs the following:

1. Spins up the Bedrock stack (op-node, op-batcher, op-proposer, op-challenger, infra services) via Docker Compose.
2. Generates deterministic config and state snapshots into .agents-devnet/.
3. Deploys the Nexis contracts suite using the Base-aligned configuration.

Stop the stack with:

pnpm dev:down
rm -rf .agents-devnet  # optional cleanup

Access the Devnet

• RPC: http://127.0.0.1:9545
• Default chain ID: 84532
• Deployed contracts: artifacts stored at packages/contracts-bedrock/deployments/AgentsL3/
• Hardhat network alias: agentsL3

Run Tests

pnpm test                 # run nx test targets across packages
pnpm exec forge test      # run Foundry contract tests
./scripts/agents-devnet/hardhat-test.sh  # run Hardhat integration tests

Continuous integration can target pnpm lint, pnpm test, and chain-specific smoke tests using the devnet scripts.

Usage Guide

Registering an Agent

1. Call Agents.register(metadata, serviceURI) from the desired owner account.
2. Optionally delegate permissions using setDelegate(agentId, permission, delegateAddress) for metadata edits, inference submissions, or withdrawals.
3. Update metadata or service endpoints at any time with AgentMetadataUpdated and AgentServiceURIUpdated emitting on-chain events.

Staking & Withdrawals

• Use stakeETH or stakeERC20(agentId, asset, amount) to fund your agent.
• Set unbonding periods per asset with setAssetConfigurations (admin-controlled).
• Initiate withdrawals through beginWithdrawal, which queues a PendingWithdrawal released after the configured unbonding period.
• Cancel or execute withdrawals once they mature; early exits incur penalties routed to the treasury via handleEarlyExitPenalty.

Task Lifecycle

1. Create: Builders post tasks from Tasks.postTask, specifying reward token, bond amount, metadata URI, optional input URI, and deadlines.
2. Claim: Agents lock stake using Tasks.claimTask. Locked stake is tracked in Agents to secure task delivery.
3. Submit Work: Use Tasks.submitTask with the inference commitment ID produced via Agents.recordInference.
4. Attest or Dispute: Verifiers with VERIFIER_ROLE confirm success (Tasks.completeTask) or flag disputes (Tasks.disputeTask).
5. Resolve: Authorized dispute managers slash stake or refund rewards through Tasks.resolveTask, which communicates with the treasury for payouts or penalties.

Proof-of-Inference & Reputation

• Agents.recordInference(agentId, inputHash, outputHash, modelHash, taskId, proofURI) captures verifiable metadata.
• Verifiers register attestations with Agents.attestInference, unlocking rewards and reputation adjustments.
• Reputation weights by dimension (reliability, accuracy, performance, trustworthiness) are configurable to reflect desired incentive models.

Treasury Operations

• Slashes and penalties call Treasury.handleSlash or handleEarlyExitPenalty, dividing inflows between treasury, insurance, and rewards pools according to DistributionConfig.
• Rewards teams distribute incentives with distributeReward. Funds can be paid directly to agents or delegated payout addresses.
• Governance can withdraw accumulated balances per pool using role-gated functions for treasury management.

Subscriptions & Streaming Payments

• Subscriptions: createSubscription locks prefunded epochs and charges on a fixed cadence. processSubscription triggers payouts when epochs elapse.
• Streams: createStream starts a per-second payment window; agents call withdrawFromStream to collect accrued balances. Streams can be paused or cancelled with refunds governed by role permissions.
• Metadata URIs enable LangGraph or other orchestrators to fetch integration details tied to each subscription or stream.

Events & Indexing

Key events are emitted across the modules (AgentRegistered, StakeIncreased, TaskCreated, TaskCompleted, VerifierAttested, RewardPaid, SubscriptionProcessed, etc.). Use the provided indexer and endpoint-monitor services or integrate with your preferred ingestion stack to track lifecycle changes.

Development Guide

• Configuration: Adjust rollup parameters and governance addresses in packages/contracts-bedrock/deploy-config/AgentsL3.json before deploying.
• Contract Deployment: Update Hardhat network settings in packages/contracts-bedrock/hardhat.config.ts to target new environments, then run pnpm --filter @eth-optimism/contracts-bedrock run deploy:agents --network <networkName>.
• Artifacts: Deployment artifacts, ABIs, and addresses are written to packages/contracts-bedrock/deployments/<Network>/.
• Go Services: Build individual services with go build ./op-node, go build ./op-proposer, etc., or rely on pnpm build to run Nx orchestrated builds.
• Make Targets: make <target> wrappers are available for common flows (e.g., make devnet-up) if you prefer GNU Make.
• Formatting & Linting: Use pnpm lint, pnpm lint:fix, and Go's gofmt to keep changes consistent with repo standards.

Directory Map

Path	Description
packages/contracts-bedrock/contracts	Nexis smart contracts and dependencies.
packages/contracts-bedrock/scripts	Hardhat deployment scripts, including deployAgents.ts.
packages/contracts-bedrock/test	Foundry and Hardhat test suites covering agent, task, treasury, and subscription flows.
ops-bedrock/	Docker Compose manifests and configs bringing up the rollup stack locally.
scripts/agents-devnet/	Shell helpers for devnet lifecycle and integration testing.
bedrock-devnet/	Python tooling for deterministic bedrock devnets.
indexer/, endpoint-monitor/, op-heartbeat/	Optional services for chain data, RPC health, and latency monitoring.
specs/	Protocol specifications inherited from the Optimism stack.
docs/	Additional documentation, audits, and post-mortems.

Troubleshooting

• Devnet fails to start: Ensure Docker resources are sufficient (≥ 8 GB RAM) and no prior containers are running on required ports. Run pnpm dev:down then retry.
• Missing pnpm: Enable corepack or install pnpm globally (npm i -g pnpm) before running repo scripts.
• Foundry not available: Execute pnpm install:foundry and re-source your shell (source ~/.bashrc or restart terminal).
• Hardhat network mismatch: Confirm HARDHAT_NETWORK=agentsL3 or adjust RPC URLs in packages/contracts-bedrock/hardhat.config.ts.
• Go build issues: Install Go 1.21+, set GO111MODULE=on, and run go env -w GOPRIVATE=github.com/ethereum-optimism if fetching private modules.

Contributing & Security

• Follow the guidelines in CONTRIBUTING.md before submitting pull requests or opening issues.
• Security disclosures should follow SECURITY.md. Please do not file public issues for vulnerabilities.
• Typo fixes, documentation updates, and bug reports are welcome—batch changes thoughtfully to avoid noise.

License

This repository is licensed under the MIT License. Individual components may include additional third-party licenses; consult their respective directories for details.