About Projects Articles
Recent projects

Forge

Built Oct–Nov 2025

ERC-1155 Token-Composition

SBSiegfried Bozza
View GitHubView Live
Forge — screenshot 1
Forge — screenshot 2
Forge — screenshot 3
Forge — screenshot 4
Forge — screenshot 5
Forge — screenshot 6
Forge — screenshot 7
Forge — screenshot 8

Tier composition

Atomic burn/mint paths for forged token IDs (Forge README).

Overview

ERC-1155 games and crafting loops need supply mutations that stay atomic: burn inputs and mint outputs in one transaction, with rules separated from the token ledger so balances cannot be half-updated.

Forge splits FToken (ledger) from Forge (rules). Composite IDs 3–6 use burnBatch + mint in a single tx; basic mints are cooldown-gated; the Next.js UI syncs via Alchemy WebSockets and TanStack Query invalidation.

Technical Architecture

Forge is an experiment in keeping composition rules and supply mutations honest on ERC-1155. The ledger (FToken) stays supply-focused; the rules (Forge) encode cooldowns, recipes, trade constraints, and burn permissions. Every supply change routes through Forge, which is the immutable owner of FToken after deploy. For forged token IDs 3–6, Forge.mint calls burnBatch then mint in one transaction so balances do not end up half-updated on success paths. Basic mints (0–2) are cooldown-gated; the Next.js UI listens to Forge events over Alchemy WebSockets with wagmi and invalidates TanStack Query keys instead of polling. The same split between rules and balances shows up in other domains (crafting loops, inventory-like state machines, enforced burn-mint flows) — spelled out under transferable patterns below rather than as product claims here.

Key features

  • On-Chain Crafting System (ERC-1155): Players mint basic tokens and forge rare items by burning combinations, enforced entirely by Solidity logic.
  • CEI & Atomic Composition: Basic mint updates userCoolDownTimer before the external I_TOKEN.mint call (Checks-Effects-Interactions). For forged IDs 3–6, mint performs burnBatch then mint in one transaction — no half-updated balances.
  • Logic / Asset Contract Separation: FToken mint, burn, and burnBatch are onlyOwner; only the deployed Forge address can mutate supply. Forge owns FToken immutably after deployment.
  • Cooldown-Based Minting: Per-address cooldown on basic mints (IDs 0–2) enforces rate limits without a centralised API.
  • Event-Driven UI Updates: Real-time syncing of mint, burn, forge, and trade events via Alchemy WebSockets.
  • 100% Contract Test Coverage: Foundry coverage report: 100% lines, statements, branches, and functions across Forge.sol, FToken.sol, and both deployment scripts (ForgeScript, FTokenScript).
  • Verified Smart Contracts: Deployed to Sepolia and automatically verified on Etherscan for transparency.

Technologies Used

ERC-1155 crafting case study — atomic burn-then-mint for composites, access-controlled logic vs ledger split, and 100% Foundry coverage on project-owned contracts (Next.js + wagmi).
  • TypeScript
  • React
  • Next.js
  • Zod
  • React Hook Form
  • TanStack Query
  • Solidity
  • Foundry
  • OpenZeppelin
  • Wagmi
  • RainbowKit
  • Viem
  • Alchemy
  • IPFS
  • shadcn/ui
  • Tailwind CSS
  • Solidity + Foundry: Implements ERC-1155 minting, forging, burning, trading logic, plus full test suite with 100% coverage.
  • Next.js + Wagmi: Frontend framework with wallet integration, event listeners, and reactive state management.
  • Alchemy WebSockets: Real-time synchronization for mint, forge, burn, and trade events with selective refetching.
  • ERC-1155 Architecture: Efficient multi-token setup supporting crafting rules, metadata, and IPFS hosting.
  • OpenZeppelin: ERC-1155 base implementation behind FToken; supply mutations gated behind onlyOwner so only the immutable Forge owner can mutate balances.

Challenges and Learnings

Encoding recipes, cooldowns, and trade/burn rules so they stay readable in Solidity without hiding edge cases. Reaching 100% Foundry coverage meant exhaustive happy-path and revert coverage across Forge.sol, FToken.sol, and deploy scripts. Event-driven UI updates required careful TanStack Query key design so each Forge event only invalidates what changed.

Outcome

Forge on Sepolia shows atomic ERC-1155 composition with verified contracts and a small single-page Next.js client — a focused case study, not a shipped game economy.

Key Metrics

  • Test rigor: 37 Foundry tests — 100% coverage on project-owned contracts
  • Coverage (Foundry): 95/95 lines · 99/99 statements · 19/19 branches · 17/17 functions — Forge.sol, FToken.sol, and deploy scripts
  • Sepolia addresses: Forge · FToken
  • Deployment: Sepolia — Forge & FToken verified on Etherscan
  • Architecture: Forge is immutable owner of FToken; only Forge mutates supply; forged IDs use burnBatch + mint in one tx

Transferable patterns: DeFi-style position composition, supply-chain traceability metaphors, on-chain cooldowns as simple rate limits, ERC-1155 batch operations for atomic multi-token updates.

Known limitations

  • Single network — Sepolia deployment for learning; no mainnet or multi-chain story in this repo.
  • Cooldown model — One global delay for basic mints (IDs 0–2); no per-token issuance curves yet.
  • Marketplace — No secondary marketplace integration beyond the on-chain trade helper into basics.

Roadmap

  • L2 comparison — Deploy the same Forge/FToken pattern to an L2 testnet and compare gas on burnBatch + mint paths vs Sepolia.
  • Progressive cooldowns — Per-id or tiered cooldown tuning instead of a single mapping.
  • Marketplace hooks — Pair the contracts with standard ERC-1155 marketplace flows.
View GitHubView Live