Skip to content

Contracts reference

StargazeLaunchFactory, StargazeFairLaunch and StargazeToken.

Stargaze launches are executed by two Solidity 0.8.24 contracts in contracts/src, all Ownable2Step, ReentrancyGuard and Pausable (OpenZeppelin v5). Every token they create is a StargazeToken: a fixed-supply ERC-20 with permit and no owner. TypeScript ABIs ship in lib/web3/abis.ts (launchFactoryAbi, fairLaunchAbi) and the configured addresses in stargazeContracts from lib/config/chains.ts.

Deployments

Addresses come from NEXT_PUBLIC_LAUNCH_FACTORY_{MAINNET|SEPOLIA}, NEXT_PUBLIC_FAIR_LAUNCH_{MAINNET|SEPOLIA} and NEXT_PUBLIC_DEPLOY_BLOCK_{MAINNET|SEPOLIA}, read when the app is built. A network without an address has not been deployed for this build.

NetworkContractAddressDeploy block
Ethereum 1StargazeLaunchFactoryNot deployed yet—
Ethereum 1StargazeFairLaunchNot deployed yet—
Sepolia 11155111StargazeLaunchFactoryNot deployed yet—
Sepolia 11155111StargazeFairLaunchNot deployed yet—
addresses.ts
import { stargazeContracts } from "@/lib/config/chains"; const { launchFactory, fairLaunch, deployBlock } = stargazeContracts[11155111];// launchFactory / fairLaunch are undefined when the env var is unset or not a valid address

StargazeLaunchFactory

"Instant launch": a single permissionless transaction deploys a fixed-supply token, distributes the allocations and seeds a Uniswap V2 ETH pool.

Constant / immutableValue
BPS10_000
MAX_LAUNCH_FEE0.05 ether
DEAD0x000000000000000000000000000000000000dEaD
router, wethUniswap V2 Router02 and its WETH(), fixed at deployment

createToken

StargazeLaunchFactory.sol
function createToken(LaunchParams calldata p)    external payable nonReentrant    returns (address token, address pair); struct LaunchParams {    string  name;            // 1–64 bytes    string  symbol;          // 1–16 bytes    uint8   decimals;        // <= 18    uint256 totalSupply;     // raw units (already scaled by decimals), 1..type(uint112).max    string  metadataURI;     // e.g. ipfs://CID — stored once on the token    uint16  creatorBps;    uint16  communityBps;    uint16  liquidityBps;    // creatorBps + communityBps + liquidityBps == 10_000    address communityWallet; // required when communityBps > 0    bool    burnLiquidity;   // true => LP tokens to 0x…dEaD    uint256 deadline;        // unix seconds}
  • Send msg.value = launchFee + liquidityEth. Everything above launchFee is paired with the liquidity allocation.
  • communityAmount = totalSupply × communityBps / 10_000, liquidityTokenAmount = totalSupply × liquidityBps / 10_000; the creator (msg.sender) receives the remainder, so rounding dust goes to the creator and supply is conserved exactly.
  • Liquidity is added with amountTokenMin = liquidityAmt and amountETHMin = liquidityEth: the brand-new pool must open exactly at the configured ratio.
  • LP tokens go to 0x…dEaD when burnLiquidity is true, otherwise to the creator. pair is the zero address when liquidityBps == 0.
  • Any unused ETH or tokens are returned to the creator; the launch fee is forwarded to feeRecipient. The factory retains nothing.
RevertCondition
Expired()block.timestamp > deadline
InvalidName()name empty or longer than 64 bytes
InvalidSymbol()symbol empty or longer than 16 bytes
InvalidDecimals()decimals > 18
InvalidSupply()totalSupply == 0 or > type(uint112).max (Uniswap V2 reserve bound)
InvalidAllocation()the three bps values do not sum to exactly 10_000
InvalidCommunityWallet()communityBps > 0 and communityWallet == address(0)
InsufficientFee()msg.value < launchFee
LiquidityEthRequired()liquidityBps > 0 but no ETH beyond the fee
UnexpectedEth()liquidityBps == 0 but ETH was sent beyond the fee

TokenLaunched

StargazeLaunchFactory.sol
event TokenLaunched(    address indexed token,    address indexed creator,    address indexed pair,    string  name,    string  symbol,    uint8   decimals,    uint256 totalSupply,    uint256 creatorAmount,    uint256 communityAmount,    uint256 liquidityTokenAmount,    uint256 liquidityEthAmount,   // ETH actually used by the router    bool    liquidityBurned,      // burnLiquidity && liquidityAmt > 0    string  metadataURI);

Views and admin

FunctionNotes
launchFee() → uint256Current fee in wei. Read it right before launching — the owner can change it.
feeRecipient() → address
isStargazeToken(address) → boolTrue for tokens created by this factory.
allTokensLength() → uint256
allTokens(uint256) → addressIndex into the registry of every launched token.
setLaunchFee(uint256)Owner only; reverts FeeTooHigh() above MAX_LAUNCH_FEE. Emits LaunchFeeUpdated.
setFeeRecipient(address)Owner only; reverts ZeroAddress(). Emits FeeRecipientUpdated.
paused() → boolWhen true, createToken reverts EnforcedPause(). Launched tokens are never affected.
pause() / unpause()Owner only. Emit Paused(account) / Unpaused(account).

Example: createToken with viem

launch.ts
import "viem/window";import { createPublicClient, createWalletClient, custom, http, parseEther, parseEventLogs, parseUnits, zeroAddress } from "viem";import { sepolia } from "viem/chains";import { launchFactoryAbi } from "@/lib/web3/abis";import { stargazeContracts } from "@/lib/config/chains"; const factory = stargazeContracts[11155111].launchFactory;if (!factory) throw new Error("StargazeLaunchFactory is not deployed on Sepolia for this build"); const publicClient = createPublicClient({ chain: sepolia, transport: http("https://ethereum-sepolia-rpc.publicnode.com") });const wallet = createWalletClient({ chain: sepolia, transport: custom(window.ethereum!) });const [account] = await wallet.requestAddresses(); const launchFee = await publicClient.readContract({ address: factory, abi: launchFactoryAbi, functionName: "launchFee" });const liquidityEth = parseEther("0.05"); // simulate first: InvalidAllocation, Expired, InsufficientFee… surface before the wallet promptconst { request } = await publicClient.simulateContract({  account,  address: factory,  abi: launchFactoryAbi,  functionName: "createToken",  value: launchFee + liquidityEth,  args: [{    name: "Nebula",    symbol: "NEB",    decimals: 18,    totalSupply: parseUnits("1000000000", 18),    metadataURI: "ipfs://…",    creatorBps: 1_000,      // 10 %    communityBps: 0,    liquidityBps: 9_000,    // 90 % seeds the pool    communityWallet: zeroAddress,    burnLiquidity: true,    deadline: BigInt(Math.floor(Date.now() / 1000) + 20 * 60),  }],}); const hash = await wallet.writeContract(request);const receipt = await publicClient.waitForTransactionReceipt({ hash });if (receipt.status !== "success") throw new Error("createToken reverted"); const [launched] = parseEventLogs({  abi: launchFactoryAbi,  eventName: "TokenLaunched",  logs: receipt.logs.filter((l) => l.address.toLowerCase() === factory.toLowerCase()),});console.log("token", launched.args.token, "pair", launched.args.pair);

StargazeFairLaunch

"Fair launch": a uniform-price batch auction. During [startTime, endTime) anyone commits ETH; everyone pays the same clearing price totalRaised / saleTokens. The whole supply is held by the contract until finalisation, so nobody can pre-seed a pool at a manipulated price.

ConstantValue
BPS10_000
MAX_PLATFORM_FEE_BPS500 (5 %)
MIN_LIQUIDITY_ETH_BPS2_000 (≥ 20 % of the raise goes to the pool)
MIN_DURATION / MAX_DURATION1 hours / 30 days
MAX_CLAIM_DELAY7 days

createSale

StargazeFairLaunch.sol
function createSale(SaleConfig calldata c)    external nonReentrant              // not payable    returns (uint256 saleId, address token); struct SaleConfig {    string  name;               // 1–64 bytes    string  symbol;             // 1–16 bytes    uint256 totalSupply;        // raw units, 18 decimals, 1..type(uint112).max    string  metadataURI;    uint256 saleTokens;         // > 0, sold to committers    uint256 liquidityTokens;    // > 0, reserved for the pool; unused part is burned    uint16  liquidityEthBps;    // share of raised ETH paired into the pool    uint256 reserveEth;         // minimum raise for success (wei)    uint256 maxCommitPerWallet; // 0 = unlimited    uint64  startTime;          // >= block.timestamp    uint64  endTime;            // startTime + [1 hour, 30 days]    uint64  claimDelay;         // <= 7 days after endTime    bool    burnLiquidity;      // true => LP tokens to 0x…dEaD}

Tokens always have 18 decimals. The creator's allocation is totalSupply − saleTokens − liquidityTokens, paid out at a successful finalisation. The current platformFeeBps is snapshotted into the sale at creation, so later fee changes never affect it. Every validation failure reverts with InvalidConfig():

  • name / symbol length outside 1–64 / 1–16 bytes; totalSupply is 0 or above type(uint112).max
  • saleTokens == 0, liquidityTokens == 0, or saleTokens + liquidityTokens > totalSupply
  • liquidityEthBps < 2_000 or liquidityEthBps + 500 > 10_000
  • startTime < block.timestamp; endTime not within startTime + 1 hour … startTime + 30 days
  • claimDelay > 7 days

commit

StargazeFairLaunch.sol
function commit(uint256 saleId) external payable nonReentrant whenNotPaused; // reverts EnforcedPause() while paused
RevertCondition
NotLive()block.timestamp < startTime or >= endTime
InvalidConfig()msg.value == 0
CommitCapExceeded()maxCommitPerWallet != 0 and the wallet's running total would exceed it

finalize

StargazeFairLaunch.sol
function finalize(uint256 saleId) external nonReentrant; // permissionless, never pausable
  • Reverts NotEnded() before endTime and AlreadyFinalized() on a second call. Anyone can call it, so funds can never be stuck behind the creator.
  • Failure (totalCommitted < reserveEth or nothing committed): the whole supply returns to the creator; participants refund.
  • Success: fee = raised × feeBps / 10_000 goes to feeRecipient; raised × liquidityEthBps / 10_000 ETH is paired with min(liquidityTokens, ethForLiquidity × saleTokens / raised) tokens so the pool opens at the clearing price; unused liquidity tokens are sent to 0x…dEaD; the creator receives the creator allocation and the remaining ETH.

claim and refund

StargazeFairLaunch.sol
function claim(uint256 saleId) external nonReentrant;  // tokens = committed × saleTokens / totalCommittedfunction refund(uint256 saleId) external nonReentrant; // 100 % of committed ETH
Revertclaimrefund
NotFinalized()sale not finalizedsale not finalized
NothingToSettle()sale failed, nothing committed, or already settledsale succeeded, nothing committed, or already settled
ClaimNotOpen()block.timestamp < endTime + claimDelay—

Each wallet can settle once per sale (settled[saleId][wallet]), which prevents double claims and double refunds.

Fair launch events

StargazeFairLaunch.sol
event SaleCreated(    uint256 indexed saleId, address indexed token, address indexed creator,    string name, string symbol, uint256 totalSupply, uint256 saleTokens, uint256 liquidityTokens,    uint256 reserveEth, uint64 startTime, uint64 endTime, uint64 claimDelay, uint16 feeBps, string metadataURI);event Committed(uint256 indexed saleId, address indexed user, uint256 amount, uint256 totalCommitted);event Finalized(    uint256 indexed saleId, bool succeeded, uint256 totalRaised, address pair,    uint256 liquidityTokensUsed, uint256 liquidityEthUsed, uint256 tokensBurned);event Claimed(uint256 indexed saleId, address indexed user, uint256 tokens);event Refunded(uint256 indexed saleId, address indexed user, uint256 amount);event PlatformFeeUpdated(uint16 oldBps, uint16 newBps);event FeeRecipientUpdated(address oldRecipient, address newRecipient);

Fair launch views

FunctionReturns
getSale(uint256)the Sale struct: token, creator, saleTokens, liquidityTokens, creatorTokens, liquidityEthBps, feeBps, reserveEth, maxCommitPerWallet, startTime, endTime, claimDelay, burnLiquidity, finalized, succeeded, totalCommitted, pair
status(uint256) → uint80 Pending · 1 Live · 2 Ended · 3 Succeeded · 4 Failed
committed(uint256, address) → uint256ETH committed by a wallet
settled(uint256, address) → boolclaimed or refunded
salesLength() → uint256
platformFeeBps() → uint16fee applied to sales created from now on
clearingPrice(uint256) → uint256wei per whole token (1e18 units)

Example: commit, then claim or refund

fair-sale.ts
import { parseEther, type PublicClient, type WalletClient, type Address } from "viem";import { fairLaunchAbi } from "@/lib/web3/abis";import { stargazeContracts } from "@/lib/config/chains"; const fairLaunch = stargazeContracts[11155111].fairLaunch!; export async function commit(publicClient: PublicClient, wallet: WalletClient, account: Address, saleId: bigint) {  const { request } = await publicClient.simulateContract({    account, address: fairLaunch, abi: fairLaunchAbi,    functionName: "commit", args: [saleId], value: parseEther("0.1"),  });  const hash = await wallet.writeContract(request);  return publicClient.waitForTransactionReceipt({ hash });} export async function settle(publicClient: PublicClient, wallet: WalletClient, account: Address, saleId: bigint) {  const status = await publicClient.readContract({ address: fairLaunch, abi: fairLaunchAbi, functionName: "status", args: [saleId] });  // 2 = Ended: anyone may finalize first  if (status === 2) {    const { request } = await publicClient.simulateContract({ account, address: fairLaunch, abi: fairLaunchAbi, functionName: "finalize", args: [saleId] });    await publicClient.waitForTransactionReceipt({ hash: await wallet.writeContract(request) });  }  const sale = await publicClient.readContract({ address: fairLaunch, abi: fairLaunchAbi, functionName: "getSale", args: [saleId] });  const { request } = await publicClient.simulateContract({    account, address: fairLaunch, abi: fairLaunchAbi,    functionName: sale.succeeded ? "claim" : "refund", args: [saleId],  });  return publicClient.waitForTransactionReceipt({ hash: await wallet.writeContract(request) });}

StargazeToken

  • OpenZeppelin ERC20 + ERC20Permit. The entire supply is minted once in the constructor, to the launching contract, which distributes it.
  • No owner, no mint function, no pause, no blacklist, no transfer tax, no max-wallet logic, not upgradeable.
  • creator, launcher and metadataURI are public and informational only; metadataURI has no setter.

Owner privileges

ContractOwner canOwner cannot
StargazeLaunchFactorysetLaunchFee (≤ 0.05 ETH), setFeeRecipient, pause/unpause new launchestouch launched tokens, pools or LP tokens
StargazeFairLaunchsetPlatformFeeBps (≤ 500 bps, future sales only), setFeeRecipient, pause/unpause new sales and commitschange a live sale, move committed ETH, or block finalize, claim or refund

Ownership transfers use Ownable2Step (transferOwnership then acceptOwnership).