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
)
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
)
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 WalrusGET /api/walrus/blobs/:blobId
- Retrieve data from Walrus
NFT Operations
POST /api/nft/publish
- Publish NFT metadataPOST /api/nft/mint
- Mint new access tokenPOST /api/nft/use/:tokenId
- Use agent with tokenGET /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