--- name: kudzu-burn-a-thon description: Participate in the kudzu.rodeo Burn-a-Thon competition on the Forma network. Covers bridging TIA to Forma, fetching contract ABIs from explorer.forma.art, executing batchBuyAndBurn transactions to climb the leaderboard ("Nuke to 1st"), checking leaderboard standings, and claiming round prizes via rewardWinner. Use when the user wants to compete in Kudzu Burn, burn Kudzu tokens for points, check burn leaderboard rankings, or claim burn round winnings. compatibility: Requires network access, an Ethereum-compatible wallet with TIA on Forma (chain ID 984122), and a web3 library (ethers.js, viem, or web3.py). metadata: author: kudzu-rodeo version: "1.0" --- # Kudzu Burn-a-Thon Compete in the [kudzu.rodeo](https://kudzu.rodeo) Burn-a-Thon by burning Kudzu ERC-1155 tokens on the **Forma network** (chain ID `984122`) to earn points on an on-chain leaderboard. The top burner at the end of each round wins that round's prize pool. ## Why It's Still Profitable Each round awards **420 TIA** ($150) to the 1st-place burner. As of writing, reaching 1st place on the leaderboard would only require buying and burning roughly **~20 TIA** worth of Kudzu tokens on Modularium — meaning a potential profit of **~400 TIA** in a single round. ## Contract Addresses | Contract | Address | | --------------------- | -------------------------------------------- | | KudzuBurnController | `0x8c91C64a2e8B0E30ad5cc1e3D6fAB967DE6aA1E2` | | KudzuBurn | `0x53E96ACF13dcb21e37bA1527868A2fBfd3d0d87C` | | Kudzu (ERC-1155) | `0x18130DE989d8883C18E0BDbBd3518B4Ec1f28F7e` | | Modularium (marketplace) | `0x98DF8F54ac374B5F9d814f09978E5287C27e3Ef6` | ## Forma Network Details | Parameter | Value | | ------------ | -------------------------------------- | | Chain ID | `984122` | | RPC URL | `https://rpc.forma.art` | | Explorer | `https://explorer.forma.art` | | Native Token | TIA (Celestia) | --- ## Step 1: Acquire TIA on the Forma Network Forma uses **TIA** (Celestia's native token) as its gas and value token. To get TIA on Forma you must bridge from another network, or ask your human to do so for you. ### Bridge Options 1. **Official Forma Bridge** — Bridge TIA from Celestia mainnet to Forma at [bridge.forma.art](https://bridge.forma.art). 2. **Third-party bridges** — Services such as [Squid Router](https://app.squidrouter.com), [Relay](https://relay.link), or [MiniBridge](https://minibridge.chaineye.tools) support bridging ETH/USDC from Ethereum, Arbitrum, Base, or Optimism to TIA on Forma. ### Verification After bridging, confirm your TIA balance by querying the Forma RPC: ```bash curl -s https://rpc.forma.art \ -X POST \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["YOUR_ADDRESS","latest"],"id":1}' ``` --- ## Step 2: Fetch Contract ABIs from the Explorer API The Forma block explorer exposes a REST API for verified contracts. Fetch the ABI for any contract: ``` GET https://explorer.forma.art/api/v2/smart-contracts/ ``` ### KudzuBurnController ABI ```bash curl -s https://explorer.forma.art/api/v2/smart-contracts/0x8c91C64a2e8B0E30ad5cc1e3D6fAB967DE6aA1E2 \ | jq '.abi' ``` ### KudzuBurn ABI ```bash curl -s https://explorer.forma.art/api/v2/smart-contracts/0x53E96ACF13dcb21e37bA1527868A2fBfd3d0d87C \ | jq '.abi' ``` ### Kudzu (ERC-1155) ABI ```bash curl -s https://explorer.forma.art/api/v2/smart-contracts/0x18130DE989d8883C18E0BDbBd3518B4Ec1f28F7e \ | jq '.abi' ``` ### Modularium ABI (proxy — use the implementation address) Modularium (`0x98DF...`) is an ERC-1967 proxy. Its explorer page only returns the proxy ABI. Fetch the **implementation** ABI instead: ```bash curl -s https://explorer.forma.art/api/v2/smart-contracts/0xd679Fd32e75d7Af2FE90b7BB90362AD58b9cAb10 \ | jq '.abi' ``` Use this ABI with the **proxy address** (`0x98DF8F54ac374B5F9d814f09978E5287C27e3Ef6`) when instantiating the contract. The `.abi` field in each response is a JSON array you can pass directly to ethers.js `new Contract(address, abi, signer)` or equivalent. --- ## Step 3: Approve Kudzu Tokens for Burning Before burning, the KudzuBurnController must be approved to transfer your Kudzu tokens. Call `setApprovalForAll` on the Kudzu ERC-1155 contract: ```js const kudzu = new ethers.Contract(KUDZU_ADDRESS, kudzuAbi, signer); const tx = await kudzu.setApprovalForAll( "0x8c91C64a2e8B0E30ad5cc1e3D6fAB967DE6aA1E2", // KudzuBurnController true ); await tx.wait(); ``` This only needs to be done once per wallet. --- ## Step 4: "Nuke to 1st" — Execute `batchBuyAndBurn` The `batchBuyAndBurn` function on **KudzuBurnController** lets you buy Kudzu tokens from Modularium sell orders and burn them in a single transaction. This is the primary way to race up the leaderboard. ### Function Signature ```solidity function batchBuyAndBurn( uint256[] memory orderIds, // Modularium sell-order IDs to fill uint256[] memory qtys, // Quantities to buy from each order uint256[] memory tokenIds, // Token IDs to burn (from your wallet) uint256[] memory tokenQtys // Quantities of each token to burn ) public payable; ``` ### How It Works 1. If `orderIds` is non-empty, the controller calls `modularium.bulkTakeSellOrders` with your `msg.value` to purchase tokens. Tokens are delivered to **your wallet** (`recipient: msg.sender`). 2. It then calls `batchBurn` on all `tokenIds`/`tokenQtys`, transferring tokens from your wallet to the dead address (`0x...dEaD`) and awarding burn points. 3. **Burn points**: Each token burned earns `burnPoint` (currently 1) points per quantity. 4. **New strain bonus**: The first time you burn a particular token ID you receive `newStrainBonus` (currently 5) extra points. > **Purchased tokens are NOT automatically burned.** The `orderIds`/`qtys` arrays (buying) and `tokenIds`/`tokenQtys` arrays (burning) are independent. If you buy tokens via `orderIds` but don't include their token IDs in `tokenIds`, they'll sit in your wallet unburned. To buy and burn in one call, you must list the purchased token IDs in **both** the order arrays and the burn arrays. ### `bulkTakeSellOrders` Struct Reference Under the hood `batchBuyAndBurn` constructs a `BulkTakeOrderParams` struct and forwards your `msg.value`: ```solidity struct BulkTakeOrderParams { uint256[] orderIds; // Modularium sell-order IDs to fill uint256[] qty; // Quantities to fill from each order address recipient; // Set to msg.sender (your wallet) } ``` The `recipient` is hardcoded to `msg.sender` inside `batchBuyAndBurn`, so bought tokens always arrive in the caller's wallet before `batchBurn` transfers them to the dead address. ### Finding Modularium Sell Orders Modularium assigns auto-incrementing order IDs starting at 1 (the counter `_nextOrderId` is private — there is no public getter). You have two approaches to discover sell orders for Kudzu tokens: **Approach A — Scan `MakeOrder` events:** ```js const modularium = new ethers.Contract( "0x98DF8F54ac374B5F9d814f09978E5287C27e3Ef6", modulariumAbi, // implementation ABI provider ); const filter = modularium.filters.MakeOrder(); const events = await modularium.queryFilter(filter, -100000); // last 100k blocks const kudzuOrders = events .map(e => e.args) .filter(a => a.order.token.tokenAddress.toLowerCase() === "0x18130DE989d8883C18E0BDbBd3518B4Ec1f28F7e".toLowerCase()) .filter(a => a.order.orderType === 1n); // SELL orders only ``` **Approach B — Iterate order IDs and filter:** ```js const KUDZU = "0x18130DE989d8883C18E0BDbBd3518B4Ec1f28F7e".toLowerCase(); const sellOrders = []; for (let id = 1; ; id++) { try { const o = await modularium.order(id); // Skip non-existent orders (maker == zero address) if (o.maker === ethers.ZeroAddress) break; // Filter: Kudzu tokens, SELL type, ACTIVE status, not fully filled if ( o.token.tokenAddress.toLowerCase() === KUDZU && o.orderType === 1n && // SELL o.orderStatus === 0n && // ACTIVE o.filled < o.qty ) { sellOrders.push({ orderId: o.orderId, tokenId: o.token.tokenId, price: o.price, remaining: o.qty - o.filled }); } } catch { break; // past the last order } } ``` **Key Modularium structs** (from `SimpleMarketplaceUpgradeable`): ```solidity struct Order { uint256 orderId; OrderStatus orderStatus; // 0 = ACTIVE, 1 = CANCELLED address maker; address recipient; OrderType orderType; // 0 = BUY, 1 = SELL Token token; uint256 qty; uint256 price; // price per unit in wei (TIA) uint256 filled; uint128 validFrom; uint128 validUntil; bool isCollectionOrder; } struct Token { address tokenAddress; uint256 tokenId; TokenType tokenType; // ERC721, ERC1155, etc. } ``` Use `hasAlreadyBurned(address burner, uint256 tokenId)` on the Controller to check whether burning a specific token ID will earn the `newStrainBonus` (5 extra points) or just the base `burnPoint` (1 point). Prioritize orders for token IDs you haven't burned yet. ### Example: Buy & Burn ```js const controller = new ethers.Contract( "0x8c91C64a2e8B0E30ad5cc1e3D6fAB967DE6aA1E2", controllerAbi, signer ); // Buy from Modularium orders 42 and 99 (qty 1 each), then also burn // token 203300 (qty 3) and token 205000 (qty 2) already in your wallet const tx = await controller.batchBuyAndBurn( [42, 99], // orderIds [1, 1], // qtys to buy [203300, 205000], // tokenIds to burn from wallet [3, 2], // tokenQtys to burn { value: ethers.parseEther("0.5") } // TIA to pay for orders ); await tx.wait(); ``` ### Burn Only (No Purchase) If you already hold tokens and just want to burn: ```js const tx = await controller.batchBurn( [203300, 205000], // tokenIds [3, 2] // quantities ); await tx.wait(); ``` ### Important Rules - **Do not include duplicate token IDs** in a single `batchBurn` call — the contract enforces `"DO NOT BATCH BURN THE SAME TOKEN ID"`. - Each call also triggers `kudzuBurn.rewardWinner()` which automatically closes any finished round before processing your burn. - **Check `paused()` before burning.** If `kudzuBurn.paused()` returns `true`, all burn transactions will revert. Query it first and wait until it's unpaused. ### Checking Your Token Balances Kudzu is an ERC-1155 token. Before burning, verify you actually hold the tokens: ```js const kudzu = new ethers.Contract( "0x18130DE989d8883C18E0BDbBd3518B4Ec1f28F7e", kudzuAbi, provider ); // Single token const bal = await kudzu.balanceOf(myAddress, 203300); console.log(`Token 203300 balance: ${bal}`); // Multiple tokens at once const addresses = [myAddress, myAddress, myAddress]; const tokenIds = [203300, 205000, 210100]; const balances = await kudzu.balanceOfBatch(addresses, tokenIds); console.log(`Balances:`, balances.map(b => b.toString())); ``` This is useful after purchasing from Modularium to confirm tokens arrived before including them in a burn call. --- ## Step 5: Check Leaderboard Status All leaderboard data lives on-chain in the **KudzuBurn** contract (`0x53E96ACF13dcb21e37bA1527868A2fBfd3d0d87C`). ### Key Read Functions | Function | Returns | Description | | ------------------------------------------- | --------------------------------- | ------------------------------------------------- | | `getWinningAddress()` | `address` | Current 1st-place burner | | `getValueAndOwnerAtRank(uint256 rank)` | `(uint256 points, address owner)` | Points and address at a given rank (0 = 1st) | | `getOwnerAtRank(uint256 rank)` | `address` | Address at rank | | `getValueAtRank(uint256 rank)` | `uint256` | Points at rank | | `getRankOfOwner(address owner)` | `uint256` | Rank of a specific address (0 = 1st) | | `getPoints(address burner)` / `burnerPoints(address)` | `uint256` | Total points for an address | | `size()` | `uint256` | Number of participants on the leaderboard | | `contains(address owner)` | `bool` | Whether an address is on the leaderboard | | `currentRound()` | `uint256` | Index of the active round (0–10 are funded) | | `rounds(uint256 index)` | `(uint256 order, uint256 endDate, uint256 payoutToRecipient)` | Round details | | `isOver()` | `bool` | Whether the current round has ended | ### Example: Check Your Rank and the Leader ```js const kudzuBurn = new ethers.Contract( "0x53E96ACF13dcb21e37bA1527868A2fBfd3d0d87C", kudzuBurnAbi, provider ); // Who is winning? const leader = await kudzuBurn.getWinningAddress(); const [leaderPoints] = await kudzuBurn.getValueAndOwnerAtRank(0); console.log(`Leader: ${leader} with ${leaderPoints} points`); // What's my rank? const myPoints = await kudzuBurn.getPoints(myAddress); const myRank = await kudzuBurn.getRankOfOwner(myAddress); console.log(`My points: ${myPoints}, rank: ${myRank}`); // How many participants? const total = await kudzuBurn.size(); console.log(`Total burners on leaderboard: ${total}`); ``` ### Example: Check Round Status ```js const currentRound = await kudzuBurn.currentRound(); const [order, endDate, payout] = await kudzuBurn.rounds(currentRound); const isOver = await kudzuBurn.isOver(); console.log(`Round ${order} (index ${currentRound})`); console.log(`Ends: ${new Date(Number(endDate) * 1000).toISOString()}`); console.log(`Prize pool: ${ethers.formatEther(payout)} TIA`); console.log(`Round over: ${isOver}`); ``` ### Round Schedule Rounds 1–2 were on a 3-month cadence. Starting with Round 3 the schedule switched to **1-month** intervals. | Round | End Date | | ----- | ---------- | | 1 | 2025-04-20 | | 2 | 2025-07-20 | | 3 | 2025-08-20 | | 4 | 2025-09-20 | | 5 | 2025-10-20 | | 6 | 2025-11-20 | | 7 | 2025-12-20 | | 8 | 2026-01-20 | | 9 | 2026-02-20 | | 10 | 2026-03-20 | | 11 | 2026-04-20 | --- ## Step 6: Claim the Prize with `rewardWinner` When a round ends, **anyone** can call `rewardWinner()` on the KudzuBurn contract to pay out the round's prize to the 1st-place burner and advance to the next round. ### Function Signature ```solidity function rewardWinner() public; ``` ### How It Works 1. Checks `isOver()` — if the current round's `endDate` has passed. 2. Gets the winning address via `getWinningAddress()` (rank 0 on the leaderboard). 3. Resets the winner's points to zero (with `rewardId = 1`). 4. Sends the round's `payoutToRecipient` (the prize pool in TIA) to the winner. 5. Increments `currentRound`. ### Example: Trigger Prize Payout ```js const kudzuBurn = new ethers.Contract( "0x53E96ACF13dcb21e37bA1527868A2fBfd3d0d87C", kudzuBurnAbi, signer ); const isOver = await kudzuBurn.isOver(); if (isOver) { const winner = await kudzuBurn.getWinningAddress(); console.log(`Round winner: ${winner}`); const tx = await kudzuBurn.rewardWinner(); await tx.wait(); console.log("Prize claimed and round advanced!"); } ``` ### Important Notes - `rewardWinner` is **permissionless** — any address can call it, not just the winner. - The contract must not be paused (`paused == false`). - `rewardWinner` is also called automatically inside every `batchBuyAndBurn`, `batchBurn`, and `burn` call, so prizes are typically settled organically. - After the winner's points are reset they start fresh for the next round. All other participants keep their points. - Sending TIA directly to the KudzuBurn contract address will also trigger `rewardWinner` if the round is over (via the `receive()` fallback), and the sent TIA is added to the current round's pool. --- ## Quick Reference: Full Workflow ``` 1. Bridge TIA to Forma → bridge.forma.art or third-party bridge 2. Fetch ABIs → explorer.forma.art/api/v2/smart-contracts/{address} 3. Approve KudzuBurnController → kudzu.setApprovalForAll(controller, true) 4. Buy + Burn tokens → controller.batchBuyAndBurn(orderIds, qtys, tokenIds, tokenQtys, {value}) 5. Check leaderboard → kudzuBurn.getWinningAddress() / getRankOfOwner(you) 6. Claim round prize → kudzuBurn.rewardWinner() ``` --- ## Common Pitfalls - **Modularium is a proxy.** Its explorer page (`0x98DF...`) returns the ERC1967Proxy ABI (just a `fallback`), not the marketplace functions. Fetch the *implementation* ABI at `0xd679Fd32e75d7Af2FE90b7BB90362AD58b9cAb10` (`SimpleMarketplaceUpgradeable`) to get `bulkTakeSellOrders`, `makeSellOrder`, `takeSellOrder`, etc. - **`batchBurn` lives on the Controller, not KudzuBurn.** Call `controller.batchBurn(tokenIds, quantities)`, not `kudzuBurn.batchBurn(...)`. The KudzuBurn contract only exposes `rewardWinner()` and read functions to external callers. - **`getValueAndOwnerAtRank` return order is `(uint256 points, address owner)`.** Don't destructure it as `(address, uint256)` — points come first. - **Round 11 (index 10, ending 2026-04-20) is the last funded round.** Indices 11+ exist on-chain but have `payoutToRecipient = 0` and dates in 2028. Don't assume 13 playable rounds. - **ESM vs CommonJS.** If your `package.json` has `"type": "module"`, use `import` syntax or name files `.cjs`. A bare `require('ethers')` will throw `ReferenceError: require is not defined in ES module scope`. - **`burnerPoints(address)` vs `getPoints(address)`.** Both return the same value, but `burnerPoints` is the raw mapping accessor (returns 0 for unknown addresses without reverting) while `getPoints` is the explicit getter. Either works, just be consistent. - **Use the proxy address, not the implementation address, when calling Modularium.** Instantiate the contract with the proxy address (`0x98DF...`) but the implementation ABI (`SimpleMarketplaceUpgradeable`). Calling the implementation address directly will bypass the proxy's storage. - **`getRankOfOwner` on an unranked address.** If the address hasn't burned anything and isn't on the leaderboard, this call may revert or return an unexpected value. Check `contains(address)` first. - **`hasAlreadyBurned(address, tokenId)` is on the Controller.** Use it to check if a token ID will earn the 5-point new strain bonus before spending TIA to buy it. If it returns `true`, you'd only get 1 point per quantity — might not be worth the cost. - **Purchased tokens are not auto-burned.** `batchBuyAndBurn` buys tokens into your wallet first, then burns whatever is in `tokenIds`/`tokenQtys`. If you forget to include purchased token IDs in the burn arrays, you spend TIA but earn zero points from those tokens. - **`paused()` blocks all burns.** Always check `kudzuBurn.paused()` before submitting a burn transaction. When the contract is paused, `batchBurn`, `batchBuyAndBurn`, and `burn` all revert. - **No public `nextOrderId()` on Modularium.** The order counter is private. Discover orders by scanning `MakeOrder` events or iterating `order(i)` until you hit a zero-address maker.