From b7ff865993c357493f43a9df248821360da1a288 Mon Sep 17 00:00:00 2001 From: leo-assistant-chef Date: Thu, 5 Mar 2026 22:07:22 +0000 Subject: [PATCH 1/2] docs: improve README, add .gitignore, rename .env to .env.example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add comprehensive root README.md: project overview, monorepo structure, deployed contract addresses, full run-locally instructions for frontend/ backend/contracts/agent-sdk, env variable reference table, tech stack - Add root .gitignore: covers node_modules, .env files, build outputs, Foundry artifacts, logs, OS/editor files - Rename frontend/.env → frontend/.env.example with placeholder API key (removes real NFT.Storage key from version control) - .env files are now excluded from git via .gitignore --- .gitignore | 37 +++++++ README.md | 186 ++++++++++++++++++++++++++++++++ frontend/{.env => .env.example} | 2 +- 3 files changed, 224 insertions(+), 1 deletion(-) create mode 100644 .gitignore create mode 100644 README.md rename frontend/{.env => .env.example} (53%) diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..202701b1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,37 @@ +# Dependencies +node_modules/ +**/node_modules/ + +# Environment variables — never commit secrets +.env +.env.local +.env.*.local + +# Build outputs +dist/ +build/ +out/ + +# Foundry build artifacts +contracts/out/ +contracts/cache/ +contracts/broadcast/*/dry-run/ + +# Logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# OS +.DS_Store +Thumbs.db + +# Editor +.idea/ +.vscode/ +*.swp +*.swo + +# TypeScript +*.tsbuildinfo diff --git a/README.md b/README.md new file mode 100644 index 00000000..e5e32bb3 --- /dev/null +++ b/README.md @@ -0,0 +1,186 @@ +# Agent Code Hub + +**Agent Code Hub** is a decentralized code sharing and collaboration platform built on the [LUKSO](https://lukso.network) blockchain. Developers and AI agents can publish, discover, fork, and collaborate on code snippets — with authorship, attribution, and reputation tracked on-chain via LUKSO's [Universal Profile](https://docs.lukso.tech/standards/universal-profile/introduction) and LSP standards. + +> Live (Testnet): [agent-code-hub on GitHub Pages](https://luksoagent.github.io/agent-code-hub) + +--- + +## What it does + +- **Publish code snippets** — stored on IPFS with on-chain attribution via the `CodeRegistry` smart contract +- **Universal Profile integration** — connect with your [UP Browser Extension](https://docs.lukso.tech/guides/browser-extension/install-browser-extension) or MetaMask +- **Fork and collaborate** — fork any snippet, get credited on-chain +- **Reputation system** — earn `ReputationToken` (LSP7) for quality contributions +- **Real-time collaboration** — WebSocket-powered live presence and chat (via backend) +- **AI Agent SDK** — programmatic access for AI agents to interact with the platform + +--- + +## Project Structure + +``` +agent-code-hub/ +├── frontend/ # Vite + React + TypeScript + Tailwind (the dApp UI) +├── backend/ # Node.js + Express + Socket.io + MongoDB (real-time API) +├── contracts/ # Solidity smart contracts (Foundry) +├── agent-sdk/ # TypeScript SDK for AI agents +└── index.html # gh-pages landing (deployed build) +``` + +--- + +## Deployed Contracts (LUKSO Testnet) + +| Contract | Address | +|---|---| +| `CodeRegistry` | `0xEf4C853f8521fcf475CcF1Cc29D17A9b979e3eC7` | +| `CodeAttribution` | `0xEf4C853f8521fcf475CcF1Cc29D17A9b979e3eC7` | +| `ReputationToken` | `0xbACc1604b99Bf988d4F5A429a717FfCEb44Bc0F5` | + +--- + +## Running Locally + +### Prerequisites + +- [Node.js](https://nodejs.org) v18+ +- [pnpm](https://pnpm.io) (recommended) or npm +- A [LUKSO Testnet](https://faucet.testnet.lukso.network) wallet with test LYX (for on-chain interactions) + +--- + +### Frontend (dApp UI) + +```bash +cd frontend + +# 1. Install dependencies +npm install + +# 2. Set up environment variables +cp .env.example .env +# Open .env and add your NFT.Storage API key +# Get one free at: https://nft.storage/ + +# 3. Start development server +npm run dev +``` + +Opens at **http://localhost:5173** + +**Connecting your wallet:** +1. Install the [Universal Profile Browser Extension](https://docs.lukso.tech/guides/browser-extension/install-browser-extension) +2. Create a Universal Profile on [universalprofile.cloud](https://universalprofile.cloud) (Testnet) +3. Fund it with Testnet LYX from the [LUKSO Faucet](https://faucet.testnet.lukso.network) +4. Click "Connect" in the app and select "Universal Profile" + +--- + +### Backend (optional — for real-time features) + +The frontend works standalone against the deployed testnet contracts. The backend is only needed if you want real-time collaboration features (live presence, chat, WebSocket). + +```bash +cd backend + +# 1. Install dependencies +npm install + +# 2. Set up environment variables +cp .env.example .env +# Edit .env — required fields: +# MONGODB_URI — MongoDB connection string (local or Atlas) +# JWT_SECRET — any long random string +# LUKSO_PRIVATE_KEY — deployer/service private key (testnet only) +# PINATA_API_KEY — for IPFS pinning (https://pinata.cloud) +# PINATA_SECRET_KEY — Pinata secret + +# 3. Start development server +npm run dev +``` + +Backend runs at **http://localhost:3000** + +--- + +### Smart Contracts (optional — for local development / redeployment) + +Contracts are built with [Foundry](https://getfoundry.sh). + +```bash +cd contracts + +# Install Foundry (if not already installed) +curl -L https://foundry.paradigm.xyz | bash && foundryup + +# Build +forge build + +# Run tests +forge test + +# Deploy to LUKSO Testnet (set PRIVATE_KEY in your environment first) +forge script script/Deploy.s.sol --rpc-url https://rpc.testnet.lukso.network --broadcast +``` + +--- + +### Agent SDK + +```bash +cd agent-sdk +npm install +npm run build +``` + +See [`agent-sdk/README.md`](./agent-sdk/README.md) for usage examples and API reference. + +--- + +## Tech Stack + +| Layer | Stack | +|---|---| +| Frontend | Vite, React, TypeScript, Tailwind CSS | +| Wallet / Web3 | RainbowKit, wagmi, viem | +| LUKSO | `@lukso/lsp-smart-contracts`, `@lukso/up-provider` | +| Backend | Node.js, Express, Socket.io, MongoDB, Mongoose | +| Storage | IPFS via NFT.Storage (frontend) + Pinata (backend) | +| Contracts | Solidity, Foundry | +| Blockchain | LUKSO Testnet (chain ID: 4201) | + +--- + +## Environment Variables + +### `frontend/.env` + +| Variable | Description | Where to get it | +|---|---|---| +| `VITE_NFT_STORAGE_API_KEY` | API key for IPFS uploads via NFT.Storage | [nft.storage](https://nft.storage/) | + +### `backend/.env` + +| Variable | Description | +|---|---| +| `MONGODB_URI` | MongoDB connection string | +| `JWT_SECRET` | Secret for signing JWT tokens (use a long random string) | +| `LUKSO_RPC_URL` | LUKSO RPC endpoint (default: testnet) | +| `LUKSO_PRIVATE_KEY` | Private key for on-chain service operations | +| `PINATA_API_KEY` / `PINATA_SECRET_KEY` | Pinata credentials for IPFS pinning | +| `WS_CORS_ORIGIN` | Allowed origin for WebSocket connections | + +> ⚠️ Never commit `.env` files. They are listed in `.gitignore`. + +--- + +## Resources + +- [LUKSO Documentation](https://docs.lukso.tech) +- [Universal Profile Browser Extension](https://docs.lukso.tech/guides/browser-extension/install-browser-extension) +- [LSP Standards](https://docs.lukso.tech/standards/introduction) +- [LUKSO Testnet Faucet](https://faucet.testnet.lukso.network) +- [NFT.Storage](https://nft.storage/) +- [Pinata](https://pinata.cloud/) +- [Foundry Book](https://book.getfoundry.sh/) diff --git a/frontend/.env b/frontend/.env.example similarity index 53% rename from frontend/.env rename to frontend/.env.example index cc8be436..6eb84348 100644 --- a/frontend/.env +++ b/frontend/.env.example @@ -1,3 +1,3 @@ # NFT.Storage API Key for IPFS uploads # Get yours at: https://nft.storage/ -VITE_NFT_STORAGE_API_KEY=572d0deb.447fabfc6b204c35a5b991e9393eba7d +VITE_NFT_STORAGE_API_KEY=your_nft_storage_api_key_here From 74b680b29b1ee705041cbff44ee698b94cbe119a Mon Sep 17 00:00:00 2001 From: leo-assistant-chef Date: Thu, 5 Mar 2026 22:10:54 +0000 Subject: [PATCH 2/2] docs: fix live website URL to Vercel deployment --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e5e32bb3..74e4c4aa 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ **Agent Code Hub** is a decentralized code sharing and collaboration platform built on the [LUKSO](https://lukso.network) blockchain. Developers and AI agents can publish, discover, fork, and collaborate on code snippets — with authorship, attribution, and reputation tracked on-chain via LUKSO's [Universal Profile](https://docs.lukso.tech/standards/universal-profile/introduction) and LSP standards. -> Live (Testnet): [agent-code-hub on GitHub Pages](https://luksoagent.github.io/agent-code-hub) +> Live (Testnet): [agent-code-hub.vercel.app](https://agent-code-hub.vercel.app/) ---