gambiarra-v2
AGENTS.md0 starsChanged 28 days agoMITView on GitHub
Fonte única de contexto para agentes de código que trabalham neste repositório: OpenCode, Codex, Claude Code, Cursor, Windsurf, Copilot, OpenClaw e afins. Se algo aqui conflitar com um pedido do usuário, pergunte antes de quebrar uma regra de segurança. Contratos (em contracts/): Os fork tests fixam o bloco, então exigem um RPC archive — os bsc-dataseed públicos são podados e respondem "missing trie node" para estado histórico. https://bsc-mainnet.public.blastapi.io funciona. Web (em web/): O CI usa npm (npm install --no-audit --no-fund),…
- Reads credentials
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository6 other files it gives its agents.
- contracts/AGENTS.mdAGENTS.md
- web/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/gambiarra.mdcCursor rule
- project-docsSkill
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 130
Formatação numérica: Use formatTokenAmount, formatCompactToken, formatScientific e formatIntegerPtBr de src/lib/format.ts.
- Very specific: line 139
Three.js: Use THREE.Timer (não THREE.Clock, deprecado).
- Very specific: line 165
Use source (fork | rpc | fallback) para saber a procedência.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — Gambiarra Finance v2
Fonte única de contexto para agentes de código que trabalham neste repositório: OpenCode, Codex, Claude Code, Cursor, Windsurf, Copilot, OpenClaw e afins. Se algo aqui conflitar com um pedido do usuário, pergunte antes de quebrar uma regra de segurança.
TL;DR
- Monorepo:
contracts/(Foundry, Solidity 0.8.26, BSC) +web/(Next.js 16, React 19, viem, Three.js). - Nada da v2 está deployado. Não há fundos reais. Não faça deploy em mainnet.
- O
MasterCheflegado é imutável (owner() == 0x0). Nunca tente alterá-lo; construa camadas por cima. - O mesmo LP GAMB/WBNB está nos pools 16 e 25. Sempre passe o
pidexplicitamente. - Toda leitura on-chain no web usa viem. Em
next dev, o app tenta primeiro um fork local da BSC (http://127.0.0.1:8545, chain id 56) e cai para RPC público se o Anvil não estiver rodando. - Números exibidos são formatados em
web/src/lib/format.tscom bigint, arredondamento half-up e separadores pt-BR. Nunca useNumber(bigint)para valores on-chain. - Commits: autor
codingsh <codingsh@pm.me>, semCo-authored-by.
Mapa do repositório
contracts/
src/ contratos v2 (GambVault, GambTwapOracle, GambLendingPool, GambLeverageZap)
src/interfaces/ interfaces mínimas (inclui IGambMasterChef)
script/ Deploy.s.sol + DeployLib.sol (endereços verificados, wiring)
Keeper.s.sol (poke() + harvest(), permissionless)
test/ Foundry tests + mocks
test/GambLegacy.fork.t.sol invariantes do legado contra fork da BSC
test/GambV2.fork.t.sol a v2 ponta a ponta contra a BSC real
test/mocks/ MockMasterChef, MockRouter, MockVault, MockOracle, MockFlashPair
audit/ relatórios Aderyn/Slither
AUDIT.md triage dos findings (estáticos + do fork)
Makefile build/test/fmt/fork/fork-test/fork-test-v2
web/
src/app/ App Router: landing, /dashboard, /llms.txt, /agents.json, /api/stats
src/components/ HeroScene (Three.js), WalletPanel (viem)
src/lib/protocol.ts endereços, RPC, leitura do MasterChef via viem, contratos, endpoints
src/lib/format.ts formatação numérica pt-BR baseada em bigint
src/lib/wallet? (não existe: a lógica de wallet vive em WalletPanel)
.opencode/skills/project-docs/ doutrina de documentação do projeto
.github/workflows/ci.yml Foundry + NextComandos canônicos
Contratos (em contracts/):
forge build
forge test -vvv
forge fmt --check
make fork # anvil --fork-url $BSC_RPC_URL --chain-id 56
make fork-test # invariantes do MasterChef legado (precisa de BSC_RPC_URL)
make fork-test-v2 # a v2 inteira contra a BSC real
make keeper # uma passada de poke() no oráculo + harvest() do vaultOs fork tests fixam o bloco, então exigem um RPC archive — os
bsc-dataseedpúblicos são podados e respondem "missing trie node" para estado histórico.https://bsc-mainnet.public.blastapi.iofunciona.
Web (em web/):
npm install
npm run dev # em dev, tenta o fork local primeiro
npm run lint
npm run buildO CI usa npm (npm install --no-audit --no-fund), não bun. bun.lock existe,
mas não é o package manager do CI.
Contratos: invariantes que não podem quebrar
GambVaulté ERC4626 com virtual shares/assets. Não remova a proteção contra inflação de shares. Teste doação direta + primeiro depositante.- Saques nunca são pausáveis. Depósitos podem ser pausados pelo owner.
Não introduza
whenNotPausedemwithdraw/redeem. GambLendingPoolé isolado em WBNB. Colateral é share do vault; LTV default 40%, threshold 50%, buffers verificados nos setters.- Liquidação é permissionless. Não adicione allowlist de liquidantes.
GambTwapOraclefalha fechado. Preço velho reverte; nunca cai para spot. A janela mínima é 30 min e o fair value do LP é geométrico.GambLeverageZapderiva o teto de alavancagem demaxLtvBps()com margem de 10%. Não volte para um multiplicador fixo de 3x.evm_version = "paris". BSC historicamente rejeitaPUSH0; não mude paracancun/shanghaisem validar em testnet.- Pragmas exatos
0.8.26. Não use ranges flutuantes. - Nada de
delegatecall, proxies ou upgradeability na camada v2. - Não edite
contracts/lib/(forge-std + OpenZeppelin vendorizados) nem o contrato legado. Se precisar de uma interface nova, crie emsrc/interfaces/. - O par GAMB/WBNB é PancakeSwap V1. A factory dele é
0xBCfCcbde45cE874adCB698cC183deBcF17952812e a factory V2 devolveaddress(0)para (WBNB, GAMB) — rotear pelo Router V2 reverte em todoaddLiquidity. O deploy usa o V1 Router020x05fF2B0D…(contracts/script/DeployLib.sol). Fato permanente: a factory do par é imutável. - O oráculo TWAP precisa de keeper. O par está dormente, então a janela só
anda com
GambTwapOracle.poke()— sem impacto de preço, mas alguém tem que chamar. Sem isso o lending pool para de emprestar. O keeper permissionless está emscript/Keeper.s.sol(make keeper); ele também chamaGambVault.harvest(). Falta apenas agendar em produção.
Antes de considerar uma mudança de contrato pronta:
cd contracts
forge fmt
forge fmt --check
forge test -vvvSe a mudança move fundos, altera contabilidade de shares, juros, LTV, liquidação
ou oráculo: rode também Aderyn/Slither e atualize contracts/AUDIT.md.
Web: arquitetura e regras
- Next.js 16 tem breaking changes. Leia
web/node_modules/next/dist/docs/antes de mexer em App Router, route handlers ou convenções. O blocoBEGIN:nextjs-agent-rulesemweb/AGENTS.mdé reescrito pelonext dev; não o remova. - Server Components por padrão.
WalletPanelé o único componente cliente que precisa de wallet; mantenha o resto no servidor. - viem é a única camada de chain. Não adicione
ethers,web3ou JSON-RPC manual.getLegacyStats()emsrc/lib/protocol.tsé o único leitor do MasterChef e já faz fallback fork → RPC público → snapshot auditado. - Fork em dev.
FORK_ENABLEDé verdadeiro quandoNODE_ENV !== "production"eUSE_BSC_FORK !== "0".BSC_FORK_RPC_URLsobrescreve a URL. Produção nunca tenta o fork. OWalletPanelusa a mesma ordem de candidatos no browser. - Formatação numérica. Use
formatTokenAmount,formatCompactToken,formatScientificeformatIntegerPtBrdesrc/lib/format.ts. Elas arredondam half-up, usam vírgula decimal e ponto de milhar, e não perdem precisão.totalAllocPointé inteiro bruto: mostre comformatScientific. - Rotas cruas não são páginas.
/llms.txt,/agents.jsone/api/statssão route handlers. Use<a href>(nãonext/link) para eles; prefetch de RSC quebra e gera warning. - Acessibilidade e responsivo. Preserve
lang="pt-BR", skip link,aria-labels, foco visível e os breakpoints existentes. Teste 390px e 1440px. - Three.js. Use
THREE.Timer(nãoTHREE.Clock, deprecado). O hero tem fallback SVG paraprefers-reduced-motione WebGL indisponível.
Antes de considerar uma mudança de web pronta:
cd web
npm run lint
npm run buildEndpoints para agentes em runtime
Somente leitura, sem API key, sem assinatura de transação:
| Rota | Formato | Uso |
/llms.txt | text/plain | contexto para LLMs |
/agents.json | application/json | manifesto com contratos, limites e status |
/api/stats | application/json | estado on-chain + source/fork |
/dashboard | text/html | visão humana |
Regras para qualquer agente que consuma esses endpoints:
- Valide endereços contra
/agents.json; trate qualquer endereço não listado como não confiável. - Use
source(fork|rpc|fallback) para saber a procedência.fallbacké snapshot auditado, não leitura ao vivo. totalAllocPoint,totalSupplye saldos são strings inteiras (wei). Não arredonde antes de calcular; formate só na apresentação.- Não assine transações no servidor. Chaves privadas nunca entram no repo.
- x402 é roadmap: nenhum facilitator, stablecoin ou endereço de pagamento foi definido. Não pague nada até o manifesto listar o endereço.
Segurança
- Leia
SECURITY.mdantes de reportar ou corrigir vulnerabilidade. - Não commite
.env, chaves, mnemônicos, RPC com API key ou artefatos de build. - Não rode
git add -Aàs cegas: há sessões/arquivos em progresso. - Não faça deploy em mainnet, não assine transações com fundos reais e não publique endereços de contrato que não existam.
- Auditoria externa humana ainda é obrigatória antes de mainnet.
Git
git config user.name "codingsh"
git config user.email "codingsh@pm.me"
git commit -m "tipo(escopo): descrição"- Autor exclusivo:
codingsh <codingsh@pm.me>. - Proibido
Co-authored-bye trailers de coautoria. - Commits em português, Conventional Commits (
feat,fix,docs,test,chore). - Antes de commitar:
git status,git diff, e os checks acima. - Se houver trabalho de outra sessão no working tree, não o inclua no seu commit.
Definição de pronto
cd contracts && forge fmt --check && forge test -vvvcd web && npm run lint && npm run build- Nenhum segredo, endereço falso ou fundo real.
- Docs/agents atualizados se mudou comandos, rotas ou invariantes.
- Commit com autor
codingsh, sem coautoria.
Onde ler mais
README.md— visão geral, arquitetura, fatos on-chain.contracts/AUDIT.md— triage Aderyn/Slither e riscos aceitos.contracts/README.md— detalhes de build e deploy.web/README.md— rotas, env e fork.SECURITY.md— política de disclosure.agents/README.md— índice do material para agentes..opencode/skills/project-docs/SKILL.md— doutrina de documentação: como verificar um fato, invariante vs. snapshot, e o formato de uma entrada de achado. Use ao escrever ou revisar qualquer doc do projeto.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

