Cobox NFT Contracts

On-chain identity and creator-world NFT smart contracts for Cobox — a gaming and creator NFT marketplace — deployed on BNB Smart Chain (BSC).

BNB Chain deployment: These contracts are built for and deployed to BNB Smart Chain Mainnet (Chain ID 56). BNB Smart Chain Testnet (Chain ID 97) is used for staging. BNB is the native gas and mint-payment currency throughout these contracts.

---

Overview

Cobox is a gaming and creator marketplace. This repository holds the official source code for the platform's two NFT contracts, both running on BNB Smart Chain:

Contract	Symbol	Standard	Purpose
COBX	COBX	ERC-20	Cobox platform token. Fixed supply, fully minted at deployment.
UsernameNFT	CBXU	ERC-721	On-chain identity. One username NFT per wallet, always user-paid in BNB.
EnvironmentNFT	CBXE	ERC-721 + ERC-2981	Creator-minted worlds/environments with on-chain creator royalties.

Both inherit a shared revenue/treasury base, CoboxNFTRevenue, which routes all mint revenue (paid in BNB) to an on-chain treasury address that only a finance admin role can change.

This repository contains only the smart-contract layer of the Cobox platform. Backend microservices, indexers, and the frontend are maintained separately; the contracts here are self-contained and independently verifiable on BNB Smart Chain.

---

Why BNB Smart Chain

• Native currency: All mint prices, treasury sweeps, and gas are denominated in BNB.
• Primary network: hardhat.config.ts sets BNB Smart Chain Mainnet (56) as the production target and BSC Testnet (97) for staging — see bnbconfig.json.
• RPC endpoints: Configuration points explicitly at BNB Smart Chain data-seed nodes (bsc-dataseed.bnbchain.org).
• Verification: Contracts are verified on BscScan (bscscan.com) via the included verification script.
• EVM target: Compiled with the paris EVM version for full BNB Smart Chain compatibility.

---

Technology Stack

• Blockchain: BNB Smart Chain (BSC) — Chain ID 56 mainnet, 97 testnet
• Smart Contracts: Solidity 0.8.24
• Libraries: OpenZeppelin Contracts ^5.0 (ERC721, ERC721URIStorage, ERC2981, AccessControl, Pausable, ReentrancyGuard)
• Tooling: Hardhat + @nomicfoundation/hardhat-toolbox, TypeScript
• Explorer / Verification: BscScan

---

Supported Networks

Network	Chain ID	Role	RPC	Explorer
BNB Smart Chain Mainnet	56	Production (primary)	https://bsc-dataseed.bnbchain.org	https://bscscan.com
BNB Smart Chain Testnet	97	Staging	https://data-seed-prebsc-1-s1.bnbchain.org:8545	https://testnet.bscscan.com

---

Contract Addresses

Deployment addresses are written to deployments/ after each deploy and recorded below.

Network	COBX (ERC-20)	UsernameNFT (CBXU)	EnvironmentNFT (CBXE)
BNB Smart Chain Mainnet (56)	0x8AE78dbD907FF0BDFb539aC41696190a600b66F1	0xbaa0ef80cec0b2efc93cc7fb70e528b4366fba96	0x79D5be51CE95F2ca034a34a590aa739A10142ad6
BNB Smart Chain Testnet (97)	0x...	0x...	0x...

COBX is live and verifiable on BscScan. NFT addresses are recorded in deployments/bscMainnet.json; confirm each on BscScan before relying on it.

---

Features

• Platform token (COBX) — A fixed-supply ERC-20 token on BNB Smart Chain, fully minted to the owner at deployment with no further minting. Live at 0x8AE78dbD…b66F1.
• On-chain identity — Username NFTs (CBXU) provide a wallet-bound, transferable handle on BNB Smart Chain. Enforced one-per-wallet, validated charset (a–z, 0–9, _), reservation and ban support.
• Creator royalties — Environment NFTs (CBXE) implement ERC-2981, with royalties capped on-chain (≤ 50%) and payable to the original creator.
• BNB treasury routing — All mint revenue accrues in BNB and can only be swept to an on-chain treasury address, changeable solely by ADMIN_FINANCE_ROLE. The sweeper needs no privileged role.
• Gas-less onboarding — A whitelisted SPONSOR_ROLE can mint usernames/environments on a user's behalf, with a hard on-chain cap (sponsoredMintLimit) to bound exposure.
• Safety controls — Pausable halts mint/transfer/burn in emergencies; ReentrancyGuard protects treasury withdrawals; role-gated administration designed for a multisig (Gnosis Safe) on BNB Chain.

---

Repository Structure

cobox-nft-contracts/
├── contracts/
│   ├── CoboxNFTRevenue.sol     # Shared revenue/treasury base (abstract)
│   ├── COBX.sol                # COBX — platform token (ERC-20)
│   ├── UsernameNFT.sol         # CBXU — on-chain identity (ERC-721)
│   └── EnvironmentNFT.sol      # CBXE — creator worlds (ERC-721 + ERC-2981)
├── scripts/
│   ├── deploy.ts               # Deploy to BNB Smart Chain
│   └── verify.ts               # Verify on BscScan
├── test/
│   └── CoboxNFT.test.ts        # Full test suite
├── deployments/                # Per-network deployment records (BNB Chain)
├── docs/
│   ├── ARCHITECTURE.md         # System & contract architecture
│   └── diagrams/               # Mint, treasury, role flow diagrams (Mermaid)
├── bnbconfig.json              # BNB Chain network configuration
├── hardhat.config.ts           # Hardhat config (BSC mainnet/testnet)
├── .env.example                # Environment variable template
└── README.md

---

Quick Start

Prerequisites

• Node.js ≥ 18
• A funded deployer wallet on BNB Smart Chain (BNB for gas)
• A BscScan API key for verification

Install

git clone https://github.com/cobox-games/cobox-nft-contracts.git
cd cobox-nft-contracts
npm install
cp .env.example .env   # then fill in your values

Compile & Test

npm run compile
npm test

Deploy to BNB Smart Chain

# Testnet (Chain ID 97)
npm run deploy:bsc-testnet

# Mainnet (Chain ID 56)
npm run deploy:bsc

Verify on BscScan

npm run verify:bsc          # mainnet
npm run verify:bsc-testnet  # testnet

---

Architecture

See docs/ARCHITECTURE.md for the full breakdown, including mint flows, treasury/sweep flow, role hierarchy, and how the contracts fit into the broader Cobox platform on BNB Smart Chain. Diagrams live in docs/diagrams/.

---

Security

• Administration is role-gated (DEFAULT_ADMIN_ROLE, ADMIN_FINANCE_ROLE, PAUSER_ROLE, METADATA_ROLE, SPONSOR_ROLE, RESERVATION_ROLE). For production these should be held by a multisig (Gnosis Safe) on BNB Chain.
• SPONSOR_ROLE can only be granted to a pre-whitelisted address; de-whitelisting auto-revokes it.
• Treasury withdrawals are permissionless to trigger but can never be redirected by the caller.
• Contracts use OpenZeppelin audited primitives and ReentrancyGuard.

Report vulnerabilities to security@cobox.games rather than opening a public issue.

---

License

MIT © Cobox

---

Cobox is built on BNB Smart Chain. Official site: cobox.games.