@dilukangelo/web3-ai-skills 1.0.0

package/template/.agent/skills/smart-contract-auditing/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: smart-contract-auditing
+description: Smart contract security audit methodology. Slither, Mythril, Aderyn, Echidna, manual review patterns. Vulnerability classification, attack vectors, DeFi exploit patterns.
+---
+
+# Smart Contract Auditing — Security Analysis Methodology
+
+Expert knowledge for systematically identifying vulnerabilities in smart contracts.
+
+## Use this skill when
+
+- Performing pre-deployment security audits
+- Reviewing smart contract code for vulnerabilities
+- Analyzing DeFi protocol security
+- Investigating post-exploit incidents
+- Preparing contracts for bug bounty programs
+
+---
+
+## Audit Workflow
+
+```
+1. SCOPE DEFINITION
+   └── Identify contracts, dependencies, trust assumptions
+
+2. AUTOMATED ANALYSIS
+   └── Slither → Mythril → Aderyn → Echidna
+
+3. MANUAL REVIEW
+   └── Line-by-line, state machine analysis
+
+4. EXPLOIT DEVELOPMENT
+   └── PoC for each finding
+
+5. REPORT
+   └── Findings, severity, recommendations
+```
+
+---
+
+## Automated Tools
+
+### Slither (Static Analysis)
+```bash
+# Full analysis
+slither . --detect all --exclude-low
+
+# Specific detectors
+slither . --detect reentrancy-eth,reentrancy-no-eth
+
+# Print contract summary
+slither . --print contract-summary
+
+# Check for upgradeable issues
+slither . --detect delegatecall-loop
+```
+
+### Mythril (Symbolic Execution)
+```bash
+# Analyze single contract
+myth analyze contracts/Token.sol --solv 0.8.24
+
+# Deep analysis with more solvers
+myth analyze contracts/Token.sol --execution-timeout 300 --solver-timeout 60
+```
+
+### Aderyn (Rust-Based)
+```bash
+# Fast Rust-based analysis
+aderyn .
+
+# With specific output
+aderyn . --output report.md
+```
+
+### Echidna (Fuzzing)
+```yaml
+# echidna.config.yaml
+testMode: assertion
+testLimit: 50000
+shrinkLimit: 5000
+```
+```solidity
+// Property test
+function echidna_total_supply_invariant() public view returns (bool) {
+    return token.totalSupply() <= MAX_SUPPLY;
+}
+```
+
+---
+
+## Vulnerability Taxonomy
+
+### Critical (Immediate fund loss)
+
+| Vulnerability | Pattern | Check |
+|---------------|---------|-------|
+| **Reentrancy** | External call before state update | CEI pattern enforced? |
+| **Access Control Bypass** | Missing `onlyOwner` / role check | All admin functions protected? |
+| **Uninitialized Proxy** | Proxy without `_disableInitializers()` | Constructor blocks init? |
+| **Oracle Manipulation** | Spot price as oracle | TWAP with sufficient window? |
+| **Arbitrary External Call** | User-controlled `target.call(data)` | Target address validated? |
+
+### High (Conditional fund loss)
+
+| Vulnerability | Pattern | Check |
+|---------------|---------|-------|
+| **Flash Loan Attack** | State manipulable in single tx | Same-block protections? |
+| **Front-Running** | Profitable tx ordering | Commit-reveal or MEV protection? |
+| **Signature Replay** | Missing nonce/chainId in signature | EIP-712 with full domain? |
+| **Integer Overflow** | Unsafe `unchecked` blocks | Bounds validated before unchecked? |
+| **Delegate Call Injection** | User-controlled delegatecall target | Target hardcoded or validated? |
+
+### Medium (Limited impact)
+
+| Vulnerability | Pattern | Check |
+|---------------|---------|-------|
+| **Centralization Risk** | Single admin key controls funds | Timelock + multisig? |
+| **Precision Loss** | Division before multiplication | Correct order of operations? |
+| **DoS via Revert** | Loop depends on external call | Pull pattern used? |
+| **Timestamp Dependence** | Business logic on `block.timestamp` | Acceptable tolerance? |
+| **Storage Collision** | Proxy upgrade changes layout | Storage gap pattern? |
+
+---
+
+## DeFi-Specific Attack Vectors
+
+### Price Oracle Attacks
+```solidity
+// ❌ VULNERABLE: Spot price manipulation
+uint256 price = pair.getReserves()[0] / pair.getReserves()[1];
+
+// ✅ SAFE: TWAP oracle with sufficient window
+uint256 price = oracle.consult(token, 1e18, TWAP_PERIOD);
+```
+
+### ERC-4626 Inflation Attack
+```solidity
+// ❌ VULNERABLE: First depositor can inflate share price
+function deposit(uint256 assets) {
+    uint256 shares = (totalSupply == 0) ? assets : assets * totalSupply / totalAssets;
+}
+
+// ✅ SAFE: Virtual shares and assets
+function deposit(uint256 assets) {
+    uint256 shares = assets * (totalSupply + 1) / (totalAssets + 1);
+}
+```
+
+### Governance Attack
+- Flash-borrow governance tokens
+- Create and vote on malicious proposal
+- Execute in same block
+
+### Cross-Chain Bridge Exploits
+- Message verification failures
+- Replay across chains
+- Race conditions in finality
+
+---
+
+## Report Template
+
+```markdown
+# Security Audit Report
+
+## Summary
+- **Project:** [Name]
+- **Commit:** [Hash]
+- **Scope:** [Contracts audited]
+- **Duration:** [Days]
+
+## Findings Summary
+
+| ID | Title | Severity | Status |
+|----|-------|----------|--------|
+| H-01 | [Title] | High | Open |
+| M-01 | [Title] | Medium | Fixed |
+
+## Detailed Findings
+
+### [H-01] Title
+
+**Severity:** High
+**Location:** `Contract.sol#L45-L62`
+
+**Description:**
+[Detailed description]
+
+**Impact:**
+[What an attacker can achieve]
+
+**Proof of Concept:**
+[Exploit code or test]
+
+**Recommendation:**
+[How to fix]
+```

package/template/.agent/skills/solidity-patterns/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: solidity-patterns
+description: Solidity 0.8.x+ patterns, ERC standards, gas optimization, upgradeable contracts, DeFi integrations. Use when writing or reviewing Solidity smart contracts.
+---
+
+# Solidity Patterns — EVM Smart Contract Mastery
+
+Expert knowledge for writing secure, gas-efficient Solidity smart contracts on EVM chains.
+
+## Use this skill when
+
+- Writing new Solidity contracts
+- Optimizing gas consumption
+- Implementing ERC standards
+- Creating upgradeable proxy contracts
+- Integrating with DeFi protocols
+
+## Do not use this skill when
+
+- Working with Solana or non-EVM chains (use `rust-smart-contracts`)
+- Building frontend code (use `rainbowkit-wagmi`)
+
+## Instructions
+
+1. Identify the contract type and ERC standard needed
+2. Apply security patterns (CEI, access control, reentrancy guards)
+3. Optimize gas with storage packing, calldata usage, custom errors
+4. Write comprehensive Foundry tests (unit, fuzz, invariant)
+5. Create deployment scripts with verification
+
+---
+
+## Core Patterns
+
+### Storage Optimization
+```solidity
+// ❌ BAD: 3 storage slots (96 bytes used, 96 bytes allocated)
+uint256 amount;     // slot 0
+address owner;      // slot 1
+bool active;        // slot 2
+
+// ✅ GOOD: 2 storage slots (53 bytes used, 64 bytes allocated)
+uint256 amount;     // slot 0
+address owner;      // slot 1 (20 bytes)
+bool active;        // slot 1 (1 byte, packed with address)
+```
+
+### Custom Errors (Gas Efficient)
+```solidity
+// ❌ BAD: ~50+ bytes for string
+require(balance >= amount, "Insufficient balance");
+
+// ✅ GOOD: 4 bytes selector only
+error InsufficientBalance(uint256 available, uint256 required);
+if (balance < amount) revert InsufficientBalance(balance, amount);
+```
+
+### Check-Effects-Interactions (CEI)
+```solidity
+function withdraw(uint256 amount) external {
+    // 1. CHECK
+    if (balances[msg.sender] < amount) revert InsufficientBalance();
+
+    // 2. EFFECTS (state changes BEFORE external calls)
+    balances[msg.sender] -= amount;
+
+    // 3. INTERACTIONS (external calls LAST)
+    (bool success, ) = msg.sender.call{value: amount}("");
+    if (!success) revert TransferFailed();
+}
+```
+
+### Transient Storage (EIP-1153, Solidity 0.8.24+)
+```solidity
+// Gas-efficient reentrancy guard using transient storage
+modifier nonReentrant() {
+    assembly {
+        if tload(0) { revert(0, 0) }
+        tstore(0, 1)
+    }
+    _;
+    assembly {
+        tstore(0, 0)
+    }
+}
+```
+
+### Upgradeable Contracts (UUPS)
+```solidity
+import "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
+
+contract MyContract is UUPSUpgradeable {
+    /// @custom:oz-upgrades-unsafe-allow constructor
+    constructor() { _disableInitializers(); }
+
+    function initialize() public initializer {
+        __UUPSUpgradeable_init();
+    }
+
+    function _authorizeUpgrade(address) internal override onlyOwner {}
+}
+```
+
+---
+
+## ERC Implementation Quick Reference
+
+### ERC-20 (Fungible Token)
+- Use OpenZeppelin `ERC20` base
+- Add `permit` for gasless approvals (ERC-2612)
+- Consider `ERC20Votes` for governance tokens
+- Handle fee-on-transfer and rebasing edge cases
+
+### ERC-721 (NFT)
+- Use `ERC721Enumerable` only if on-chain enumeration needed (expensive)
+- Implement `ERC2981` for royalties
+- Use `_safeMint` to check receiver compatibility
+- Consider `ERC721A` for batch minting optimization
+
+### ERC-1155 (Multi-Token)
+- Ideal for gaming assets and mixed fungible/non-fungible
+- Batch operations reduce gas significantly
+- Implement `uri()` with token ID substitution
+
+### ERC-4626 (Tokenized Vault)
+- Standard for yield-bearing vaults
+- Beware of inflation attack on first deposit
+- Always round against the user (deposit up, withdraw down)
+
+---
+
+## Gas Optimization Checklist
+
+| Technique | Savings |
+|-----------|---------|
+| Custom errors | ~50 gas per revert |
+| `calldata` instead of `memory` | ~60 gas per param |
+| `unchecked` (safe arithmetic) | ~20-40 gas per op |
+| Storage packing | ~20,000 gas per slot saved |
+| `immutable` / `constant` | ~2,100 gas on read |
+| Caching `.length` in loops | ~6 gas per iteration |
+| `bytes32` instead of `string` | ~100+ gas |
+| `mapping` instead of `array` | Variable, often significant |
+
+---
+
+## Testing Patterns (Foundry)
+
+```solidity
+// Unit Test
+function test_Transfer() public {
+    token.mint(alice, 1000);
+    vm.prank(alice);
+    token.transfer(bob, 500);
+    assertEq(token.balanceOf(bob), 500);
+}
+
+// Fuzz Test
+function testFuzz_Transfer(uint256 amount) public {
+    amount = bound(amount, 1, MAX_SUPPLY);
+    token.mint(alice, amount);
+    vm.prank(alice);
+    token.transfer(bob, amount);
+    assertEq(token.balanceOf(bob), amount);
+}
+
+// Invariant Test
+function invariant_TotalSupplyMatchesBalances() public {
+    uint256 sum = token.balanceOf(alice) + token.balanceOf(bob);
+    assertEq(token.totalSupply(), sum);
+}
+```
+
+---
+
+## Deployment Script (Foundry)
+```solidity
+// script/Deploy.s.sol
+contract DeployScript is Script {
+    function run() public {
+        uint256 deployerKey = vm.envUint("PRIVATE_KEY");
+        vm.startBroadcast(deployerKey);
+
+        MyContract c = new MyContract();
+
+        vm.stopBroadcast();
+
+        // Verify
+        // forge verify-contract <address> MyContract --chain <chain-id>
+    }
+}
+```

package/template/.agent/skills/subgraph-indexing/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: subgraph-indexing
+description: Chain indexing with The Graph, Ponder, Envio, and custom indexers. Event-driven data, GraphQL APIs, entity relationships, and real-time sync.
+---
+
+# Subgraph & Indexing — Blockchain Data Access
+
+Expert knowledge for building efficient blockchain data indexing solutions.
+
+## Use this skill when
+
+- Building subgraphs for The Graph
+- Setting up Ponder or Envio indexers
+- Creating real-time data feeds from on-chain events
+- Designing entity schemas for blockchain data
+- Querying historical blockchain data efficiently
+
+---
+
+## The Graph (Subgraph)
+
+### Project Structure
+```
+subgraph/
+├── schema.graphql       # Entity definitions
+├── subgraph.yaml        # Data source manifest
+├── src/
+│   ├── token.ts         # Event handlers
+│   └── utils.ts         # Helper functions
+├── tests/
+│   └── token.test.ts    # Matchstick unit tests
+├── package.json
+└── tsconfig.json
+```
+
+### Schema Definition
+```graphql
+# schema.graphql
+type Token @entity {
+  id: Bytes!
+  name: String!
+  symbol: String!
+  totalSupply: BigInt!
+  holders: [TokenHolder!]! @derivedFrom(field: "token")
+}
+
+type TokenHolder @entity {
+  id: Bytes!  # address
+  token: Token!
+  balance: BigInt!
+  transferCount: BigInt!
+}
+
+type Transfer @entity(immutable: true) {
+  id: Bytes!
+  from: Bytes!
+  to: Bytes!
+  value: BigInt!
+  blockNumber: BigInt!
+  timestamp: BigInt!
+  transactionHash: Bytes!
+}
+```
+
+### Event Handlers
+```typescript
+// src/token.ts
+import { Transfer as TransferEvent } from '../generated/Token/Token'
+import { Token, TokenHolder, Transfer } from '../generated/schema'
+
+export function handleTransfer(event: TransferEvent): void {
+  // Create Transfer entity (immutable — never updated)
+  let transfer = new Transfer(event.transaction.hash.concatI32(event.logIndex.toI32()))
+  transfer.from = event.params.from
+  transfer.to = event.params.to
+  transfer.value = event.params.value
+  transfer.blockNumber = event.block.number
+  transfer.timestamp = event.block.timestamp
+  transfer.transactionHash = event.transaction.hash
+  transfer.save()
+
+  // Update holder balances
+  updateHolder(event.params.from, event.params.value.neg())
+  updateHolder(event.params.to, event.params.value)
+}
+```
+
+### Deployment
+```bash
+# Build
+graph codegen && graph build
+
+# Deploy to Subgraph Studio
+graph deploy --studio my-subgraph
+
+# Deploy to hosted service
+graph deploy --node https://api.thegraph.com/deploy/ my-org/my-subgraph
+```
+
+---
+
+## Ponder (TypeScript Indexer)
+
+### Configuration
+```typescript
+// ponder.config.ts
+import { createConfig } from '@ponder/core'
+import { http } from 'viem'
+import { TokenAbi } from './abis/Token'
+
+export default createConfig({
+  networks: {
+    mainnet: {
+      chainId: 1,
+      transport: http(process.env.PONDER_RPC_URL_1),
+    },
+  },
+  contracts: {
+    Token: {
+      network: 'mainnet',
+      abi: TokenAbi,
+      address: '0x...',
+      startBlock: 18_000_000,
+    },
+  },
+})
+```
+
+### Schema
+```typescript
+// ponder.schema.ts
+import { createSchema } from '@ponder/core'
+
+export default createSchema((p) => ({
+  Token: p.createTable({
+    id: p.hex(),
+    name: p.string(),
+    symbol: p.string(),
+    totalSupply: p.bigint(),
+  }),
+  Transfer: p.createTable({
+    id: p.string(),
+    from: p.hex(),
+    to: p.hex(),
+    value: p.bigint(),
+    timestamp: p.int(),
+  }),
+}))
+```
+
+### Event Handlers
+```typescript
+// src/Token.ts
+import { ponder } from '@/generated'
+
+ponder.on('Token:Transfer', async ({ event, context }) => {
+  const { from, to, value } = event.args
+
+  await context.db.Transfer.create({
+    id: `${event.transaction.hash}-${event.log.logIndex}`,
+    data: { from, to, value, timestamp: Number(event.block.timestamp) },
+  })
+})
+```
+
+---
+
+## Indexer Selection Guide
+
+| Tool | Best For | Language | Hosting |
+|------|----------|----------|---------|
+| **The Graph** | Decentralized, production | AssemblyScript | Decentralized |
+| **Ponder** | TypeScript-native, fast dev | TypeScript | Self-hosted |
+| **Envio** | High-performance, HyperSync | TypeScript | Managed |
+| **Goldsky** | Mirror + Subgraphs | GraphQL | Managed |
+| **Subsquid** | Multi-chain, archive data | TypeScript | Managed |
+| **Custom** | Full control | Any | Self-hosted |
+
+---
+
+## GraphQL Query Patterns
+
+```graphql
+# Get recent transfers
+query RecentTransfers {
+  transfers(
+    first: 10
+    orderBy: blockNumber
+    orderDirection: desc
+    where: { value_gt: "1000000000000000000" }
+  ) {
+    from
+    to
+    value
+    blockNumber
+    transactionHash
+  }
+}
+
+# Get top holders
+query TopHolders($token: Bytes!) {
+  tokenHolders(
+    first: 100
+    orderBy: balance
+    orderDirection: desc
+    where: { token: $token }
+  ) {
+    id
+    balance
+    transferCount
+  }
+}
+```
+
+---
+
+## Best Practices
+
+- Use `immutable: true` for event entities (never need updates)
+- Cache derived values instead of computing in queries
+- Use `@derivedFrom` for reverse lookups
+- Index only the data you need — less storage, faster sync
+- Handle chain reorgs gracefully
+- Test handlers with Matchstick or local tests
+- Monitor indexing health and sync lag