z0gcode 0.2.0

package/skills/0g/CHAIN.md

@@ -0,0 +1,229 @@
+# Chain Patterns
+
+EVM patterns, deployment configurations, and best practices for 0G Chain.
+
+## Overview
+
+0G Chain is an EVM-compatible Layer 1 blockchain. It supports standard Solidity smart contracts with
+a critical requirement: **all contracts must be compiled with `evmVersion: "cancun"`**.
+
+## Hardhat Configuration
+
+```typescript
+// hardhat.config.ts
+import { HardhatUserConfig } from 'hardhat/config';
+import '@nomicfoundation/hardhat-toolbox';
+import 'dotenv/config';
+
+const config: HardhatUserConfig = {
+  solidity: {
+    version: '0.8.24',
+    settings: {
+      optimizer: { enabled: true, runs: 200 },
+      evmVersion: 'cancun', // REQUIRED for 0G Chain
+    },
+  },
+  networks: {
+    '0g-testnet': {
+      url: 'https://evmrpc-testnet.0g.ai',
+      chainId: 16602,
+      accounts: [process.env.PRIVATE_KEY!],
+    },
+    '0g-mainnet': {
+      url: 'https://evmrpc.0g.ai',
+      chainId: 16661,
+      accounts: [process.env.PRIVATE_KEY!],
+    },
+  },
+};
+
+export default config;
+```
+
+## Foundry Configuration
+
+```toml
+# foundry.toml
+[profile.default]
+src = "src"
+out = "out"
+libs = ["lib"]
+evm_version = "cancun"  # REQUIRED for 0G Chain
+solc_version = "0.8.24"
+optimizer = true
+optimizer_runs = 200
+
+[rpc_endpoints]
+0g_testnet = "https://evmrpc-testnet.0g.ai"
+0g_mainnet = "https://evmrpc.0g.ai"
+```
+
+## Contract Deployment
+
+### With Hardhat
+
+```typescript
+// scripts/deploy.ts
+import { ethers } from 'hardhat';
+
+async function main() {
+  const [deployer] = await ethers.getSigners();
+  console.log('Deploying with:', deployer.address);
+
+  const Contract = await ethers.getContractFactory('MyContract');
+  const contract = await Contract.deploy(/* constructor args */);
+  await contract.waitForDeployment();
+
+  const address = await contract.getAddress();
+  console.log('Deployed to:', address);
+}
+
+main().catch(console.error);
+```
+
+```bash
+npx hardhat run scripts/deploy.ts --network 0g-testnet
+```
+
+### With Foundry
+
+```bash
+forge create src/MyContract.sol:MyContract \
+  --rpc-url https://evmrpc-testnet.0g.ai \
+  --private-key $PRIVATE_KEY \
+  --constructor-args "arg1" "arg2"
+```
+
+### With ethers v6 (Direct)
+
+```typescript
+import { ethers, ContractFactory } from 'ethers';
+import 'dotenv/config';
+
+const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
+const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
+
+// ABI and bytecode from compilation output
+const factory = new ContractFactory(abi, bytecode, wallet);
+const contract = await factory.deploy(/* constructor args */);
+await contract.waitForDeployment();
+
+console.log('Deployed to:', await contract.getAddress());
+```
+
+## Contract Interaction
+
+### Read (View Functions)
+
+```typescript
+import { ethers } from 'ethers';
+
+const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
+const contract = new ethers.Contract(contractAddress, abi, provider);
+
+// Read-only calls (no gas)
+const value = await contract.getValue();
+const balance = await contract.balanceOf(address);
+```
+
+### Write (State-Changing Functions)
+
+```typescript
+const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
+const contract = new ethers.Contract(contractAddress, abi, wallet);
+
+// State-changing calls (costs gas)
+const tx = await contract.setValue(42);
+const receipt = await tx.wait();
+console.log('Tx hash:', receipt.hash);
+```
+
+### Events
+
+```typescript
+// Listen for events
+contract.on('Transfer', (from, to, amount) => {
+  console.log(`Transfer: ${from} → ${to}: ${amount}`);
+});
+
+// Query past events
+const filter = contract.filters.Transfer(null, myAddress);
+const events = await contract.queryFilter(filter, fromBlock, toBlock);
+```
+
+## ethers v6 Migration Notes
+
+0G Chain examples use ethers v6 exclusively. Key differences from v5:
+
+| v5 (DO NOT USE)                    | v6 (CORRECT)                   |
+| ---------------------------------- | ------------------------------ |
+| `ethers.providers.JsonRpcProvider` | `ethers.JsonRpcProvider`       |
+| `ethers.utils.parseEther`          | `ethers.parseEther`            |
+| `ethers.utils.formatEther`         | `ethers.formatEther`           |
+| `contract.deployed()`              | `contract.waitForDeployment()` |
+| `contract.address`                 | `await contract.getAddress()`  |
+| `BigNumber.from()`                 | Native `BigInt`                |
+| `ethers.utils.keccak256`           | `ethers.keccak256`             |
+
+## Gas Estimation
+
+```typescript
+const gasEstimate = await contract.setValue.estimateGas(42);
+console.log('Estimated gas:', gasEstimate.toString());
+
+// With manual gas limit
+const tx = await contract.setValue(42, {
+  gasLimit: (gasEstimate * 120n) / 100n, // 20% buffer
+});
+```
+
+## Verification
+
+### Hardhat Verify
+
+```bash
+npx hardhat verify --network 0g-testnet <CONTRACT_ADDRESS> "arg1" "arg2"
+```
+
+### Foundry Verify
+
+```bash
+forge verify-contract <CONTRACT_ADDRESS> src/MyContract.sol:MyContract \
+  --chain-id 16602 \
+  --verifier-url https://chainscan-galileo.0g.ai/api
+```
+
+## Critical Rules
+
+### ALWAYS
+
+- Use `evmVersion: "cancun"` in compiler settings
+- Use ethers v6 syntax (NOT v5)
+- Load private keys from environment variables
+- Wait for transaction confirmation (`tx.wait()`)
+- Test on testnet before mainnet deployment
+
+### NEVER
+
+- Use `evmVersion` other than `"cancun"` for 0G Chain
+- Use ethers v5 patterns (`ethers.providers`, `ethers.utils`, etc.)
+- Hardcode private keys in source files
+- Deploy to mainnet without testnet validation
+
+## Common Errors
+
+| Error                 | Cause                | Fix                             |
+| --------------------- | -------------------- | ------------------------------- |
+| `invalid opcode`      | Wrong evmVersion     | Set `evmVersion: "cancun"`      |
+| `execution reverted`  | Contract logic error | Check require/revert conditions |
+| `insufficient funds`  | Wallet empty         | Fund from faucet (testnet)      |
+| `nonce too low`       | Pending tx           | Wait or manually set nonce      |
+| `cannot estimate gas` | Function will revert | Check function parameters       |
+
+## References
+
+- [0G Chain Docs](https://docs.0g.ai/build-with-0g/0g-chain)
+- [Hardhat Documentation](https://hardhat.org/docs)
+- [Foundry Documentation](https://book.getfoundry.sh)
+- [ethers v6 Migration](https://docs.ethers.org/v6/migrating/)
+- See also: [NETWORK_CONFIG.md](./NETWORK_CONFIG.md), [SECURITY.md](./SECURITY.md)

package/skills/0g/COMPUTE.md

@@ -0,0 +1,296 @@
+# Compute Patterns
+
+Architecture, broker lifecycle, processResponse() deep-dive, and best practices for 0G decentralized
+compute.
+
+## Architecture Overview
+
+```
+┌────────────────────────────────────┐
+│         Your Application           │
+├────────────────────────────────────┤
+│     0G Serving Broker SDK          │
+│  (@0glabs/0g-serving-broker)       │
+├────────────────────────────────────┤
+│      Provider Network              │
+│  (TEE-verified GPU nodes)          │
+├────────────────────────────────────┤
+│       0G Chain                     │
+│  (Settlement & verification)       │
+└────────────────────────────────────┘
+```
+
+## Service Types
+
+| Type             | Endpoint Path           | Models                              | Use Case            |
+| ---------------- | ----------------------- | ----------------------------------- | ------------------- |
+| `chatbot`        | `/chat/completions`     | DeepSeek V3.1, Qwen, Gemma, GPT-OSS | Conversational AI   |
+| `text-to-image`  | `/images/generations`   | Flux Turbo                          | Image generation    |
+| `speech-to-text` | `/audio/transcriptions` | Whisper Large V3                    | Audio transcription |
+
+## Broker Lifecycle
+
+### 1. Initialize Broker
+
+```typescript
+import { ethers } from 'ethers';
+import { createZGComputeNetworkBroker } from '@0glabs/0g-serving-broker';
+
+const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
+const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
+const broker = await createZGComputeNetworkBroker(wallet);
+```
+
+### 2. Discover Providers
+
+```typescript
+const services = await broker.inference.listService();
+
+// Services are returned as tuple arrays:
+//   [0] = providerAddress, [1] = serviceType, [2] = url,
+//   [6] = model, [10] = teeVerified
+const chatbotServices = services.filter((s: any) => s[1] === 'chatbot');
+const imageServices = services.filter((s: any) => s[1] === 'text-to-image');
+const speechServices = services.filter((s: any) => s[1] === 'speech-to-text');
+
+// Access provider info: s[0] = address, s[6] = model, s[10] = TEE verified
+```
+
+### 3. Fund Account
+
+```typescript
+// Deposit to main account
+await broker.ledger.depositFund(10);
+
+// Transfer to provider sub-account
+await broker.ledger.transferFund(providerAddress, 'inference', ethers.parseEther('5'));
+
+// Acknowledge provider (one-time per provider)
+await broker.inference.acknowledgeProviderSigner(providerAddress);
+```
+
+### 4. Get Service Metadata
+
+```typescript
+const { endpoint, model } = await broker.inference.getServiceMetadata(providerAddress);
+```
+
+### 5. Generate Auth Headers
+
+```typescript
+// For chatbot (no body needed)
+const headers = await broker.inference.getRequestHeaders(providerAddress);
+
+// For text-to-image (body MUST be included for signing)
+const headers = await broker.inference.getRequestHeaders(
+  providerAddress,
+  JSON.stringify(requestBody),
+);
+```
+
+### 6. Make Request & Process Response
+
+See the processResponse() section below — this is the most critical step.
+
+## processResponse() Deep-Dive
+
+**This is the most important function in the 0G Compute SDK.** It MUST be called after every
+inference request for fee settlement and response verification.
+
+### Signature
+
+```typescript
+await broker.inference.processResponse(
+  providerAddress, // string — provider's Ethereum address
+  chatID, // string | undefined — response identifier
+  usageData, // string | undefined — JSON-stringified usage stats
+);
+```
+
+### Parameter Order is CRITICAL
+
+```
+processResponse(providerAddress, chatID, usageData)
+                 ↑ FIRST           ↑ SECOND  ↑ THIRD
+```
+
+Getting the order wrong will cause silent fee miscalculation.
+
+### ChatID Extraction Rules
+
+| Service Type            | Primary Source                       | Fallback                        |
+| ----------------------- | ------------------------------------ | ------------------------------- |
+| Chatbot (non-streaming) | `response.headers.get("ZG-Res-Key")` | `data.id` from response body    |
+| Chatbot (streaming)     | `response.headers.get("ZG-Res-Key")` | `message.id` from stream chunks |
+| Text-to-Image           | `response.headers.get("ZG-Res-Key")` | None                            |
+| Speech-to-Text          | `response.headers.get("ZG-Res-Key")` | None                            |
+
+**ALWAYS check headers first, body as fallback (chatbot only):**
+
+```typescript
+let chatID = response.headers.get('ZG-Res-Key') || response.headers.get('zg-res-key');
+if (!chatID) {
+  chatID = data.id; // Fallback for chatbot only
+}
+```
+
+### Usage Data by Service Type
+
+| Service Type   | Usage Data Required | Format                       |
+| -------------- | ------------------- | ---------------------------- |
+| Chatbot        | Yes                 | `JSON.stringify(data.usage)` |
+| Text-to-Image  | No                  | Omit or pass `undefined`     |
+| Speech-to-Text | Yes (if available)  | `JSON.stringify(data.usage)` |
+
+### Complete Examples
+
+#### Chatbot processResponse
+
+```typescript
+const data = await response.json();
+let chatID = response.headers.get('ZG-Res-Key') || response.headers.get('zg-res-key');
+if (!chatID) chatID = data.id;
+
+await broker.inference.processResponse(providerAddress, chatID, JSON.stringify(data.usage));
+```
+
+#### Text-to-Image processResponse
+
+```typescript
+const chatID = response.headers.get('ZG-Res-Key') || response.headers.get('zg-res-key');
+
+if (chatID) {
+  await broker.inference.processResponse(providerAddress, chatID);
+}
+```
+
+#### Speech-to-Text processResponse
+
+```typescript
+const data = await response.json();
+const chatID = response.headers.get('ZG-Res-Key') || response.headers.get('zg-res-key');
+
+await broker.inference.processResponse(
+  providerAddress,
+  chatID,
+  data.usage ? JSON.stringify(data.usage) : undefined,
+);
+```
+
+## Streaming Pattern
+
+```typescript
+const response = await fetch(`${endpoint}/chat/completions`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json', ...headers },
+  body: JSON.stringify({ messages, model, stream: true }),
+});
+
+let chatID = response.headers.get('ZG-Res-Key') || response.headers.get('zg-res-key');
+let usage = null;
+let streamChatID = null;
+
+const decoder = new TextDecoder();
+const reader = response.body!.getReader();
+let rawBody = '';
+
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  const chunk = decoder.decode(value, { stream: true });
+  rawBody += chunk;
+  process.stdout.write(chunk); // Real-time output
+}
+
+// Parse stream for chatID fallback and usage
+for (const line of rawBody.split('\n')) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed === 'data: [DONE]') continue;
+  try {
+    const jsonStr = trimmed.startsWith('data:') ? trimmed.slice(5).trim() : trimmed;
+    const message = JSON.parse(jsonStr);
+    if (!streamChatID && message.id) streamChatID = message.id;
+    if (message.usage) usage = message.usage;
+  } catch {}
+}
+
+const finalChatID = chatID || streamChatID;
+await broker.inference.processResponse(providerAddress, finalChatID, JSON.stringify(usage || {}));
+```
+
+## Account Structure
+
+```
+Your Wallet
+    ↓ deposit
+Main Account
+    ↓ transfer-fund
+Provider Sub-Accounts (one per provider)
+    ↓ service usage (auto-deducted)
+    ↓ retrieve-fund (24h lock)
+Main Account
+    ↓ refund
+Your Wallet
+```
+
+## TEE Verification
+
+Trusted Execution Environment verification ensures provider integrity:
+
+```typescript
+const services = await broker.inference.listService();
+// Tuple: [0]=providerAddress, [1]=serviceType, [10]=teeVerified
+for (const service of services) {
+  if (service[0] === targetProvider) {
+    console.log('TEE verified:', service[10]);
+  }
+}
+```
+
+## CLI Commands Reference
+
+| Action               | Command                                                           |
+| -------------------- | ----------------------------------------------------------------- |
+| Setup network        | `0g-compute-cli setup-network`                                    |
+| Login                | `0g-compute-cli login`                                            |
+| Deposit              | `0g-compute-cli deposit --amount 10`                              |
+| Check balance        | `0g-compute-cli get-account`                                      |
+| Transfer to provider | `0g-compute-cli transfer-fund --provider <ADDR> --amount 5`       |
+| Acknowledge provider | `0g-compute-cli inference acknowledge-provider --provider <ADDR>` |
+| List providers       | `0g-compute-cli inference list-providers`                         |
+| Start local proxy    | `0g-compute-cli inference serve --provider <ADDR>`                |
+| Get API secret       | `0g-compute-cli inference get-secret --provider <ADDR>`           |
+
+## Critical Rules
+
+### ALWAYS
+
+- Call `processResponse()` after EVERY inference request
+- Use correct parameter order: `(providerAddress, chatID, usageData)`
+- Extract ChatID from `ZG-Res-Key` header first, body as fallback
+- Acknowledge provider before first use
+- Check balance before making requests
+
+### NEVER
+
+- Skip `processResponse()` — causes fee settlement failure
+- Reverse the parameter order of `processResponse()`
+- Hardcode private keys
+- Use ethers v5 syntax (use v6)
+- Skip provider acknowledgment
+
+## Common Errors
+
+| Error                       | Cause                            | Fix                                            |
+| --------------------------- | -------------------------------- | ---------------------------------------------- |
+| `Insufficient balance`      | Sub-account empty                | Transfer funds: `broker.ledger.transferFund()` |
+| `Provider not acknowledged` | First-time use                   | `broker.inference.acknowledgeProviderSigner()` |
+| `Invalid request headers`   | Stale auth                       | Re-call `getRequestHeaders()`                  |
+| `Fee verification failed`   | Wrong `processResponse()` params | Check param order and chatID source            |
+| `Connection refused`        | Wrong RPC URL                    | Verify RPC_URL in .env                         |
+
+## References
+
+- [0G Compute SDK Docs](https://docs.0g.ai/build-with-0g/compute-network/sdk)
+- [0G Serving Broker](https://github.com/0gfoundation/0g-serving-broker)
+- See also: [NETWORK_CONFIG.md](./NETWORK_CONFIG.md), [SECURITY.md](./SECURITY.md)

package/skills/0g/NETWORK_CONFIG.md

@@ -0,0 +1,163 @@
+# Network Configuration
+
+Single source of truth for all 0G network endpoints, chain IDs, SDK versions, and environment setup.
+
+## Network Environments
+
+### Testnet (Galileo — Recommended for Development)
+
+| Parameter       | Value                                         |
+| --------------- | --------------------------------------------- |
+| Network Name    | 0G-Galileo-Testnet                            |
+| RPC Endpoint    | `https://evmrpc-testnet.0g.ai`                |
+| Chain ID        | `16602`                                       |
+| Currency Symbol | 0G                                            |
+| Block Explorer  | `https://chainscan-galileo.0g.ai`             |
+| Storage RPC     | `https://storagerpc-testnet.0g.ai`            |
+| Storage Indexer | `https://indexer-storage-testnet-turbo.0g.ai` |
+
+### Mainnet (Aristotle)
+
+| Parameter       | Value                                 |
+| --------------- | ------------------------------------- |
+| Network Name    | 0G Mainnet                            |
+| RPC Endpoint    | `https://evmrpc.0g.ai`                |
+| Chain ID        | `16661`                               |
+| Currency Symbol | 0G                                    |
+| Block Explorer  | `https://chainscan.0g.ai`             |
+| Storage RPC     | `https://storagerpc.0g.ai`            |
+| Storage Indexer | `https://indexer-storage-turbo.0g.ai` |
+
+## SDK Versions
+
+| Package                     | Version   | Purpose                                     |
+| --------------------------- | --------- | ------------------------------------------- |
+| `@0glabs/0g-ts-sdk`         | `^0.3.3`  | Storage operations (upload, download)       |
+| `@0glabs/0g-serving-broker` | `^0.6.5`  | Compute operations (inference, fine-tuning) |
+| `ethers`                    | `^6.13.0` | Chain interaction (MUST be v6, NOT v5)      |
+| `dotenv`                    | `^16.4.0` | Environment variable management             |
+
+## Environment Variables Template
+
+```bash
+# .env — NEVER commit this file
+
+# Network Configuration
+RPC_URL=https://evmrpc-testnet.0g.ai
+CHAIN_ID=16602
+
+# Wallet (NEVER hardcode in source files)
+PRIVATE_KEY=your_private_key_here
+
+# Storage Endpoints
+STORAGE_INDEXER=https://indexer-storage-testnet-turbo.0g.ai
+
+# Compute
+PROVIDER_ADDRESS=your_provider_address
+
+# Optional
+OUTPUT_DIR=./output
+```
+
+## SDK Initialization Patterns
+
+### ethers v6 Provider (Chain)
+
+```typescript
+import { ethers } from 'ethers';
+import 'dotenv/config';
+
+const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
+const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
+```
+
+### Storage Client
+
+```typescript
+import { ZgFile, Indexer } from '@0glabs/0g-ts-sdk';
+import { ethers } from 'ethers';
+
+const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
+const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
+const indexer = new Indexer(process.env.STORAGE_INDEXER!);
+```
+
+### Compute Broker
+
+```typescript
+import { ethers } from 'ethers';
+import { createZGComputeNetworkBroker } from '@0glabs/0g-serving-broker';
+
+const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
+const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
+const broker = await createZGComputeNetworkBroker(wallet);
+```
+
+### Browser Environment (Compute)
+
+```typescript
+import { BrowserProvider } from 'ethers';
+import { createZGComputeNetworkBroker } from '@0glabs/0g-serving-broker';
+
+if (typeof window.ethereum === 'undefined') {
+  throw new Error('Please install MetaMask');
+}
+
+const provider = new BrowserProvider(window.ethereum);
+const signer = await provider.getSigner();
+const broker = await createZGComputeNetworkBroker(signer);
+```
+
+## Browser Polyfills
+
+When using 0G SDKs in browser environments:
+
+```bash
+pnpm add -D vite-plugin-node-polyfills
+```
+
+```javascript
+// vite.config.js
+import { nodePolyfills } from 'vite-plugin-node-polyfills';
+
+export default {
+  plugins: [
+    nodePolyfills({
+      include: ['crypto', 'stream', 'util', 'buffer', 'process'],
+      globals: { Buffer: true, global: true, process: true },
+    }),
+  ],
+};
+```
+
+## Network Selection Helper
+
+```typescript
+type Network = 'testnet' | 'mainnet';
+
+function getNetworkConfig(network: Network) {
+  const configs = {
+    testnet: {
+      rpcUrl: 'https://evmrpc-testnet.0g.ai',
+      chainId: 16602,
+      storageRpc: 'https://storagerpc-testnet.0g.ai',
+      storageIndexer: 'https://indexer-storage-testnet-turbo.0g.ai',
+      explorer: 'https://chainscan-galileo.0g.ai',
+    },
+    mainnet: {
+      rpcUrl: 'https://evmrpc.0g.ai',
+      chainId: 16661,
+      storageRpc: 'https://storagerpc.0g.ai',
+      storageIndexer: 'https://indexer-storage-turbo.0g.ai',
+      explorer: 'https://chainscan.0g.ai',
+    },
+  };
+  return configs[network];
+}
+```
+
+## References
+
+- [0G Testnet Info](https://docs.0g.ai/run-a-node/testnet-information)
+- [0G Storage SDK](https://docs.0g.ai/build-with-0g/storage-network/sdk)
+- [0G Compute SDK](https://docs.0g.ai/build-with-0g/compute-network/sdk)