Skip to main content

​
Why Diamond?

Gotchipus uses the Diamond Standard (EIP-2535) — a proxy pattern that splits contract logic into modular pieces called Facets. This means:
  • No monolithic contract — features are isolated into separate facets
  • Upgradeable without redeployment — individual facets can be added, replaced, or removed
  • Shared storage — all facets share a unified AppStorage struct, avoiding fragmentation
  • Gas efficient — common logic is shared across facets

​
How It Works

User / Agent
    ↓
Diamond Proxy (single address)
    ↓ (delegates call based on function selector)
┌─────────────────┬──────────────────┬───────────────────┐
│  GotchipusFacet │   MintFacet      │  AttributesFacet  │
│  (ERC-721)      │   (mint/summon)   │  (stats/pet)      │
├─────────────────┼──────────────────┼───────────────────┤
│  TimeFacet      │   HooksFacet     │  ERC6551Facet     │
│  (weather)      │   (hook mgmt)    │  (TBA execution)  │
├─────────────────┼──────────────────┼───────────────────┤
│  SecurityFacet  │   SetBonusFacet  │  PaymasterFacet   │
│  (sessions)     │   (set effects)  │  (sponsored tx)   │
├─────────────────┼──────────────────┼───────────────────┤
│  MetadataFacet  │   TimeFacet      │  WearableFacet    │
│  (tokenURI)     │   (weather)      │  (equip mgmt)     │
└─────────────────┴──────────────────┴───────────────────┘
    ↑
Shared AppStorage (unified diamond storage)
All facets are accessed through a single Diamond proxy address. The proxy routes function calls to the correct facet based on the function selector.

​
The 12 Facets

FacetResponsibility
GotchipusFacetERC-721 standard (transfers, approvals, enumeration, burning)
MintFacetMinting Pharos NFTs, summoning Gotchipus, whitelist management
AttributesFacetPet interaction, naming, attribute queries, soul queries
DNAFacetIdentity seed and trait data storage
GotchiWearableFacetWearable balance, equipping, cross-diamond calls
HooksFacetHook registration, removal, and querying
ERC6551FacetToken-Bound Account creation and execution
SecurityFacetSession management, security flags, transfer limits, whitelists
SetBonusFacetWearable set creation, updates, and activation
TimeFacetTimezone-based weather system
MetadataFacetToken URI generation, trait indexing
PaymasterFacetSponsored transaction processing, nonce management

​
Core Libraries

The heavy lifting happens in shared libraries:
LibraryPurpose
LibAppStorageCentral state storage struct
LibDnaIdentity seed storage and trait packing
LibAttributesBase attribute initialization and decay calculation
LibExperienceLevel and skill point calculations
LibSoulSoul energy balance and collateral conversion
LibDynamicStatesHealth/energy/morale/focus mechanics
LibFactionFaction assignment and stat bonuses
LibWearableStatsWearable bonus calculations with faction multiplier
LibSetBonusSet detection and bonus aggregation
LibSecurityTransfer limits and session validation
LibHooksHook execution pipeline
LibSvgOn-chain SVG rendering

​
Wearable Diamond

Wearables live in a separate Diamond with its own ERC-1155 implementation. The two Diamonds communicate via cross-contract calls — the main Diamond queries wearable balances and stats from the Wearable Diamond.

​
Compilation

  • Solidity: 0.8.29
  • VIA-IR: Enabled (optimized compilation pipeline)
  • Optimizer: 44,000,000 runs
  • Network: Pharos (devnet + testnet)