hamstr
🇬🇧 English · 🇩🇪 Deutsch
DeFi BTC maxi aggregator: Stack Bitcoin. Automatically.
Users deposit USDC or ETH. The principal stays where it is – only the interest is turned into Bitcoin (cbBTC) automatically and can be claimed at any time. Runs on Base.
⚠️ Beta, not externally audited. Do not use with money you cannot afford to lose.
How it works
User ──USDC/ETH──▶ BtcYieldVault ──▶ AaveV3Strategy ──▶ Aave V3 (interest)
│
Keeper ──harvest()──▶ OracleUniswapSwapper ──▶ Uniswap V3 ──▶ cbBTC
│ ▲
│ Chainlink price as floor
▼
claim() ──cbBTC──▶ User
- Principal 1:1: deposit 1,000 USDC = 1,000 shares = withdraw 1,000 USDC any time.
- Fair distribution: interest is credited to existing holders on every deposit and withdrawal. Depositing right before a harvest does not capture other people's interest.
- Harvest: a keeper regularly swaps the accumulated interest into cbBTC on Uniswap. Every period has its own rate; everyone gets exactly their share.
- Swap protection: if the Uniswap price is more than 1 % below Chainlink, the swap is rejected (protects against MEV and a compromised keeper). Stale prices or a Base sequencer outage also block it.
- Fee: 10 % of the interest (performance fee), capped at 20 % in the contract. 0 % on deposits and withdrawals.
Turbo Hamster (high risk)
An optional vault for people who knowingly take risk: ETH is deposited, the vault provides concentrated WETH/cbBTC liquidity on Uniswap V3 (range ±8 %), and the trading fees are paid out as cbBTC. The deposit is not protected – when ETH and BTC move apart, the position ends up holding more of the weaker coin (impermanent loss); withdrawing makes the loss final. Fork test: ETH −15 % vs BTC → 6.2 % less than holding half/half.
- Shares priced with Chainlink, never with the pool price; withdrawals and keeper actions revert if the pool is more than 1 % away from Chainlink (anti-manipulation)
- Fees are credited per share on every deposit/withdrawal/transfer, so late depositors get nothing earned before them
- The keeper re-centers the range when the price leaves it and deploys idle deposits
- In the UI: interactive impermanent-loss simulator, two quiz questions and a risk confirmation before the vault unlocks; the dashboard always shows value vs. ETH deposited
- Deploy on top of the existing contracts:
contracts/script/deploy-turbo-mainnet.ps1 (limits 0.5 ETH total / 0.2 ETH per address)
Security model
| Role | Who | Can |
|---|
| Admin | TimelockController (2-day delay), controlled by the multisig | change strategy, swapper, fees, limits |
| Guardian | Multisig | pause immediately, pull funds out of the strategy |
| Keeper | Bot wallet | only harvest() – swap floor enforced by Chainlink |
Withdrawing and claiming always work, even while paused. The deployer keeps no rights after deployment (checked by the deploy script).
Project structure
contracts/ Foundry: smart contracts, tests, deploy script
src/BtcYieldVault.sol Vault ("interest becomes BTC")
src/swappers/OracleUniswapSwapper.sol Uniswap swap with Chainlink floor
src/strategies/AaveV3Strategy.sol Aave V3 lending
src/TurboVault.sol HIGH RISK: Uniswap V3 WETH/cbBTC liquidity, fees paid as cbBTC
src/YieldVault.sol ERC-4626 vault (base for a future pure BTC vault)
script/Deploy.s.sol Deployment incl. timelock, roles, limits
web/ Next.js frontend with hamster UI, passkey login (Base Account), English + German
keeper/ Harvest bot (Node + viem), runs daily via GitHub Actions
Development
Requirements: Foundry, Node.js 20+, Git.
git clone --recursive https://github.com/gabbergandalfderreiche/hamstr.git
cd hamstr/contracts
forge test # unit tests + tests against a copy of Base mainnet
Test locally with real contracts (Base fork, test money)
# terminal 1
anvil --fork-url https://mainnet.base.org --chain-id 31337
# terminal 2
cd contracts && bash script/local-fork.sh # deploys + 20,000 test USDC
cd ../web && npm install && npm run sync-contracts
cp .env.example .env.local # set NEXT_PUBLIC_NETWORK=fork
npm run dev # http://localhost:3000/app → "Test wallet (local)"
# move time forward + harvest like the keeper
cd contracts && HOURS=12 bash script/local-harvest.sh
The local scripts use anvil's public test keys. Never use these addresses on a real network – on Base mainnet they carry EIP-7702 "sweeper" delegations that steal incoming ETH.
Mainnet deployment
cd contracts
MULTISIG=0x... KEEPER=0x... TREASURY=0x... \
forge script script/Deploy.s.sol --rpc-url https://mainnet.base.org --broadcast --account <keystore>
cd ../web && npm run sync-contracts
Beta defaults (override via environment variables): 2-day timelock, 50,000 USDC / 5,000 USDC per person, 15 ETH / 1.5 ETH per person, 10 % performance fee, max. 1 % deviation from Chainlink, Chainlink prices at most 1 h old (ETH, cbBTC) or 25 h (USDC).
Keeper (daily harvest)
keeper/src/keeper.mjs harvests both vaults, but only when it pays off:
- skips paused vaults and amounts below
minHarvest
- values the interest in USD and sats via Chainlink
- simulates
harvest() first – stale prices, a deficit or a missing role cost no gas
- estimates the fee (L2 + L1 data) and only harvests when the interest is worth ≥ 5× the fee
- sets its own minimum output (0.75 % below Chainlink) on top of the swapper's floor
Runs daily via GitHub Actions. Add BASE_RPC_URL and KEEPER_PRIVATE_KEY under Settings → Secrets → Actions and fund the keeper wallet with ~0.005 ETH on Base. Until the mainnet deployment the job simply exits. Real problems (stale oracle, deficit, missing role, low gas balance) fail the run → GitHub sends an e-mail.
Note: GitHub pauses scheduled workflows in public repos after 60 days without commits – re-enable it under Actions.
# test locally against the fork (anvil gas prices are ~170x higher than Base, so lower the threshold)
cd contracts && HOURS=24 SKIP_HARVEST=1 bash script/local-harvest.sh
cd .. && RPC_URL=http://127.0.0.1:8545 DEPLOYMENT=contracts/deployments/31337.json \
KEEPER_PRIVATE_KEY=<anvil #0> MIN_PROFIT_MULTIPLE=0.05 node keeper/src/keeper.mjs
Languages
The website is available in English and German (/en/..., /de/...). Visitors without a language in the URL are redirected based on their browser language; the DE | EN switcher remembers the choice in a cookie. All texts live in web/src/i18n – en.ts is type-checked against de.ts, so a missing translation fails the build.
Status
License
MIT
