A collection of smart contract templates, for working with existing infrastructure contracts in the MoonCatRescue ecosystem.

Usage

To add this module to an existing Node.js application:

npm install --save @mooncatrescue/contracts

Then within a Solidity contract, you can import an interface by referencing it like this:

// SPDX-License-Identifier: AGPL-3.0
pragma solidity ^0.8.9;

import { IMoonCatRescue } from "@mooncatrescue/contracts/IMoonCatRescue.sol";

Within a JavaScript or TypeScript file, the moonCatUtils helper library has a contracts mapping that can be used by Ethereum interface libraries like viem or wagmi to assemble transactions to interact with those smart contracts.

import { publicClient } from './client'
import { contracts } from '@mooncatrescue/contracts/moonCatUtils';

const data = await publicClient.readContract({
  address: contracts.rescue.address,
  abi: contracts.rescue.abi,
  functionName: 'name'
})

Contracts

MoonCat​Rescue

• Address: 0x60cd862c9C687A9dE49aecdC3A99b74A4fc54aB6
• Deployed: 0x79d48c41b99f0ac8f735dbf4d048165542576862df2b05a80be9a4dbe233a623
• Functions: acceptAdoptionOffer, acceptAdoptionRequest, activate, activateInTestMode, addGenesisCatGroup, adoptionOffers, adoptionRequests, balanceOf, cancelAdoptionOffer, cancelAdoptionRequest, catNames, catOwners, decimals, disableBeforeActivation, getCatDetails, getCatIds, getCatNames, getCatOfferPrices, getCatOwners, getCatRequestPrices, giveCat, imageGenerationCodeMD5, makeAdoptionOffer, makeAdoptionOfferToAddress, makeAdoptionRequest, mode, name, nameCat, pendingWithdrawals, remainingCats, remainingGenesisCats, rescueCat, rescueIndex, rescueOrder, searchSeed, symbol, totalSupply, and withdraw
• Events: AdoptionOfferCancelled, AdoptionOffered, AdoptionRequestCancelled, AdoptionRequested, CatAdopted, CatNamed, CatRescued, GenesisCatsAdded, and Transfer

The original contract that started this project off! It is an ERC20-like contract that creates the possibility of a collection of 25,600 MoonCat tokens, each with a unique five-byte hexadecimal identifier to be "rescued" into the blockchain. It was created before the ERC721 standard existed, so the function names are different than that standard. Some of the Genesis MoonCats did not get released as originally planned, and the community opted to have them remain on the moon, so the total collection size is 25,440 MoonCats.

This contract has a built-in marketplace where those who already own a MoonCat can create AdoptionOffers to list their MoonCat as adoptable (either by anyone or only by a specific address), and those who want to adopt a MoonCat can create an AdoptionRequest for a specific MoonCat.

Each MoonCat's hexadecimal identifier defines the MoonCat's pose, facial expression, fur pattern, and color. This identifier was permanently stored in this contract when that MoonCat was rescued, and cannot be changed. Each MoonCat can have a name given to them by their owner, but can only be named once. Once a MoonCat is named, the name is permanently stored in this contract, and cannot be changed.

Old MoonCat Wrapper

• Address: 0x7C40c393DC0f283F318791d746d894DdD3693572
• Deployed: 0xb27719066844420204ba6b5ce4ce2d2fdae1262270a8b1a211e96cda16636818
• Functions: _catIDToTokenID, _tokenIDToCatID, approve, balanceOf, isApprovedForAll, ownerOf, safeTransferFrom, setApprovalForAll, tokenOfOwnerByIndex, unwrap, and wrap

A "wrapping" contract that was created in the flurry that happened after the March 2021 "rediscovery". It converts MoonCats from the original contract into ERC721 tokens, but does not preserve other metadata about the MoonCats. This contract enables MoonCats to be seen by modern wallet and portfolio tools, but is considered deprecated in favor of the Acclimator wrapper contract.

MoonCat​Acclimator

• Address: 0xc3f733ca98E0daD0386979Eb96fb1722A1A05E69
• Deployed: 0x5585c88321058bde24b5ed025b51323731e2186836d3d5bdf66e7aed7ab63461
• Functions: approve, balanceOf, batchReWrap, batchUnwrap, batchWrap, buyAndWrap, childContractByIndex, childTokenByIndex, getApproved, getChild, isApprovedForAll, name, onERC721Received, ownerOf, ownerOfChild, pause, rootOwnerOf, rootOwnerOfChild, safeTransferChild, safeTransferFrom, setApprovalForAll, setBaseURI, supportsInterface, symbol, tokenByIndex, tokenOfOwnerByIndex, tokensIdsByOwner, tokenURI, totalChildContracts, totalChildTokens, totalSupply, transferChild, transferChildToParent, transferFrom, unpause, unwrap, and wrap
• Events: Approval, ApprovalForAll, MoonCatAcclimated, MoonCatDeacclimated, ReceivedChild, Transfer, and TransferChild

A "wrapping" contract that takes a MoonCat from the original contract, and converts it to an ERC721- and ERC998-compatible token. The web interface for interacting with this contract is The Acclimator.

The ERC998 functionality is a "top down, ERC721" implementation, which enables individual MoonCats to own other ERC721 tokens. Other ERC721 tokens that get sent to this smart contract using the safeTransferFrom function should specify in the data parameter the Rescue Order of the MoonCat that should receive the token.

MoonCat​Accessories

• Address: 0x8d33303023723dE93b213da4EB53bE890e747C63
• Deployed: 0x21b831be284a48d6f2d72b84e94cfdd8123ec4b28779b098e8bc8caa7f02755a
• Functions: AccessoriesByMoonCat, accessoryEligibleList, accessoryHashes, accessoryImageData, accessoryInfo, accessoryPalette, accessoryPaletteCount, addAccessoryPalette, alterAccessories, alterAccessory, balanceOf, batchAndMetaByte, batchOrMetaByte, buyAccessories, buyAccessory, clearEligibleList, createAccessory, discontinueAccessory, doesMoonCatOwnAccessory, editEligibleMoonCats, feeDenominator, freeze, frozen, isAccessoryUnique, isEligible, managedAccessoryByIndex, managerApplyAccessory, managerOf, ownedAccessoryByIndex, owner, ownerCreateAccessory, referralDenonminator, setAccessoryPrice, setEligibleList, setFee, setMetaByte, setReferralFee, toggleEligibleList, totalAccessories, transferAccessoryManagement, transferOwnership, unfreeze, withdrawForeignERC20, and withdrawForeignERC721
• Events: AccessoryApplied, AccessoryCreated, AccessoryDiscontinued, AccessoryManagementTransferred, AccessoryPriceChanged, AccessoryPurchased, EligibleListCleared, and EligibleListSet

On-chain visual modifications for MoonCats that can be purchased by their owners. The web interface for interacting with this contract is The Boutique.

Purchasing an accessory (buyAccessory or buyAccessories functions) is like "unlocking a skin" for your MoonCat. Once purchased, the accessory becomes available to that MoonCat forever ("part of their wardrobe"). The owner of a MoonCat can choose which of the MoonCat's accessories are visible via the alterAccessory or alterAccessories functions.

The data for an accessory's visual is stored as a PNG-8 image, though split up into multiple pieces to make it easier to swap in different palettes. This allows each accessory to have multiple color variants without needing to store the image data multiple times, and allows for accessories to have colors that adapt to the MoonCat that wears them.

MoonCatNameService (MCNS)

• Address: 0x2eCcDA7C84837Da55ce34A36a5AD2B936479E76e
• Deployed: 0x21b831be284a48d6f2d72b84e94cfdd8123ec4b28779b098e8bc8caa7f02755a
• Functions: addr, announceMoonCat, avatarBaseURI, contenthash, defaultTTL, ENSDomain, getRescueOrderFromNodeId, getSubdomainNameHash, giveControl, mapMoonCat, mapMoonCats, multicall, needsAnnouncing, owner, rootHash, setAddr, setAvatarBaseUrl, setContenthash, setDefaultTTL, setText, setTTL, supportsInterface, text, transferOwnership, withdrawForeignERC20, and withdrawForeignERC721
• Events: AddrChanged, AddressChanged, ContenthashChanged, and TextChanged

A contract that adheres to the Ethereum Name Service (ENS) Resolver interface, but has custom logic to allow all MoonCat owners to claim subdomains that matches their MoonCat's hexadecimal identifier and rescue order. The web interface for interacting with this contract is the MoonCatNameService (MCNS).

MoonCat​Moments

• Address: 0x367721b332F4697d440EBBe6780262411Fd03409
• Deployed: 0xe13e6e711af7ea6a2ea61c23f4b03be5c8957d05ef19fd190eb9ca65456503b0
• Functions: acclimatorBalance, approve, balanceOf, batchClaim, claim, contractOwner, getApproved, getMomentId, isApprovedForAll, isClaimable, listClaimableMoments, mint, mintClaimable, Moments, moonCatAcclimatorContract, name, ownerOf, paused, paws, safeTransferFrom, setApprovalForAll, setMomentURI, supportsInterface, symbol, tokenByIndex, tokenExists, tokenOfOwnerByIndex, tokenURI, tokenURIByMomentId, totalMoments, totalSupply, transferFrom, transferOwnership, unpaws, withdrawForeignERC20, and withdrawForeignERC721
• Events: Approval, ApprovalForAll, and Transfer

An ERC721 token collection that represents moments in time for the MoonCat​Rescue community. They are photographic souvenirs for the MoonCats that participated in each Moment. The web interface for interacting with this contract is on ChainStation.

Each token in this collection shares a visual with many others (all tokens from the same Moment have the same visual). However this is done not with different "classes" (like an ERC1155 collection), but rather sequential ranges of token IDs are used for each Moment. This collection is expected to grow as additional Moments are created.

lootprints (for MoonCats)

• Address: 0x1e9385eE28c5C7d33F3472f732Fb08CE3ceBce1F
• Deployed: 0xce2a9c92f69b5276ffbe3ccbe453f289a6f619bb623b3ded3ebfa1239ac9f77e
• Functions: approve, balanceOf, decodeColor, getApproved, getDetails, isApprovedForAll, name, ownerOf, safeTransferFrom, setApprovalForAll, supportsInterface, symbol, tokenByIndex, tokenOfOwnerByIndex, tokenURI, totalSupply, and transferFrom
• Events: Approval, ApprovalForAll, and Transfer

An ERC721 token collection that represents plans for building MoonCat-styled space ships. The visuals for these tokens come in all the colors that the original MoonCat collection does, so they're not just "blueprints", but are instead "lootprints".

Inspired by the Loot project, these tokens show their stats in a simplified way as SVGs, output directly by the smart contract.

The JumpPort

• Address: 0xF4d150F3D03Fa1912aad168050694f0fA0e44532
• Deployed: 0x591059774a676071a188fd8805e066b9f53c95c1cdeb76f1a4347c011b35f9b4
• Functions: ADMIN_ROLE, adminPong, adminWithdrawPing, balanceOf, blockExecution, deposit, depositedSince, depositPaused, doc, DocumentationRepository, executeAction, executionBlocked, getApproved, hasRole, isApprovedForAll, isDeposited, isLocked, isValidSignature, lockedBy, lockOverride, lockToken, markMessageSigned, onERC721Received, ownedTokens, ownerOf, ownerPong, ownersOf, PORTAL_ROLE, safeWithdraw, setAdmin, setAdminExecutionBlocked, setAdminLockOverride, setCopilot, setCopilotForAll, setPaused, setPortalValidation, setReverseResolver, tokenPingRequestBlock, tokenPingRequestBlocks, unlockAllTokens, unlockToken, withdraw, withdrawForeignERC20, and withdrawForeignERC721
• Events: ActionExecuted, Approval, ApprovalForAll, Deposit, Lock, RoleChange, Unlock, and Withdraw
• Errors: , and MissingRole

A universal staking contract, designed to be a programmable hub for MoonCats to participate in other projects that require them be held in place for specific times. But this contract is universal; any ERC721 collection can use the JumpPort as well!

The JumpPort is different than other "bridge" contracts in that it is designed for tokens to interact with multiple things at once. In lore this is described as "projecting" them into other blockchains, rather than moving/bridging them there. Therefore, if a project wishes to integrate with the JumpPort, it is vital that tokens that are "projected" to other chains are not sold to a new owner while there (it should not be treated as "real" while on the other chain).

The JumpPort operates by having additional smart contracts that are designated as "Portals", which implement logic to allow tokens to be removed from the JumpPort or not. A single token in the JumpPort can interact with multiple portals, but to withdraw the token from the JumpPort, it must be unlocked by all the portals it has interacted with.

MoonCat​Traits

• Address: 0x9330BbfBa0C8FdAf0D93717E4405a410a6103cC2
• Deployed: 0xc6a79b35660dbc06cafce69f9d544c44c911004d30d0f0b269c6f82378cec0f7
• Functions: catIdOf, doc, expressionNames, facingNames, kTraitsOf, nameOf, owner, ownerOf, patternNames, poseNames, rescueYearOf, setERC721Proxy, setReferenceContract, traitsOf, transferOwnership, withdrawForeignERC20, and withdrawForeignERC721

Part of the suite of on-chain metadata contracts for MoonCats. A smart-contract implementation of the original JavaScript parser. This contract can take any MoonCat's hexadecimal ID (its "DNA") and parse out the trait information for it. It's useful for other smart contracts that wish to be able to parse MoonCat identifiers, and turn them into human-friendly labels.

MoonCat​Colors

• Address: 0x2fd7E0c38243eA15700F45cfc38A7a7f66df1deC
• Deployed: 0xd2c70642c15d5e068c331459f5d12e5cd2926729cfd3c010d9a1e00df69a4410
• Functions: accessoryColorsOf, BasePalette, colorAlpha, colorsOf, deriveColors, doc, finalize, finalized, glowOf, hueIntOf, hueName, hueToRGB, mapColors, owner, paletteOf, RGBToHue, setReferenceContract, transferOwnership, withdrawForeignERC20, and withdrawForeignERC721

Part of the suite of on-chain metadata contracts. This contract parses a MoonCat's hexadecimal ID and returns the calculated color palette for that MoonCat. This is useful for other smart contracts that wish to be able to parse MoonCat identifiers, and determine what colors should be used to render them. The canonical parser for MoonCat data was created in JavaScript, and due to the differences in how floating point numbers are represented between JavaScript and Solidity, this contract has baked in a static list of which MoonCats have different outcomes between JavaScript and Solidity, and does output the original JavaScript values for those MoonCats.

MoonCat​SVGs

• Address: 0xB39C61fe6281324A23e079464f7E697F8Ba6968f
• Deployed: 0xbabdec945b57fd0b1a009aa0b98e84b310d91c91d3033e7ce9f0881dcfde2954
• Functions: Border, boundingBox, CatBox, Coat, doc, Eyes, Face, flip, getPattern, getPixelData, glowGroup, imageOf, owner, Patterns, pixelGroup, setReferenceContract, Skin, svgTag, transferOwnership, Tummy, uint2str, Whiskers, withdrawForeignERC20, and withdrawForeignERC721

Part of the suite of on-chain metadata contracts. This contract parses a MoonCat's hexadecimal ID and returns a visual of that MoonCat in SVG format. It relies on the MoonCat​Colors contract to determine the colors used in the SVG.

MoonCat​AccessoryImages

• Address: 0x91CF36c92fEb5c11D3F5fe3e8b9e212f7472Ec14
• Deployed: 0xf1b559d8772f4c8d831a723826fd6bb045be8d5740a7fe3255a581300a90c147
• Functions: accessorizedImageOf, accessoryPNG, crc32, doc, generatePNGChunk, IHDRDetails, owner, placementOf, PNGFooter, PNGHeader, prepAccessories, setReferenceContract, transferOwnership, withdrawForeignERC20, and withdrawForeignERC721

Part of the suite of on-chain metadata contracts. This contract parses a MoonCat's hexadecimal ID and returns a visual of that MoonCat in SVG format with accessories that MoonCat owns. This contract uses the MoonCat​SVGs contract to determine the base visual of the MoonCat, and then uses the MoonCat​Accessories contract to determine the accessories that the MoonCat owns and overlays them.

The MoonCat is drawn with native SVG shapes (rects and polygons), and the accessories are embedded into this as PNG images in the SVG file.

MoonCat​Reference

• Address: 0x0B78C64bCE6d6d4447e58b09E53F3621f44A2a48
• Deployed: 0x4a3b15b2b44f896526ef5e158309a1fefee7db51fdcb58c5ecc1232833bee21a
• Functions: batchSetDocs, contractAddressByIndex, doc, MoonCatRescue, owner, setDoc, totalContracts, transferOwnership, updateDetails, withdrawForeignERC20, and withdrawForeignERC721

A contract for storing on-chain documentation in a human-friendly way. It provides on-chain links between the MoonCat​Rescue-related contracts, and links to longer descriptions of each of those smart contracts.