diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..e272df5 --- /dev/null +++ b/.env.example @@ -0,0 +1,12 @@ +# Local development only. Copy to .env and replace with your own values. +# Create this disposable PostgreSQL database before running Prisma schema setup. +DATABASE_URL="postgresql://postgres:postgres@localhost:5432/agentshack_dev" +NEXT_PUBLIC_APP_URL="http://localhost:3000" + +# Your development Privy app ID is required for wallet/auth UI. +NEXT_PUBLIC_PRIVY_APP_ID="" +# Server-side Privy verification only. Never use a NEXT_PUBLIC_ prefix for secrets. +PRIVY_APP_SECRET="" + +# No private keys, production credentials, relayer or settlement flags are supplied. +# This file does not change the fixed BSC Testnet marketplace configuration. diff --git a/.gitignore b/.gitignore index 01e5501..03b6abc 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ node_modules .next .env* +!.env.example *.log *.patch *.diff diff --git a/HACKATHON.md b/HACKATHON.md index 86e8115..06ae7c6 100644 --- a/HACKATHON.md +++ b/HACKATHON.md @@ -2,6 +2,8 @@ A BSC Testnet marketplace for discovering, inspecting and hiring curated BNB Agent Studio agents across all four main-track categories. +[Project overview](README.md) · [Development](docs/development.md) · [Documentation](docs/README.md) + - Track: Main Track — Build the BNB Agent Studio Marketplace. - Repository: https://github.com/jh1nresh/agentshack - Public marketplace: https://www.agentshack.io/market @@ -30,8 +32,8 @@ The marketplace lists third-party Studio Desk services. The descriptions above d 3. Open its setup page and connect a BSC Testnet wallet. 4. Request a signed quote. The server checks its canonical hash, signer, chain, agent, commerce contract, policy, fee token, selector and fee cap. 5. Approve the five wallet transactions: create job, register policy, set budget, approve exact fee, fund. -6. Request delivery. Retrying after confirmed funding only repeats the delivery notification in the current page session. -7. Inspect the seller response and transaction links. Record delivery and actual execution evidence separately. +6. Request delivery. My agents (`/dashboard`) and Activity (`/activity`) retain wallet-scoped records in the same browser. Recovery verifies the original successful create/fund transactions before retrying notification, without creating another payment. +7. Inspect the seller response and transaction links. Record delivery and actual execution evidence separately. Partial/replaced transactions require manual review; history is not imported from older sessions without saved records or other devices. Notification retry is not an exactly-once guarantee. The wallet needs testnet BNB for gas and the seller's quoted test $U token. The four currently listed fees total 0.0042 test $U, excluding gas. The app does not acquire tokens or send a private key to a server. @@ -65,7 +67,7 @@ Use https://testnet.bscscan.com to inspect these addresses and each transaction. - Unit/property tests cover changed identities, endpoint paths, wrong chain/payment targets, modified quote terms, invalid signatures, fee bounds, malformed payloads, oversized streams and funded-job retry decisions. - Funded-hire evidence: pending selection of the buyer wallet and its signatures. No new funded job or delivery is claimed by this document. - Deployment must be confirmed against `/api/health` and the deployed commit; a successful build alone is not deployment evidence. -- Registration/submission confirmation: not found in the checked inbox. Confirm an existing response before submitting again. +- Registration/submission confirmation: not established by repository or CI evidence. Confirm an existing response before submitting again. For each category, record buyer address, job ID, quote hash, all five transaction hashes, seller response, and any resulting execution transaction. A response saying accepted/pending is not completed execution. diff --git a/README.md b/README.md index e754893..d5f5ac0 100644 --- a/README.md +++ b/README.md @@ -1,267 +1,77 @@ -# Maiat Dojo +# AgentShack -> The real ones rise — not the loudest, not the richest, the best. +A BSC Testnet marketplace for discovering, inspecting and hiring curated AI agents for bounded DeFi tasks. Users approve each transaction in their own wallet and can inspect job records and seller responses. -**NFA Agent Marketplace with On-Chain Reputation Settlement.** +[Marketplace](https://www.agentshack.io/market) · [Hackathon overview](HACKATHON.md) · [Local development](docs/development.md) · [Documentation](docs/README.md) -Dojo is the consumer-facing product of the [Maiat Protocol](https://maiat.io): a transaction network where creators publish non-fungible agents and service decks that others can run, fork, subscribe to, and monetize. Dojo acts like the HR and routing layer for agent labor: it knows which agent families exist, what each agent can do, who forked or deployed them, and which agents have credible outcome history. Each run is evaluated, cleared, settled, and turned into reputation. No fake reviews. No bought ratings. Just real executions, receipts, and outcomes. +## What you can do -The delivery path is evidence-gated: app and Foundry CI produce a -release-readiness receipt, then a read-only production check requires -`/api/health` to report the exact merged commit and approved chain policy. -Contract broadcasts, settlement cron calls, signer changes, and fund movements -are never part of automated delivery. +| Category | Bounded service | +| --- | --- | +| Rebalancing | Prepare a PancakeSwap V3 range-rebalance proposal | +| Grid Trading | Request one grid step on a fixed pair | +| Yield Optimisation | Request a bounded allocation at one Venus venue | +| Health Factor Monitoring | Read Venus liquidity/shortfall and request a bounded repayment proposal | -Current API skills are treated as one-step workflows. The product direction is workflow-first: multi-step agent processes with versioning, fork lineage, royalties, execution receipts, and non-transferable reputation. +These are third-party Studio Desk agents, not agents built by AgentShack. Identity and endpoint checks do not prove profitability or completed execution. See the [service limits and evidence checklist](HACKATHON.md). -## Agent Families and NFAs +## Current scope -Dojo treats workflows as the first form of **Non-Fungible Agents (NFAs)**: portable agent identities with service endpoints, capability metadata, fork lineage, and outcome history. ERC-8004-style agent identity gives each agent a persistent `AgentID`; BAP-578-style proof history turns prompts, executions, evaluations, and receipts into an auditable work record. The current product uses workflow receipts and trust scores as the thin version of this model before committing to a full standard implementation. +- **BSC Testnet only (chain ID 97).** No mainnet hiring or mainnet-readiness claim. +- **Discover → inspect → quote → approve → fund → request delivery.** Quotes are validated before the five wallet transactions; the app never asks for a private key. +- **My agents and Activity:** wallet-scoped job history saved in the same browser. Funded-job recovery verifies original chain transactions before retrying delivery, without creating another payment. +- **Explicit limitations:** no cross-device/history import; partial or replaced transactions need manual review. A seller response is not execution proof, and retrying delivery is not an exactly-once guarantee. +- **Source is not deployment evidence.** Check the deployed `/api/health` revision before demonstrating a newly merged feature. Four funded end-to-end hires and organizer acceptance of a testnet-only entry remain separate submission gates. -Agent families are reusable templates that can be forked into vertical-specific collections: +## Start here -| Family | Role | Example vertical forks | -|--------|------|------------------------| -| `R8` | Review, rating, and taste agents | `R8 Food`, `R8 Movie`, `R8 Concert`, `R8 DeFi`, `R8 Cars`, `R8 Locations` | -| `SLR` | Seller agents | `SLR Restaurant`, `SLR Hardware`, `SLR Music`, `SLR Cars`, `SLR Real Estate` | -| `BYR` | Buyer agents | `BYR Local`, `BYR Travel`, `BYR Hardware`, `BYR Tickets` | -| `NEG` | Negotiator agents | `Jiagon Negotiator`, marketplace negotiators, procurement agents | -| `VFY` | Verifier agents | receipt verifiers, repo-output judges, payment-backed outcome checks | - -An agent family is not a static image collection. It is an agent collection: each fork carries domain attributes, execution endpoints, pricing, permissions, receipts, and reputation signals that other humans or agents can inspect before hiring it. - -Example NFA metadata: - -```json -{ - "agent_family": "R8", - "vertical": "food", - "agent_id": "0x...", - "service_endpoint": "https://agent.example.com/r8-food", - "capabilities": ["rank", "review", "receipt_check", "taste_memory"], - "proof_level": "payment_backed", - "completed_runs": 124, - "dispute_rate": 0.03, - "forked_from": "r8-base", - "receipt_schema": "WorkflowRunReceipt" -} -``` - -## How It Works - -``` -Agent calls workflow via REST API - ↓ -POST /api/v1/run { service: "jiagon-negotiator", input: { repo_url: "https://github.com/garrytan/gbrain" } } - ↓ -AgentShack routes to workflow/provider endpoint → evaluates (delivered? format? latency?) - ↓ -Run clears → DB receipt now; BSC anchor is async best-effort when configured - ↓ -Execution receipt + receipt-backed service trust stats -``` - -## REST API (v1) - -All endpoints at `/api/v1/`. Agent developers need one API key. - -```bash -# One-call lifecycle: find service → create session → execute → evaluate → receipt -POST /api/v1/run - -H "Authorization: Bearer " - -d '{"service": "jiagon-negotiator", "input": {"repo_url": "https://github.com/garrytan/gbrain"}}' -# → { "result": {...}, "cost": 0.003, "receipt": {"id": "..."}, "reputation_update": {...} } - -# Check credits -GET /api/v1/balance - -# Deposit testnet credits -POST /api/v1/deposit -d '{"amount": 10}' - -# Browse service catalog (public, no auth) -GET /api/v1/services -# DB-backed only: no demo fallback, so empty means no published receipt-backed services. - -# Fetch receipt proof (public, no auth) -GET /api/v1/receipts/:receiptId -# Path params: receiptId = WorkflowRunReceipt id. -curl http://localhost:3000/api/v1/receipts/cmop19dlo000g106kgfthrls2 -# → { "id": "...", "workflow": {...}, "clearing": {...}, "evaluator": {...}, "proof": {...} } - -# Browse legacy workflow/skill catalog (public, no auth) -GET /api/v1/skills - -# Browse workflow-native catalog (public, no auth) -GET /api/workflows - -# Fork workflow metadata (requires API key) -POST /api/workflows/:id/fork - -# Query trust score (public, no auth) -GET /api/v1/reputation?address=0x... - -# Manual session close → triggers on-chain settlement -POST /api/v1/close -d '{"session_id": "..."}' -``` - -## Workflows - -Current listed services are one-step workflows. A service is the external abstraction for a runnable agent / workflow / skill package. Workflow metadata, versions, fork lineage, run receipts, and royalties are tracked separately without breaking legacy `/api/v1/run { skill }`. - -| Workflow | Type | Price/run | Endpoint | -|-------|------|-----------|----------| -| Agent Repo Analyst | active | $0.003 | `/api/skills-internal/repo-analyst` | - -Two workflow modes: **Active** (pay-per-run via gateway sessions) and **Passive** (buy-to-download / forkable package). - -### Creator CLI - -The standalone CLI package lives in `packages/dojo-cli` and is intended to be published as `@maiat/dojo`. Once published, creators can publish an executable workflow endpoint from their own agent repo without cloning Dojo: +Use **npm** and the committed `package-lock.json`; CI uses Node.js 24. The app uses Next.js 15, React 18, Tailwind CSS, Privy, Prisma/PostgreSQL and viem. Solidity sources use Foundry. ```bash -npx @maiat/dojo init -DOJO_API_KEY=dojo_sk_... npx @maiat/dojo test --file dojo.workflow.yaml -DOJO_API_KEY=dojo_sk_... npx @maiat/dojo publish --file dojo.workflow.yaml -DOJO_API_KEY=dojo_sk_... npx @maiat/dojo fork --workflow jiagon-negotiator --name "My Repo Analyst" -DOJO_API_KEY=dojo_sk_... npx @maiat/dojo deploy --workflow my-repo-analyst --file dojo.workflow.yaml -DOJO_API_KEY=dojo_sk_... npx @maiat/dojo run --service jiagon-negotiator --input '{"repo_url":"https://github.com/garrytan/gbrain"}' +git clone https://github.com/jh1nresh/agentshack.git +cd agentshack +npm ci +cp .env.example .env ``` -`run --service` is the current form. `run --skill` remains a legacy alias for older gateway slugs. +Edit `.env` with your own **local PostgreSQL database** and development Privy app configuration. Then follow [database setup and startup](docs/development.md#database-and-startup). Never point development setup or seed commands at a shared/production database. -`publish` runs `/api/skills/dry-run` first, then creates the active `Skill`, `Workflow`, and first `WorkflowVersion` through `/api/skills/create`. Use `examples/dojo.workflow.yaml` as the starter manifest. Production creator endpoints must be public HTTPS URLs. +## Repository map -`fork` creates a draft workflow with provenance. `deploy` attaches an executable endpoint to a workflow you own and publishes it through the gateway. +| Path | Purpose | +| --- | --- | +| [`src/app/`](src/app/) | Next.js routes and APIs | +| [`src/components/market/`](src/components/market/) | Black/yellow marketplace, setup and job-history UI | +| [`src/lib/bnb-marketplace.ts`](src/lib/bnb-marketplace.ts) | Curated testnet agents and categories | +| [`src/lib/`](src/lib/) | Quote validation, chain clients, recovery and retained workflow services | +| [`src/__tests__/`](src/__tests__/) | App unit, regression and property tests | +| [`contracts/`](contracts/) | Solidity code, Foundry tests and historical audit reports | +| [`prisma/`](prisma/) | PostgreSQL schema and destructive demo seed | +| [`packages/`](packages/) | Retained Dojo creator CLI and MCP server | +| [`docs/`](docs/) | Development, workflow, design and historical documentation | +| [`scripts/`](scripts/) | Checks and operational tools; review side effects before running | +| [`config/`](config/) | Release policy, not a deployment receipt | +| [`examples/`](examples/) | Workflow manifests and agent-pack examples | +| [`specs/`](specs/) | Historical/planning documents, not release guarantees | -`dojo.workflow.yaml` is the canonical format. `SKILL.md` files with YAML frontmatter are also supported for compatibility: +## Verification ```bash -DOJO_API_KEY=dojo_sk_... npx @maiat/dojo publish --file SKILL.md +npm run lint +npm run typecheck +npm test -- --run +npm run build +npm run audit:runtime ``` -Inside this repo, developers can run the same CLI without publishing the npm package: - -```bash -npm run dojo -- help -npm run dojo -- dev-key -DOJO_API_KEY=dojo_sk_... npm run dojo -- run --service jiagon-negotiator --input '{"repo_url":"https://github.com/garrytan/gbrain"}' -``` - -`dev-key` is a local demo helper for the BNB/Codex/MCP flow. It reuses or creates -one DB-backed `dojo_sk_...` key for a user with an agent and tops up demo credits -so `/api/v1/run` can write the clearing receipt. - -## Stack - -| Layer | Tech | -|-------|------| -| Frontend | Next.js 14, Tailwind CSS, liquid-glass marketplace UI | -| Auth | Privy (email, Google, Apple, wallet) + API keys | -| Database | Prisma + SQLite (→ Postgres in prod) | -| Chain | BSC (BNB Smart Chain) — testnet 97, mainnet 56 | -| Contracts | ERC-8183 AgenticCommerceHooked + hooks (Solidity 0.8.24, Foundry) | -| Settlement | DB receipt first; gateway-signed `closeAndSettle()` is used by the session-close / BSC rail | -| Reputation | BAS attestations + TrustScoreOracle | -| Wallet | viem (server-side relayer for testnet) | - -## Contracts (BSC Testnet) - -| Contract | Address | -|----------|---------| -| AgenticCommerceHooked | `0xC159C364BFA5E9F3aa2df16538C5080c84188c04` | -| TrustBasedEvaluator | `0x0F975BFDA1Fdb6f0193c8ce5144FCe90d65BB895` | -| EvaluatorRegistry | `0x8b6D60e4EdD3A6Bf111ac46b3BaDB11FdAee9921` | -| TrustGateACPHook | `0x8D95eBb23871649EC4FB63894249c4f62770c2e3` | -| CompositeRouterHook | `0xF03b4D80d8Ba7c77ABdB2B2d1f194E00D676B4c7` | -| AgentIdentity (ERC-8004) | `0xbb1d304179bdd577d5ef15fec91a5ba9756a6e41` | -| DojoTrustScore | `0xC6cF2d59fF2e4EE64bbfcEaad8Dcb9aA3F13c6dA` | - -206 tests passing. Audited with 8-agent parallel scan (6 findings, all fixed). - -## Getting Started - -```bash -# Install -npm install - -# Database -npx prisma generate -npx prisma db push -npx tsx prisma/seed.ts # 4 skills + 3 agents + reviews - -# Dev server -npm run dev # http://localhost:3000 - -# Verify -curl http://localhost:3000/api/v1/services -``` - -## Architecture - -``` -┌──────────────────────────────────────────────────────────────┐ -│ AGENT DEVELOPERS │ -│ POST /api/v1/run { service } (one HTTP call) │ -└──────────────────────┬───────────────────────────────────────┘ - │ - ▼ -┌──────────────────────────────────────────────────────────────┐ -│ DOJO (REST API + Chat UI) │ -├────────────┬─────────────┬──────────────┬────────────────────┤ -│ /v1/run │ /v1/services│ /v1/balance │ /v1/receipts │ -│ (execute) │ (catalog) │ (credits) │ (proof) │ -└─────┬──────┴──────┬──────┴──────┬───────┴────────┬───────────┘ - │ │ │ │ - ▼ ▼ ▼ ▼ -┌──────────┐ ┌────────────┐ ┌──────────┐ ┌────────────────────┐ -│ Provider │ │ Session │ │ Prisma │ │ BSC Chain │ -│ Endpoint │ │ Evaluator │ │ DB │ │ execution receipt │ -│ (route) │ │ (sanity) │ │ (state) │ │ settlement proof │ -└──────────┘ └────────────┘ └──────────┘ │ BAS (attestations) │ - │ TrustScoreOracle │ - └─────────┬──────────┘ - │ - ▼ - ┌──────────────────────┐ - │ MAIAT REPUTATION │ - │ CLEARING NETWORK │ - │ Open API for anyone │ - └──────────────────────┘ -``` - -## Workflow Clearing Flow - -1. Agent calls `POST /api/v1/run` with a `service` slug -> session auto-created, workflow executed, evaluated, receipt returned -2. Session budget exhausted (or manual `POST /api/v1/close`) -3. AgentShack writes a `WorkflowRunReceipt` with evaluator evidence, cost, settlement status, provenance, and lineage refs -4. Service trust stats are derived from receipt rows -5. If BSC anchoring is configured, the receipt is marked `pending` and tx hashes are written back asynchronously -6. Full on-chain escrow settlement, BAS hooks, and verifier-attested clearing remain the next clearing-network upgrade - -## Product Direction - -Dojo should not compete as a generic agent launchpad. The focused wedge is cleared agent work: - -- start with one real public-repo analysis workflow -- show a concrete successful execution before asking users to pay -- charge per successful online run, not for a downloadable workflow file -- expand only after the receipt/reputation loop is obvious - -Creators publish workflows. Other agents run, fork, and deploy them. Dojo clears each run and builds reputation from real outcomes. - -Implemented workflow primitives: +Contract setup and checks are in the [contract guide](contracts/README.md). The [CI workflow](.github/workflows/ci.yml) is the source of truth for current checks; test counts and historical audit reports are not security certifications. -- `Workflow`, `WorkflowVersion`, `WorkflowFork`, and `WorkflowRunReceipt` models -- `GET /api/workflows` -- `POST /api/workflows/:id/fork` -- Agent Repo Analyst internal endpoint -- `/api/v1/services` exposes runnable service descriptors, pricing, trust stats, and security scan status -- `/api/v1/run` writes a `WorkflowRunReceipt` for receipt-backed services +Merge, deployment, database migration and chain transactions are separate actions. [Release boundaries](docs/development.md#release-boundaries) explains what CI does and does not prove. -## Links +## Naming and older surfaces -- **Maiat Protocol**: [maiat.io](https://maiat.io) +This repository is **`jh1nresh/agentshack`**. **Maiat Dojo** remains the name of the retained workflow/receipt engine, npm workspaces and some deployment identifiers. Those compatibility names do not identify another canonical repository. -## License +The current navigation exposes Market, My agents and Activity. The older `/create` workflow builder and `/api/v1/*` services still exist; see [workflow integrations](docs/workflows.md). They are separate from the curated BNB testnet hiring flow. -MIT +Historical design/specification material is linked from the [documentation index](docs/README.md#historical-material). Do not treat an old concept screenshot, address or roadmap as the current app. diff --git a/contracts/README.md b/contracts/README.md index 1000ce0..21fdc08 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -1,83 +1,45 @@ -# Dojo Contracts +# Contracts -On-chain contracts for the Maiat Dojo — Agent Skill Marketplace. +[AgentShack overview](../README.md) · [Documentation](../docs/README.md) -## Contracts +Solidity sources and Foundry tests retained by AgentShack / Maiat Dojo. This directory is **not** the source of every third-party contract used by the BNB marketplace. -| Contract | Description | -|----------|-------------| -| **SkillNFT** | ERC-1155 skill tokens with USDC auto-split (85% creator / 10% platform / 5% reputation pool) | -| **SkillRoyaltySplitter** | Agent Services payment split (80% operator / 15% creator / 5% platform) | -| **ISkillNFT** | Shared interface for cross-contract reads | +## Three distinct boundaries -## Deployments +| Surface | Configuration / source | +| --- | --- | +| Curated BNB marketplace | [`bnb-marketplace.ts`](../src/lib/bnb-marketplace.ts) and [`bnb-marketplace-activation.ts`](../src/lib/bnb-marketplace-activation.ts); chain 97, third-party registry/seller/commerce integration | +| Dojo receipt and settlement engine | [`contracts.ts`](../src/lib/contracts.ts); separate addresses and mainnet placeholders | +| Local Solidity code | [`src/`](src/): registry, job, reputation, token, royalty and swap components retained across product iterations | -### Base Sepolia (Testnet) +Do not interchange these contract addresses. The [hackathon guide](../HACKATHON.md#testnet-contracts) documents the marketplace targets; source configuration remains authoritative. -| Contract | Address | -|----------|---------| -| SkillNFT | [`0x52635F45b087c1059B3a997fb089bae5Db095B74`](https://sepolia.basescan.org/address/0x52635F45b087c1059B3a997fb089bae5Db095B74) | -| SkillRoyaltySplitter | [`0x98D34100F6030DFDc1370fB45dFa1Ad7980D4bD8`](https://sepolia.basescan.org/address/0x98D34100F6030DFDc1370fB45dFa1Ad7980D4bD8) | -| USDC (Circle testnet) | [`0x036CbD53842c5426634e7929541eC2318f3dCF7e`](https://sepolia.basescan.org/address/0x036CbD53842c5426634e7929541eC2318f3dCF7e) | +## Build and test (no transactions) -### Base Mainnet - -TBD — deploy after testnet validation. - -## Build & Test +Install Foundry and the exact dependency revisions pinned by the [CI workflow](../.github/workflows/ci.yml). In a fresh checkout, from the repository root: ```bash +git clone https://github.com/foundry-rs/forge-std.git contracts/lib/forge-std +git -C contracts/lib/forge-std checkout --detach 0844d7e1fc5e60d77b68e469bff60265f236c398 +git clone https://github.com/OpenZeppelin/openzeppelin-contracts.git contracts/lib/openzeppelin-contracts +git -C contracts/lib/openzeppelin-contracts checkout --detach 5fd1781b1454fd1ef8e722282f86f9293cacf256 cd contracts -forge build # compile -forge test # 56 tests (43 unit + 13 fuzz) -forge test -vvv # verbose output +forge build --sizes +forge test -vv ``` -## Deploy - -```bash -# Base Sepolia -PRIVATE_KEY=0x... forge script script/Deploy.s.sol --rpc-url base-sepolia --broadcast - -# Base Mainnet -PRIVATE_KEY=0x... forge script script/Deploy.s.sol --rpc-url base --broadcast -``` +If dependencies already exist, inspect their revisions and changes rather than overwriting them. `forge build` and this test suite are verification commands, not a deployment procedure. Use CI logs for current test counts. -Optional: set `BASESCAN_API_KEY` in env and uncomment `[etherscan]` in `foundry.toml` for contract verification. - -## Architecture - -``` -SkillNFT (ERC-1155 + ERC-2981 + ISkillNFT) -├── createSkill() — Owner lists a skill (price, creator, royaltyBps, URI) -├── buySkill() — Anyone pays USDC → auto-split → mint NFT -├── setSkillActive() — Owner activates/deactivates -├── setFees() — Atomic fee update (platform + reputation pool) -└── rescueTokens() — Emergency fund recovery - -SkillRoyaltySplitter -├── pay() — Service payment → 80/15/5 split (operator/creator/platform) -│ ├── Operator must hold skill NFT (M-3) -│ ├── Skill must be active (L-4) -│ ├── Pull-then-push pattern (M-2) -│ └── MIN_AMOUNT enforced (Lead) -├── setFeeSplit() — Adjust split (operator ≥ 50%) -└── rescueTokens() — Emergency fund recovery -``` +## Deployment and operational safety -## Security +- [`foundry.toml`](foundry.toml) currently defines `bsc` and `bsc_testnet` RPC aliases. +- The root [Makefile](../Makefile) still has legacy Base deploy/interaction targets. They are not supported instructions for this marketplace. +- [`script/`](script/) contains state-changing deployment and seed scripts. No broadcast, signer/role change or settlement is authorized by following this README. +- Marketplace hires are approved by the user's BSC Testnet wallet. Mainnet entries in the retained Dojo configuration include zero-address placeholders and must not be presented as ready. +- The [release policy](../config/maiat-release-policy.json) separates app readiness from contract broadcast and chain writes. -- **Audited** by Jensen (Slither + Trail of Bits skills) + Patrick (Pashov parallel 8-agent audit) -- 5 findings resolved (3 Medium + 2 Low) + 6 leads addressed -- Full audit reports: [`contracts/audits/`](./audits/) -- ReentrancyGuard on all payment functions -- Pull-then-push pattern prevents USDC blacklist DoS -- Operator NFT ownership verified on every service payment +## Security and historical references -## Key Design Decisions +[`audits/`](audits/) contains dated reports for specific code and review scopes. Their presence is not a current security certification, a formal third-party audit of the marketplace, or an audit of Studio Desk sellers. -- **USDC only** — no native ETH, no oracle dependency, minimal attack surface -- **No funds held** — contract distributes immediately, nothing to steal -- **Atomic fee updates** — prevents non-atomic misconfiguration -- **MIN_PRICE / MIN_AMOUNT** — prevents dust/spam transactions -- **royaltyBps** is ERC-2981 only (secondary market); Agent Services uses global split +The former Base deployment table, SkillNFT split descriptions and original audit claims are preserved in [legacy Base contract notes](../docs/archive/legacy-base-contracts.md), clearly separated from current setup. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..be12cb9 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,37 @@ +# Documentation + +[AgentShack overview](../README.md) is the public starting point. This index separates the current marketplace from the retained workflow engine and historical plans. + +## Current guides + +| Guide | Use it for | +| --- | --- | +| [Hackathon overview](../HACKATHON.md) | Four categories, service limits, testnet addresses and outstanding evidence | +| [Local development](development.md) | npm, PostgreSQL, Privy, checks and release boundaries | +| [Workflow integrations](workflows.md) | Older REST, creator CLI and MCP surfaces | +| [Contracts](../contracts/README.md) | Source boundaries, read-only Foundry verification and legacy deployment warnings | +| [Creator CLI](../packages/dojo-cli/README.md) | Local workflow manifest commands | +| [MCP server](../packages/dojo-mcp/README.md) | Local stdio tools and configuration | + +## Configuration sources + +- [Curated agents](../src/lib/bnb-marketplace.ts) and [seller quote targets](../src/lib/bnb-marketplace-activation.ts) define the marketplace's testnet integration. +- [Dojo chain configuration](../src/lib/contracts.ts) belongs to the retained receipt/settlement engine; do not substitute its commerce addresses into marketplace quotes. +- [Prisma schema](../prisma/schema.prisma), [package scripts](../package.json), [CI](../.github/workflows/ci.yml) and [release policy](../config/maiat-release-policy.json) define runtime/setup behavior. +- [Agent instructions](../AGENTS.md) and the [PR template](../.github/pull_request_template.md) describe engineering boundaries. + +## Historical material + +- [Marketplace visual baseline](design/agentshack-marketplace/README.md): approved black/yellow direction, with older fixture-based screenshots; not current runtime evidence. +- [April 2026 spec index](archive/spec-index-2026-04-27.md): preserved planning snapshot, including references to local-only notes. +- [Legacy Base contracts](archive/legacy-base-contracts.md): original deployment/architecture notes; not BSC instructions or current deployment proof. +- [Tracked specifications](../specs/) and [changelog](../CHANGELOG.md): historical plans and release notes. Check implementation and commit-bound evidence before treating claims as current. +- [Contract audit reports](../contracts/audits/): dated, scoped reports, not certification of the current marketplace or third-party sellers. + +## Compatibility files retained + +`package.json` and CI select npm. The older `pnpm-lock.yaml` is retained for history, not a second supported install procedure. This documentation change does not regenerate dependencies. + +The root `Makefile` still contains legacy Base broadcast targets, while current Foundry aliases are BSC. Use the explicit read-only checks in the contract guide; do not use those deploy targets for the BNB marketplace. + +Some `specs/` files were committed before that directory was ignored. Existing tracked files remain in Git; an ignore rule is not a privacy boundary. No local-only notes are imported by this documentation cleanup. diff --git a/docs/archive/legacy-base-contracts.md b/docs/archive/legacy-base-contracts.md new file mode 100644 index 0000000..fedebe5 --- /dev/null +++ b/docs/archive/legacy-base-contracts.md @@ -0,0 +1,88 @@ +# Legacy Dojo Base Contracts — Historical Notes + +> Archived original documentation. Base addresses, broadcast commands, test counts +> and audit claims below are historical and are not verified current instructions. +> Do not execute the deployment examples for the BNB marketplace. Use the +> [current contract guide](../../contracts/README.md) instead. + +On-chain contracts for the Maiat Dojo — Agent Skill Marketplace. + +## Contracts + +| Contract | Description | +|----------|-------------| +| **SkillNFT** | ERC-1155 skill tokens with USDC auto-split (85% creator / 10% platform / 5% reputation pool) | +| **SkillRoyaltySplitter** | Agent Services payment split (80% operator / 15% creator / 5% platform) | +| **ISkillNFT** | Shared interface for cross-contract reads | + +## Deployments + +### Base Sepolia (Testnet) + +| Contract | Address | +|----------|---------| +| SkillNFT | [`0x52635F45b087c1059B3a997fb089bae5Db095B74`](https://sepolia.basescan.org/address/0x52635F45b087c1059B3a997fb089bae5Db095B74) | +| SkillRoyaltySplitter | [`0x98D34100F6030DFDc1370fB45dFa1Ad7980D4bD8`](https://sepolia.basescan.org/address/0x98D34100F6030DFDc1370fB45dFa1Ad7980D4bD8) | +| USDC (Circle testnet) | [`0x036CbD53842c5426634e7929541eC2318f3dCF7e`](https://sepolia.basescan.org/address/0x036CbD53842c5426634e7929541eC2318f3dCF7e) | + +### Base Mainnet + +TBD — deploy after testnet validation. + +## Build & Test + +```bash +cd contracts +forge build # compile +forge test # 56 tests (43 unit + 13 fuzz) +forge test -vvv # verbose output +``` + +## Deploy + +```bash +# Base Sepolia +PRIVATE_KEY=0x... forge script script/Deploy.s.sol --rpc-url base-sepolia --broadcast + +# Base Mainnet +PRIVATE_KEY=0x... forge script script/Deploy.s.sol --rpc-url base --broadcast +``` + +Optional: set `BASESCAN_API_KEY` in env and uncomment `[etherscan]` in `foundry.toml` for contract verification. + +## Architecture + +``` +SkillNFT (ERC-1155 + ERC-2981 + ISkillNFT) +├── createSkill() — Owner lists a skill (price, creator, royaltyBps, URI) +├── buySkill() — Anyone pays USDC → auto-split → mint NFT +├── setSkillActive() — Owner activates/deactivates +├── setFees() — Atomic fee update (platform + reputation pool) +└── rescueTokens() — Emergency fund recovery + +SkillRoyaltySplitter +├── pay() — Service payment → 80/15/5 split (operator/creator/platform) +│ ├── Operator must hold skill NFT (M-3) +│ ├── Skill must be active (L-4) +│ ├── Pull-then-push pattern (M-2) +│ └── MIN_AMOUNT enforced (Lead) +├── setFeeSplit() — Adjust split (operator ≥ 50%) +└── rescueTokens() — Emergency fund recovery +``` + +## Security + +- **Audited** by Jensen (Slither + Trail of Bits skills) + Patrick (Pashov parallel 8-agent audit) +- 5 findings resolved (3 Medium + 2 Low) + 6 leads addressed +- Full audit reports: [`contracts/audits/`](../../contracts/audits/) +- ReentrancyGuard on all payment functions +- Pull-then-push pattern prevents USDC blacklist DoS +- Operator NFT ownership verified on every service payment + +## Key Design Decisions + +- **USDC only** — no native ETH, no oracle dependency, minimal attack surface +- **No funds held** — contract distributes immediately, nothing to steal +- **Atomic fee updates** — prevents non-atomic misconfiguration +- **MIN_PRICE / MIN_AMOUNT** — prevents dust/spam transactions +- **royaltyBps** is ERC-2981 only (secondary market); Agent Services uses global split diff --git a/SPECS.md b/docs/archive/spec-index-2026-04-27.md similarity index 92% rename from SPECS.md rename to docs/archive/spec-index-2026-04-27.md index 1361a9f..352bd0f 100644 --- a/SPECS.md +++ b/docs/archive/spec-index-2026-04-27.md @@ -1,7 +1,8 @@ -# Maiat Dojo — Spec Index +# Maiat Dojo — Historical Spec Index (April 27, 2026) -> Auto-read this file FIRST when entering the repo to avoid re-discovering existing work. -> Last updated: 2026-04-27 +> Preserved planning snapshot, not current product or release status. Start with the +> [AgentShack README](../../README.md) and [documentation index](../README.md). +> Local `~/brain` references and dated PR statuses below are historical, not public links or current instructions. --- diff --git a/docs/design/agentshack-marketplace/README.md b/docs/design/agentshack-marketplace/README.md index 7429eca..4c54edb 100644 --- a/docs/design/agentshack-marketplace/README.md +++ b/docs/design/agentshack-marketplace/README.md @@ -1,6 +1,10 @@ # BNB Agent Marketplace UI lock -Status: approved visual direction, demo-data implementation. +Status: historical approved visual baseline (fixture-data stage). The black/yellow +direction remains relevant, but these screenshots are not current runtime proof. +The source now includes curated testnet agents and wallet-approved hiring; see the +[current overview](../../../README.md) and [hackathon guide](../../../HACKATHON.md). +The flow, fixture restrictions and capture claims below describe the original UI lock. ## Product flow diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..5370997 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,78 @@ +# Local development + +[Overview](../README.md) · [Documentation index](README.md) + +## Requirements + +- Node.js 24 matches app CI; `package.json` permits Node.js >=20.9.0. +- npm (the repository declares npm 10.9.2) and `package-lock.json`. +- A disposable local PostgreSQL database. The Prisma provider is **PostgreSQL**, not SQLite. +- Your own development Privy app configuration for the wallet/auth UI. Without an app ID, the provider is disabled; do not treat a successful build as proof that connected screens work. +- Foundry only when working with the [Solidity sources](../contracts/README.md). + +## Environment + +After `npm ci`, copy the root [`.env.example`](../.env.example) to `.env` and replace its placeholders. `.env` is used here so both Prisma CLI and Next.js can load it. + +| Variable | Purpose | +| --- | --- | +| `DATABASE_URL` | Your disposable local PostgreSQL connection | +| `NEXT_PUBLIC_APP_URL` | Local application URL, normally `http://localhost:3000` | +| `NEXT_PUBLIC_PRIVY_APP_ID` | Public ID of your development Privy app | +| `PRIVY_APP_SECRET` | Private server credential for routes that verify Privy tokens; never expose it with a `NEXT_PUBLIC_` prefix | + +Do not copy production credentials, relayer keys, settlement flags or another developer's `.env`. The marketplace targets are curated in source; changing a general RPC or contract environment variable does not configure a new supported marketplace chain. + +`npm run dev` runs [`scripts/check-env.sh`](../scripts/check-env.sh) first. It checks `.env.local` before `.env`; if you already have both, inspect their configuration for conflicts. Do not bypass a database/configuration warning to force startup. + +## Database and startup + +Create the empty PostgreSQL database named in your local `DATABASE_URL` using your existing PostgreSQL installation. Confirm the URL points only to that disposable database before schema setup: + +```bash +npx prisma generate +npx prisma db push +npm run dev +``` + +`db push` changes the configured database schema. It is not a production migration procedure. Open `http://localhost:3000/market`; wallet features need the development Privy configuration, and live cards/quotes need access to BSC Testnet RPC and the configured seller endpoints. + +**Do not seed by default.** [`prisma/seed.ts`](../prisma/seed.ts) deletes existing users, agents, sessions, jobs, workflows, receipts and related records before creating the old demo catalog. `npm run seed` is only for a disposable demo database that you explicitly intend to replace. The curated BNB marketplace list is source-defined and does not require this seed. + +My agents and Activity use wallet-scoped browser storage, not the old demo database. They do not import past transactions or other devices' history. Interrupted or uncertain transactions require inspection rather than automatic payment replay. + +## Checks + +```bash +npm run lint +npm run typecheck +npm test -- --run +npm run build +npm run audit:runtime +``` + +Focused marketplace checks: + +```bash +npm test -- --run src/__tests__/bnb-marketplace-journal.test.ts src/__tests__/marketplace-navigation.test.ts +``` + +The runtime audit uses an existing advisory baseline; passing it does not mean zero vulnerabilities. CI runs its own install and Prisma generation. No real wallet login, funded transaction or live seller delivery is proved by unit/property tests. + +## Repository conventions + +- Keep root entry points short; current how-to guides belong in `docs/` and dated reference material in `docs/archive/`. +- Preserve `maiat-dojo`, `@maiat/dojo` and `@maiat/dojo-mcp` identifiers unless doing a separately scoped compatibility migration. +- Use npm; do not mix lockfile regeneration into unrelated work. +- Inspect scripts before running them. `seed`, mint/backfill, settlement, trust-setting and broadcast scripts can change data or chain state; they are not ordinary setup checks. +- Follow [AGENTS.md](../AGENTS.md) and keep unrelated work out of a PR. + +## Release boundaries + +1. Pull-request CI checks app and contracts. It does not deploy, sign or broadcast transactions. +2. Main-branch CI also creates `maiat-release-readiness.json` for an exact commit. This is a readiness record, not a production receipt. +3. An authorized deployment must be followed by a read-only `/api/health` check of the expected revision, active chain and mainnet-readiness state. See [delivery workflow](../.github/workflows/delivery.yml) and [release policy](../config/maiat-release-policy.json). + +The health payload and some deployment identifiers still say Maiat Dojo. The configured delivery-policy URL may differ from a public AgentShack alias; verify the intended host and revision explicitly. Do not assume a merged commit automatically updated `www.agentshack.io`. + +Mainnet placeholders, a testnet-only policy, or missing funded-job evidence are not resolved by a documentation change. Database migration, deployment, chain broadcast and settlement each need their own authorization. diff --git a/docs/workflows.md b/docs/workflows.md new file mode 100644 index 0000000..f94c1b2 --- /dev/null +++ b/docs/workflows.md @@ -0,0 +1,53 @@ +# Retained workflow integrations + +[Overview](../README.md) · [Documentation index](README.md) + +The repository contains two related surfaces: + +- **AgentShack marketplace:** curated BNB agents, signed quotes and user-approved testnet jobs under `/market`. My agents (`/dashboard`) and Activity (`/activity`) use the same-browser journal. +- **Maiat Dojo workflow engine:** creator endpoints, API keys, session credits, workflow versions/forks and receipt-backed execution under `/api/v1/*` and `/api/workflows`. + +The older `/create` builder remains available, but is no longer in the main marketplace navigation. Do not confuse a Dojo workflow receipt, browser job record or seller response with completed DeFi execution. + +## REST entry points + +| Endpoint | Purpose | +| --- | --- | +| `GET /api/v1/services` | Public DB-backed runnable services; an empty result is not a demo fallback | +| `GET /api/v1/skills` | Older skill catalog | +| `GET /api/workflows` | Workflow-native catalog | +| `POST /api/v1/run` | API-key-authenticated workflow execution | +| `GET /api/v1/receipts/:receiptId` | Public receipt details | +| `GET /api/v1/balance` | Authenticated session-credit balance | +| `POST /api/workflows/:id/fork` | Authenticated draft fork with provenance | + +Example read-only local catalog request: + +```bash +curl http://localhost:3000/api/v1/services +``` + +Execution, publishing and forking are state-changing operations. The REST run API accepts a `service` slug; legacy `skill` input remains supported. Database receipts and optional asynchronous BSC anchoring are separate states, not an unconditional onchain-settlement guarantee. + +## Creator tools + +Use the repository's [creator CLI](../packages/dojo-cli/README.md) rather than assuming an npm release is available: + +```bash +npm run dojo -- help +``` + +[`examples/dojo.workflow.yaml`](../examples/dojo.workflow.yaml) is the starter manifest. Markdown `SKILL.md` manifests with YAML frontmatter remain compatible. Production creator endpoints must be public HTTPS URLs. + +`dev-key` creates/reuses a database API key and tops up demo credits; use it only with an intentionally disposable local database. Publishing, deployment and running a service may contact configured providers and write records. Check `DOJO_BASE_URL` and the manifest before running those commands. + +The [MCP package](../packages/dojo-mcp/README.md) exposes service listing, execution and receipt tools over local stdio. Use a path to your own checkout; no maintainer-specific absolute path is required. + +## Source pointers + +- [`src/app/api/v1/`](../src/app/api/v1/) — gateway endpoints. +- [`src/app/api/workflows/`](../src/app/api/workflows/) — workflow discovery and mutations. +- [`prisma/schema.prisma`](../prisma/schema.prisma) — persistent models. +- [`src/lib/contracts.ts`](../src/lib/contracts.ts) — retained Dojo chain configuration, distinct from curated marketplace seller targets. + +Historical NFA families, royalties and clearing-network proposals are design context, not promises that every described capability is live. See the [historical index](README.md#historical-material). diff --git a/packages/dojo-cli/README.md b/packages/dojo-cli/README.md index 5f6392d..36d64b1 100644 --- a/packages/dojo-cli/README.md +++ b/packages/dojo-cli/README.md @@ -2,22 +2,26 @@ Creator CLI for publishing, forking, and deploying Dojo agent workflows. -## Usage +## Usage from this repository + +Run from the repository root after the [local setup](../../docs/development.md). +These commands use the checked-in CLI; they do not assume `@maiat/dojo` has been +published to npm. Commands other than help/init can write records or call providers. ```bash -npx @maiat/dojo init +npm run dojo -- init npm run dojo -- dev-key -DOJO_API_KEY=dojo_sk_... npx @maiat/dojo test --file dojo.workflow.yaml -DOJO_API_KEY=dojo_sk_... npx @maiat/dojo publish --file dojo.workflow.yaml -DOJO_API_KEY=dojo_sk_... npx @maiat/dojo fork --workflow jiagon-negotiator --name "My Repo Analyst" -DOJO_API_KEY=dojo_sk_... npx @maiat/dojo deploy --workflow my-repo-analyst --file dojo.workflow.yaml -DOJO_API_KEY=dojo_sk_... npx @maiat/dojo run --service jiagon-negotiator --input '{"repo_url":"https://github.com/garrytan/gbrain"}' +DOJO_API_KEY=dojo_sk_... npm run dojo -- test --file dojo.workflow.yaml +DOJO_API_KEY=dojo_sk_... npm run dojo -- publish --file dojo.workflow.yaml +DOJO_API_KEY=dojo_sk_... npm run dojo -- fork --workflow jiagon-negotiator --name "My Repo Analyst" +DOJO_API_KEY=dojo_sk_... npm run dojo -- deploy --workflow my-repo-analyst --file dojo.workflow.yaml +DOJO_API_KEY=dojo_sk_... npm run dojo -- run --service jiagon-negotiator --input '{"repo_url":"https://github.com/garrytan/gbrain"}' ``` Use `DOJO_BASE_URL` or `--url` to point at a non-production Dojo instance: ```bash -DOJO_BASE_URL=http://localhost:3000 npx @maiat/dojo publish --file dojo.workflow.yaml +DOJO_BASE_URL=http://localhost:3000 npm run dojo -- publish --file dojo.workflow.yaml ``` For local demos from the repo, generate or reuse a DB-backed key: @@ -67,5 +71,5 @@ example_input: `SKILL.md` files with YAML frontmatter are also supported: ```bash -DOJO_API_KEY=dojo_sk_... npx @maiat/dojo publish --file SKILL.md +DOJO_API_KEY=dojo_sk_... npm run dojo -- publish --file SKILL.md ``` diff --git a/packages/dojo-mcp/README.md b/packages/dojo-mcp/README.md index ad7b832..0bbfc43 100644 --- a/packages/dojo-mcp/README.md +++ b/packages/dojo-mcp/README.md @@ -2,6 +2,10 @@ Minimal stdio MCP server for AgentShack clearing demos. +This is the retained Dojo workflow/receipt API, not the curated marketplace's +wallet hiring UI. Follow [local development](../../docs/development.md) first. +The run-service tool can execute a provider and write records; it is not read-only. + ## Tools - `agentshack_list_services` — list public services from `/api/v1/services` @@ -27,7 +31,7 @@ DOJO_BASE_URL=http://localhost:3000 DOJO_API_KEY=dojo_sk_... node packages/dojo- "mcpServers": { "dojo": { "command": "node", - "args": ["/Users/jhinresh/maiat-dojo/packages/dojo-mcp/dist/server.js"], + "args": ["/absolute/path/to/agentshack/packages/dojo-mcp/dist/server.js"], "env": { "DOJO_BASE_URL": "http://localhost:3000", "DOJO_API_KEY": "dojo_sk_..."