@jaimevalasek/aioson 1.3.0

package/template/.aioson/skills/static/web3-ethereum-patterns.md

@@ -0,0 +1,310 @@
+# Web3 Ethereum Patterns
+
+> Solidity, Hardhat/Foundry, and frontend integration. Security first, gas second.
+
+---
+
+## Project structure (Hardhat monorepo)
+
+```
+contracts/
+  core/
+    Protocol.sol         ← main contract
+    interfaces/
+      IProtocol.sol      ← interface first, implementation second
+  tokens/
+    MyToken.sol          ← ERC-20/721/1155
+  utils/
+    Math.sol
+    Pausable.sol
+  mocks/
+    MockToken.sol        ← test doubles only, never in production
+scripts/
+  deploy/
+    01_deploy_token.ts
+    02_deploy_protocol.ts
+  verify.ts              ← Etherscan verification
+test/
+  Protocol.test.ts
+  integration/
+    fork.test.ts         ← mainnet fork tests
+hardhat.config.ts
+```
+
+---
+
+## Security patterns — always apply
+
+### 1. Reentrancy guard (any function that sends ETH or calls external contracts)
+
+```solidity
+import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+
+contract Marketplace is ReentrancyGuard {
+    // WRONG — state change after external call
+    function withdraw() external {
+        uint256 amount = balances[msg.sender];
+        payable(msg.sender).transfer(amount); // external call first = reentrancy vector
+        balances[msg.sender] = 0;             // state change after = too late
+    }
+
+    // RIGHT — CEI pattern (Checks → Effects → Interactions)
+    function withdraw() external nonReentrant {
+        uint256 amount = balances[msg.sender];  // Check
+        balances[msg.sender] = 0;               // Effect (state change BEFORE external call)
+        payable(msg.sender).transfer(amount);   // Interaction (external call LAST)
+    }
+}
+```
+
+### 2. Pull over push for payments
+
+```solidity
+// WRONG — push: sending ETH to multiple addresses in a loop
+function distributeRewards(address[] calldata recipients, uint256[] calldata amounts) external {
+    for (uint i = 0; i < recipients.length; i++) {
+        payable(recipients[i]).transfer(amounts[i]);  // one revert blocks all
+    }
+}
+
+// RIGHT — pull: let recipients withdraw their own funds
+mapping(address => uint256) public pendingWithdrawals;
+
+function claimReward() external nonReentrant {
+    uint256 amount = pendingWithdrawals[msg.sender];
+    require(amount > 0, "Nothing to claim");
+    pendingWithdrawals[msg.sender] = 0;
+    (bool success, ) = payable(msg.sender).call{ value: amount }("");
+    require(success, "Transfer failed");
+}
+```
+
+### 3. Access control
+
+```solidity
+import "@openzeppelin/contracts/access/AccessControl.sol";
+
+contract Protocol is AccessControl {
+    bytes32 public constant ADMIN_ROLE   = keccak256("ADMIN_ROLE");
+    bytes32 public constant OPERATOR_ROLE = keccak256("OPERATOR_ROLE");
+
+    constructor(address admin) {
+        _grantRole(DEFAULT_ADMIN_ROLE, admin);
+        _grantRole(ADMIN_ROLE, admin);
+    }
+
+    function pause() external onlyRole(ADMIN_ROLE) { ... }
+    function setFee(uint256 fee) external onlyRole(OPERATOR_ROLE) { ... }
+}
+```
+
+### 4. Integer arithmetic — use 18-decimal fixed point
+
+```solidity
+// WRONG — division before multiplication loses precision
+uint256 fee = (amount / 100) * 3;      // loses precision if amount < 100
+
+// RIGHT — multiply first, divide last
+uint256 FEE_BPS = 300;  // 3% in basis points
+uint256 fee = (amount * FEE_BPS) / 10_000;
+
+// Use constants for magic numbers
+uint256 public constant MAX_FEE_BPS = 1_000;  // 10% max
+uint256 public constant PRECISION    = 1e18;
+```
+
+### 5. Emit events for all state changes
+
+```solidity
+event Deposited(address indexed user, uint256 amount, uint256 timestamp);
+event Withdrawn(address indexed user, uint256 amount);
+event FeeUpdated(uint256 oldFee, uint256 newFee, address updatedBy);
+
+function deposit() external payable {
+    require(msg.value > 0, "Amount must be positive");
+    balances[msg.sender] += msg.value;
+    emit Deposited(msg.sender, msg.value, block.timestamp);
+}
+```
+
+---
+
+## Gas optimization
+
+```solidity
+// Pack struct fields to use fewer storage slots (32 bytes each)
+// WRONG — 3 slots
+struct BadPacking {
+    uint256 amount;    // slot 0
+    address owner;     // slot 1 (20 bytes, wastes 12)
+    uint256 timestamp; // slot 2
+}
+
+// RIGHT — 2 slots
+struct GoodPacking {
+    uint256 amount;    // slot 0
+    address owner;     // slot 1 (20 bytes)
+    uint96 timestamp;  // slot 1 (12 bytes — fits in same slot as owner)
+}
+
+// Use calldata instead of memory for read-only external function params
+function processItems(uint256[] calldata items) external view returns (uint256) { ... }
+
+// Cache storage reads in local variables (SLOAD costs 100+ gas)
+function calculate() external view returns (uint256) {
+    uint256 _balance = balance;  // one SLOAD
+    return _balance * _balance;  // two local reads, not two SLOADs
+}
+
+// Use custom errors instead of string revert (saves gas)
+error InsufficientBalance(uint256 available, uint256 required);
+
+function withdraw(uint256 amount) external {
+    if (balances[msg.sender] < amount) {
+        revert InsufficientBalance(balances[msg.sender], amount);
+    }
+    // ...
+}
+```
+
+---
+
+## Hardhat testing
+
+```ts
+import { ethers } from 'hardhat';
+import { expect } from 'chai';
+import { loadFixture } from '@nomicfoundation/hardhat-network-helpers';
+
+async function deployFixture() {
+    const [owner, alice, bob] = await ethers.getSigners();
+    const Protocol = await ethers.getContractFactory('Protocol');
+    const protocol = await Protocol.deploy(owner.address);
+    return { protocol, owner, alice, bob };
+}
+
+describe('Protocol', () => {
+    it('allows deposits and tracks balances', async () => {
+        const { protocol, alice } = await loadFixture(deployFixture);
+        const amount = ethers.parseEther('1.0');
+
+        await protocol.connect(alice).deposit({ value: amount });
+        expect(await protocol.balances(alice.address)).to.equal(amount);
+    });
+
+    it('prevents reentrancy on withdraw', async () => {
+        const { protocol, alice } = await loadFixture(deployFixture);
+        const MaliciousContract = await ethers.getContractFactory('MockReentrant');
+        const attacker = await MaliciousContract.deploy(await protocol.getAddress());
+
+        await protocol.connect(alice).deposit({ value: ethers.parseEther('1') });
+        await expect(attacker.attack()).to.be.revertedWith('ReentrancyGuard: reentrant call');
+    });
+
+    it('emits Deposited event', async () => {
+        const { protocol, alice } = await loadFixture(deployFixture);
+        const amount = ethers.parseEther('0.5');
+
+        await expect(protocol.connect(alice).deposit({ value: amount }))
+            .to.emit(protocol, 'Deposited')
+            .withArgs(alice.address, amount, anyValue);
+    });
+});
+```
+
+---
+
+## Frontend integration (wagmi v2)
+
+```ts
+// lib/contracts.ts — ABI and address registry
+export const PROTOCOL_ADDRESS = process.env.NEXT_PUBLIC_PROTOCOL_ADDRESS as `0x${string}`;
+export { abi as PROTOCOL_ABI } from './abis/Protocol.json';
+
+// Read contract data
+import { useReadContract } from 'wagmi';
+
+function UserBalance({ address }: { address: `0x${string}` }) {
+    const { data: balance, isLoading } = useReadContract({
+        address: PROTOCOL_ADDRESS,
+        abi: PROTOCOL_ABI,
+        functionName: 'balances',
+        args: [address],
+    });
+
+    if (isLoading) return <Skeleton />;
+    return <p>{formatEther(balance ?? 0n)} ETH</p>;
+}
+
+// Write contract
+import { useWriteContract, useWaitForTransactionReceipt } from 'wagmi';
+import { parseEther } from 'viem';
+
+function DepositButton() {
+    const { writeContract, data: hash, isPending } = useWriteContract();
+    const { isLoading: isConfirming } = useWaitForTransactionReceipt({ hash });
+
+    return (
+        <button
+            disabled={isPending || isConfirming}
+            onClick={() => writeContract({
+                address: PROTOCOL_ADDRESS,
+                abi: PROTOCOL_ABI,
+                functionName: 'deposit',
+                value: parseEther('0.1'),
+            })}
+        >
+            {isPending ? 'Waiting for wallet...' : isConfirming ? 'Confirming...' : 'Deposit 0.1 ETH'}
+        </button>
+    );
+}
+```
+
+---
+
+## Deployment scripts
+
+```ts
+// scripts/deploy/01_deploy_protocol.ts
+import { ethers, run } from 'hardhat';
+
+async function main() {
+    const [deployer] = await ethers.getSigners();
+    console.log(`Deploying with: ${deployer.address}`);
+    console.log(`Balance: ${ethers.formatEther(await ethers.provider.getBalance(deployer.address))} ETH`);
+
+    const Protocol = await ethers.getContractFactory('Protocol');
+    const protocol = await Protocol.deploy(deployer.address);
+    await protocol.waitForDeployment();
+
+    const address = await protocol.getAddress();
+    console.log(`Protocol deployed to: ${address}`);
+
+    // Verify on Etherscan
+    if (process.env.ETHERSCAN_API_KEY) {
+        await new Promise(r => setTimeout(r, 30_000)); // wait for indexing
+        await run('verify:verify', { address, constructorArguments: [deployer.address] });
+    }
+}
+
+main().catch((err) => { console.error(err); process.exit(1); });
+```
+
+---
+
+## ALWAYS
+- CEI pattern (Checks → Effects → Interactions) in every state-changing function
+- `ReentrancyGuard` on functions that send ETH or call external contracts
+- Pull pattern for ETH payments
+- `AccessControl` for role-based permissions
+- Custom errors over string reverts
+- `loadFixture` in tests for consistent state
+- Emit events for every important state change
+
+## NEVER
+- `transfer()` or `send()` in public functions (use `.call{value: ...}("")`)
+- Division before multiplication (precision loss)
+- Unbounded loops that could hit block gas limit
+- `block.timestamp` for critical time-based logic (miners can manipulate ±15s)
+- Deploy without testing on a fork of mainnet for DeFi integrations
+- `selfdestruct` — deprecated and dangerous

package/template/.aioson/skills/static/web3-security-checklist.md

@@ -0,0 +1,284 @@
+# Web3 Security Checklist
+
+> Every vulnerability on this list has drained real funds. Check all of them before mainnet.
+
+---
+
+## Critical: Reentrancy
+
+**What:** An external contract calls back into your contract before the first execution completes.
+
+```solidity
+// VULNERABLE
+function withdraw() external {
+    uint256 amount = balances[msg.sender];
+    (bool success,) = msg.sender.call{value: amount}(""); // attacker re-enters here
+    require(success);
+    balances[msg.sender] = 0; // never reached in attack
+}
+
+// SAFE — CEI pattern + ReentrancyGuard
+function withdraw() external nonReentrant {
+    uint256 amount = balances[msg.sender];
+    balances[msg.sender] = 0;                             // effect first
+    (bool success,) = msg.sender.call{value: amount}(""); // interaction last
+    require(success, "Transfer failed");
+}
+```
+
+**Checklist:**
+- [ ] All external calls come AFTER state changes (CEI pattern)
+- [ ] `ReentrancyGuard` on all functions making external calls
+- [ ] `nonReentrant` on withdraw, claim, and swap functions
+- [ ] Cross-function reentrancy checked (function A → function B → reenter A)
+
+---
+
+## Critical: Access Control
+
+**What:** Missing or bypassed authorization on privileged functions.
+
+```solidity
+// VULNERABLE — anyone can drain
+function withdrawFees() external {
+    payable(msg.sender).transfer(address(this).balance);
+}
+
+// SAFE
+function withdrawFees() external onlyRole(TREASURY_ROLE) {
+    payable(treasury).transfer(address(this).balance);
+}
+```
+
+**Checklist:**
+- [ ] Every state-changing function has explicit caller validation
+- [ ] Admin functions use `AccessControl` roles, not `onlyOwner` alone
+- [ ] Constructor sets roles explicitly — no open initialization window
+- [ ] Role transfers require two-step confirmation (propose + accept)
+- [ ] `renounceRole` / `transferOwnership` tested and working as expected
+
+---
+
+## Critical: Integer Overflow / Underflow
+
+Pre-Solidity 0.8: integers wrap silently. Post-0.8: revert on overflow by default.
+
+```solidity
+// Post-0.8 — safe by default, but watch unchecked blocks
+unchecked {
+    // No overflow protection here — only use when you've proven safety
+    total += amount;
+}
+
+// Safe arithmetic pattern for complex calculations
+uint256 fee = Math.mulDiv(amount, feeBps, 10_000); // OpenZeppelin safe mulDiv
+
+// Precision loss from division order
+uint256 bad  = (amount / 100) * 3;  // loses decimals
+uint256 good = (amount * 3) / 100;  // multiply first
+```
+
+**Checklist:**
+- [ ] Solidity version ≥ 0.8.0 (overflow protection by default)
+- [ ] All `unchecked` blocks justified with a comment explaining why it's safe
+- [ ] Multiplication happens before division in all fee calculations
+- [ ] No precision loss in basis-points calculations (use `mulDiv`)
+
+---
+
+## Critical: Oracle Manipulation
+
+**What:** Price oracles can be manipulated, especially spot prices read in a single block.
+
+```solidity
+// VULNERABLE — spot price from AMM, manipulable via flash loan
+function getPrice() external view returns (uint256) {
+    return IUniswapV2Pair(pair).getReserves(); // single-block price
+}
+
+// SAFE — use time-weighted average price (TWAP)
+function getPrice() external view returns (uint256) {
+    return IUniswapV3Pool(pool).observe(twapInterval); // time-weighted
+}
+
+// ALSO SAFE — Chainlink oracle with staleness check
+function getPrice() external view returns (uint256) {
+    (, int256 price,, uint256 updatedAt,) = AggregatorV3Interface(feed).latestRoundData();
+    require(block.timestamp - updatedAt < 3600, "Oracle: stale price");
+    require(price > 0, "Oracle: invalid price");
+    return uint256(price);
+}
+```
+
+**Checklist:**
+- [ ] No spot prices from AMMs used for liquidations, borrowing, or minting
+- [ ] TWAP or Chainlink feeds for all price-sensitive logic
+- [ ] Chainlink answers validated: `updatedAt`, `answeredInRound`, `price > 0`
+- [ ] Circuit breaker for extreme price deviations (±X% from last round)
+
+---
+
+## Critical: Flash Loan Attacks
+
+**What:** An attacker borrows a large amount, manipulates your protocol's state, and repays — all in one transaction.
+
+```solidity
+// Pattern: protect against flash loan price manipulation
+modifier noFlashLoan() {
+    require(tx.origin == msg.sender, "Flash loans not allowed");
+    _;
+}
+
+// Better: use internal accounting, not external balances
+// VULNERABLE — reads current balance (flash-loanable)
+function getReserves() view returns (uint256) {
+    return IERC20(token).balanceOf(address(this));
+}
+
+// SAFE — uses tracked internal accounting
+mapping(address => uint256) private reserves;
+function getReserves(address token) view returns (uint256) {
+    return reserves[token]; // updated only after safe deposits
+}
+```
+
+**Checklist:**
+- [ ] State does not depend on `balanceOf` for protocol invariants
+- [ ] Invariants checked before and after complex operations
+- [ ] Slippage / deviation limits on swaps and liquidations
+- [ ] Test with foundry `vm.deal` simulating flash loan amounts
+
+---
+
+## High: Front-Running
+
+**What:** Miners or MEV bots see your pending transaction and insert their own first.
+
+```solidity
+// Vulnerable: deadline and slippage in swap
+function swap(uint256 amountIn) external {
+    // No deadline, no slippage — sandwich attack trivial
+    uint256 out = pool.swap(amountIn);
+}
+
+// Protected: explicit slippage and deadline
+function swap(
+    uint256 amountIn,
+    uint256 minAmountOut,
+    uint256 deadline
+) external {
+    require(block.timestamp <= deadline, "Expired");
+    uint256 out = pool.swap(amountIn);
+    require(out >= minAmountOut, "Slippage too high");
+}
+```
+
+**Checklist:**
+- [ ] All user-facing swaps include `minAmountOut` and `deadline`
+- [ ] Governance votes have timelocks (≥48h for critical changes)
+- [ ] Commit-reveal scheme for any sensitive on-chain randomness
+- [ ] Consider using Flashbots Protect RPC for sensitive deployments
+
+---
+
+## High: Signature Replay
+
+**What:** A valid signed message is resubmitted to the same or a different contract.
+
+```solidity
+// VULNERABLE — no nonce, no chain ID
+function execute(bytes32 hash, bytes calldata sig) external {
+    address signer = ECDSA.recover(hash, sig);
+    require(signer == admin);
+    // attacker replays this on another chain or calls again
+}
+
+// SAFE — EIP-712 with nonce and chainId
+function execute(
+    address target,
+    uint256 value,
+    uint256 nonce,
+    uint256 deadline,
+    bytes calldata sig
+) external {
+    require(block.timestamp <= deadline, "Expired");
+    require(nonces[msg.sender] == nonce, "Invalid nonce");
+
+    bytes32 digest = _hashTypedDataV4(keccak256(abi.encode(
+        EXECUTE_TYPEHASH, target, value, nonce, deadline
+    )));
+
+    require(ECDSA.recover(digest, sig) == admin, "Invalid signature");
+    nonces[msg.sender]++;
+    // execute...
+}
+```
+
+**Checklist:**
+- [ ] All permit/signature functions use EIP-712 typed data
+- [ ] Nonce incremented on every use
+- [ ] `chainId` included in the domain separator
+- [ ] `deadline` on every signature
+- [ ] Signatures cannot be reused across different contract addresses
+
+---
+
+## High: Logic Errors
+
+**Checklist:**
+- [ ] All invariants documented and tested (e.g., `totalSupply == sum of balances`)
+- [ ] Edge cases: zero amounts, single user, max amounts, empty state
+- [ ] Rounding direction favors the protocol, not the user (round down on user withdrawals)
+- [ ] State transitions are complete and correct (no half-updated state on revert)
+
+---
+
+## Pre-Deployment Checklist
+
+### Code review
+- [ ] Static analysis: `slither .` — zero critical/high findings
+- [ ] Fuzzing: Foundry `forge fuzz` on all state-changing functions
+- [ ] Invariant tests: Foundry invariant testing for protocol-level invariants
+- [ ] Fork testing: mainnet fork with realistic protocols (DeFi integrations)
+- [ ] Independent audit (3rd party, not affiliated team)
+
+### Deployment
+- [ ] Compiler version pinned: `pragma solidity 0.8.24;` (not `^`)
+- [ ] All constructor arguments verified correct
+- [ ] Contract verified on Etherscan before calling any admin function
+- [ ] Multisig wallet as owner/admin (≥3 of 5)
+- [ ] Timelock on all parameter changes (≥24h, ≥48h for critical)
+- [ ] Deployment addresses, block numbers, and ABI hashes recorded
+
+### Operations
+- [ ] Emergency pause mechanism tested on testnet
+- [ ] Incident response plan documented (who to call, how to pause, how to communicate)
+- [ ] Monitoring: alerts on unusual value flows, failed transactions, admin calls
+- [ ] Upgrade strategy defined (proxy pattern) or explicitly immutable with documentation
+
+---
+
+## Testing requirements by severity
+
+| Scenario | Test type | Coverage |
+|---|---|---|
+| Normal operations | Unit tests | 100% |
+| Access control violations | Unit tests | Every protected function |
+| Reentrancy attacks | Fork tests with attacker contract | All external-call functions |
+| Oracle manipulation | Fork tests with large swaps | All price-dependent paths |
+| Integer edge cases | Fuzz tests | All arithmetic functions |
+| Protocol invariants | Invariant tests | Total supply, balances, fees |
+| Flash loan attacks | Fork tests with vm.deal | All single-tx exploit vectors |
+
+---
+
+## Emergency response
+
+If a vulnerability is found post-deployment:
+1. Pause the contract immediately (if pause mechanism exists)
+2. Assess: is there active exploitation? How much at risk?
+3. Do NOT disclose publicly until a fix is ready or funds are rescued
+4. Contact affected protocols/integrations privately
+5. Prepare and test the fix in isolation
+6. Coordinate with security researchers / auditors
+7. Deploy fix with a clear timeline communicated to users