Mosaic Backend API

Overview

The Mosaic backend provides a RESTful API for the AI Agent Marketplace, integrating with Hedera blockchain and Walrus storage services.

Project Structure

src/backend/
├── index.js              # Main application entry point
├── services/             # Business logic services
│   ├── hederaService.js  # Hedera blockchain interactions
│   └── walrusService.js  # Walrus storage operations
├── routes/               # API route handlers
│   ├── walrusRoutes.js   # Walrus-related endpoints
│   └── nftRoutes.js      # NFT-related endpoints
├── package.json          # Dependencies and scripts
└── README.md            # This file

Services

HederaService (services/hederaService.js)

Handles all blockchain interactions with Hedera:

  • setTokenMetadataURI(tokenId, blobId): Links NFT metadata to Walrus blob

  • mintNFT(to, durationInSeconds): Creates new access tokens

  • useAgent(tokenId): Validates and uses agent access

  • getTokenExpiration(tokenId): Retrieves token expiration time

  • getTokenOwner(tokenId): Gets token owner address

WalrusService (services/walrusService.js)

Manages decentralized storage operations:

  • storeBlob(data): Stores data on Walrus network

  • readBlob(blobId): Retrieves data from Walrus

  • publishNFTMetadata(tokenId, metadata): Publishes NFT metadata

API Endpoints

Health Check

  • GET /health - API status and uptime

Walrus Operations

  • POST /api/walrus/blobs - Store data on Walrus

  • GET /api/walrus/blobs/:blobId - Retrieve data from Walrus

NFT Operations

  • POST /api/nft/publish - Publish NFT metadata

  • POST /api/nft/mint - Mint new access token

  • POST /api/nft/use/:tokenId - Use agent with token

  • GET /api/nft/token/:tokenId - Get token information

Environment Variables

Create a .env file in the backend directory:

PORT=3000
CONTRACT_ADDRESS=your_contract_address
PRIVATE_KEY=your_private_key
RPC_URL=your_hedera_rpc_url
CONTRACT_ABI=your_contract_abi

Installation & Running

# Install dependencies
npm install

# Start development server
npm run dev

# The API will be available at http://localhost:3000

API Response Examples

Health Check

{
  "status": "OK",
  "message": "Mosaic AI Agent Marketplace API is running",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Store Blob

{
  "message": "Blob stored successfully",
  "blobId": "abc123...",
  "storedDataPreview": "Data preview..."
}

Mint NFT

{
  "message": "NFT minted successfully",
  "to": "0x...",
  "durationInSeconds": 3600,
  "transactionHash": "0x..."
}

Error Handling

All endpoints include proper error handling with:

  • Input validation

  • Try-catch blocks

  • Consistent error response format

  • Detailed logging

Development

The codebase follows a modular architecture:

  • Separation of Concerns: Business logic in services, routing in routes

  • Reusability: Services can be imported and used across different routes

  • Maintainability: Easy to add new features or modify existing ones

  • Testability: Services can be unit tested independently

Integration

This backend integrates with:

  • Hedera Hashgraph: For blockchain operations

  • Walrus: For decentralized storage

  • Frontend: React application (port 3001)

  • Blockchain: Smart contracts for access control

Last updated