How munnavuyyuru/agentmarketplace-smart-contract works
1. Repository shape
- This is a three-part monorepo: a Solidity/Hardhat contract layer, a TypeScript backend API, and a React/Vite frontend.
- The central product appears to be an agent/service marketplace with on-chain transactions plus off-chain metadata, ratings, reputation, and deliverables.
2. On-chain subsystem
- The smart contract area is anchored by contracts/ and the compiled artifact backend/src/blockchain/AgentMarketplace.json.
- hardhat.config.ts and scripts/deploy.ts indicate Hardhat is used for compiling and deploying the marketplace contract.
- deployment/fuji.json suggests at least one target network is Avalanche Fuji, so chain deployment is part of the architecture, not just local testing.
3. Backend application boundary
- The backend is a Node.js + TypeScript API under backend/src.
- app.ts likely assembles middleware and routes; server.ts is the process entrypoint.
- Route modules separate the domain into agent, service, rating, reputation, dashboard, payment, and agentProfile, which is a strong hint that the backend is the orchestration layer for marketplace operations.
4. Backend controller structure
- Controllers under backend/src/controllers map HTTP requests to domain actions.
- agent.controller.ts, service.controller.ts, payment.controller.ts, rating.controller.ts, reputation.controller.ts, and dashboard.controller.ts imply the backend exposes CRUD-like and workflow endpoints for marketplace entities and user-facing dashboards.
- paid.routes.ts stands out as a protected API surface for paid operations.
5. Payment and access-control flow
- backend/src/middleware/x402.middleware.ts indicates the backend enforces a payment-related gate, likely before allowing access to certain paid routes.
- The presence of payment.controller.ts and paid.routes.ts suggests a request flow where a client calls the API, payment or entitlement is checked, and only then the protected service is executed.
6. Blockchain integration layer
- backend/src/blockchain/contract.ts is the backend’s abstraction for interacting with the smart contract.
- execution.service.ts and serviceInvocation.service.ts suggest the backend can both submit on-chain transactions and invoke service logic tied to marketplace execution.
- eventSync.service.ts and backfill.service.ts indicate the backend also consumes chain events and can replay historical events to reconstruct or repair off-chain state.
7. Off-chain state and persistence
- backend/src/config/supabase.ts shows the backend uses Supabase for persistence or auxiliary data storage.
- env.ts centralizes runtime configuration, so the backend likely depends on environment-driven secrets for both blockchain and database connectivity.
- This creates a split architecture: chain for trust/minimal settlement, Supabase for indexed app data, profiles, ratings, and dashboards.
8. Frontend application boundary
- The frontend is a React + TypeScript + Vite app in frontend/src.
- main.tsx, App.tsx, and layouts/HomeLayout.tsx establish the UI shell, while pages handle user journeys such as HomePage, ServicePage, AgentProfilePage, CreateServicePage, PurchasesPage, and DeliverablePage.
- services/api.ts is the frontend’s API boundary to the backend, so the UI does not talk to blockchain directly in the visible structure.
9. Frontend component model
- Shared UI components include ServiceCard, ReviewCard, ReputationCard, DynamicForm, and ResponseRenderer.
- That suggests the frontend is designed around marketplace browsing plus interactive submission of service parameters and display of structured outputs or deliverables.
- Navbar.tsx and the CSS files indicate a fairly standard client-side SPA layout rather than server-rendered pages.
10. Domain model implied by the UI and API
- The top-level concepts are agents, services, profiles, ratings/reviews, reputation, payments, and deliverables.
- The architecture likely supports a lifecycle of: create agent/service → publish to marketplace → pay for access or purchase → execute/invoke service → receive deliverable → rate/repute the provider.
- dashboard suggests aggregated state across these entities for a user or operator view.
11. Operational scripts and developer workflow
- Root scripts/ includes deploy.ts, set-backend.ts, register-buyer.ts, test-agent.ts, test-service.ts, and check-backend.ts.
- These scripts imply operational tasks for wiring the backend to contract addresses, registering actors, and validating service/agent behavior across the chain/backend boundary.
- backend/src/test-x402.ts also hints at direct testing of the payment gate or paid-route mechanism.
12. Most important architectural boundary
- The key boundary in this repository is between trusted on-chain contract state and off-chain application services.
- The backend bridges that gap by syncing chain events, invoking contract methods, enforcing paid access, and storing extra metadata in Supabase.
- The frontend is purely a consumer of the backend API and is responsible for presenting marketplace state and initiating user actions.
13. How to draw the diagram
- Show three major tiers: frontend SPA, backend API/orchestration, and blockchain + deployment artifacts.
- Add Supabase as a separate persistence dependency off the backend.
- Highlight event flow from chain to backend sync services, and request flow from frontend to backend routes, with paid endpoints guarded by x402 middleware.
Main entry points: api.ts API client · HomeLayout.tsx Home layout · AgentMarketplace.json Marketplace contract · service.routes.ts Route layer
Components 26
Frontend SPA
React/Vite client for browsing agents, services, purchases, and deliverables.
- App shell · Bootstraps the client application and global UI shell.
frontend/src/main.tsx - Home layout · Provides the main page structure and navigation chrome.
frontend/src/layouts/HomeLayout.tsx - Home page · Landing and discovery view for the marketplace.
frontend/src/pages/HomePage.tsx - Service page · Service browsing and service detail experience.
frontend/src/pages/ServicePage.tsx - Agent profile · Shows an agent's profile, reputation, and related marketplace data.
frontend/src/pages/AgentProfilePage.tsx - Create service · UI for publishing or editing marketplace services.
frontend/src/pages/CreateServicePage.tsx - Purchases · User view for purchased items and transaction history.
frontend/src/pages/PurchasesPage.tsx - Deliverable · Displays service output or produced deliverables.
frontend/src/pages/DeliverablePage.tsx - API client · Frontend boundary to the backend API.
frontend/src/services/api.ts
Backend API
TypeScript orchestration layer for marketplace operations and paid access.
- Server entry · Starts the backend process.
backend/src/server.ts - App assembly · Composes middleware, routes, and runtime wiring.
backend/src/app.ts - Route layer · Domain route modules for marketplace operations.
backend/src/routes/service.routes.ts - Controllers · HTTP-to-domain adapters for agents, services, ratings, reputation, payments, and dashboard views.
backend/src/controllers/service.controller.ts - Paid access · Protected route surface for entitlement-gated operations.
backend/src/routes/paid.routes.ts - x402 guard · Enforces payment-related access control on protected requests.
backend/src/middleware/x402.middleware.ts - Contract bridge · Backend abstraction for interacting with the marketplace contract.
backend/src/blockchain/contract.ts - Event sync · Consumes chain events to update off-chain state.
backend/src/services/eventSync.service.ts - Backfill · Replays historical events to repair or reconstruct state.
backend/src/services/backfill.service.ts - Execution · Coordinates service execution and on-chain or off-chain work.
backend/src/services/execution.service.ts - Service invoke · Triggers service logic tied to marketplace requests.
backend/src/services/serviceInvocation.service.ts - Supabase · Off-chain storage for indexed marketplace data and metadata.
backend/src/config/supabase.ts
Chain Layer
Smart contracts, compiled artifacts, and deployment targets.
- Marketplace contract · Compiled on-chain marketplace artifact used by the backend.
backend/src/blockchain/AgentMarketplace.json - Fuji deploy · Deployment target configuration for Avalanche Fuji.
deployment/fuji.json
Ops Scripts
Developer and deployment workflows that connect backend and chain.
- Deploy script · Deploys the marketplace contract.
scripts/deploy.ts - Set backend · Wires backend configuration to deployed chain addresses.
scripts/set-backend.ts - Register buyer · Registers buyer-side actors for marketplace flows.
scripts/register-buyer.ts
Connections 34
- App shell → Home layout: renders · The app shell mounts the primary layout and navigation.
- Home layout → Home page: navigates to · Home layout routes users into the marketplace landing page.
- Home layout → Service page: navigates to · Layout hosts service discovery and detail views.
- Home layout → Agent profile: navigates to · Layout exposes agent profile pages.
- Home layout → Create service: navigates to · Layout provides access to publishing flows.
- Home layout → Purchases: navigates to · Layout exposes purchase history and account views.
- Home layout → Deliverable: navigates to · Layout leads to deliverable/result views.
- Home page → API client: loads data · Home page fetches marketplace state through the API client.
- Service page → API client: loads data · Service pages use the backend API for service details and actions.
- Agent profile → API client: loads data · Profile pages request agent metadata and reputation data.
- Create service → API client: submits · Create-service flow sends marketplace mutations to the backend.
- Purchases → API client: loads data · Purchases view reads user-specific marketplace state.
- Deliverable → API client: loads data · Deliverable page fetches produced outputs from the backend.
- Server entry → App assembly: starts · Server entry initializes the application assembly.
- App assembly → Route layer: mounts · App assembly registers domain route modules.
- Route layer → Controllers: dispatches to · Routes forward requests to controller handlers.
- Route layer → Paid access: includes · Route set includes protected paid-operation endpoints.
- Paid access → x402 guard: guards with · Paid routes are protected by payment middleware.
- Controllers → Contract bridge: uses · Controllers call into the blockchain adapter when contract state is involved.
- Controllers → Supabase: stores/reads · Controllers and services persist off-chain marketplace data in Supabase.
- Contract bridge → Marketplace contract: targets · Backend adapter speaks to the marketplace contract artifact.
- Event sync → Supabase: writes · Event sync updates indexed off-chain state.
- Backfill → Event sync: repairs · Backfill reuses sync logic to replay historical chain activity.
- Execution → Contract bridge: submits · Execution layer submits contract interactions.
- Execution → Service invoke: orchestrates · Execution coordinates service invocation flows.
- Service invoke → Supabase: reads/writes · Invocation services use persistent metadata and outputs.
- Fuji deploy → Marketplace contract: deploys · Deployment configuration targets the compiled marketplace contract.
- Deploy script → Marketplace contract: builds/deploys · Deploy script compiles and deploys the contract.
- Set backend → Contract bridge: configures · Operational script connects the backend to the deployed contract.
- Register buyer → Paid access: prepares · Buyer registration supports paid access and purchase flows.
- API client → Route layer: calls · The client talks to backend route endpoints over HTTP.
- API client → Paid access: accesses · Paid client actions reach protected backend endpoints.
- Event sync → Marketplace contract: listens to · Event sync consumes chain activity from the marketplace contract.
- Backfill → Marketplace contract: replays · Backfill reconstructs state from historical contract events.