z0gcode 0.2.0

package/skills/0g/SECURITY.md

@@ -0,0 +1,174 @@
+# Security Patterns
+
+Cross-cutting security patterns for 0G development: key management, data integrity, contract
+security, and TEE verification.
+
+## Key Management
+
+### Environment Variables Pattern
+
+```bash
+# .env — NEVER commit this file
+PRIVATE_KEY=your_private_key_here
+RPC_URL=https://evmrpc-testnet.0g.ai
+```
+
+```typescript
+import 'dotenv/config';
+
+// CORRECT — load from environment
+const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
+
+// WRONG — hardcoded key (NEVER do this)
+// const wallet = new ethers.Wallet("0xabc123...", provider);
+```
+
+### .gitignore Requirements
+
+```gitignore
+# MUST be in .gitignore
+.env
+.env.local
+.env.*.local
+*.key
+*.pem
+```
+
+### Validation Pattern
+
+```typescript
+function validateEnv() {
+  const required = ['PRIVATE_KEY', 'RPC_URL'];
+  const missing = required.filter((key) => !process.env[key]);
+  if (missing.length > 0) {
+    throw new Error(`Missing environment variables: ${missing.join(', ')}`);
+  }
+}
+```
+
+## Data Integrity (Storage)
+
+### Verified Downloads
+
+```typescript
+// ALWAYS use verified=true in production
+await indexer.download(rootHash, outputPath, true);
+// Throws if Merkle proof verification fails
+```
+
+### Hash Verification
+
+```typescript
+import { ZgFile } from '@0glabs/0g-ts-sdk';
+
+async function verifyFile(filePath: string, expectedHash: string): Promise<boolean> {
+  const file = await ZgFile.fromFilePath(filePath);
+  try {
+    const [tree, err] = await file.merkleTree();
+    if (err) return false;
+    return tree.rootHash() === expectedHash;
+  } finally {
+    await file.close();
+  }
+}
+```
+
+## TEE Verification (Compute)
+
+Always verify provider TEE attestation before sensitive workloads:
+
+```typescript
+const services = await broker.inference.listService();
+const verifiedProviders = services.filter((s) => s.teeVerified === true);
+
+if (verifiedProviders.length === 0) {
+  throw new Error('No TEE-verified providers available');
+}
+```
+
+## Smart Contract Security
+
+### Access Control
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import "@openzeppelin/contracts/access/Ownable.sol";
+
+contract SecureStorage is Ownable {
+    mapping(bytes32 => address) public fileOwners;
+
+    function registerFile(bytes32 rootHash) external {
+        require(fileOwners[rootHash] == address(0), "Already registered");
+        fileOwners[rootHash] = msg.sender;
+    }
+
+    function verifyOwner(bytes32 rootHash, address owner) external view returns (bool) {
+        return fileOwners[rootHash] == owner;
+    }
+}
+```
+
+### Input Validation
+
+```solidity
+function store(bytes32 rootHash, string calldata metadata) external {
+    require(rootHash != bytes32(0), "Invalid root hash");
+    require(bytes(metadata).length > 0, "Empty metadata");
+    require(bytes(metadata).length <= 1024, "Metadata too long");
+    // ... storage logic
+}
+```
+
+## API Security
+
+### Rate Limiting Pattern
+
+```typescript
+const requestTimes: number[] = [];
+const MAX_REQUESTS = 10;
+const WINDOW_MS = 60_000;
+
+function checkRateLimit(): boolean {
+  const now = Date.now();
+  const windowStart = now - WINDOW_MS;
+  // Remove old entries
+  while (requestTimes.length > 0 && requestTimes[0] < windowStart) {
+    requestTimes.shift();
+  }
+  if (requestTimes.length >= MAX_REQUESTS) return false;
+  requestTimes.push(now);
+  return true;
+}
+```
+
+### Balance Check Before Operations
+
+```typescript
+async function ensureSufficientBalance(broker: any, minBalance: number) {
+  // getLedger() returns tuple: [0]=address, [1]=totalBalance, [2]=availableBalance
+  const account = await broker.ledger.getLedger();
+  const available = parseFloat(ethers.formatEther(account[2]));
+  if (available < minBalance) {
+    throw new Error(`Insufficient balance: ${available} 0G available, ${minBalance} 0G required`);
+  }
+}
+```
+
+## Checklist
+
+- [ ] Private keys loaded from `.env`, never hardcoded
+- [ ] `.env` is in `.gitignore`
+- [ ] All downloads use verified mode (`true`)
+- [ ] TEE verification checked for compute providers
+- [ ] Smart contracts use access control
+- [ ] Input validation on all public functions
+- [ ] Balance checked before operations
+- [ ] No secrets in logs or error messages
+
+## References
+
+- [OWASP Smart Contract Top 10](https://owasp.org/www-project-smart-contract-top-10/)
+- [OpenZeppelin Contracts](https://docs.openzeppelin.com/contracts)
+- See also: [NETWORK_CONFIG.md](./NETWORK_CONFIG.md)

package/skills/0g/STORAGE.md

@@ -0,0 +1,167 @@
+# Storage Patterns
+
+Architecture, SDK reference, and best practices for 0G decentralized storage.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────┐
+│          Log Layer              │
+│   (Raw file / blob storage)    │
+├─────────────────────────────────┤
+│       0G Consensus              │
+│   (Data availability proofs)   │
+└─────────────────────────────────┘
+```
+
+## Log Layer (File Storage)
+
+### Core Concepts
+
+- **ZgFile**: Represents a file in the 0G storage system
+- **Merkle Tree**: Every file is split into chunks and organized as a Merkle tree
+- **Root Hash**: The Merkle root — unique identifier for the file content
+- **Indexer**: Service that locates data across storage nodes
+
+### File Upload Lifecycle
+
+1. Create a `ZgFile` from local file path or buffer
+2. Generate the Merkle tree (computes root hash)
+3. Upload via the Indexer (distributes chunks to storage nodes)
+4. Store the root hash for later retrieval
+5. **Close the file handle** (critical — prevents memory leaks)
+
+### Upload Pattern
+
+```typescript
+import { ZgFile, Indexer } from '@0glabs/0g-ts-sdk';
+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);
+
+const indexer = new Indexer(process.env.STORAGE_INDEXER!);
+const file = await ZgFile.fromFilePath(filePath);
+
+try {
+  const [tree, err] = await file.merkleTree();
+  if (err) throw err;
+
+  const rootHash = tree!.rootHash();
+  console.log('Root hash:', rootHash);
+
+  const [tx, uploadErr] = await indexer.upload(file, process.env.RPC_URL!, wallet);
+  if (uploadErr) throw new Error(`Upload failed: ${uploadErr.message}`);
+  console.log('Upload tx:', tx);
+
+  return rootHash;
+} finally {
+  await file.close();
+}
+```
+
+### Download Pattern
+
+```typescript
+import { Indexer } from '@0glabs/0g-ts-sdk';
+
+const indexer = new Indexer(process.env.STORAGE_INDEXER!);
+
+// download() can throw OR return an error — always use try/catch
+try {
+  const err = await indexer.download(rootHash, outputPath, /* verified */ true);
+  if (err) throw err;
+} catch (error: any) {
+  throw new Error(`Download failed: ${error.message}`);
+}
+```
+
+### Upload from Buffer
+
+```typescript
+import { ZgFile } from '@0glabs/0g-ts-sdk';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+// Write buffer to temp file (SDK requires file path)
+const tempPath = path.join(os.tmpdir(), `0g-upload-${Date.now()}`);
+fs.writeFileSync(tempPath, buffer);
+
+const file = await ZgFile.fromFilePath(tempPath);
+try {
+  const [tree, err] = await file.merkleTree();
+  if (err) throw err;
+  const rootHash = tree!.rootHash();
+  const [, uploadErr] = await indexer.upload(file, process.env.RPC_URL!, wallet);
+  if (uploadErr) throw new Error(`Upload failed: ${uploadErr.message}`);
+  return rootHash;
+} finally {
+  await file.close();
+  fs.unlinkSync(tempPath); // Clean up temp file
+}
+```
+
+## Merkle Verification
+
+### Computing Root Hash
+
+```typescript
+import { ZgFile } from '@0glabs/0g-ts-sdk';
+
+const file = await ZgFile.fromFilePath(filePath);
+try {
+  const [tree, err] = await file.merkleTree();
+  if (err) throw err;
+  console.log('Root hash:', tree.rootHash());
+} finally {
+  await file.close();
+}
+```
+
+### Verified Download
+
+```typescript
+// The third parameter enables Merkle proof verification
+// Note: download() can throw or return errors — always use try/catch
+try {
+  const err = await indexer.download(rootHash, outputPath, true);
+  if (err) throw err;
+} catch (error: any) {
+  throw new Error(`Download failed: ${error.message}`);
+}
+```
+
+## Critical Rules
+
+### ALWAYS
+
+- Generate the Merkle tree before uploading
+- Close file handles after upload (`file.close()`)
+- Store root hashes — they are the ONLY way to retrieve files
+- Use verified downloads in production (third param = `true`)
+- Clean up temp files when uploading from buffers
+
+### NEVER
+
+- Skip Merkle tree generation before upload
+- Forget to close `ZgFile` handles (causes memory leaks)
+- Lose the root hash (data becomes irretrievable)
+- Upload without a funded wallet (transaction will fail)
+
+## Common Errors
+
+| Error                   | Cause                      | Fix                                 |
+| ----------------------- | -------------------------- | ----------------------------------- |
+| `merkle tree error`     | File is empty or corrupted | Verify file exists and has content  |
+| `insufficient funds`    | Wallet has no 0G           | Fund wallet from faucet (testnet)   |
+| `indexer not available` | Wrong indexer URL          | Check STORAGE_INDEXER in .env       |
+| `file not found`        | Root hash doesn't exist    | Verify root hash is correct         |
+| `connection refused`    | RPC endpoint down          | Try alternative RPC or check status |
+
+## References
+
+- [0G Storage SDK Docs](https://docs.0g.ai/build-with-0g/storage-network/sdk)
+- [0G Storage Architecture](https://docs.0g.ai/learn/0g-storage)
+- See also: [NETWORK_CONFIG.md](./NETWORK_CONFIG.md), [SECURITY.md](./SECURITY.md)

package/skills/0g/TESTING.md

@@ -0,0 +1,263 @@
+# Testing Patterns
+
+Testing strategies, mock patterns, and testnet workflows for 0G applications.
+
+## Testing Strategy
+
+```
+┌─────────────────────────────────────┐
+│       Integration Tests             │
+│   (Testnet, real transactions)      │
+├─────────────────────────────────────┤
+│         Unit Tests                  │
+│   (Mocked SDK, local only)         │
+├─────────────────────────────────────┤
+│       Static Analysis               │
+│   (TypeScript, Solhint, Slither)   │
+└─────────────────────────────────────┘
+```
+
+## Unit Testing
+
+### Mock Storage SDK
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+
+// Mock the 0G SDK
+vi.mock('@0glabs/0g-ts-sdk', () => ({
+  ZgFile: {
+    fromFilePath: vi.fn().mockResolvedValue({
+      merkleTree: vi.fn().mockResolvedValue([{ rootHash: () => '0xabc123' }, null]),
+      close: vi.fn(),
+    }),
+  },
+  Indexer: vi.fn().mockImplementation(() => ({
+    upload: vi.fn().mockResolvedValue('0xtxhash'),
+    download: vi.fn().mockResolvedValue(undefined),
+  })),
+}));
+
+describe('Storage Upload', () => {
+  it('should return root hash after upload', async () => {
+    const { ZgFile, Indexer } = await import('@0glabs/0g-ts-sdk');
+    const file = await ZgFile.fromFilePath('test.txt');
+    const [tree] = await file.merkleTree();
+    expect(tree.rootHash()).toBe('0xabc123');
+  });
+});
+```
+
+### Mock Compute Broker
+
+```typescript
+vi.mock('@0glabs/0g-serving-broker', () => ({
+  createZGComputeNetworkBroker: vi.fn().mockResolvedValue({
+    inference: {
+      listService: vi
+        .fn()
+        .mockResolvedValue([
+          { providerAddress: '0x123', serviceType: 'chatbot', model: 'test-model' },
+        ]),
+      getServiceMetadata: vi.fn().mockResolvedValue({
+        endpoint: 'http://localhost:3000',
+        model: 'test-model',
+      }),
+      getRequestHeaders: vi.fn().mockResolvedValue({ Authorization: 'Bearer test' }),
+      processResponse: vi.fn().mockResolvedValue(true),
+      acknowledgeProviderSigner: vi.fn().mockResolvedValue(undefined),
+    },
+    ledger: {
+      getLedger: vi.fn().mockResolvedValue({
+        totalBalance: 10000000000000000000n,
+        availableBalance: 5000000000000000000n,
+      }),
+      depositFund: vi.fn(),
+      transferFund: vi.fn(),
+    },
+  }),
+}));
+```
+
+### Mock ethers
+
+```typescript
+vi.mock('ethers', async () => {
+  const actual = await vi.importActual('ethers');
+  return {
+    ...actual,
+    JsonRpcProvider: vi.fn().mockImplementation(() => ({
+      getNetwork: vi.fn().mockResolvedValue({ chainId: 16602n }),
+    })),
+    Wallet: vi.fn().mockImplementation(() => ({
+      address: '0xTestAddress',
+      provider: {},
+    })),
+  };
+});
+```
+
+## Contract Testing
+
+### Hardhat Tests
+
+```typescript
+import { expect } from 'chai';
+import { ethers } from 'hardhat';
+
+describe('MyContract', function () {
+  it('should deploy and set initial value', async function () {
+    const Contract = await ethers.getContractFactory('MyContract');
+    const contract = await Contract.deploy(42);
+    await contract.waitForDeployment();
+
+    expect(await contract.getValue()).to.equal(42);
+  });
+
+  it('should update value', async function () {
+    const Contract = await ethers.getContractFactory('MyContract');
+    const contract = await Contract.deploy(0);
+    await contract.waitForDeployment();
+
+    const tx = await contract.setValue(100);
+    await tx.wait();
+
+    expect(await contract.getValue()).to.equal(100);
+  });
+});
+```
+
+```bash
+npx hardhat test
+```
+
+### Foundry Tests
+
+```solidity
+// test/MyContract.t.sol
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import "forge-std/Test.sol";
+import "../src/MyContract.sol";
+
+contract MyContractTest is Test {
+    MyContract public myContract;
+
+    function setUp() public {
+        myContract = new MyContract(42);
+    }
+
+    function testGetValue() public view {
+        assertEq(myContract.getValue(), 42);
+    }
+
+    function testSetValue() public {
+        myContract.setValue(100);
+        assertEq(myContract.getValue(), 100);
+    }
+}
+```
+
+```bash
+forge test
+```
+
+## Testnet Integration Testing
+
+### Test Workflow
+
+1. Use testnet endpoints (never mainnet for tests)
+2. Fund test wallet from faucet
+3. Run operations against real infrastructure
+4. Verify results on block explorer
+
+### Integration Test Example
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { ethers } from 'ethers';
+import { ZgFile, Indexer } from '@0glabs/0g-ts-sdk';
+
+// Only run in integration test mode
+describe.skipIf(!process.env.RUN_INTEGRATION)('Storage Integration', () => {
+  const provider = new ethers.JsonRpcProvider('https://evmrpc-testnet.0g.ai');
+  const wallet = new ethers.Wallet(process.env.TEST_PRIVATE_KEY!, provider);
+  const indexer = new Indexer('https://indexer-storage-testnet-turbo.0g.ai');
+
+  it('should upload and download a file', async () => {
+    // Upload
+    const file = await ZgFile.fromFilePath('./test-fixtures/sample.txt');
+    try {
+      const [tree, err] = await file.merkleTree();
+      if (err) throw err;
+      const rootHash = tree!.rootHash();
+      const [, uploadErr] = await indexer.upload(file, process.env.RPC_URL!, wallet);
+      if (uploadErr) throw uploadErr;
+
+      // Download (can throw — use try/catch)
+      const outputPath = './test-output/downloaded.txt';
+      const dlErr = await indexer.download(rootHash, outputPath, true);
+      if (dlErr) throw dlErr;
+
+      // Verify
+      expect(fs.existsSync(outputPath)).toBe(true);
+    } finally {
+      await file.close();
+    }
+  }, 120_000); // Long timeout for network operations
+});
+```
+
+### Running Integration Tests
+
+```bash
+# Run unit tests only
+npm test
+
+# Run with integration tests
+RUN_INTEGRATION=1 TEST_PRIVATE_KEY=0x... npm test
+```
+
+## Project Setup (vitest)
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    testTimeout: 30_000,
+    include: ['test/**/*.test.ts'],
+  },
+});
+```
+
+```json
+// package.json scripts
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "RUN_INTEGRATION=1 vitest run"
+  }
+}
+```
+
+## Best Practices
+
+1. **Mock external calls** in unit tests — never hit real networks
+2. **Use testnet** for integration tests — never mainnet
+3. **Set long timeouts** for network operations (60-120s)
+4. **Fund test wallets** with small amounts only
+5. **Clean up** test artifacts (uploaded files, deployed contracts)
+6. **Use separate keys** for testing and production
+
+## References
+
+- [Vitest Documentation](https://vitest.dev)
+- [Hardhat Testing](https://hardhat.org/tutorial/testing-contracts)
+- [Foundry Testing](https://book.getfoundry.sh/forge/tests)
+- See also: [NETWORK_CONFIG.md](./NETWORK_CONFIG.md)