EVE Frontier Builder Complete Course

Approximately 2 hours per lesson, 54 lessons total: 36 foundational chapters + 18 practical examples = 108 hours of complete learning content.

📖 Chapter Roadmap (Recommended Learning Order, ~2 hours per lesson)

Prerequisite

Phase 1: Getting Started (Chapter 1-5)

Companion examples: Example 1 Turret whitelist, Example 2 Stargate toll booth

Phase 2: Builder Engineering Loop (Chapter 6-10)

Companion examples: Example 4 Quest unlocking system, Example 11 Item rental system

Phase 3: Advanced Contract Design (Chapter 11-17)

Companion examples: Example 3 On-chain auction house, Example 6 Dynamic NFTs, Example 7 Stargate logistics network, Example 9 Cross-Builder protocol, Example 13 Subscription-based pass, Example 14 NFT staking and lending, Example 16 NFT crafting and decomposition, Example 18 Cross-alliance diplomatic treaties

Phase 4: Architecture, Integration, and Products (Chapter 18-25)

Companion examples: Example 5 Alliance DAO, Example 12 Alliance recruitment, Example 15 PvP item insurance, Example 17 In-game overlay implementation

🔬 Phase 5: World Contract Source Code Deep Dive (Chapter 26-32)

Based on real source code from world-contracts, deep analysis of EVE Frontier core system mechanisms.

Companion examples: Example 8 Builder competition system, Example 10 Comprehensive implementation

🔐 Phase 6: Wallet Internals and Future (Chapter 33-35)

After mastering wallet integration and dApps, dive deeper into wallet internals and future directions for a smoother learning curve.

Recommended companion: After completing this phase, review Example 17’s wallet connection, signing, and in-game integration workflow.

🛠 Example Index (By Complexity, 2 hours each)

Main roadmap distributed above; index by complexity below for topic selection and review.

Beginner Examples (Example 1-3) — Basic Component Applications

Intermediate Examples (Example 4-7) — Economy and Governance

Advanced Examples (Example 8-10) — System Integration

Extended Examples (Example 11-15) — Finance and Productization

Advanced Extended Examples (Example 16-18) — Innovative Gameplay

📖 Reading Recommendations

Recommended Learning Paths

Quick Builder Start (Shortest Path, ~26h): Prelude → Chapter 1-4 → Example 1-2 → Chapter 6-10 → Example 4

Complete Builder Path (~96h): Prelude → Chapter 1-5 → Example 1-2 → Chapter 6-10 → Example 4, 11 → Chapter 11-17 → Example 3, 6, 7, 9, 13, 14, 16, 18 → Chapter 18-25 → Example 5, 12, 15, 17 → Chapter 26-32 → Example 8, 10 → Chapter 33-35

Source Code Researcher Path (~32h): Prelude → Chapter 3 → Chapter 11 → Chapter 15 → Chapter 26-32 → Example 8, 10 → Chapter 6-10

📚 Reference Resources

• Official builder-documentation
• builder-scaffold
• World Contracts Source Code
• Sui Documentation
• Move Book
• EVE Frontier dapp-kit API
• Sui GraphQL IDE (Testnet)
• EVE Frontier Discord
• Glossary

Glossary

This page provides unified explanations for frequently occurring terms that appear across multiple chapters. When reading Chapters 26-35 and Examples 11-18, use this page as a quick reference guide.

AdminACL

An authorization control object for server-side access in World contracts. The game server or Builder backend writes approved sponsor addresses into AdminACL, and on-chain logic verifies whether the caller has “server representative” identity through validation functions like verify_sponsor.

OwnerCap

An ownership credential for objects or structures. Many World-side permission checks don’t just look at ctx.sender(), but require the caller to explicitly hold an OwnerCap associated with the target object.

AdminCap

An admin capability object within a Builder’s own module. It’s typically issued to the publisher during init and used to configure settings, modify rules, pause functionality, or withdraw funds.

Typed Witness

A pattern that uses the type system to tighten authorization boundaries. EVE Frontier’s Gate / Turret / Storage Unit extensions often use it to restrict “only specific modules and specific entry points” from calling sensitive APIs.

Shared Object

A shared object on Sui that can be concurrently accessed by multiple parties. World structures like Gates, Storage Units, and Registries often adopt this model.

Derived Object

An object ID deterministically derived from a parent object and business key. Scenarios like KillMail and registry sub-objects use this to ensure the business ID -> on-chain object ID mapping is stable and non-repeatable.

Sponsored Transaction

A transaction initiated by a player but with Gas paid by the Builder or server. EVE Vault supports sponsored transaction extensions, which is the core foundation for “users can use dApps without SUI”.

zkLogin

Sui’s passwordless login solution. After users complete OAuth login with their Web2 identity, the wallet derives the on-chain address based on ephemeral keys, salt, and proof.

Epoch

Sui’s epoch unit. zkLogin’s temporary proofs and certain caches are bound to Epochs, requiring reissuance or login state refresh after expiration.

0x6

The fixed object ID for Sui’s Clock system object. Many time-related examples in this course pass 0x6 as a parameter.

0x8

The fixed object ID for Sui’s Random system object. Examples requiring on-chain randomness typically pass this object.

LUX and SUI

Many examples in this course “use SUI instead of LUX for demonstration” to facilitate explanation in public environments and with standard SDKs. When actually integrating with EVE Frontier, use the in-game real assets and World/wallet interfaces as the standard.

GraphQL / Indexer

GraphQL mentioned in this book mostly refers to the query endpoints provided by Sui’s indexing layer; Indexer refers to off-chain retrieval services built around events and object state. They are primarily responsible for “reads”, not “writes”.

Prelude: Understanding EVE Frontier as a Game First

Objective: Before diving into contracts, components, and dApps, first understand what players in EVE Frontier are competing for, building, and why these mechanics are naturally suited to become on-chain rules.

Status: Introductory chapter. Focus is on establishing “gameplay intuition” first, so that Gate, Turret, StorageUnit, KillMail, and LocationProof won’t feel like abstract nouns in later chapters.

0.1 This Is Not a “Wallet Game with Blockchain Attached”

If you start thinking of EVE Frontier as “a space game with NFTs and tokens,” you’ll likely find things increasingly awkward as you learn more. Because the true core of this game isn’t about issuing assets—it’s a persistent, resource-competitive, geographically-constrained, player-conflict-driven open world.

It’s closer to this combination:

So you can start by remembering this:

The “unit of fun” in EVE Frontier isn’t a single NFT, but the long-term strategic interplay between player groups around infrastructure, resource flows, and territorial control.

0.2 What Does a Typical Player Actually Do in This World?

From a gameplay perspective, player activities usually revolve around this main loop:

Enter the world
  -> Establish character and identity
  -> Find a safe foothold
  -> Acquire resources, items, and fuel
  -> Build your own base or connect to others' facilities
  -> Transport, trade, charge fees, defend, or raid
  -> Lose, recover, rebuild, and upgrade through conflicts

This isn’t a linear quest chain, but a repeating cycle of operation and conflict. Players may focus on different playstyles:

• Survival-focused players: Prioritize supply, safety, and sustainable presence
• Industrial players: Focus on storage, logistics, item circulation, and markets
• Military players: Care about turrets, defensive lines, friend-or-foe identification, KillMail, and combat losses
• Operator players: Focus on toll gates, permission systems, alliance collaboration, and service pricing
• Builder/Operator players: Focus on turning infrastructure into fee-charging, filtering, incentivizing, and auto-executing rule systems

This book targets the last type, but what you design ultimately serves the first four types, so you must first understand what problems they actually encounter in the game.

From a Player’s Perspective, What Does a Typical Day Look Like?

If we compress gameplay into a more concrete daily loop, many actions happen like this:

Log in
  -> Check current location and base status
  -> Verify fuel, inventory, access permissions, nearby risks
  -> Decide whether to mine, transport, trade, defend, or attack today
  -> Use Gate, Storage, market, or alliance facilities to achieve goals
  -> May encounter interception, tolls, turret checks, or PvP en route
  -> Successfully bring back gains, or regroup resources after losses

In this daily loop, almost every step can be influenced by Builders:

• “Can I safely go out” encounters Gate
• “Check inventory and supplies” encounters Storage Unit
• “Is my base still operational” encounters Network Node / Energy / Fuel
• “Will I get intercepted on the route” encounters Turret and regional governance
• “Can losses from losing fights be tracked” encounters KillMail
• “Is someone actually physically present” encounters LocationProof

In other words, Builders aren’t just making extra web pages—they’re integrating into decision points players encounter daily.

What Do Players Really Weigh Repeatedly in This World?

From a gameplay perspective, many choices in EVE Frontier ultimately come down to these 4 trade-offs:

This is also why many rules you’ll see later don’t look like “button features” but more like institutional design. Fees, permissions, whitelists, insurance, deposits, payouts, and rewards are essentially tuning these contradictions.

The Same World Looks Completely Different to Different Players

If you want to build truly useful Builder products, you must realize: the same gate, turret, or warehouse has completely different value to different people.

This table is important because it explains why the same facility generates different demands:

• Newcomers want gates with “fewer restrictions”
• Operators want gates with “stronger screening and governance capabilities”
• Merchants want gates with “transparent pricing, stable passage”
• Pirates want gates that “create congestion and exposure”

A Builder’s job isn’t to satisfy just one party, but to consciously decide which side your product stands with.

Viewing the Same Base Through Five Typical Identities

Suppose there’s a base built on a route node with Network Node + Gate + Turret + Storage Unit. Different people think completely differently when entering:

1. Newcomer

When a newcomer enters this base, their first reaction usually isn’t “how elegant this rule system is,” but:

• Will I get attacked
• Do I need to pay to pass through the gate
• Will my stuff be lost if I store it here
• Can I understand what this system is asking me to do

For newcomers, a good Builder system often has these characteristics:

• Clear rules
• Low failure cost
• Few erroneous operations
• Clearly explain “why you were rejected”

So many things you think are “UX copy” are actually part of gameplay retention.

2. Merchant / Logistics Player

Merchants won’t first look at whether this base is “cool”—they calculate:

• How much time does passing through this Gate save versus detouring
• Are tolls stable
• Can the Storage Unit safely store cargo temporarily
• Can turrets ensure basic safety for high-value cargo transport

If a base makes merchants form the expectation that “although expensive, it’s stable and reliable,” it might gradually become a trading node. For merchants, predictability itself is product value.

3. Pirate / Raider

Pirates see not services, but vulnerabilities and traffic:

• Is this route a must-pass
• Does the gate entrance create queues and slowdowns
• Which players will linger because of paying, opening boxes, or trading
• Can turrets be circumvented, baited, or exploited

This perspective forces Builders to rethink security issues. Many systems aren’t just “as long as the function runs”—you must ask:

• Will it create fixed ambush points
• Will it expose high-value users
• Will it allow certain playstyles to become overly stable farming machines

4. Alliance Operator

Alliance operators look at sustained order:

• Is this base worth long-term defense
• Are power and maintenance costs manageable
• Can gate access rules distinguish allies, visitors, and hostiles
• Can KillMail and passage data help judge defense zone quality

For them, facilities aren’t one-time interaction tools but part of territorial institutions. If Builders only provide one-off functions without sustained operational perspective, products will struggle to enter these players’ long-term workflows.

5. Builder / Operator

Builders and Operators usually see things more “institutionally”:

• Can this ruleset scale
• Which parts should be on-chain, which parts off-chain
• Is there a way to reduce customer service explanation costs
• Can it accumulate data, build reputation, create reusable templates

This perspective views a base as a replicable business model, not a collection of scattered functions.

0.3 What Are the Most Critical “Game Objects” in This World?

Character

Character is your core identity in the game. You can think of it as “you in the game,” but in EVE Frontier, it also assumes a very special responsibility: it’s the central hub for on-chain permissions and asset control.

Characters have at least three layers of meaning:

1. It’s the character identity in the game
2. It’s the on-chain Character object
3. It’s also the “keychain” holding many OwnerCaps

Later when you learn about OwnerCap, Receiving, and borrow-use-return, if you don’t first know that characters in gameplay are “the carrier of player control,” you’ll easily find the whole design overly convoluted.

Tribe

Tribes can initially be understood as the character’s initial affiliation or identity tag. It doesn’t necessarily equal permanent political faction, but it’s often used for:

• Newbie protection
• Gate access conditions
• Passage permissions
• Faction identification
• Gameplay segmentation

So when you later see “only allow certain tribe through stargate” or “determine turret attitude by tribe,” don’t treat it as just a random u32 field—in gameplay it carries identity classification.

Items

Items are resources, equipment, loot, keys, licenses, and economic carriers in the game. What’s most important in gameplay isn’t whether “it’s an NFT,” but whether it can participate in these actions:

• Be carried by characters
• Be deposited in storage facilities
• Be traded, rented, collateralized, synthesized, destroyed
• Become loot or loss upon player death
• Become a ticket, deposit, or consumable for certain services

This is also why StorageUnit is so important in EVE Frontier. You’re not simply making an on-chain warehouse but controlling “how items flow” in the game.

Bases and Facilities (Assemblies)

Players don’t just survive on wallets and characters—they build facility networks around spatial locations. Facilities are true gameplay amplifiers because they turn “one player’s action” into “one region’s rules.”

What Roles Do High-Frequency Terms Actually Play?

The table below tries to explain terms you’ll frequently see using “gameplay language” rather than “source code language”:

If you want to remember these terms more deeply, use a simpler classification:

• Character / Wallet / Tribe This group solves “who you are”
• Item / Storage Unit / Logistics This group solves “how things flow”
• Gate / Turret / Location This group solves “who can enter, who can stay, who gets attacked”
• Network Node / Energy / Fuel This group solves “can facilities continue operating”
• KillMail / LocationProof / AdminACL This group solves “which facts are worth public verification”
• OwnerCap / Extension This group solves “who has authority to change rules, how rules get attached”

Looking Deeper, What Problems Does Each Term Actually Solve for the World?

If you only memorize “definitions,” these terms still scatter easily. A more useful approach is: what long-term problems does each solve for this world?

When designing a new product later, you can ask in reverse:

• Are you solving a “path problem” or “permission problem”?
• An “item circulation problem” or “presence verification problem”?
• A “regional consequence enforcement problem” or “combat loss recording problem”?

This way you’ll more easily find which World capabilities to interface with, rather than randomly piling modules.

Why Do Many Beginners Mix Up These Terms?

Because these terms all look like “on-chain concepts,” but they actually come from different layers:

As long as you separate these layers first, many concepts won’t pile up together later.

Another Set of Easily Confused Terms

These terms are often mentioned together, but they’re actually not the same:

0.4 Why Are Smart Assemblies the Gameplay Core?

One of EVE Frontier’s most special features is making infrastructure into player-ownable, configurable, extensible Smart Assemblies.

You can first understand them as “service nodes in space”:

The value of these facilities isn’t that “they’re on-chain objects,” but that they directly control players’ most real needs:

• Can I pass through here?
• Can I safely store cargo here?
• Will I be shot by the turrets here?
• Can I buy, rent, or deliver certain items here?

Once a facility controls these entry points, it naturally becomes an economic node, strategic node, or political node.

0.5 Why Can’t Bases Avoid Network Node, Energy, and Fuel?

Many people first encountering EVE Frontier instinctively think of facilities as “on-chain objects you can use once placed.” Actually not. Facilities in gameplay have survival costs and operational conditions.

A minimal base roughly looks like this:

First find an anchorable location
  -> Establish Network Node
  -> Refuel the node and bring it online
  -> Connect Gate / Turret / Storage Unit
  -> These facilities reserve Energy from the network node
  -> They rely on Fuel and online status to continue operating

Here there are at least three completely different constraints:

1. Geographic constraint: You must first have a foothold in space
2. Capacity constraint: How much Energy the node can provide determines how many facilities you can mount
3. Consumption constraint: Fuel burns over time, facilities aren’t permanently cost-free online

This means “why can’t I use my gate” in gameplay could be three completely different problems:

• This gate isn’t connected to an available node at all
• Node capacity is insufficient, Energy is occupied by other facilities
• Fuel burned out, building entered offline state

This is also why the later Energy / Fuel chapters aren’t just technical details. They directly determine whether a base is a truly operable, fee-chargeable, sustainable system.

Why Does a Base Naturally Grow Into a “Service Network”?

Many people think bases are just “placing several buildings together.” But in EVE Frontier, a mature base is more like a small institutional system:

• Network Node provides underlying power capability
• Gate determines who can enter, exit, detour, or pay
• Turret determines safety consequences for those approaching
• Storage Unit determines how cargo, supplies, and deposits are managed

Once these 4 types of facilities combine, bases no longer just become footholds but gradually evolve into:

• Toll outposts
• Alliance defense zones
• Logistics transit stations
• Border trading ports
• War supply nodes

So what Builders actually write is often not individual functions, but rule networks for “how a certain region should operate.”

What “Secondary Gameplay” Usually Emerges Once a Base Matures?

Initially bases are just tools for survival, but once stabilized, many secondary gameplays emerge:

• Fee gameplay Like passage fees, storage fees, agent fees, rush fees
• Screening gameplay Like whitelists, memberships, tribe-exclusives, post-quest access
• Security gameplay Like gate entrance turret linkage, critical cargo warehouse defense zones, danger list auto-identification
• Financial gameplay Like deposits, insurance, rental, payouts, bounties
• Social / Political gameplay Like alliance-exclusive corridors, diplomatic treaties, regional joint defense, war zone access systems

This is also why a base that’s “just gates and turrets” eventually becomes something like a hybrid of port, checkpoint, market, and border station.

0.6 Why Are Stargates, Location, and Spatial Control So Important?

EVE Frontier is a strongly spatial world. You’re not just “clicking a button to go to a page,” but moving in a universe with distance, paths, and risk exposure.

What Does Gate Mean in Gameplay?

The essence of Gate isn’t teleportation effects, but a passage rights controller. Who can pass, when they can pass, how much they pay, whether they meet certain conditions—all affect player behavior paths.

So a stargate can naturally evolve into many gameplay forms:

• Toll stations
• Whitelist corridors
• Reward entrance after quest completion
• Alliance-exclusive routes
• Risk zone customs

More specifically, Gates in gameplay control at least 4 things simultaneously:

1. Path choice Whether players are willing to take this route depends on whether it’s fast, stable, and cheap.
2. Access qualification Who can pass, who must first meet conditions, who gets rejected.
3. Passage cost Can this become a fee node, monthly card node, alliance privilege node.
4. Regional rhythm Once a gate is fee-charged, blockaded, or militarized, surrounding logistics and conflict distribution change.

So Gates are never “a jump button,” but transportation institutions.

Why Are Gates Often the First Commercialized Facility?

Because Gates naturally sit on “must-pass paths.” Whoever controls paths controls three particularly monetizable capabilities:

1. Fee capability Tolls, membership fees, temporary license fees all come naturally.
2. Screening capability Who can enter, who can’t directly affects regional population and cargo flow.
3. Traffic capability Players lingering at gates means surrounding storage, shops, and quest points can be activated.

So many Builders’ first truly decent commercial product starts from Gates, not from more abstract Token models.

Why Do We Need Location Proofs?

Because many actions aren’t “as long as you own a certain wallet address you can do it,” but “only if you’ve actually arrived on site.” For example:

• You must be near a certain gate to pass through
• You must be near a certain treasure chest to open it
• You must be near a certain market node to trade on-site

On-chain contracts can’t know your real-time coordinates in the game world themselves, so the game server needs to issue proof that “you’re near a certain object,” then the chain verifies it. This is the gameplay background for why LocationProof and proximity systems exist later.

You can also understand location proof as “making geographic presence a ticket condition.” Without it, many gameplays that should depend on on-site presence will degrade into remote script operations:

• Remote gate opening
• Remote chest opening
• Remote trading
• Remote submission of tasks that should be completed on-site

Once these can all be done remotely, space loses meaning, and the strategic value of bases and routes declines together.

0.7 How Do Turrets, Defense Lines, and “Regional Order” Come About?

If Gates solve “who can pass,” then Turret solves “who approaching gets shot.”

Turrets in gameplay aren’t simply damage devices but part of regional order. They turn a space from “anyone can come” into “better consider consequences before coming.” This directly changes:

• Friend-or-foe identification
• Newbie protection
• Base defense
• Corridor deterrence
• Logistics safety costs

By default turrets only provide basic defense logic, but after Builder intervention, turrets can become more complex strategic facilities:

• Prioritize attacking active aggressors
• Spare whitelists or specific tribes
• Escalate threats for high-risk targets
• Work with gates and fees to govern entire regions

So don’t only view turrets as combat modules. They’re essentially spatial governance modules.

In mature regional gameplay, turrets often work together with other facilities:

• Gate + Turret Forms fee-charging border ports with enforcement power
• Storage Unit + Turret Forms defense system for high-value material nodes
• LocationProof + Turret Forms regional rules where “only on-site and condition-meeting people can safely operate”

In other words, turrets aren’t just damage output but “consequence machines when rules aren’t followed.”

Why Do Turrets Directly Change Economics?

Because safety is never a free environmental variable but part of transaction costs. As long as turrets exist, these things change:

• Whether cargo players are willing to take certain routes
• Whether high-value cargo dares to temporarily store at certain nodes
• Whether fees in certain regions can be enforced
• Whether pirate interception costs rise

So turrets aren’t just “things military players care about.” They actually affect decisions of merchants, operators, and ordinary passing players.

0.8 Death, Loot, KillMail, and “Visibility of Losses”

EVE-style gameplay has a fundamental difference from many lightweight blockchain games: losses aren’t abstract numerical drops, but real asset, location, and opportunity losses.

A PvP or wrong navigation can bring these results:

• Ships or facilities destroyed
• Items lost
• Loot picked up by others
• Certain transport line forced to interrupt
• Opponent obtains a public KillMail record

KillMail’s significance isn’t just “making a combat rankings look good.” It has at least 4 roles in gameplay:

1. Makes losses publicly verifiable
2. Makes combat history part of economic and reputation systems
3. Lets Builders design rewards, insurance, bounties, leaderboards around kill records
4. Makes conflicts in the world leave lasting traces

This is also why you’ll later see designs around KillMail for insurance, bounties, achievements, and statistics. Because it’s not marginal logs but part of war narratives.

If we speak more directly, KillMail makes many things in this world institutionalizable for the first time:

• “Is this loss real” can be verified
• “Is this person recently a high-risk target” can be statistically tracked
• “Should insurance pay out” doesn’t rely on hearsay
• “Is this alliance defending routes” can be indirectly reflected through combat records

So it’s not simply combat reports but public baseline for warfare, insurance, reputation, and bounty systems.

Why Does “Death Has Records” Profoundly Change Player Behavior?

Because once losses leave public traces, player behavior no longer just short-term results but also affects long-term reputation and institutional evaluation:

• Operators care more about route safety
• Insurers care more about whether payout conditions are real
• Bounty systems can more precisely identify targets
• Players care more about which places are prone to incidents

KillMail makes “what happened in this world” no longer just exist in chat records and memories, but enter the statistically composable rules layer.

0.9 Why Do Storage, Logistics, and Trading Become an Entire Economy?

In EVE Frontier, items aren’t “done once in backpack.” What’s truly valuable is how items are stored, transported, exchanged, and permission-accessed.

An item from production to consumption may go through many stages:

Player obtains item
  -> Temporarily carry
  -> Deposit in Storage Unit
  -> Listed for sale / as deposit / as rental target
  -> Purchased, rented, redeemed, or consumed by other players
  -> Recirculated in war, transport, or death

Thus storage facilities no longer just warehouses but naturally evolve into:

• Stores
• Vending machines
• Consignment points
• Shared warehouses
• Reward pools
• Loot recovery points
• Inter-alliance material exchange interfaces

From a gameplay perspective, where Builders most easily create value is often not “issuing a new Token,” but making existing item circulation paths smoother, safer, more rule-bound.

This is also why Storage Unit is often the most underestimated facility. Many product innovations look like markets, rentals, insurance, loot boxes, or quest systems on the surface, but underneath are answering one question:

When can certain items be taken by whom, put in, locked, released, transferred, destroyed, or redeemed?

Whoever controls this process controls a considerable portion of the game economy.

Why Is Storage Unit Often the “Behind-the-Scenes Star” of All Gameplay?

Because many systems ultimately come down to “where things are placed, who can take them, when to release”:

• Markets must solve settlement
• Rentals must solve temporary transfer and expiry recovery
• Reward pools must solve conditional release
• Insurance must solve payout material or fund distribution
• Quest systems must solve delivery and pickup item sequence

So although Storage Unit doesn’t look as conspicuous as Gate on the surface, it’s often the facility closest to the economic base.

0.10 In the Economic System, What Roles Do SUI and LUX Play?

In this book’s context, you can first make a sufficiently practical understanding:

• SUI is more like underlying on-chain fuel and general settlement asset
• LUX is more like assets closer to game services and daily economic interactions

Many Builder products will design around these actions in gameplay:

• Passage fees
• Service fees
• Deposits
• Rental settlement
• Insurance premiums and payouts
• Reward distribution

What’s truly important isn’t “which Coin is more advanced,” but whether your designed fee model fits gameplay. For example:

• High-frequency small-amount services care more about low friction
• Risk scenarios need more deposits and breach penalties
• Long-term relationships suit subscriptions, memberships, license models better
• War-related products value payouts, guarantees, and reputation more

So economic design is never an independent chapter. It’s always embedded in gameplay like passage, defense, warehousing, logistics, and diplomacy.

0.11 Which Things Are On-Chain, Which Things Still on Game Server?

The most critical point to understanding EVE Frontier is not to mix “open world game” and “on-chain contracts” into one system.

Both sides are collaborative, not replacement relationships.

You can understand it as:

• Game server handles “what’s happening in the world”
• Blockchain handles “which rules and results need to be public, persistent, composably established”

Precisely because of this, what Builders write is more like “rule infrastructure,” not taking over the entire game engine.

If this layer of division is misunderstood, two common misconceptions will arise later:

• One misconception is “why not move all real-time gameplay on-chain” Real-time physics and high-frequency judgments aren’t suitable to be directly made into public chain state
• Another misconception is “since the server knows, why put it on-chain” Because permissions, assets, licenses, payouts, public records—these things precisely need public verification

EVE Frontier’s special feature isn’t extremely choosing only one side, but piecing together the parts each side excels at into a stronger system.

As a Builder, 10 Types of Gameplay Entry Points Most Worth Observing First

If you want to transition from “knowing the worldview” to “knowing what to do,” the most worthwhile first observations are these entry points:

1. Who has natural traffic on a certain route.
2. Which locations require players to physically be present.
3. Which items are frequently deposited, withdrawn, traded, bet on, or consumed.
4. Which rules need automatic enforcement, not just verbal agreements.
5. Which losses need public records to support subsequent payouts or statistics.
6. Which regions already have stable but inefficient fee or screening demand.
7. Which services can’t scale because they need manual trust.
8. Which alliances or groups need to long-term maintain their own order and boundaries.
9. Which players abandon certain trades or collaborations due to excessive operational costs.
10. Which places, once rules are standardized, can be replicated to many bases and routes.

These 10 types of entry points are essentially where Builders most easily discover real needs.

0.12 What Can Developers (Builders) Do in This World?

After understanding players’ game loops, as a developer (Builder), you can leverage Sui smart contracts and EVE Frontier’s open interfaces to excel in four core directions:

1. Write Smart Component Extensions

In-game stargates (Gate), turrets (Turret), and storage boxes (Storage Unit) only have the most basic operational logic by default. Builders can write Move contracts to turn these facilities into complex business rule engines:

• Stargate toll stations: Charge per use, provide monthly card subscriptions, or charge high “tolls” for hostile alliances.
• Smart fire control networks: Let turrets identify “wanted criminals with bounties” or “passersby who haven’t paid protection fees” and automatically fire.
• Automated logistics boxes: Players deposit ore objects, contract automatically settles LUX tokens at current market rate.

2. Build Decentralized Applications & Interfaces (dApps & UI)

With on-chain rules, players need convenient user interfaces to interact. You can develop using EVE Vault (player digital identity plugin) combined with frontend and dApp Kit:

• Ticket sales hall: A webpage for players to purchase “Jump Permits” online.
• Alliance finance dashboard: Shows shared treasury real-time balance, daily tax revenue, and loot distribution records.
• In-game embedded overlay: Web UI that pops up directly in-game, letting players complete interactions and signing without leaving the client.

3. Design Advanced Deep Space Finance & Economic Models (DeFi)

Since all items (ships, weapons, resources) can be mapped on-chain as unique Objects, EVE Frontier naturally suits breeding hardcore financial protocols:

• Combat loss insurance contracts: Verify exact combat losses based on kill logs (KillMail), automatically payout to exploded ship players.
• Decentralized rental protocols: Mechanisms with great player safety to temporarily borrow premium firepower equipment (like turrets), automatically forfeit deposit or revoke control if not returned on time.
• Futures & options markets: Combine major corporation war zone resource output rates to establish large-depth trading pools (like DeepBook integration) to lock mineral prices.

4. Data Intelligence & Intelligence Networks (Data & Intel Indexing)

Every on-chain event broadcasts real-time changes in the game world. Builders can use indexers or backend monitoring to build ecosystem intelligence tools:

• Interstellar warfare heat maps: By aggregating network-wide jump permit records and KillMail data, real-time prompt which star systems are erupting in warfare, becoming frontline high-risk areas.
• Network-wide bounty hunter red name list: Record each player’s malicious breach, hostile kill behavior and other on-chain footprints, letting mercenary alliances form quantifiable reputation ratings.

In short, ordinary players are experiencing this digital universe’s cruelty and grandeur, while Builders are directly writing and distributing this universe’s fundamental operating laws.

0.13 Using a Complete Scenario to String These Concepts Together

Suppose a Builder team operates a outpost base on an important route:

1. They first establish Network Node, giving the entire base power capability.
2. Then deploy a Gate, turning this route into a fee-chargeable corridor.
3. Deploy Turret near the gate to prevent hostile players from freeloading or harassing.
4. Add a Storage Unit, letting passing players buy supplies, store materials, pay deposits.
5. To avoid anyone passing through the gate, they write an extension for Gate:
   • Whitelist alliance members pass free
   • Ordinary players pay tolls
   • High-risk area players must hold temporary permits
6. To handle “only allowing trades if person is on-site” gameplay, they require market operations to attach location proof.
7. If nearby kills occur, KillMail gets indexed and used to give combat rewards to security alliances.

You’ll find this already strings together most major themes of the entire book:

• Character and permissions
• Gate / Turret / StorageUnit
• Energy / Fuel
• LocationProof
• KillMail
• Fees, licenses, insurance, rewards
• dApp display and off-chain indexing

So each chapter later isn’t actually about “an abstract technical point,” but dissecting certain types of real gameplay needs in this world.

0.14 After Reading This Chapter, What Should You Bring Into Subsequent Chapters?

If this chapter has established these intuitions for you, later content will go much smoother:

1. EVE Frontier’s core isn’t issuing assets but operating infrastructure and rule entry points.
2. Facilities are gameplay nodes, not decorations.
3. Location, passage, warehousing, defense, combat losses, and economics are interconnected.
4. Game server and on-chain contracts have clear division of labor but collaborate on key rules.
5. Builders write not “plugin features” but rule systems that may long-term embed into world order.

Next recommend entering in this order:

• Chapter 1: EVE Frontier Macro Architecture
• Chapter 2: Development Environment Setup
• Chapter 3: Move Contract Basics

When you read further into these chapters later, you can always come back to this one:

• Chapter 16: Location and Proximity Systems
• Chapter 32: KillMail System
• Chapter 29: Energy and Fuel Systems
• Chapter 30: Extension Pattern Practice
• Chapter 31: Turret AI Extensions
• Chapter 26: Complete Access Control Analysis

Chapter 1: EVE Frontier Macro Architecture and Core Concepts

Objective: Understand what EVE Frontier is, why it chose the Sui blockchain, and the core philosophy of a “programmable universe.”

Status: Foundation chapter. The main text focuses on macro architecture and terminology establishment, suitable as an entry point for the entire book.

If you haven’t formed a clear intuition about the game itself, we recommend reading Preface Chapter: First Understand the EVE Frontier Game.

1.1 Why is EVE Frontier Different?

Traditional online games have world rules dictated solely by developers—economic systems, combat formulas, content updates—players are merely participants. EVE Frontier challenges this paradigm: the game’s core mechanics are open, and developers (Builders) can truly rewrite and extend game rules within the framework defined by the game server.

This isn’t simply “MOD plugins”—the logic you write runs as smart contracts on the Sui public blockchain, permanently auditable, requiring no centralized server hosting, and executing automatically 7×24.

What is it NOT?

Beginners most easily confuse EVE Frontier with the following things, but it’s not entirely equivalent to any of them:

You can understand it as:

EVE Frontier isn’t about “putting the entire game on-chain,” but rather putting the sufficiently important, sufficiently composable, sufficiently worthy of public verification portions of game rules on-chain.

Three Player Roles

The target audience of this course is Builders, but understanding the other two roles helps you design more valuable products.

How Do These Three Roles Interact?

Many people initially think these three roles are completely separate. Actually, they’re not—they describe three types of responsibilities within the same ecosystem:

• Builder is responsible for “defining rules” Example: Write a toll stargate, rental market, alliance dividend system
• Operator is responsible for “operating rules” Example: Actually buy facilities, set rates, issue passes, maintain inventory
• Player is responsible for “consuming rules” Example: Buy tickets, rent equipment, pass turret checks, claim rewards

A minimal business chain typically looks like this:

Builder writes contract
  -> Operator deploys and configures facility
  -> Player interacts with facility
  -> On-chain state changes are consumed by dApp / other Builders

This is why Builders can’t just know how to write contracts. You also need to understand:

• What Operators care about: revenue, permissions, security, maintenance costs
• What Players care about: price, convenience, predictability, whether they’re being scammed

What Does a Minimal Builder Closed Loop Look Like?

If you compress the EVE Builder ecosystem into a minimal closed loop, it’s typically this chain:

Builder designs rules
  -> Deploys facilities and extensions
  -> Operator configures parameters and operates
  -> Player pays or meets conditions to use
  -> Transactions, permissions, and asset changes land on-chain
  -> Front-end and indexing layer display results

Every link in this chain is essential:

• Without Builders, there are no new rule facilities in the world
• Without Operators, facilities lack sustained managers
• Without Players, rules won’t form real economic activity

So when designing any component later, it’s best to first ask yourself three things:

1. Who defines the rules?
2. Who operates and maintains it?
3. Why would players be willing to use it?

1.2 Smart Assemblies: Programmable Space Infrastructure

Smart Assemblies are physical facilities built by players in space in EVE Frontier. They are both game objects and programmable contract objects on the blockchain.

More precisely, a smart assembly typically has three layers of identity simultaneously:

1. Physical facility in the game world Example: You can actually see a turret or stargate in space
2. Shared object on-chain Example: It has an object ID, state fields, permission rules
3. Service entry point accessible to dApps Example: Front-end can query its inventory, rates, online status, and initiate transactions

So when you say “I made a smart stargate,” you’re essentially not just making a UI, nor just writing a Move module, but creating:

An infrastructure service that’s visible in-game, verifiable on-chain, and operable from the front-end.

Main Component Types

🏗 Network Node

• Anchored at Lagrange Points
• Provides Energy for the entire base
• All facilities must connect to a network node to operate
• Not directly programmable, but the operational foundation for other components

📦 Smart Storage Unit (SSU)

• Stores items on-chain, supports “main inventory” and “Ephemeral Inventory”
• By default, only allows Owner to deposit/withdraw items
• Through custom contracts can become: vending machines, auction houses, guild vaults

⚡ Smart Turret

• Automated defense facility
• Default behavior is standard attack logic
• Through contracts can customize target locking judgment logic (e.g., only attack characters without permits)

🌀 Smart Gate

• Links two locations, allows character jumps
• By default, everyone can jump
• Through contracts introduces “Jump Permit” mechanisms, enabling whitelists, fees, time limits, etc.

Four Most Common Builder Transformation Directions for Components

If you’re unsure which component to start from for an idea, first ask yourself:

• Is it fundamentally about “storing things”? Start with Storage Unit
• Is it fundamentally about “deciding who can pass”? Start with Gate
• Is it fundamentally about “deciding who gets attacked”? Start with Turret
• Does it fundamentally depend on power/network constraints? Need to understand Network Node simultaneously

Smart Assembly Lifecycle

A smart assembly isn’t “done once deployed on-chain”—it typically goes through an entire lifecycle:

1. Creation / Anchoring Facility is first established in the world
2. Attribution It’s bound to a character or operating entity
3. Online It obtains energy, network, and interactive state
4. Extension Builder plugs in custom rules
5. Operation Operator adjusts prices, inventory, permissions
6. Consumption Player has real interactions with it
7. Offline / Migration / Deactivation Facility may lose energy, upgrade, be replaced, or cease operations

The contracts, dApps, scripts, wallets, and indexing you’ll learn later all serve around this lifecycle.

1.3 Three-Layer Architecture: How is the Game World Built?

EVE Frontier’s world contracts use a strict three-layer architecture, which is key to understanding all subsequent content:

┌────────────────────────────────────────────────────┐
│  Layer 3: Player Extensions (Player Extension Layer)  │
│  Your Move contracts are here                          │
└────────────────┬───────────────────────────────────┘
                 │  Invoked via Typed Witness Pattern
┌────────────────▼───────────────────────────────────┐
│  Layer 2: Smart Assemblies (Smart Component Layer)    │
│  storage_unit.move  gate.move  turret.move            │
└────────────────┬───────────────────────────────────┘
                 │  Internal calls
┌────────────────▼───────────────────────────────────┐
│  Layer 1: Primitives (Basic Primitive Layer)          │
│  status  location  inventory  fuel  energy            │
└────────────────────────────────────────────────────┘

• Layer 1 - Primitives: Bottom-layer modules not directly callable, implementing “digital physics” (like location, inventory, fuel)
• Layer 2 - Smart Assemblies: Component objects exposed to players, each is a Sui Shared Object
• Layer 3 - Player Extensions: Where you as a Builder work, safely inserting custom logic through Typed Witness

Key Understanding: You cannot directly modify Layer 1/2, but you can write logic in Layer 3 that interacts with components through officially authorized APIs. This ensures both the safety of the game world and provides sufficient freedom for Builders.

What Does Each Layer Actually Handle?

A very practical judgment criterion:

• If you’re defining “world basic laws,” that’s usually a Layer 1 issue
• If you’re defining “how official facilities work by default,” that’s usually a Layer 2 issue
• If you’re defining “how I want my facility to work,” that’s usually a Layer 3 issue

How Does a Real Interaction Pass Through Three Layers?

Taking “player pays to pass through stargate” as an example:

Player clicks "Purchase and Jump" in dApp
  -> Layer 3: Your fee extension checks if payment made / if holding ticket
  -> Layer 2: Gate component executes jump entry
  -> Layer 1: Underlying location, state, permissions, fuel primitives complete validation and state updates
  -> Result written back to on-chain object, front-end refreshes

So when writing extensions, keep in mind to always distinguish:

• Which part is “my business rules”
• Which part is “behavior guaranteed by official components”
• Which part is “underlying world physics rules”

Why is This Layering Important for Builders?

Because it directly determines where you should write your logic.

For example, if you want to make a “toll stargate”:

• Fee rules and discount strategies: Write in your extension
• How the stargate jump itself executes: Handled by official components
• Location, permissions, state transitions involved in jumping: Handled by underlying primitives

If you mix these three things together, two common problems will occur:

• You reimplement rules in extensions that are already guaranteed at the bottom layer
• You think you can modify the official component core, but actually have no such authority

What is Typed Witness?

Here’s an intuitive understanding first, without diving into syntax details:

• You can’t just tell an official stargate “use my function from now on”
• You must access through a type identity marker accepted by officials
• This type identity is the Typed Witness that will repeatedly appear later

You can roughly understand it as:

“I’m not directly modifying official code, but holding a typed authorization badge to attach my extension logic to official components.”

Later in Chapter 30 you’ll see how it works specifically.

1.4 Why Choose the Sui Blockchain?

EVE Frontier’s migration to Sui wasn’t accidental, but a carefully considered technical choice.

Sui’s Core Advantages

What Does the Object Model Mean?

On Sui, every item, every character, every component in the game is an independent on-chain object, with:

• Unique ObjectID
• Clear ownership (owned by address / shared / owned by object)
• Complete traceable operation history

This is especially important for game worlds, because many game objects are naturally suited to “independent entity” representation:

• A permit is an independent ticket
• A warehouse is an independent facility
• A treaty is an independent agreement
• A kill record is an independent battle report

When these things are all objects, you can naturally do:

• Transfer
• Authorization
• Query
• Composition
• History tracking

This is why EVE Frontier can make “facilities, permissions, transactions, events” into a programmable ecosystem, rather than a pile of database records that can only be consumed internally.

This makes decentralized ownership, trading, and game history archives naturally viable capabilities.

Three Most Critical Object States

If this section isn’t explained clearly, much of the content later will feel awkward.

These three states determine almost all your later designs:

• How to write permissions
• How to assemble transactions
• How the front-end queries objects
• Whether parallel execution is possible

Why is the Object Model Particularly Suitable for Space Games?

Because space games are naturally “many discrete objects interacting”:

• Ships are objects
• Characters are objects
• Gates, turrets, storage units are objects
• Passes, policies, rental vouchers are also objects

Sui’s object model means these things don’t need to be forcibly stuffed into a centralized database table or a huge contract mapping. You can make each facility, each voucher, each relationship into independent objects, then through:

• Ownership relationships
• Shared access
• Events
• Dynamic fields

Organize them together.

Why are Sponsored Tx and zkLogin Important for Game Experience?

The two most discouraging points for players in traditional on-chain applications are:

1. Need to learn about wallets, mnemonic phrases, Gas first
2. Must pay transaction fees yourself for every action

Sui’s value in EVE Frontier isn’t just “higher performance,” but that it provides the foundational conditions for gradually introducing Web2 players to on-chain interactions:

• zkLogin: Lower wallet barriers
• Sponsored Tx: Lower transaction barriers
• Low-latency object transactions: Reduce interaction waiting time

These three points combined make “one click in-game completes on-chain action” a reality.

1.5 EVE Vault: Your Identity and Wallet

EVE Vault is the officially provided browser extension + Web wallet, serving as your digital identity as a Builder and player.

Core Functions

• Store LUX, EVE Token, and in-game NFTs
• Create Sui wallet through zkLogin using EVE Frontier SSO account, no need to manage mnemonic phrases
• Serve as dApp connection protocol, authorizing third-party dApp access in-game and external browsers
• FusionAuth OAuth binds game character identity with wallet

How is it Different from Regular Wallets?

Regular crypto wallets typically follow the mindset: “Have wallet first, then find applications.”

EVE Vault is more like: “I’m first a user in EVE Frontier, then wallet capability naturally embeds into this identity system.”

This means it simultaneously handles three things:

1. Asset Container Holds LUX, Tokens, NFTs, credentials
2. Identity Bridge Connects game account, SSO login, Sui address
3. Interaction Authorizer Provides dApps with connection, signing, sponsored transaction capabilities

What Do You Need to Remember About zkLogin First?

Don’t dive into cryptographic details right away—understanding these three points is enough:

• It allows users to enter on-chain systems using familiar login methods
• Behind it still falls to a wallet identity usable on Sui
• This isn’t “no wallet,” but “wallet creation and recovery experience is repackaged”

When you reach Chapter 33, dive into its proof structure and temporary key mechanism.

Two Currencies

1.6 Programmable Economy: Builder’s Business Possibilities

Review what real business logic Builders can implement:

💰 Economic Systems
  ├── Custom trading markets (auto-matching, bidding auctions)
  ├── Alliance tokens (Sui-based Fungible Tokens)
  └── Service fees (stargate tolls, storage rent)

🛡 Security & Permissions
  ├── Whitelist access control (which players can use your facilities)
  └── Conditional locks (only characters who complete quests can withdraw items)

🤖 Automation
  ├── Turret custom locking logic
  ├── Automatic item distribution (quest rewards, airdrops)
  └── Cross-facility linkage (facility A's behavior triggers facility B's response)

🏗 Infrastructure Services
  ├── Third-party dApps read on-chain state
  └── External API linkage (off-chain data triggers on-chain actions)

What Does a Minimal Builder Business Closed Loop Look Like?

If you still find “what Builders actually do” a bit abstract, remember this minimal closed loop:

I control a facility
  -> I define rules others must follow when using it
  -> Rules written on-chain
  -> Players use facility after paying/holding credentials/meeting conditions per rules
  -> Revenue, permissions, credentials, history records all stay on-chain

For example:

• Toll stargate: Charge per use
• Alliance warehouse: Place items by permissions
• Quest gate: Can only enter after completing assessment
• Auction box: Sell resources by price curve

The biggest difference from “making a regular game plugin” is:

• Rules are public
• State is verifiable
• Asset flows are traceable
• Other Builders can continue composing your rules

After Finishing Chapter 1, You Should Be Able to Answer These 5 Questions

1. Why isn’t EVE Frontier a regular MOD system?
2. What are Builder, Operator, and Player each responsible for?
3. Why is a Smart Assembly both a game facility and an on-chain object?
4. In the three-layer architecture, which layer do Builders actually work in?
5. Why is Sui’s object model more suitable for this type of game than traditional account balance models?

🔖 Chapter Summary

📚 Extended Reading

• Why Build on EVE Frontier?
• Smart Infrastructure
• EVE Frontier World Explainer
• Sui Documentation: Object Model

Chapter 2: Sui and EVE Environment Configuration

Objective: Complete only the two most fundamental and necessary installations for this book: Sui CLI and EVE Vault. This chapter no longer expands on common development tools like Git, Docker, Node.js, pnpm.

Status: Foundation chapter. The main text only covers installations and configurations directly related to Sui and EVE Frontier.

2.1 What Does This Chapter Install?

This chapter only handles two types of installations directly related to this book:

2.2 Why Only Install These Two First?

Because before you continue reading, the minimum capabilities you truly need are only two:

• Can run sui commands locally All your Move compilation, testing, publishing, and object queries depend on it
• Have a working EVE wallet identity in browser All your dApp connections, signing, and test asset claiming depend on it

Tools like Git, Docker, Node.js, pnpm will certainly be used later, but they belong to:

• Common development tools
• Scaffolding engineering tools
• Front-end and script running tools

These are better installed when you reach Chapter 6 and Chapter 7, combining them with the project directory.

What This Chapter Really Establishes Isn’t Just Two Software Programs

More precisely, this chapter establishes two working entry points:

• Command-line entry For compilation, publishing, querying, testing
• Browser entry For wallet connection, signing, dApp interaction

Almost all your development actions later will switch back and forth between these two entry points:

• After writing contracts, use CLI to compile and publish
• Open front-end, use EVE Vault to connect and sign
• When querying objects, might use CLI, or might use front-end or GraphQL

So although this chapter seems to be just about installation, it’s actually laying down the “workbench” for the entire book.

2.3 Installing Sui CLI

Recommend directly using the official suiup installation method. This way this chapter doesn’t need to distinguish between system toolchains like Homebrew, apt, nvm.

# Install suiup
curl -sSfL https://raw.githubusercontent.com/MystenLabs/suiup/main/install.sh | sh

# Reopen terminal or reload shell, then execute
suiup install sui@testnet

# Verify
sui --version

If sui --version can output the version number normally, the first step of this chapter is complete.

2.4 Initialize Sui Client

After installing Sui CLI, you need to initialize the client and connect to the network:

# Initialize configuration (first run will prompt to select network)
sui client

# Select testnet, or connect to local node:
# localnet: http://0.0.0.0:9000

# View current address
sui client active-address

# View balance
sui client balance

What Did You Actually Complete Here?

After executing sui client, you’ll have a basic on-chain identity and network configuration locally:

• Current active address
• Current default network
• RPC configuration corresponding to that network
• Account context that local CLI will use when sending transactions and querying objects

In other words, sui client isn’t simply a command to “check balance,” but laying the foundation for all your Move development actions.

What’s the Relationship Between sui client and EVE Vault?

These two things are most easily confused by beginners:

• sui client is the identity and network configuration in the command-line environment
• EVE Vault is the identity and signing entry in the browser environment

They can both represent “you,” but serve different scenarios:

• When you publish contracts, run tests, query objects in the terminal, you mainly rely on sui client
• When you connect dApps, click buttons, sign transactions in web pages, you mainly rely on EVE Vault

Must They Be the Same Address?

Not necessarily.

Many developers will encounter this situation:

• CLI uses one test address
• EVE Vault has another zkLogin address

This isn’t absolutely wrong, but you must be very clear about:

• Which address you’re publishing packages from now
• Which address or character controls your facilities
• Which wallet address your front-end connects to

As long as these three things aren’t aligned, you’ll frequently encounter “I clearly published, why can’t the front-end see it / operate it” problems.

Get Test SUI from Faucet

If connected to testnet:

# Request test coins through CLI
sui client faucet

# Or visit web Faucet:
# https://faucet.testnet.sui.io

2.5 Install and Initialize EVE Vault

EVE Vault is your browser identity, used to connect to dApps and authorize transactions.

Installation Steps

1. Download the latest Chrome extension:

   https://github.com/evefrontier/evevault/releases/download/v0.0.6/eve-vault-chrome.zip
   

2. Unzip the zip file
3. Open Chrome → Extension Management → Enable “Developer mode” → “Load unpacked extension” → Select unzipped folder
4. Click the extension icon, use EVE Frontier SSO account (Google/Twitch, etc.) to create your Sui wallet through zkLogin

Advantage: zkLogin doesn’t need mnemonic phrases, your Sui address is uniquely derived from your OAuth identity, secure and convenient.

What’s most worth understanding here isn’t the “installation method,” but why it greatly lowers the barrier for new users:

• No need to first educate users about saving mnemonic phrases
• No need to first install a set of traditional wallet mindset
• Users can directly enter on-chain interactions using familiar account systems

For Builders, this means your dApp doesn’t have to assume users are “already experienced crypto users.” This will directly affect your product design approach:

• Login and connection flow can be shorter
• Gas experience can be further optimized with sponsored transactions
• You can focus on facility experience rather than wallet education

2.6 What Does EVE Vault Specifically Handle in This Book?

After installing EVE Vault, it will undertake three types of responsibilities in subsequent chapters:

• Wallet Hold LUX, SUI, NFTs, permission credentials
• Identity Use EVE Frontier account to enter on-chain interaction system
• Authorization Entry Provide dApps with connection, signing, sponsored transaction capabilities

You can understand it first as:

sui client is the on-chain identity in command line, EVE Vault is the on-chain identity in browser and dApps.

The two aren’t necessarily the same address, but they must both work properly.

When Should You Check CLI First, When Should You Check Wallet First?

This can help you locate problems faster:

• Contract compilation failure Check CLI first
• Publishing transaction failure Check CLI current network and address first
• Front-end can’t connect wallet Check EVE Vault first
• Front-end can connect wallet but buttons report permission errors Verify wallet address, character attribution, and object permissions first

Don’t attribute all on-chain problems to “wallet broken” or “CLI misconfigured.” Most of the time, you haven’t first distinguished which layer the problem occurs in.

2.7 EVE Vault Faucet: Get Test Assets

During development and testing phases, you’ll encounter at least two types of test assets:

• Test SUI Used for on-chain transaction Gas
• Test LUX Used to simulate EVE Frontier in-game economic interactions

How to get LUX:

1. After installing EVE Vault, find GAS Faucet in the extension interface
2. Enter your Sui address to request test tokens
3. LUX will appear in your EVE Vault balance

Detailed instructions: GAS Faucet Documentation

Why Do You Need Both SUI and LUX During Testing?

Because they play different roles:

• SUI Is the Gas resource for on-chain transactions, without it many transactions can’t even be sent
• LUX Is more like an economic asset in the EVE Frontier business environment, many tutorials and cases use it to simulate in-game fees, settlements, permit purchases

If you only have SUI, no LUX:

• You can send transactions
• But many business processes can’t be practiced according to the book

If you only have LUX, no SUI:

• You’ll find it hard to complete even the most basic on-chain interactions

2.8 Minimum Acceptance Checklist

At this point, you don’t need to run scaffolding immediately, nor install front-end dependencies first. First confirm these four things:

1. sui --version can output the version
2. sui client active-address can return the current address
3. EVE Vault has completed zkLogin initialization
4. At least you can see test assets in wallet or can request from Faucet

If all four things are true, it means you already have the minimum environment to continue learning the first half of this book.

Three Most Common Environment Misalignments

1. CLI on testnet, wallet switched to a different network

Manifestation:

• Can query objects in terminal
• Can’t see corresponding assets or components in front-end

2. CLI address and wallet address aren’t the same, but you didn’t realize it

Manifestation:

• Contract published from one address
• dApp connected to another address
• Front-end operations prompt no permission

3. Faucet tokens received, but received to “another identity set”

Manifestation:

• You clearly claimed test coins
• But current wallet or CLI address balance is still 0

Once you encounter “I clearly did it, but the system says I didn’t” problems, don’t rush to doubt the tutorial. Verify these three things again first.

When to Install Other Tools?

• By Chapter 6: Install and use builder-scaffold
• By Chapter 7: Handle script and dApp dependencies
• By specific case chapters: Supplement front-end running environment as needed

🔖 Chapter Summary

📚 Extended Reading

• Sui CLI Complete Documentation
• Sui Client Configuration Guide
• EVE Vault
• EVE Vault GAS Faucet Documentation

Chapter 3: Move Smart Contract Fundamentals

Objective: Master core concepts of the Move language, understand the Sui object model, and be able to read and modify EVE Frontier contract code.

Status: Foundation chapter. Main text focuses on Move language, object model, and minimal examples.

3.1 Move Language Overview

Move is the smart contract language used by Sui, specifically designed for the problem that “on-chain assets cannot be arbitrarily copied, discarded, or transferred.” It’s not about first writing a general programming language and then using libraries to constrain assets; rather, it treats “resources” as the most important objects at the language level.

You can first grasp three intuitions:

• Assets aren’t just balance numbers On Sui, many assets are truly independent objects with their own id, fields, ownership, and lifecycle
• Types determine whether you can copy, store, discard Move uses an ability system to restrict what you can do with a value, preventing you from mistakenly treating “precious assets” as ordinary variables
• Contracts are more like modules + object systems What you write isn’t “one giant global state,” but a set of module functions to create, read, and modify objects

So learning Move isn’t just about learning syntax. What you really need to establish is a new way of thinking:

1. First distinguish between ordinary data and resources
2. Then distinguish who owns objects, who can modify them, who can transfer them
3. Only then write these rules into function entries and business processes

This is also well-suited to EVE Frontier. Because in EVE, many things are naturally not “a row in a database record,” but more like independently existing assets or facilities:

• A pass NFT
• A smart stargate
• A storage unit
• A permission credential
• A kill record

When these things are in Move, the expression becomes very natural.

3.2 Module Structure

A Move contract consists of one or more modules:

// File: sources/my_contract.move

// Module declaration: package_name::module_name
module my_package::my_module {

    // Import dependencies
    use sui::object::{Self, UID};
    use sui::tx_context::TxContext;
    use sui::transfer;

    // Struct definition (assets/data)
    public struct MyObject has key, store {
        id: UID,
        value: u64,
    }

    // Init function (automatically executed once during contract deployment)
    fun init(ctx: &mut TxContext) {
        let obj = MyObject {
            id: object::new(ctx),
            value: 0,
        };
        transfer::share_object(obj);
    }

    // Public function (can be called externally)
    public fun set_value(obj: &mut MyObject, new_value: u64) {
        obj.value = new_value;
    }
}

Although this code is short, it already contains the four most common types of Move elements:

• Module declaration module my_package::my_module indicates “this file defines a module”
• Dependency imports use is used to introduce types or functions exposed by other modules
• Struct definition MyObject describes what an on-chain object looks like
• Function entries Functions like init, set_value define how objects are created and modified

What’s the Relationship Between Modules and Packages?

Many newcomers conflate “packages” and “modules” into one thing, but they’re actually not at the same level:

• Package Is an entire Move project directory, typically containing Move.toml, sources/, tests/
• Module Is a code unit within a package, a package can have multiple modules

Here’s a structure closer to a real project:

my-extension/
├── Move.toml
├── sources/
│   ├── gate_logic.move
│   ├── gate_auth.move
│   └── pricing.move
└── tests/
    └── gate_tests.move

Here:

• my-extension is a package
• gate_logic, gate_auth, pricing are three modules

You can think of “package” as a deployment unit, and “module” as a code organization unit.

Why is init Important?

init executes once when the package is first published. Common uses include:

• Create shared objects
• Send AdminCap to the deployer
• Initialize global configuration
• Establish registry objects

It’s typically the “boot action when the system first comes online.” If you don’t create key objects properly in init, many entry functions won’t work properly later.

Why Do Fields Almost Always Start with id: UID?

Because on Sui, a true on-chain object must have UID, which represents a globally unique identity. Structs without UID are often just:

• Ordinary nested data
• Configuration items
• Event payloads
• One-time credentials

This is also your first clue when reading EVE contracts to determine “is this an independent object or not.”

3.3 Move’s Abilities (Ability System)

This is one of the most important concepts in Move. Each struct type can have the following abilities:

Don’t treat abilities as “syntax decoration.” They’re essentially answering a very serious question:

How is this value allowed to be handled by developers?

What Do the Four Abilities Mean?

1. key

has key indicates this type can exist as a top-level on-chain object.

Common characteristics:

• Usually contains id: UID
• Can be owned by an address, shared, or owned by an object
• Can be a core object for transaction reads/writes

Without key, this type cannot independently hang in on-chain global state.

2. store

has store indicates this type can be safely placed in other object fields.

For example:

• Put a configuration struct into StorageUnit
• Put a whitelist rule into SmartAssembly
• Embed metadata structure into NFT

Often, a type isn’t an independent object, but it must be able to exist as a component of other objects—this is when you need store.

3. copy

has copy indicates this value can be copied.

This is usually only suitable for:

• Small pure data
• Values that don’t represent scarce resources
• Similar to ID, boolean markers, enums, simple configurations

If something represents “permission,” “asset,” “unique credential,” it usually shouldn’t be given copy.

4. drop

has drop indicates this value can be directly discarded if not used.

This ability seems inconspicuous, but is actually quite critical. Because Move is very strict by default: if a value isn’t properly consumed, the compiler will chase you asking “what exactly do you plan to do with it?”

So:

• With drop, not using it is okay
• Without drop, you must explicitly consume or transfer it

Why Do Abilities Directly Affect Security?

Because many security boundaries are not guarded by if judgments, but by “the type simply doesn’t allow you to do this.”

For example:

• If an NFT doesn’t have copy, you can’t duplicate a second copy
• If a hot potato object doesn’t have drop, you can’t secretly ignore it
• If a permission object doesn’t have a public construction path, external parties can’t forge it

This is one of Move’s strong points: it moves many business constraints forward into the type system.

Application in EVE Frontier

// JumpPermit: has key + store, is a real on-chain asset, cannot be copied
public struct JumpPermit has key, store {
    id: UID,
    character_id: ID,
    route_hash: vector<u8>,
    expires_at_timestamp_ms: u64,
}

// VendingAuth: only has drop, is a one-time "credential" (Witness Pattern)
public struct VendingAuth has drop {}

These two examples can be viewed together:

• JumpPermit is a true object that should exist on-chain, so it has key
• VendingAuth is only a witness value in a call flow, doesn’t need on-chain persistence, so only given drop

When reading EVE contracts, you can often directly guess the author’s intent through abilities:

• has key, store: Likely a real object or quasi-object
• Only drop: Likely witness, receipt, one-time intermediate state
• copy, drop, store: Likely ordinary value type or configuration data

3.4 Sui Object Model Explained

On Sui, all structs with key ability are objects, divided into three ownership types:

Ownership Types

1. Address-owned
   └── Only the person holding that address can access
   └── Example: Player character's OwnerCap

2. Shared Object
   └── Anyone can read/write on-chain (controlled by contract logic)
   └── Example: Smart storage unit, stargate body

3. Object-owned
   └── Held by another object, external cannot directly access
   └── Example: Configuration stored inside components

These three ownership types aren’t abstract classifications, but one of the most core decisions when designing business models.

1. Address-owned: Most Like “My Assets”

Address-owned objects are typically suitable for:

• Player personal NFTs
• OwnerCap
• Character private credentials
• Transferable tickets, permits, badges

Characteristics are:

• Controlled by a certain address
• Transaction usually requires signature from that address
• Very suitable for expressing “who owns, who controls”

2. Shared Objects: Most Like “Public Facilities”

Shared objects are suitable for:

• Markets
• Stargates
• Storage units
• Alliance vaults
• Server-wide registries

The focus isn’t “who owns this object,” but “who can perform what operations on it under what rules.”

This is the core form of many EVE Frontier facility contracts. Because although a facility also has an operator, it’s first a public object that will be interacted with by many players together.

3. Object-owned: Most Like “Facility Internal Components”

Object ownership is commonly used to hide complex internal state, such as:

• Configuration object inside a facility
• Inventory table inside a component
• Auxiliary index inside a registry

Its benefit is encapsulating state, not letting external parties randomly take it out and misuse it.

Why is the Object Model Easier to Express Game Worlds Than “Global Mapping”?

Because many entities in games are naturally independently existing, can be referenced, can be transferred, can be composed:

• A turret
• A permit
• A character permission
• An alliance treaty

If all stuffed into one big table, logic becomes more and more like “database management scripts.” The object model is closer to real-world “entities + relationships + ownership.”

Objects Don’t Just Have Two States of “Exist or Not”

When designing, you also need to consider object lifecycle:

1. Creation Who creates it? In init or in business entry?
2. Holding Who owns it after creation? Address, shared, or object internal?
3. Modification Who can get &mut? Under what premise is modification allowed?
4. Transfer Can it be transferred? Do permissions follow after transfer?
5. Destruction When can it disappear? Need to settle balance or reclaim resources before destruction?

Deterministic Derivation of Object IDs

In EVE Frontier, each in-game entity’s ObjectID on-chain is deterministically derived through TenantItemId:

public struct TenantItemId has copy, drop, store {
    item_id: u64,          // Unique ID in-game
    tenant: String,        // Distinguish different game server instances
}

This means after the game server knows item_id, it can pre-calculate that item’s ObjectID on-chain without waiting for on-chain response.

This is very important in the EVE scenario, because off-chain servers and on-chain objects need long-term alignment:

• Game server knows a facility’s, character’s, item’s business ID
• Contract needs to map it to on-chain object keys using stable rules
• Front-end and indexing services query according to the same rules

If this mapping isn’t stable, the entire system will be chaotic:

• Off-chain considers it the same facility
• On-chain found another object
• Data displayed by front-end and real interactive objects don’t match

So when you later see TenantItemId, derived_object, registries, you need to first realize: the author is solving not “how to write code,” but “how to keep cross-system identity consistent.”

3.5 Key Security Patterns

EVE Frontier and other Sui projects widely use several Move-specific security design patterns:

Pattern 1: Capability Pattern

Permissions are represented by holding objects, not account roles.

// Define capability object
public struct OwnerCap<phantom T> has key, store {
    id: UID,
}

// Function that requires OwnerCap to call
public fun withdraw_by_owner<T: key>(
    storage_unit: &mut StorageUnit,
    owner_cap: &OwnerCap<T>,  // Must hold this credential
    ctx: &mut TxContext,
): Item {
    // ...
}

Advantage: OwnerCap can be transferred, can be delegated, more flexible than account-level permissions.

You can think of Capability as “permission materialization”:

• Traditional thinking is often “determine if sender == admin”
• Move/Sui’s more common thinking is “do you hold a certain permission object”

This brings several direct benefits:

• Permissions can be transferred
• Permissions can be split
• Permissions can be made into NFT / Badge / Cap
• Permission relationships are easier to audit on-chain

Pattern 2: Typed Witness Pattern

This is the core of EVE Frontier’s extension system! Used to verify the caller is a specific package’s module.

// Builder defines a Witness type in their own package
module my_extension::custom_gate {
    // Only this module can create Auth instances (because it has no public constructor)
    public struct Auth has drop {}

    // When calling stargate API, pass Auth {} as credential
    public fun request_jump(
        gate: &mut Gate,
        character: &Character,
        ctx: &mut TxContext,
    ) {
        // Custom logic (e.g., check fees)
        // ...

        // Use Auth {} to prove call comes from this authorized module
        gate::issue_jump_permit(
            gate, destination, character,
            Auth {},      // Witness: prove I am my_extension::custom_gate
            expires_at,
            ctx,
        )
    }
}

The Star Gate component knows your Auth type has been registered in the whitelist, so it allows the call.

This pattern feels strange the first time because Auth {} has no data inside. But what it really wants to express is:

“I’m not proving identity through field content, I’m proving which module I’m from through the type itself.”

Why is this strong?

• External modules can’t arbitrarily forge your witness type
• Components can only trust witness types in the whitelist
• So “who can call a certain underlying capability” can be restricted to specific extension packages

This is the core of EVE Frontier’s extensible components. Many components don’t simply expose a public entry for anyone to call, but require you to bring a specific witness to enter.

Pattern 3: Hot Potato

An object with no copy, store, drop abilities, must be consumed within the same transaction:

// No abilities = hot potato, must be handled in this tx
public struct NetworkCheckReceipt {}

public fun check_network(node: &NetworkNode): NetworkCheckReceipt {
    // Perform check...
    NetworkCheckReceipt {}  // Return hot potato
}

public fun complete_action(
    assembly: &mut Assembly,
    receipt: NetworkCheckReceipt,  // Must pass in, ensures check was executed
) {
    let NetworkCheckReceipt {} = receipt; // Consume hot potato
    // Formally execute operation
}

Purpose: Force certain operations to be atomically combined (e.g., “first check network node → then execute component operation”).

This pattern is especially suitable for “prerequisite checks cannot be skipped” processes:

• First verify eligibility, then mint credential
• First check network status, then execute facility action
• First read and lock a certain context, then settle

Its focus isn’t storing data, but using the type system to force callers to do things in order.

3.6 Function Visibility and Access Control

module example::access_demo {

    // Private function: can only be called within this module
    fun internal_logic() { }

    // Package-visible: other modules in the same package can call (Layer 1 Primitives use this)
    public(package) fun package_only() { }

    // Entry: can be directly called as top-level of a Transaction
    public fun user_action(ctx: &mut TxContext) { }

    // Public: any module can call
    public fun read_data(): u64 { 42 }
}

3.7 Writing Your First Move Extension Module

Let’s combine the above concepts to write a simplest Storage Unit extension:

module my_extension::simple_vault;

use world::storage_unit::{Self, StorageUnit};
use world::character::Character;
use world::inventory::Item;
use sui::tx_context::TxContext;

// Our Witness type
public struct VaultAuth has drop {}

/// Anyone can deposit items (open deposit)
public fun deposit_item(
    storage_unit: &mut StorageUnit,
    character: &Character,
    item: Item,
    ctx: &mut TxContext,
) {
    // Use VaultAuth{} as witness, proving this call is a legally bound extension
    storage_unit::deposit_item(
        storage_unit,
        character,
        item,
        VaultAuth {},
        ctx,
    )
}

/// Only characters with specific Badge (NFT) can withdraw items
public fun withdraw_item_with_badge(
    storage_unit: &mut StorageUnit,
    character: &Character,
    _badge: &MemberBadge,  // Must hold member badge to call
    type_id: u64,
    ctx: &mut TxContext,
): Item {
    storage_unit::withdraw_item(
        storage_unit,
        character,
        VaultAuth {},
        type_id,
        ctx,
    )
}

3.8 Compilation and Testing

# In your Move package directory
cd my-extension

# Compile (checks types and logic)
sui move build

# Run unit tests
sui move test

# Publish to testnet
sui client publish

After successful publication, you’ll get a Package ID (like 0xabcdef...), which is your contract’s on-chain address.

🔖 Chapter Summary

📚 Extended Reading

• Move Book (Official)
• Sui Move Concepts
• Typed Witness Pattern
• Capability Pattern
• EVE Frontier World Contract Code

Chapter 4: Smart Assembly Development and On-Chain Deployment

Objective: Understand the working principles and APIs of each smart assembly, master the complete workflow from character creation to contract deployment.

Status: Foundation chapter. Main text focuses on deployment workflow and on-chain component operations.

4.1 Complete Deployment Workflow

Before your code can take effect in the real game, you need to complete the following complete chain:

1. Create on-chain character (Smart Character)
        ↓
2. Deploy network node (Network Node), deposit fuel and go online
        ↓
3. Anchor smart assembly (Anchor Assembly)
        ↓
4. Bring assembly online (Assembly Online)
        ↓
5. Write and publish custom Move extension package
        ↓
6. Register extension to assembly (authorize_extension)
        ↓
7. Players interact with assembly through extension API

In local development, steps 1-5 can be completed with one click using builder-scaffold initialization scripts.

Many people when first encountering this chapter will mistakenly think “publishing contracts” is the main process. Actually it’s not. For EVE Builders, the real main process is:

1. First have on-chain entity
2. Then have operable facilities
3. Then have custom extension logic
4. Finally attach extensions to facilities for player consumption

In other words, the Move package you write doesn’t work independently out of thin air. It must be attached to a smart assembly that actually exists, is already online, and is already attributed to the character system.

The Three Most Easily Confused “IDs” in Deployment

During deployment, at least three types of IDs will appear simultaneously:

• Package ID Represents your Move package published on-chain
• Object ID Represents specific objects, such as characters, stargates, turrets, storage units
• Business ID Represents character, item, facility numbers in the game server

Don’t mix these three:

• Package ID determines “where your code is”
• Object ID determines “where your facilities and assets are”
• Business ID determines “who things in the game world are”

Later you’ll frequently switch back and forth between “code address” and “facility object address.” If these two concepts aren’t separated, debugging will be very painful.

4.2 Smart Character

Smart Character is your main identity on-chain, all assemblies belong to your character.

Character’s On-Chain Structure

public struct Character has key {
    id: UID,                        // Unique object ID
    // Each owned asset corresponds to an OwnerCap
    // owner_caps stored as dynamic fields
}

OwnerCap: Asset Ownership Credential

Whenever you own an assembly (network node/turret/stargate/storage unit), the character will hold the corresponding OwnerCap<T> object. All write operations to that assembly require first “borrowing” this OwnerCap from the character:

// TypeScript script example: Borrow OwnerCap
const [ownerCap] = tx.moveCall({
    target: `${packageId}::character::borrow_owner_cap`,
    typeArguments: [`${packageId}::assembly::Assembly`],
    arguments: [tx.object(characterId), tx.object(ownerCapId)],
});

// ... use ownerCap to execute operations ...

// Must return after use
tx.moveCall({
    target: `${packageId}::character::return_owner_cap`,
    typeArguments: [`${packageId}::assembly::Assembly`],
    arguments: [tx.object(characterId), ownerCap],
});

💡 Borrow & Return pattern combined with Hot Potato ensures OwnerCap won’t leave the character object.

Why Not Take OwnerCap Out and Hold Permanently?

Because OwnerCap isn’t an ordinary key, but a high-privilege credential. Designing it as “borrow then must return” has several direct benefits:

• Permissions won’t easily leave the character system
• After a transaction ends, won’t leave dangling high-privilege objects
• Assembly ownership still stably belongs to character, rather than scattered to script addresses or temporary objects

From a design perspective, this is equivalent to implementing “temporary privilege escalation” on-chain:

• You first prove you’re a legitimate operator of the character
• System temporarily lends you the permission object
• After completing high-privilege operations, you must return the permission

This is more flexible than “hardcoded admin address,” and more suitable for game scenarios’ delegation, transfer, inheritance, shell-changing operations and other needs.

What Role Does Character Actually Play in Business?

Don’t just understand Character as an alias for wallet address. It’s more like an on-chain “operating entity”:

• Assemblies hang under character name, not directly under wallet address name
• Character can internally manage multiple OwnerCap uniformly
• Character can serve as a bridge between on-chain permissions and in-game identity

So in many Builder scenarios, the truly stable entity isn’t “which wallet clicked the button,” but “which character is operating these facilities.”

4.3 Network Node

What is a Network Node?

• Energy station anchored at Lagrange Points
• Provides Energy for all nearby smart assemblies
• Each assembly when going online needs to “reserve” a certain amount of energy from the network node

Lifecycle

Anchored (Anchored)
    ↓ depositFuel (Deposit fuel)
Fueled (Fueled)
    ↓ online (Go online)
Online (Running)  ←→ offline (Go offline)

What’s most important here isn’t remembering state names, but understanding:

Whether a facility can work depends not only on “whether the contract is published,” but also on whether it’s actually powered in the game world.

This is a key difference between EVE Frontier and ordinary dApps. In ordinary dApps, after a contract is successfully published, theoretically anyone can call it; but in EVE, many facilities’ availability is also constrained by “world state”:

• Is there a network node
• Does the network node have fuel
• Is the facility properly anchored
• Is the facility online

From Builder’s Perspective, What Does Network Node Actually Solve?

It solves the problem of “facilities shouldn’t be online unconditionally forever.”

If this layer of design didn’t exist:

• Stargates could be open forever
• Turrets could work forever
• Storage facilities could keep responding

Then many meanings of operation, maintenance, supply, and occupation in the game would be lost. With network nodes added, facilities become assets that truly need maintenance, rather than “one deployment permanent money printer.”

Initialization Scripts for Local Testing (from builder-scaffold)

# Execute in builder-scaffold/ts-scripts directory
pnpm setup:character      # Create character
pnpm setup:network-node   # Create and start network node
pnpm setup:assembly       # Create and connect smart assembly

4.4 Smart Storage Unit (SSU) In-Depth Analysis

Two Types of Inventory

Ephemeral inventory is used for non-Owner players to interact with your SSU (e.g., when purchasing items, first transfer items to ephemeral inventory, then player takes them).

How Do Items Reach the Chain?

In-game item → game_item_to_chain_inventory() → On-chain Item object
On-chain Item object → chain_item_to_game_inventory() → In-game item (requires proximity proof)

What’s truly difficult here isn’t “which function to call,” but understanding that inventories on both sides aren’t simple mirrors.

Many newcomers will default to thinking:

• There’s a gun in the game backpack
• After going on-chain it’s just “copying a record”

Actually the correct understanding is closer to:

• A certain in-game item is mapped to an on-chain object through a trusted process
• This object then enters the on-chain inventory system
• When it’s taken back to the game world, it needs to go through another trusted return path

So the essence of Storage Unit isn’t a “on-chain cabinet,” but an asset exchange node between on-chain and game world.

Why Distinguish Between Primary and Ephemeral Inventory?

Because many interactions aren’t “Owner opening the warehouse to get things themselves,” but “third-party players having a controlled interaction with your facility.”

For example, a vending machine:

1. Player pays tokens
2. Facility first transfers corresponding items to a temporary intermediate area
3. Player then claims from that path

Benefits of doing this:

• Don’t have to fully expose main inventory to external parties
• Intermediate states of transactions are easier to audit
• Easier to do rollback and settlement when failures occur

Extension API Overview

// 1. Register extension (Owner calls)
public fun authorize_extension<Auth: drop>(
    storage_unit: &mut StorageUnit,
    owner_cap: &OwnerCap<StorageUnit>,
)

// 2. Extension deposits item
public fun deposit_item<Auth: drop>(
    storage_unit: &mut StorageUnit,
    character: &Character,
    item: Item,
    _auth: Auth,           // Witness
    ctx: &mut TxContext,
)

// 3. Extension withdraws item
public fun withdraw_item<Auth: drop>(
    storage_unit: &mut StorageUnit,
    character: &Character,
    _auth: Auth,           // Witness
    type_id: u64,
    ctx: &mut TxContext,
): Item

4.5 Smart Gate In-Depth Analysis

Default vs Custom Behavior

No extension: Anyone can jump
    ↓ authorize_extension<MyAuth>()
Has extension: Players must hold JumpPermit to jump

JumpPermit Mechanism

// Jump permit: time-limited on-chain object
public struct JumpPermit has key, store {
    id: UID,
    character_id: ID,
    route_hash: vector<u8>,   // A↔B bidirectional valid
    expires_at_timestamp_ms: u64,
}

The key to JumpPermit isn’t that “it’s a ticket,” but that it splits a complex judgment into two segments:

1. First decide “are you qualified to get the ticket”
2. Then decide “can you execute the jump with the ticket”

This split is very suitable for game rule extensions, because “qualification judgment” can be very complex:

• Are you a whitelist member
• Have you paid
• Have you completed prerequisite quests
• Are you within the valid time window

But once the ticket is issued, the logic when actually executing the jump can be more standard and unified.

This is also a common thinking for many extension designs:

Move complex business judgments forward to “credential issuance,” converge underlying facility actions to “credential consumption.”

Complete jump process:

1. Player calls your extension function (e.g., pay_and_request_permit())
2. Extension verifies conditions (check tokens, check whitelist, etc.)
3. Extension calls gate::issue_jump_permit() to issue Permit
4. Permit transferred to player
5. Player calls gate::jump_with_permit() to jump, Permit consumed

Extension API

// Register extension
public fun authorize_extension<Auth: drop>(
    gate: &mut Gate,
    owner_cap: &OwnerCap<Gate>,
)

// Issue jump permit (only registered Auth types can call)
public fun issue_jump_permit<Auth: drop>(
    source_gate: &Gate,
    destination_gate: &Gate,
    character: &Character,
    _auth: Auth,
    expires_at_timestamp_ms: u64,
    ctx: &mut TxContext,
)

// Jump using permit (consumes JumpPermit)
public fun jump_with_permit(
    source_gate: &Gate,
    destination_gate: &Gate,
    character: &Character,
    jump_permit: JumpPermit,
    admin_acl: &AdminACL,
    clock: &Clock,
    ctx: &mut TxContext,
)

What is authorize_extension Actually Authorizing?

It’s authorizing not “a certain address,” nor “a certain transaction,” but a certain type identity.

In other words, what assemblies truly trust is:

• Only calls bringing a certain designated witness type
• Can enter underlying capability entry points

This gives assembly extensions two important properties:

• Assembly kernel doesn’t need to know what your business logic looks like
• But it can very clearly know “which extension types are qualified to access”

So Builders’ work is often not “modifying official logic,” but “packaging their own logic into officially allowed typed extensions to access.”

4.6 Smart Turret In-Depth Analysis

Turret’s extension pattern is similar to stargate, authorized through Typed Witness.

Default Behavior

Turret uses standard attack logic provided by game server.

Custom Behavior

Builder can register extensions to change turret’s target judgment logic. For example:

• Allow characters holding specific NFT to pass safely
• Only attack characters not on alliance list
• Turn attack on/off based on time period (open daytime, closed nighttime)

4.7 Publishing and Registering Extension to Assembly

Step 1: Publish Your Extension Package

# In your Move package directory
sui client publish

# Output example:
# Package ID: 0x1234abcd...
# Transaction Digest: HMNaf...

Record the Package ID, this is your contract address.

After publishing completes, you should immediately record at least three types of information:

• Your Package ID
• The assembly object ID you want to bind
• Transaction digest

Because when troubleshooting problems later, almost all chains trace back from these three things:

• Was the contract successfully published
• Is the facility the object you thought it was
• Did this authorization or registration actually succeed on-chain

Step 2: Authorize Extension to Assembly

Through TypeScript script (or dApp call) to register your extension:

import { Transaction } from "@mysten/sui/transactions";

const tx = new Transaction();

// Borrow OwnerCap from character
const [ownerCap] = tx.moveCall({
    target: `${WORLD_PACKAGE}::character::borrow_owner_cap`,
    typeArguments: [`${WORLD_PACKAGE}::gate::Gate`],
    arguments: [tx.object(CHARACTER_ID), tx.object(OWNER_CAP_ID)],
});

// Authorize extension (tell stargate: allow my_extension::custom_gate::Auth type to call)
tx.moveCall({
    target: `${WORLD_PACKAGE}::gate::authorize_extension`,
    typeArguments: [`${MY_PACKAGE}::custom_gate::Auth`],  // Your Witness type
    arguments: [tx.object(GATE_ID), ownerCap],
});

// Return OwnerCap
tx.moveCall({
    target: `${WORLD_PACKAGE}::character::return_owner_cap`,
    typeArguments: [`${WORLD_PACKAGE}::gate::Gate`],
    arguments: [tx.object(CHARACTER_ID), ownerCap],
});

await client.signAndExecuteTransaction({ signer: keypair, transaction: tx });

Here you need to pay special attention to one thing:

“Publish successful” doesn’t equal “extension already in effect.”

You should at least confirm three layers of binding relationships are established:

1. Your package is already on-chain
2. Your assembly object is the correct assembly
3. Assembly has added your witness type to allowed list

Step 3: Verify Registration Success

# Query stargate object, confirm extension type has been added to allowed_extensions
sui client object <GATE_ID>

4.8 Using TypeScript to Read On-Chain State

import { SuiClient } from "@mysten/sui/client";

const client = new SuiClient({ url: "https://fullnode.testnet.sui.io:443" });

// Read stargate object
const gateObject = await client.getObject({
    id: GATE_ID,
    options: { showContent: true },
});

console.log(gateObject.data?.content);

// GraphQL query all assemblies of specified type
const query = `
  query {
    objects(filter: { type: "${WORLD_PACKAGE}::gate::Gate" }) {
      nodes {
        address
        asMoveObject { contents { json } }
      }
    }
  }
`;

Why Does Deployment Chapter Also Need to Discuss Reading State?

Because in actual development, deployment and reading have never been two separate things. After completing each step, you need to immediately verify:

• Was the object created
• Did state switch to online
• Was extension registered successfully
• Did assembly fields change as expected

So the real rhythm is usually:

Execute one step
  -> Immediately read on-chain state
  -> Confirm object and field changes
  -> Continue to next step

If you only know how to “send transactions” but don’t know how to “immediately verify state,” it’s hard to judge whether it’s:

• Transaction didn’t send
• Sent but wrong object
• Object correct but state didn’t change
• State changed but front-end queried wrong place

From Developer’s Perspective, What’s the Minimum Closed Loop of This Chapter?

The minimum closed loop isn’t “I published a package,” but:

1. Have character
2. Have facility
3. Have permission credential
4. Have custom extension package
5. Have successful registration record
6. Have one real verifiable player interaction

Only when all 6 things are completed do you truly finish a Builder facility extension.

🔖 Chapter Summary

📚 Extended Reading

• Smart Storage Unit Documentation
• Smart Gate Documentation
• Interfacing with the World
• builder-scaffold ts-scripts

Chapter 5: dApp Front-End Development and Wallet Integration

Objective: Use @evefrontier/dapp-kit to build a front-end dApp that can connect to EVE Vault wallet, read on-chain data, and execute transactions.

Status: Foundation chapter. Main text focuses on wallet integration, front-end state reading, and transaction initiation.

5.1 The Role of dApp in EVE Frontier

After completing Move contract development, players need an interface to interact with your facilities. The dApp (decentralized application) is that interface, it can:

• Display real-time status of your smart assemblies (inventory, online status, etc.)
• Let players connect EVE Vault wallet
• Trigger on-chain transactions through UI (purchase items, apply for jump permits, etc.)
• Run in standard web browsers without downloading game client

Two Usage Scenarios

Many people misunderstand dApps as “wrapping contracts with a front-end skin.” In EVE Frontier, its more accurate role is:

Turn on-chain facilities into service interfaces that players actually want to use.

Because for the same facility, if there’s only a contract without a dApp, players usually lack these key pieces of information:

• What is the current state
• Do I have permission to operate
• How much does the operation cost
• What exactly happened after clicking the button

So dApps aren’t just “presentation layer,” they also bear three very practical responsibilities:

• Explain state Translate object fields into business states players can understand
• Organize transactions Help users assemble complex parameters, object IDs, amounts into a legal transaction
• Handle feedback Tell users whether they’re currently waiting for signature, waiting for on-chain, success, failure, or need to retry

A dApp’s Minimum Working Loop

Regardless of whether you’re making a shop, stargate, or turret console, front-ends basically can’t avoid this loop:

Connect wallet
  -> Read assembly and user state
  -> Determine currently allowed actions
  -> Build transaction
  -> Request signature / Initiate sponsored transaction
  -> Wait for result
  -> Refresh objects and interface

As long as one link in this loop isn’t done well, user experience will break.

5.2 Installing dapp-kit

# Create React project (using Vite as example)
npx create-vite my-dapp --template react-ts
cd my-dapp

# Install EVE Frontier dApp SDK and dependencies
npm install @evefrontier/dapp-kit @tanstack/react-query react

SDK Core Features Overview

5.3 Project Basic Configuration

Configure Provider

All dApp functionality must be wrapped in EveFrontierProvider:

// src/main.tsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { EveFrontierProvider } from '@evefrontier/dapp-kit'
import App from './App'

// React Query client (manage cache)
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 1000, // Refetch after 5 seconds
    }
  }
})

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    {/* EVE Frontier SDK Provider */}
    <EveFrontierProvider queryClient={queryClient}>
      <App />
    </EveFrontierProvider>
  </React.StrictMode>
)

The role of Provider isn’t just “making Hooks work.” It actually helps you uniformly manage three types of contexts:

• Wallet connection context
• On-chain query and cache context
• dApp-kit’s own environment information

So it’s essentially the “operating platform” for the entire dApp. If this layer is misconfigured, many errors that seem like business problems later are actually context not initialized properly.

Bind Assembly Through URL Parameters

dApp knows which assembly to display through URL parameters:

# In-game access:
https://your-dapp.com/?tenant=utopia&itemId=0x1234abcd...

# tenant: Game server instance name (prod/testnet/dev)
# itemId: Assembly's ObjectID on-chain

SDK automatically reads these parameters from URL, you don’t need to handle manually.

The core idea here is:

The same front-end page doesn’t serve a fixed assembly, but dynamically binds current assembly context according to URL.

This has two direct benefits:

• You can reuse the same front-end to serve many facilities
• In-game overlay only needs to pass tenant and itemId in, page will know “who I’m serving now”

Why Are tenant and itemId Both Essential?

• itemId solves “which object is it”
• tenant solves “which world instance it belongs to”

If only passing itemId, in multi-tenant or multi-environment scenarios, it’s easy to read data from wrong world; if only passing tenant, you don’t know which facility object it currently is.

5.4 Core Hooks Explained

Hook 1: useConnection (Wallet Connection State)

import { useConnection } from '@evefrontier/dapp-kit'

function WalletButton() {
  const {
    isConnected,          // boolean: whether wallet connected
    currentAddress,       // string | null: current wallet address
    handleConnect,        // () => void: trigger connection flow
    handleDisconnect,     // () => void: disconnect
  } = useConnection()

  if (!isConnected) {
    return (
      <button onClick={handleConnect} className="connect-btn">
        Connect EVE Vault Wallet
      </button>
    )
  }

  return (
    <div>
      <span>Connected: {currentAddress?.slice(0, 8)}...</span>
      <button onClick={handleDisconnect}>Disconnect</button>
    </div>
  )
}

useConnection solves not simply “can pop up wallet,” but the first layer of state forking for the entire page:

• When wallet not connected, page can only show public information
• When wallet connected but no character, page might need to prompt to initialize identity first
• Only when wallet connected and has character, page can enter real interactive state

Hook 2: useSmartObject (Current Assembly Data)

import { useSmartObject } from '@evefrontier/dapp-kit'

function AssemblyStatus() {
  const {
    assembly,    // Current assembly's complete data (inventory, state, name, etc.)
    loading,     // Whether loading
    error,       // Error message
    refetch,     // Manual refresh
  } = useSmartObject()

  if (loading) return <div className="spinner">Reading on-chain data...</div>
  if (error) return <div className="error">Error: {error.message}</div>

  return (
    <div className="assembly-card">
      <h2>{assembly?.name}</h2>
      <p>Status: {assembly?.status}</p>
      <p>Owner: {assembly?.owner}</p>
    </div>
  )
}

What’s most important here isn’t the Hook name, but developing a habit:

Pages should always center on “on-chain object state,” not on local button state.

In other words, after users click buttons, don’t just set status = success locally on front-end. A more stable approach is:

1. Wait for transaction to return
2. Re-read object
3. Refresh UI with on-chain true state

Otherwise you’ll easily get:

• Front-end thinks it succeeded
• But on-chain object didn’t change
• Page still shows “operation completed”

Hook 3: useNotification (User Notifications)

import { useNotification } from '@evefrontier/dapp-kit'

function ActionButton() {
  const { showNotification } = useNotification()

  const handleAction = async () => {
    try {
      // ... execute transaction ...
      showNotification({ type: 'success', message: 'Transaction successful!' })
    } catch (e) {
      showNotification({ type: 'error', message: 'Transaction failed: ' + e.message })
    }
  }

  return <button onClick={handleAction}>Execute Operation</button>
}

The true value of notification systems isn’t “making a popup,” but breaking on-chain asynchronous processes into stages users can understand:

• Connecting wallet
• Waiting for signature
• On-chain processing
• Confirmed
• Failed, need retry

If you only give users “success / failure,” many complex transactions will seem like black boxes.

5.5 Executing On-Chain Transactions

Standard Transaction (User Pays Gas)

Use useDAppKit from @mysten/dapp-kit-react to execute:

import { useDAppKit } from '@mysten/dapp-kit-react'
import { Transaction } from '@mysten/sui/transactions'

function BuyItemButton({ storageUnitId, typeId }: Props) {
  const dAppKit = useDAppKit()

  const handleBuy = async () => {
    // Build transaction
    const tx = new Transaction()

    tx.moveCall({
      // Call your published extension contract function
      target: `${MY_PACKAGE_ID}::vending_machine::buy_item`,
      arguments: [
        tx.object(storageUnitId),
        tx.object(CHARACTER_ID),
        tx.splitCoins(tx.gas, [tx.pure.u64(100)]),  // Pay 100 SUI
        tx.pure.u64(typeId),
      ],
    })

    // Sign and execute
    try {
      const result = await dAppKit.signAndExecuteTransaction({
        transaction: tx,
      })
      console.log('Transaction successful!', result.digest)
    } catch (e) {
      console.error('Transaction failed', e)
    }
  }

  return <button onClick={handleBuy}>Buy Item</button>
}

What Stages Does a Front-End Transaction Typically Split Into?

From front-end perspective, a transaction splits into at least 5 stages:

1. Prepare parameters Are assembly ID, character ID, amount, type parameters complete
2. Build transaction Assemble objects, pure values, coin split actions, and function entries into Transaction
3. Request signature Have wallet or sponsorship service confirm this transaction
4. Submit execution Transaction truly enters on-chain execution
5. Write back to interface Refresh UI based on digest and latest object state

Many front-end bugs don’t occur at “transaction failed,” but at steps 1 and 5:

• Parameters got wrong object
• Using old cache locally
• Transaction succeeded but page didn’t refresh
• Have digest but object query not updated yet

Sponsored Transaction (Sponsored Tx, Gas-Free)

When operation needs server verification or platform pays Gas:

import { signAndExecuteSponsoredTransaction } from '@evefrontier/dapp-kit'

const result = await signAndExecuteSponsoredTransaction({
  transaction: tx,
  // SDK automatically handles sponsorship logic, communicates with EVE Frontier backend
})

Sponsored transactions have better experience, but longer chain. It typically means:

1. Front-end first builds transaction
2. Request backend to check if sponsorship allowed
3. Backend performs risk control / co-sign / pay
4. User completes necessary signature
5. Transaction then submitted for execution

So once sponsored transactions fail, when troubleshooting you can’t just stare at front-end, need to distinguish which layer the problem is at:

• Front-end built transaction incorrectly
• User qualifications not met
• Backend refused sponsorship
• Wallet signature stage failed
• On-chain execution itself failed

5.6 Reading On-Chain Data (GraphQL)

import {
  getAssemblyWithOwner,
  getObjectWithJson,
  executeGraphQLQuery,
} from '@evefrontier/dapp-kit'

// Get assembly and its owner information
async function loadAssembly(assemblyId: string) {
  const { moveObject, character } = await getAssemblyWithOwner(assemblyId)
  console.log('Assembly data:', moveObject)
  console.log('Owner character:', character)
}

// Custom GraphQL query
async function queryGates() {
  const query = `
    query GetGates($type: String!) {
      objects(filter: { type: $type }, first: 10) {
        nodes {
          address
          asMoveObject { contents { json } }
        }
      }
    }
  `
  const data = await executeGraphQLQuery(query, {
    type: `${WORLD_PACKAGE}::gate::Gate`
  })
  return data
}

Why Can’t Front-End Only Rely on Event Streams?

Because front-end pages typically need “current state,” not just “what historically happened.”

Events are better suited to answer:

• Who did what when
• Whether a certain action occurred
• Used for logs, notifications, timelines

Object queries are better suited to answer:

• What is this facility’s state now
• How much current inventory remains
• Who is current owner
• Whether currently online

So mature dApps are often:

• Use object queries to get current state
• Use event queries to supplement history and timeline

Only relying on events to restore current state usually becomes increasingly fragile.

5.7 Practical Utility Functions

import {
  abbreviateAddress,
  isOwner,
  formatM3,
  formatDuration,
  getTxUrl,
  getDatahubGameInfo,
} from '@evefrontier/dapp-kit'

// Shorten address: 0x1234...cdef
abbreviateAddress('0x1234567890abcdef')

// Check if currently connected wallet is specified object's owner
const isMine = isOwner(assembly, currentAddress)

// Format volume
formatM3(1500)  // "1.5 m³"

// Format time
formatDuration(3661000)  // "1h 1m 1s"

// Get transaction browser link
getTxUrl('HNFaf...')  // Returns Sui Explorer URL

// Get game item metadata (name, icon, etc.)
const info = await getDatahubGameInfo(83463)
console.log(info.name, info.iconUrl)

These utility functions seem like scraps, but they directly determine whether your front-end will seem “like a product rather than a script page.”

For example:

• Addresses not abbreviated, page becomes hard to read
• Amounts and volumes not formatted, players have difficulty judging quickly
• No transaction links, when problems occur users and developers can’t track

Front-end product feel is often piled up by these small functions.

5.8 Complete dApp Example

// src/App.tsx
import { useConnection, useSmartObject, useNotification } from '@evefrontier/dapp-kit'
import { useDAppKit } from '@mysten/dapp-kit-react'
import { Transaction } from '@mysten/sui/transactions'

export default function App() {
  const { isConnected, handleConnect, currentAddress } = useConnection()
  const { assembly, loading } = useSmartObject()
  const { showNotification } = useNotification()
  const dAppKit = useDAppKit()

  const handleJump = async () => {
    if (!isConnected) {
      showNotification({ type: 'warning', message: 'Please connect wallet first' })
      return
    }

    const tx = new Transaction()
    tx.moveCall({
      target: `${MY_PACKAGE}::toll_gate::pay_and_jump`,
      arguments: [
        tx.object(GATE_ID),
        tx.object(DEST_GATE_ID),
        tx.object(CHARACTER_ID),
        tx.splitCoins(tx.gas, [tx.pure.u64(100)]),
      ],
    })

    try {
      await dAppKit.signAndExecuteTransaction({ transaction: tx })
      showNotification({ type: 'success', message: 'Jump successful!' })
    } catch (e: any) {
      showNotification({ type: 'error', message: e.message })
    }
  }

  if (loading) return <div>Loading...</div>

  return (
    <div className="app">
      <header>
        <h1>🌀 Stargate Console</h1>
        {!isConnected
          ? <button onClick={handleConnect}>Connect Wallet</button>
          : <span>✅ {currentAddress?.slice(0, 8)}...</span>
        }
      </header>

      <main>
        <div className="gate-info">
          <h2>{assembly?.name ?? 'Unknown Gate'}</h2>
          <p>Status: {assembly?.status}</p>
        </div>

        <button
          className="jump-btn"
          onClick={handleJump}
          disabled={!isConnected}
        >
          💳 Pay 100 SUI and Jump
        </button>
      </main>
    </div>
  )
}

Although this example is simple, it has completely demonstrated a minimal interaction loop:

• Connect wallet
• Read current assembly
• Build transaction
• Request signature and execute
• Give result notification

In Real Projects Usually Need to Add Three More Layers of State

Example works, but if you want to make it a stable product, usually need to add:

1. Local UI state For example button loading, modal open/close, form input
2. Wallet state Current address, whether authorized, whether switched to wrong network
3. On-chain object state Facility state, inventory, price, current owner

Don’t mix these three layers of state into one layer. They update at different speeds, have different reliability, different troubleshooting methods.

5.9 Embedding dApp in Game

When approaching your assembly in-game, client will load your registered dApp URL in an overlay. Configuration method:

1. Deploy dApp to public URL (like Vercel, Netlify)
2. Set your dApp URL in assembly configuration
3. Game client will automatically open and pass in ?itemId=...&tenant=... parameters when players interact

Related documentation: Connecting In-Game | Customizing External dApps

Biggest Difference Between In-Game Overlay and External Browser

Although both are called dApps, runtime constraints aren’t completely the same:

• In-Game Overlay More like embedded page controlled by host environment, focus is fast, stable, clear parameters, short interaction path
• External Browser More like independent Web application, can accommodate more complete page structure and longer interaction processes

So when making in-game dApps, usually need extra attention to:

• Page first screen must be fast
• Can’t rely on too complex multi-page jumps
• When parameters lost need fallback prompts
• When wallet not connected, character not initialized, facility not online, need clear state pages

🔖 Chapter Summary

📚 Extended Reading

• dapp-kit Complete Documentation
• TypeDoc API Documentation
• Connecting from an External Browser
• @mysten/dapp-kit-react Documentation

Practical Example 1: Whitelisted Mining Zone Guard (Smart Turret Access Control)

Goal: Write a smart turret extension that only allows players holding a “Mining Pass NFT” to pass; build a management interface that enables the Owner to issue passes online.

Status: Mapped to local code directory. The content covers Pass NFT and turret whitelist logic, suitable as a complete Builder closed-loop example.

Corresponding Code Directory

• example-01
• example-01/dapp

Minimal Call Chain

Owner issues pass -> Player holds MiningPass -> Turret extension reads credentials -> Grant passage or fire

Requirements Analysis

Scenario: Your alliance has mined a rare mineral zone in deep space and deployed a smart turret to protect the base. You want to treat different roles differently:

• ✅ Alliance members: Hold MiningPass NFT, turret grants passage
• ❌ Non-members: No MiningPass, turret automatically fires

Additional requirements:

• Owner (you) can issue MiningPass to trusted roles via dApp
• MiningPass can be revoked by Owner
• dApp displays current protection status and pass holder list

Part 1: Move Contract Development

Directory Structure

mining-guard/
├── Move.toml
└── sources/
    ├── mining_pass.move      # NFT definition
    └── guard_extension.move  # Turret extension

Step 1: Define MiningPass NFT

// sources/mining_pass.move
module mining_guard::mining_pass;

use sui::object::{Self, UID};
use sui::tx_context::TxContext;
use sui::transfer;
use sui::event;

/// Mining zone pass NFT
public struct MiningPass has key, store {
    id: UID,
    holder_name: vector<u8>,    // Holder name (for identification)
    issued_at_ms: u64,          // Issue timestamp
    zone_id: u64,               // Which mining zone (supports multiple zones)
}

/// Admin capability (only held by contract deployer)
public struct AdminCap has key, store {
    id: UID,
}

/// Event: New pass issued
public struct PassIssued has copy, drop {
    pass_id: ID,
    recipient: address,
    zone_id: u64,
}

/// Contract initialization: Deployer receives AdminCap
fun init(ctx: &mut TxContext) {
    let admin_cap = AdminCap {
        id: object::new(ctx),
    };
    // Transfer AdminCap to deployer address
    transfer::transfer(admin_cap, ctx.sender());
}

/// Issue mining zone pass (only callable by AdminCap holder)
public fun issue_pass(
    _admin_cap: &AdminCap,             // Verify caller is admin
    recipient: address,                 // Recipient address
    holder_name: vector<u8>,
    zone_id: u64,
    ctx: &mut TxContext,
) {
    let pass = MiningPass {
        id: object::new(ctx),
        holder_name,
        issued_at_ms: ctx.epoch_timestamp_ms(),
        zone_id,
    };

    // Emit event
    event::emit(PassIssued {
        pass_id: object::id(&pass),
        recipient,
        zone_id,
    });

    // Transfer pass to recipient
    transfer::transfer(pass, recipient);
}

/// Revoke pass
/// Owner can destroy a specific role's pass via admin_cap
/// (Actually, you can design "recall + destroy", here simplified to let holder burn it themselves)
public fun revoke_pass(
    _admin_cap: &AdminCap,
    pass: MiningPass,
) {
    let MiningPass { id, .. } = pass;
    id.delete();
}

/// Check if pass belongs to a specific zone
public fun is_valid_for_zone(pass: &MiningPass, zone_id: u64): bool {
    pass.zone_id == zone_id
}

Step 2: Write Turret Extension

// sources/guard_extension.move
module mining_guard::guard_extension;

use mining_guard::mining_pass::{Self, MiningPass};
use world::turret::{Self, Turret};
use world::character::Character;
use sui::tx_context::TxContext;

/// Turret extension Witness type
public struct GuardAuth has drop {}

/// Protected zone ID (this version protects zone 1)
const PROTECTED_ZONE_ID: u64 = 1;

/// Request safe passage (player with pass is allowed by turret)
///
/// Note: The actual turret's "no-fire" logic is executed by the game server,
/// this contract is used to verify and record the permission intent
public fun request_safe_passage(
    turret: &mut Turret,
    character: &Character,
    pass: &MiningPass,           // Must hold pass
    ctx: &mut TxContext,
) {
    // Verify pass belongs to correct zone
    assert!(
        mining_pass::is_valid_for_zone(pass, PROTECTED_ZONE_ID),
        0  // Error code: Invalid zone pass
    );

    // Call turret's safe passage function, pass GuardAuth{} as extension credential
    // (Actual API depends on world contract)
    turret::grant_safe_passage(
        turret,
        character,
        GuardAuth {},
        ctx,
    );
}

Step 3: Compile and Publish

cd mining-guard

# Compile check
sui move build

# Publish to testnet
sui client publish

# Record output:
# Package ID: 0x_YOUR_PACKAGE_ID_
# AdminCap Object ID: 0x_YOUR_ADMIN_CAP_

Step 4: Register Extension to Turret

// scripts/register-extension.ts
import { Transaction } from "@mysten/sui/transactions";
import { SuiClient } from "@mysten/sui/client";
import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";

const WORLD_PACKAGE = "0x...";
const MY_PACKAGE = "0x_YOUR_PACKAGE_ID_";
const TURRET_ID = "0x...";
const CHARACTER_ID = "0x...";
const OWNER_CAP_ID = "0x...";

async function registerExtension() {
  const client = new SuiClient({ url: "https://fullnode.testnet.sui.io:443" });
  const keypair = Ed25519Keypair.fromSecretKey(/* your key */);

  const tx = new Transaction();

  // 1. Borrow turret's OwnerCap from character
  const [ownerCap] = tx.moveCall({
    target: `${WORLD_PACKAGE}::character::borrow_owner_cap`,
    typeArguments: [`${WORLD_PACKAGE}::turret::Turret`],
    arguments: [tx.object(CHARACTER_ID), tx.object(OWNER_CAP_ID)],
  });

  // 2. Register our extension
  tx.moveCall({
    target: `${WORLD_PACKAGE}::turret::authorize_extension`,
    typeArguments: [`${MY_PACKAGE}::guard_extension::GuardAuth`],
    arguments: [tx.object(TURRET_ID), ownerCap],
  });

  // 3. Return OwnerCap
  tx.moveCall({
    target: `${WORLD_PACKAGE}::character::return_owner_cap`,
    typeArguments: [`${WORLD_PACKAGE}::turret::Turret`],
    arguments: [tx.object(CHARACTER_ID), ownerCap],
  });

  const result = await client.signAndExecuteTransaction({
    signer: keypair,
    transaction: tx,
  });
  console.log("Extension registration successful! Tx:", result.digest);
}

registerExtension();

Part 2: Admin dApp

Feature: Pass Issuance Interface

// src/AdminPanel.tsx
import { useState } from 'react'
import { useDAppKit } from '@mysten/dapp-kit-react'
import { useConnection } from '@evefrontier/dapp-kit'
import { Transaction } from '@mysten/sui/transactions'

const MY_PACKAGE = "0x_YOUR_PACKAGE_ID_"
const ADMIN_CAP_ID = "0x_YOUR_ADMIN_CAP_"

export function AdminPanel() {
  const { isConnected, handleConnect } = useConnection()
  const dAppKit = useDAppKit()
  const [recipient, setRecipient] = useState('')
  const [holderName, setHolderName] = useState('')
  const [status, setStatus] = useState('')

  const issuePass = async () => {
    if (!recipient || !holderName) {
      setStatus('❌ Please fill in recipient address and name')
      return
    }

    const tx = new Transaction()
    tx.moveCall({
      target: `${MY_PACKAGE}::mining_pass::issue_pass`,
      arguments: [
        tx.object(ADMIN_CAP_ID),
        tx.pure.address(recipient),
        tx.pure.vector('u8', Array.from(new TextEncoder().encode(holderName))),
        tx.pure.u64(1), // Zone ID
      ],
    })

    try {
      setStatus('⏳ Submitting transaction...')
      const result = await dAppKit.signAndExecuteTransaction({ transaction: tx })
      setStatus(`✅ Pass issued! Tx: ${result.digest.slice(0, 12)}...`)
    } catch (e: any) {
      setStatus(`❌ Failed: ${e.message}`)
    }
  }

  if (!isConnected) {
    return (
      <div className="admin-panel">
        <button onClick={handleConnect}>🔗 Connect Admin Wallet</button>
      </div>
    )
  }

  return (
    <div className="admin-panel">
      <h2>🛡 Mining Pass Management</h2>

      <div className="form-group">
        <label>Recipient Sui Address</label>
        <input
          value={recipient}
          onChange={e => setRecipient(e.target.value)}
          placeholder="0x..."
        />
      </div>

      <div className="form-group">
        <label>Holder Name</label>
        <input
          value={holderName}
          onChange={e => setHolderName(e.target.value)}
          placeholder="Mining Corp Alpha"
        />
      </div>

      <button className="issue-btn" onClick={issuePass}>
        📜 Issue Mining Pass
      </button>

      {status && <p className="status">{status}</p>}
    </div>
  )
}

Part 3: Player dApp

// src/PlayerPanel.tsx
import { useConnection, useSmartObject } from '@evefrontier/dapp-kit'
import { useDAppKit } from '@mysten/dapp-kit-react'
import { Transaction } from '@mysten/sui/transactions'

const MY_PACKAGE = "0x_YOUR_PACKAGE_ID_"
const TURRET_ID = "0x..."
const CHARACTER_ID = "0x..."

export function PlayerPanel() {
  const { isConnected, handleConnect } = useConnection()
  const { assembly, loading } = useSmartObject()
  const dAppKit = useDAppKit()
  const [passId, setPassId] = useState('')
  const [status, setStatus] = useState('')

  const requestPassage = async () => {
    const tx = new Transaction()
    tx.moveCall({
      target: `${MY_PACKAGE}::guard_extension::request_safe_passage`,
      arguments: [
        tx.object(TURRET_ID),
        tx.object(CHARACTER_ID),
        tx.object(passId),  // Player's MiningPass Object ID
      ],
    })

    try {
      await dAppKit.signAndExecuteTransaction({ transaction: tx })
      setStatus('✅ Safe passage recorded, turret will grant access')
    } catch (e: any) {
      setStatus('❌ Pass verification failed, cannot enter mining zone')
    }
  }

  if (!isConnected) return <button onClick={handleConnect}>Connect Wallet</button>
  if (loading) return <div>Loading turret status...</div>

  return (
    <div className="player-panel">
      <h2>⚡ {assembly?.name ?? 'Mining Zone Guard Turret'}</h2>
      <p>Status: {assembly?.status}</p>

      <div className="pass-input">
        <label>Enter your Mining Pass Object ID</label>
        <input
          value={passId}
          onChange={e => setPassId(e.target.value)}
          placeholder="0x..."
        />
        <button onClick={requestPassage}>🛡 Request Safe Passage</button>
      </div>

      {status && <p>{status}</p>}
    </div>
  )
}

🎯 Complete Implementation Review

1. Move Contracts
   ├── mining_pass.move → Define MiningPass NFT + AdminCap + issue_pass / revoke_pass
   └── guard_extension.move → Turret extension + request_safe_passage (verify pass then call turret API)

2. Registration Flow
   └── authorize_extension<GuardAuth>(turret, owner_cap)

3. Admin dApp
   └── Enter address and name → Call issue_pass → Transfer NFT to target role

4. Player dApp
   └── Enter pass ID → Call request_safe_passage → Turret passage record on-chain

🔧 Extension Exercises

1. Add expiration time to MiningPass, turret denies passage after expiration
2. Record all active passes in contract for dApp query and display
3. Implement “team license”: one pass can be used by multiple predefined members

📚 Related Documentation

• Smart Turret Documentation
• Chapter 3: Move Security Patterns
• Chapter 4: Register Extensions to Components

Practical Example 2: Space Highway Toll Station (Smart Stargate Toll System)

Goal: Write a smart stargate extension that charges LUX tokens per jump; build a player-facing ticket purchase dApp interface.

Status: Mapped to local code directory. The content covers toll stargate, tickets, and treasury triple set, one of the most typical Builder commercialization examples.

Corresponding Code Directory

• example-02
• example-02/dapp

Minimal Call Chain

Player pays toll -> Treasury receives payment -> Mint JumpTicket -> Stargate verifies ticket -> Complete jump

Requirements Analysis

Scenario: You and your alliance control a strategic corridor consisting of two stargates, connecting two busy regions of the universe. You decide to commercialize this route:

• 🎟 Any player wanting to jump must pay 50 LUX to purchase a JumpTicket
• 🏦 All collected LUX goes into the treasury (contract-managed shared object)
• 💰 Only the Owner (you) can withdraw LUX from the treasury
• 📊 dApp displays current ticket price, jump count, and treasury balance in real-time

Part 1: Move Contract Development

Directory Structure

toll-gate/
├── Move.toml
└── sources/
    ├── treasury.move       # Treasury: Collect and manage LUX
    └── toll_gate.move      # Stargate extension: Toll logic

Step 1: Define Treasury Contract

// sources/treasury.move
module toll_gate::treasury;

use sui::object::{Self, UID};
use sui::balance::{Self, Balance};
use sui::coin::{Self, Coin};
use sui::sui::SUI;
use sui::tx_context::TxContext;
use sui::transfer;
use sui::event;

// ── Type Definitions ─────────────────────────────────────────────

/// Here we use SUI token to represent LUX (demo)
/// In actual deployment, replace with LUX Coin type

/// Treasury: Collect all tolls
public struct TollTreasury has key {
    id: UID,
    balance: Balance<SUI>,
    total_jumps: u64,      // Total jump count (for statistics)
    toll_amount: u64,      // Current ticket price (in MIST, 1 SUI = 10^9 MIST)
}

/// OwnerCap: Only holders can withdraw treasury funds
public struct TreasuryOwnerCap has key, store {
    id: UID,
}

// ── Events ──────────────────────────────────────────────────

public struct TollCollected has copy, drop {
    payer: address,
    amount: u64,
    total_jumps: u64,
}

public struct TollWithdrawn has copy, drop {
    recipient: address,
    amount: u64,
}

// ── Initialization ────────────────────────────────────────────────

fun init(ctx: &mut TxContext) {
    // Create treasury (shared object, anyone can deposit)
    let treasury = TollTreasury {
        id: object::new(ctx),
        balance: balance::zero(),
        total_jumps: 0,
        toll_amount: 50_000_000_000,  // 50 SUI (unit: MIST)
    };

    // Create Owner credential (transfer to deployer)
    let owner_cap = TreasuryOwnerCap {
        id: object::new(ctx),
    };

    transfer::share_object(treasury);
    transfer::transfer(owner_cap, ctx.sender());
}

// ── Public Functions ──────────────────────────────────────────────

/// Deposit toll (called by stargate extension)
public fun deposit_toll(
    treasury: &mut TollTreasury,
    payment: Coin<SUI>,
    payer: address,
) {
    let amount = coin::value(&payment);

    // Verify correct amount
    assert!(amount >= treasury.toll_amount, 1); // E_INSUFFICIENT_FEE

    treasury.total_jumps = treasury.total_jumps + 1;
    balance::join(&mut treasury.balance, coin::into_balance(payment));

    event::emit(TollCollected {
        payer,
        amount,
        total_jumps: treasury.total_jumps,
    });
}

/// Withdraw treasury LUX (only callable by TreasuryOwnerCap holder)
public fun withdraw(
    treasury: &mut TollTreasury,
    _cap: &TreasuryOwnerCap,
    amount: u64,
    ctx: &mut TxContext,
) {
    let coin = coin::take(&mut treasury.balance, amount, ctx);
    transfer::public_transfer(coin, ctx.sender());

    event::emit(TollWithdrawn {
        recipient: ctx.sender(),
        amount,
    });
}

/// Change ticket price (Owner calls)
public fun set_toll_amount(
    treasury: &mut TollTreasury,
    _cap: &TreasuryOwnerCap,
    new_amount: u64,
) {
    treasury.toll_amount = new_amount;
}

/// Read current ticket price
public fun toll_amount(treasury: &TollTreasury): u64 {
    treasury.toll_amount
}

/// Read treasury balance
public fun balance_amount(treasury: &TollTreasury): u64 {
    balance::value(&treasury.balance)
}

Step 2: Write Stargate Extension

// sources/toll_gate.move
module toll_gate::toll_gate_ext;

use toll_gate::treasury::{Self, TollTreasury};
use world::gate::{Self, Gate};
use world::character::Character;
use sui::coin::Coin;
use sui::sui::SUI;
use sui::clock::Clock;
use sui::tx_context::TxContext;

/// Stargate extension Witness type
public struct TollAuth has drop {}

/// Default jump permit validity: 15 minutes
const PERMIT_DURATION_MS: u64 = 15 * 60 * 1000;

/// Pay toll and get jump permit
public fun pay_toll_and_get_permit(
    source_gate: &Gate,
    destination_gate: &Gate,
    character: &Character,
    treasury: &mut TollTreasury,
    payment: Coin<SUI>,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    // 1. Collect toll
    treasury::deposit_toll(treasury, payment, ctx.sender());

    // 2. Calculate Permit expiration time
    let expires_at = clock.timestamp_ms() + PERMIT_DURATION_MS;

    // 3. Request jump permit from stargate (TollAuth{} is extension credential)
    gate::issue_jump_permit(
        source_gate,
        destination_gate,
        character,
        TollAuth {},
        expires_at,
        ctx,
    );

    // Note: JumpPermit object is automatically transferred to character's Owner
}

Step 3: Publish Contract

cd toll-gate

sui move build

sui client publish

# Record:
# Package ID: 0x_TOLL_PACKAGE_
# TollTreasury ID: 0x_TREASURY_ID_ (shared object)
# TreasuryOwnerCap ID: 0x_OWNER_CAP_ID_

Step 4: Register Extension to Stargate

// scripts/authorize-toll-gate.ts
import { Transaction } from "@mysten/sui/transactions";
import { SuiClient } from "@mysten/sui/client";

const WORLD_PACKAGE = "0x...";
const TOLL_PACKAGE = "0x_TOLL_PACKAGE_";
const GATE_ID = "0x...";
const CHARACTER_ID = "0x...";
const GATE_OWNER_CAP_ID = "0x...";

async function authorizeTollGate() {
  const client = new SuiClient({ url: "https://fullnode.testnet.sui.io:443" });
  const tx = new Transaction();

  // Borrow stargate OwnerCap
  const [ownerCap] = tx.moveCall({
    target: `${WORLD_PACKAGE}::character::borrow_owner_cap`,
    typeArguments: [`${WORLD_PACKAGE}::gate::Gate`],
    arguments: [tx.object(CHARACTER_ID), tx.object(GATE_OWNER_CAP_ID)],
  });

  // Register TollAuth as authorized extension
  tx.moveCall({
    target: `${WORLD_PACKAGE}::gate::authorize_extension`,
    typeArguments: [`${TOLL_PACKAGE}::toll_gate_ext::TollAuth`],
    arguments: [tx.object(GATE_ID), ownerCap],
  });

  // Return OwnerCap
  tx.moveCall({
    target: `${WORLD_PACKAGE}::character::return_owner_cap`,
    typeArguments: [`${WORLD_PACKAGE}::gate::Gate`],
    arguments: [tx.object(CHARACTER_ID), ownerCap],
  });

  const result = await client.signAndExecuteTransaction({
    signer: keypair,
    transaction: tx,
  });
  console.log("Toll station extension registered successfully!", result.digest);
}

Part 2: Player Ticket Purchase dApp

Complete Ticket Purchase Interface

// src/TollGateApp.tsx
import { useState, useEffect } from 'react'
import { useConnection, useSmartObject, getObjectWithJson } from '@evefrontier/dapp-kit'
import { useDAppKit } from '@mysten/dapp-kit-react'
import { Transaction } from '@mysten/sui/transactions'

const WORLD_PACKAGE = "0x..."
const TOLL_PACKAGE = "0x_TOLL_PACKAGE_"
const SOURCE_GATE_ID = "0x..."
const DEST_GATE_ID = "0x..."
const CHARACTER_ID = "0x..."
const TREASURY_ID = "0x_TREASURY_ID_"

interface TreasuryData {
  toll_amount: string
  total_jumps: string
  balance: string
}

export function TollGateApp() {
  const { isConnected, handleConnect, currentAddress } = useConnection()
  const { assembly, loading } = useSmartObject()
  const dAppKit = useDAppKit()

  const [treasury, setTreasury] = useState<TreasuryData | null>(null)
  const [txStatus, setTxStatus] = useState('')
  const [isPaying, setIsPaying] = useState(false)

  // Load treasury data
  const loadTreasury = async () => {
    const data = await getObjectWithJson(TREASURY_ID)
    if (data?.content?.dataType === 'moveObject') {
      setTreasury(data.content.fields as TreasuryData)
    }
  }

  useEffect(() => {
    loadTreasury()
    const interval = setInterval(loadTreasury, 10_000) // Refresh every 10 seconds
    return () => clearInterval(interval)
  }, [])

  const payAndJump = async () => {
    if (!isConnected) {
      setTxStatus('❌ Please connect wallet first')
      return
    }

    setIsPaying(true)
    setTxStatus('⏳ Submitting transaction...')

    const tollAmount = BigInt(treasury?.toll_amount ?? 50_000_000_000)
    const tx = new Transaction()

    // Split out ticket price amount of SUI
    const [paymentCoin] = tx.splitCoins(tx.gas, [
      tx.pure.u64(tollAmount)
    ])

    // Call toll and get Permit
    tx.moveCall({
      target: `${TOLL_PACKAGE}::toll_gate_ext::pay_toll_and_get_permit`,
      arguments: [
        tx.object(SOURCE_GATE_ID),
        tx.object(DEST_GATE_ID),
        tx.object(CHARACTER_ID),
        tx.object(TREASURY_ID),
        paymentCoin,
        tx.object('0x6'), // Clock system object
      ],
    })

    try {
      const result = await dAppKit.signAndExecuteTransaction({
        transaction: tx,
      })
      setTxStatus(`✅ Jump permit obtained! Tx: ${result.digest.slice(0, 12)}...`)
      loadTreasury() // Refresh treasury data
    } catch (e: any) {
      setTxStatus(`❌ ${e.message}`)
    } finally {
      setIsPaying(false)
    }
  }

  const tollInSui = treasury
    ? (Number(treasury.toll_amount) / 1e9).toFixed(2)
    : '...'

  const balanceInSui = treasury
    ? (Number(treasury.balance) / 1e9).toFixed(2)
    : '...'

  return (
    <div className="toll-gate-app">
      {/* Stargate Info */}
      <header className="gate-header">
        <div className="gate-icon">🌀</div>
        <div>
          <h1>{loading ? '...' : assembly?.name ?? 'Stargate'}</h1>
          <span className={`status-badge ${assembly?.status?.toLowerCase()}`}>
            {assembly?.status ?? 'Detecting...'}
          </span>
        </div>
      </header>

      {/* Toll Info */}
      <section className="toll-info">
        <div className="info-card">
          <span className="label">💰 Current Price</span>
          <span className="value">{tollInSui} SUI</span>
        </div>
        <div className="info-card">
          <span className="label">🚀 Total Jumps</span>
          <span className="value">{treasury?.total_jumps ?? '...'} times</span>
        </div>
        <div className="info-card">
          <span className="label">🏦 Treasury Balance</span>
          <span className="value">{balanceInSui} SUI</span>
        </div>
      </section>

      {/* Jump Action */}
      <section className="jump-section">
        {!isConnected ? (
          <button className="connect-btn" onClick={handleConnect}>
            🔗 Connect EVE Vault Wallet
          </button>
        ) : (
          <>
            <div className="wallet-info">
              ✅ {currentAddress?.slice(0, 6)}...{currentAddress?.slice(-4)}
            </div>
            <button
              className="jump-btn"
              onClick={payAndJump}
              disabled={isPaying || assembly?.status !== 'Online'}
            >
              {isPaying ? '⏳ Processing...' : `🛸 Pay ${tollInSui} SUI and Jump`}
            </button>
          </>
        )}

        {txStatus && (
          <div className={`tx-status ${txStatus.startsWith('✅') ? 'success' : 'error'}`}>
            {txStatus}
          </div>
        )}
      </section>

      {/* Destination Info */}
      <section className="destination-info">
        <p>📍 Destination: <strong>Alpha Centauri Mining Zone</strong></p>
        <p>⏱ Permit Validity: <strong>15 minutes</strong></p>
      </section>
    </div>
  )
}

Part 3: Owner Management Panel

// src/OwnerPanel.tsx
import { useDAppKit } from '@mysten/dapp-kit-react'
import { Transaction } from '@mysten/sui/transactions'

const TOLL_PACKAGE = "0x_TOLL_PACKAGE_"
const TREASURY_ID = "0x_TREASURY_ID_"
const OWNER_CAP_ID = "0x_OWNER_CAP_ID_"

export function OwnerPanel({ treasuryBalance }: { treasuryBalance: number }) {
  const dAppKit = useDAppKit()
  const [withdrawAmount, setWithdrawAmount] = useState('')
  const [newToll, setNewToll] = useState('')
  const [status, setStatus] = useState('')

  const withdraw = async () => {
    const amountMist = Math.floor(parseFloat(withdrawAmount) * 1e9)

    const tx = new Transaction()
    tx.moveCall({
      target: `${TOLL_PACKAGE}::treasury::withdraw`,
      arguments: [
        tx.object(TREASURY_ID),
        tx.object(OWNER_CAP_ID),
        tx.pure.u64(amountMist),
      ],
    })

    try {
      await dAppKit.signAndExecuteTransaction({ transaction: tx })
      setStatus(`✅ Withdrawn ${withdrawAmount} SUI`)
    } catch (e: any) {
      setStatus(`❌ ${e.message}`)
    }
  }

  const updateToll = async () => {
    const amountMist = Math.floor(parseFloat(newToll) * 1e9)

    const tx = new Transaction()
    tx.moveCall({
      target: `${TOLL_PACKAGE}::treasury::set_toll_amount`,
      arguments: [
        tx.object(TREASURY_ID),
        tx.object(OWNER_CAP_ID),
        tx.pure.u64(amountMist),
      ],
    })

    try {
      await dAppKit.signAndExecuteTransaction({ transaction: tx })
      setStatus(`✅ Ticket price updated to ${newToll} SUI`)
    } catch (e: any) {
      setStatus(`❌ ${e.message}`)
    }
  }

  return (
    <div className="owner-panel">
      <h2>⚙️ Toll Station Management</h2>

      <div className="panel-section">
        <h3>💵 Withdraw Revenue</h3>
        <p>Treasury Balance: {(treasuryBalance / 1e9).toFixed(2)} SUI</p>
        <input
          type="number"
          value={withdrawAmount}
          onChange={e => setWithdrawAmount(e.target.value)}
          placeholder="Withdraw amount (SUI)"
        />
        <button onClick={withdraw}>Withdraw to Wallet</button>
      </div>

      <div className="panel-section">
        <h3>🏷 Adjust Price</h3>
        <input
          type="number"
          value={newToll}
          onChange={e => setNewToll(e.target.value)}
          placeholder="New price (SUI)"
        />
        <button onClick={updateToll}>Update Price</button>
      </div>

      {status && <p className="status">{status}</p>}
    </div>
  )
}

🎯 Complete Implementation Review

Move Contract Layer
├── treasury.move
│   ├── TollTreasury (shared treasury object)
│   ├── TreasuryOwnerCap (withdrawal credential)
│   ├── deposit_toll()      ← Extension calls
│   ├── withdraw()          ← Owner calls
│   └── set_toll_amount()   ← Owner calls
│
└── toll_gate_ext.move
    ├── TollAuth (Witness type)
    └── pay_toll_and_get_permit()  ← Player calls
        ├── 1. Verify and charge → treasury.deposit_toll()
        └── 2. Issue permit → gate::issue_jump_permit()

dApp Layer
├── TollGateApp.tsx       → Player ticket purchase interface
│   ├── Real-time display of price, jump count, treasury balance
│   └── One-click payment and get JumpPermit
└── OwnerPanel.tsx        → Admin panel
    ├── Withdraw treasury revenue
    └── Adjust ticket price

🔧 Extension Exercises

1. Tiered Membership: Alliance members holding membership NFT get discounts (check NFT then apply different prices)
2. Limited-Time Free Passage: Automatically accept 0 LUX Permits during specific time periods (e.g., maintenance)
3. Revenue Distribution: Treasury revenue automatically distributed to multiple alliance stakeholder addresses by proportion
4. History dApp: Listen to TollCollected events, display recent 50 jump records

📚 Related Documentation

• Smart Gate Documentation
• Interfacing with the World
• Chapter 3: Move Resources and Coin Model
• Chapter 5: dApp Initiating On-Chain Transactions
• builder-scaffold Smart Gate Example

Chapter 6: Complete Guide to Builder Scaffold (Part 1) — Project Structure and Contract Development

Learning Objectives: Master the complete directory structure of builder-scaffold, understand both Docker and native development workflows, and be able to independently complete local development and deployment of the smart_gate contract.

Status: Mapped to local scaffold directory. Commands in this text are based on the existing builder-scaffold directory in this repository.

Minimal Call Chain

Start local chain -> Compile smart_gate -> Deploy -> Record package/object id -> Configure rules -> Issue permit

Corresponding Code Directory

• builder-scaffold

1. What is Builder Scaffold?

builder-scaffold is the official one-stop Builder development scaffold provided by EVE Frontier, including:

• Move Contract Templates: Two complete Smart Gate Extension examples
• TypeScript Interaction Scripts: Ready-to-use on-chain interaction scripts after deployment
• Docker Development Environment: Zero-configuration, out-of-the-box local chain
• dApp Template: React + EVE Frontier dapp-kit frontend starting point

builder-scaffold/
├── docker/             # Docker dev environment (Sui CLI + Node.js container)
├── move-contracts/     # Move contract examples
│   ├── smart_gate/     # Main example: Star Gate Extension
│   ├── storage_unit/   # Storage Unit Extension example
│   └── tokens/         # Token contract example
├── ts-scripts/         # TypeScript interaction scripts
│   ├── smart_gate/     # 6 operation scripts for smart_gate
│   ├── utils/          # Common utilities: env config, derive-object-id, proof
│   └── helpers/        # Helper functions for querying OwnerCap, etc.
├── dapps/              # React dApp template (EVE Frontier dapp-kit)
└── docs/               # Complete deployment flow documentation

The most important thing about this chapter isn’t memorizing the directory structure, but understanding:

builder-scaffold isn’t just an example repository; it’s actually pre-wiring “local chain, contracts, scripts, and frontend” together for you.

So the real value is:

• Reducing the cost of getting the full loop working for the first time
• Giving you a standard skeleton that can be modified and run iteratively
• Making future custom development start from “modifying templates” rather than “building the platform yourself”

2. Choosing a Development Workflow

The official documentation supports two workflows:

The Real Trade-offs of These Two Workflows

• Docker More stable, fewer environment differences, suitable for getting it working first
• Host Faster, closer to daily development, but more dependent on your local environment being clean

If your goal is to “understand the complete loop first”, prioritize Docker. If your goal is “high-frequency iteration writing your own code”, you’ll typically gradually transition to Host.

3. Docker Development Environment (Recommended for Beginners)

Quick Start

# Clone the repository
git clone https://github.com/evefrontier/builder-scaffold.git
cd builder-scaffold

# Start the development container (first time will download images, ~2-3 minutes)
cd docker
docker compose run --rm --service-ports sui-dev

On first startup, the container will automatically:

1. Create 3 ed25519 key pairs (ADMIN, PLAYER_A, PLAYER_B)
2. Start the local Sui node
3. Fund accounts with test SUI

Keys are persistently saved in Docker Volume and won’t be lost when the container restarts.

Working Directory Structure Inside Container

/workspace/
├── builder-scaffold/    # Complete repository (synced with host)
└── world-contracts/     # Visible in container after cloning on host

Edit files on the host, run commands in the container — both are synced in real-time.

Why Use -e testnet When Building?

sui move build -e testnet   # ← The testnet here is "build environment", not deployment target

The local chain’s chain ID changes every restart and can’t be fixed in Move.toml. -e testnet lets dependency resolution use testnet rules, but actual deployment still goes to the local chain.

The most easily misunderstood part here is conflating “build environment” with “deployment target” as the same thing.

Using -e testnet here doesn’t mean you’re actually deploying to testnet now, but rather tells the builder:

• By which set of rules should dependencies be resolved
• How should package builds be processed according to which environment conventions

If this concept isn’t separated, later when switching between localnet / testnet / mainnet, you’ll be very prone to making incorrect judgments.

Container Common Commands Reference

PostgreSQL + GraphQL Indexer

The Docker environment has built-in Sui indexer and GraphQL support:

# Query chain ID (verify GraphQL startup)
curl -X POST http://localhost:9125/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ chainIdentifier }"}'

GraphQL endpoint: http://localhost:9125/graphql (can be debugged with Altair)

4. Smart Gate Contract File Structure

move-contracts/smart_gate/
├── Move.toml                # Package config (depends on world-contracts)
├── sources/
│   ├── config.move          # Shared config foundation: ExtensionConfig + AdminCap + XAuth
│   ├── tribe_permit.move    # Example 1: Tribal identity verification pass
│   └── corpse_gate_bounty.move # Example 2: Submit corpse items for pass
└── tests/
    └── gate_tests.move      # Tests

Move.toml Analysis

[package]
name = "smart_gate"
edition = "2024"

[dependencies]
# Git dependency (recommended to lock stable tag)
world = { git = "https://github.com/evefrontier/world-contracts.git", subdir = "contracts/world", rev = "v0.0.14" }

[addresses]
smart_gate = "0x0"   # Automatically replaced with actual address on deployment

Important: It’s recommended to use git dependencies and lock the rev (e.g., v0.0.14), don’t track main, otherwise breaking changes in the world-contracts main branch will directly affect compilation results.

Why the Scaffold Example Is Best for Learning “Extension Pattern”

Because it’s not an abstract demo, but rather puts several key Builder elements in:

• Dynamic field configuration
• AdminCap management
• Typed Witness extension
• Gate component integration

In other words, smart_gate isn’t teaching you to write a specific business case, but teaching you the core extension skeleton of EVE Builder.

5. config.move: Extension Base Framework

module smart_gate::config;

use sui::dynamic_field as df;

/// Automatically created after deployment, shared storage for all rules
public struct ExtensionConfig has key {
    id: UID,
}

/// Admin permission credential (transferred to deployer on init)
public struct AdminCap has key, store {
    id: UID,
}

/// Authorization witness type (Typed Witness), passed to gate::issue_jump_permit<XAuth>
public struct XAuth has drop {}

fun init(ctx: &mut TxContext) {
    // Transfer AdminCap to deployer
    transfer::transfer(AdminCap { id: object::new(ctx) }, ctx.sender());
    // Share ExtensionConfig (everyone can read, only AdminCap holders can write)
    transfer::share_object(ExtensionConfig { id: object::new(ctx) });
}

Dynamic Field Rules System

ExtensionConfig uses dynamic fields to store various rules, allowing a single config object to support multiple different extension rules simultaneously:

// set_rule: Insert or overwrite rule (value needs drop ability)
public fun set_rule<K: copy + drop + store, V: store + drop>(
    config: &mut ExtensionConfig,
    _: &AdminCap,      // Only AdminCap can set
    key: K,
    value: V,
) {
    if (df::exists_(&config.id, copy key)) {
        let _old: V = df::remove(&mut config.id, copy key);
    };
    df::add(&mut config.id, key, value);
}

6. tribe_permit.move: Tribal Pass (Detailed Reading)

This is the simplest Extension implementation, suitable for understanding the core structure of the extension pattern:

module smart_gate::tribe_permit;

// Rule configuration (dynamic field value)
public struct TribeConfig has drop, store {
    tribe: u32,              // Allowed tribe ID
    expiry_duration_ms: u64, // Pass validity period (milliseconds)
}

// Rule identifier (dynamic field Key)
public struct TribeConfigKey has copy, drop, store {}

Issuing a Pass

pub fun issue_jump_permit(
    extension_config: &ExtensionConfig,
    source_gate: &Gate,
    destination_gate: &Gate,
    character: &Character,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    // 1. Read rule configuration
    let tribe_cfg = extension_config.borrow_rule<TribeConfigKey, TribeConfig>(TribeConfigKey {});

    // 2. Verify character tribe
    assert!(character.tribe() == tribe_cfg.tribe, ENotStarterTribe);

    // 3. Calculate expiry time (overflow check)
    let ts = clock.timestamp_ms();
    assert!(ts <= (0xFFFFFFFFFFFFFFFFu64 - tribe_cfg.expiry_duration_ms), EExpiryOverflow);
    let expires_at = ts + tribe_cfg.expiry_duration_ms;

    // 4. Call world contract to issue JumpPermit NFT
    gate::issue_jump_permit<XAuth>(
        source_gate, destination_gate, character,
        config::x_auth(),  // Package-unique XAuth instance
        expires_at, ctx,
    );
}

Design Detail: Compared to the original in world-contracts, this adds overflow checking (EExpiryOverflow), making it a more robust production implementation.

Admin Rule Setting

pub fun set_tribe_config(
    extension_config: &mut ExtensionConfig,
    admin_cap: &AdminCap,
    tribe: u32,
    expiry_duration_ms: u64,
) {
    extension_config.set_rule<TribeConfigKey, TribeConfig>(
        admin_cap,
        TribeConfigKey {},
        TribeConfig { tribe, expiry_duration_ms },
    );
}

7. Compilation and Testing

# Enter smart_gate directory
cd move-contracts/smart_gate

# Compile (use testnet as build environment)
sui move build -e testnet

# Run tests
sui move test -e testnet

Common Compilation Failure Issues

8. Publishing Contract to Local Chain

# Ensure world-contracts is deployed, obtaining its publication file
sui client test-publish \
  --build-env testnet \
  --pubfile-path ../../deployments/Pub.localnet.toml

# After successful publication, record the output Package ID
# Fill in BUILDER_PACKAGE_ID in .env file

test-publish vs publish: test-publish is Sui’s special publish mode that allows publishing packages with unpublished dependencies on the local chain (for testing). For actual deployment to testnet/mainnet, use sui client publish.

9. Adding Your Own Extension Rules

Using the example of adding a “toll gate rule”:

Step 1: Create a new file toll_gate.move alongside config.move

module smart_gate::toll_gate;

use smart_gate::config::{Self, AdminCap, XAuth, ExtensionConfig};
use sui::coin::{Self, Coin};
use sui::sui::SUI;
use sui::balance::{Self, Balance};

// Rule data
public struct TollConfig has drop, store {
    toll_amount: u64,
    expiry_duration_ms: u64,
}
public struct TollConfigKey has copy, drop, store {}

// Fee ledger (shared object)
public struct TollVault has key {
    id: UID,
    balance: Balance<SUI>,
}

// Create vault on initialization
public fun create_vault(ctx: &mut TxContext) {
    transfer::share_object(TollVault {
        id: object::new(ctx),
        balance: balance::zero(),
    });
}

Step 2: Implement Issuance Function

pub fun pay_and_jump(
    extension_config: &ExtensionConfig,
    vault: &mut TollVault,
    source_gate: &Gate,
    destination_gate: &Gate,
    character: &Character,
    mut payment: Coin<SUI>,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    let toll_cfg = extension_config.borrow_rule<TollConfigKey, TollConfig>(TollConfigKey {});
    assert!(coin::value(&payment) >= toll_cfg.toll_amount, ETollInsufficient);

    let toll = coin::split(&mut payment, toll_cfg.toll_amount, ctx);
    balance::join(&mut vault.balance, coin::into_balance(toll));
    if (coin::value(&payment) > 0) {
        transfer::public_transfer(payment, ctx.sender());
    } else {
        coin::destroy_zero(payment);
    };

    let expires = clock.timestamp_ms() + toll_cfg.expiry_duration_ms;
    gate::issue_jump_permit<XAuth>(
        source_gate, destination_gate, character, config::x_auth(), expires, ctx,
    );
}

const ETollInsufficient: u64 = 0;

Chapter Summary

Next Chapter: TypeScript Scripts and dApp Development — After contract deployment, how to interact with on-chain contracts using 6 ready-made scripts, and how to build an EVE Frontier frontend based on the dApp template.

Chapter 7: Complete Guide to Builder Scaffold (Part 2) — TS Scripts and dApp Development

Learning Objectives: Master the usage and principles of the 6 interaction scripts in ts-scripts/, understand the helper.ts toolchain, and learn to build your own EVE Frontier dApp based on the dapps/ React template.

Status: Mapped scripts and dApp directories. This text is based on the script layout in the builder-scaffold within this repository.

Minimal Call Chain

Read .env -> helper.ts initializes client/object ID -> TS script initiates PTB -> On-chain object changes -> dApp queries and displays new state

Directory Responsibility Boundaries

To use builder-scaffold smoothly, the key isn’t memorizing every script name, but first distinguishing the three layers of responsibilities:

What Should a Complete Script Chain Look Like?

.env
  -> helper.ts reads network / package id / key
  -> Business script assembles PTB
  -> Submit on-chain transaction
  -> dApp or query script refreshes object state

If a script is simultaneously responsible for “reading config + querying objects + assembling complex business rules + printing UI text”, it should basically be split up.

What the script system really needs to solve isn’t just “automating command lines”, but separating responsibilities clearly:

• Where does configuration come from
• Who is responsible for common queries
• Who organizes individual business actions
• How do frontend and scripts share the same object understanding

Two Common Anti-patterns

• helper.ts keeps growing until it becomes an unmaintainable “god file”
• Frontend directly copies object IDs and network configs from scripts, causing scripts and pages to drift over time

Corresponding Code Directories

• builder-scaffold/ts-scripts
• builder-scaffold/dapps

1. Prerequisites for TypeScript Scripts

Before running any script, you need to complete the following preparation:

Prerequisites:
1. ✅ world-contracts deployed (local or testnet)
2. ✅ smart_gate contract deployed (execute sui client publish)
3. ✅ .env file filled with all necessary environment variables
4. ✅ test-resources.json + extracted-object-ids.json exist in project root

Configure .env File

cp .env.example .env

Key environment variables:

# Network selection
NETWORK=localnet        # localnet | testnet | mainnet

# Admin private key (exported Sui key, 0x prefixed Bech32 format)
ADMIN_EXPORTED_KEY=suiprivkey1...

# Contract addresses
WORLD_PACKAGE_ID=0xabc...    # Package ID after world-contracts deployment
BUILDER_PACKAGE_ID=0xdef...  # Package ID after smart_gate deployment

# Tenant name (game world namespace)
TENANT=evefrontier

The Essence of .env Isn’t a Config Table, But Engineering Boundaries

As long as a value changes depending on the environment, it shouldn’t be scattered throughout script bodies.

The most common drifting values include:

• Network
• Package IDs
• Admin keys
• Tenant names
• Key object IDs

Once these things are written separately in scripts, frontend, and tests, troubleshooting later will be very painful.

2. Execution Order and Functions of the 6 Scripts

Complete Execution Flow

① pnpm configure-rules       → Set Gate extension rules (tribe ID, bounty item type_id)
② pnpm authorise-gate        → Register extension to Gate object
③ pnpm authorise-storage-unit → Register extension to StorageUnit
④ pnpm issue-tribe-jump-permit → Issue pass for characters meeting tribal conditions
⑤ pnpm jump-with-permit      → Jump with pass
⑥ pnpm collect-corpse-bounty → Submit corpse items → Receive pass (bounty flow)

3. Detailed Reading: configure-rules.ts

This is the most frequently modified script, responsible for initializing two types of rules:

// ts-scripts/smart_gate/configure-rules.ts
import { Transaction } from "@mysten/sui/transactions";
import { getEnvConfig, initializeContext, hydrateWorldConfig } from "../utils/helper";
import { resolveSmartGateExtensionIds } from "./extension-ids";

async function main() {
    // 1. Read .env config
    const env = getEnvConfig();

    // 2. Initialize Sui client + keypair
    const ctx = initializeContext(env.network, env.adminExportedKey);
    const { client, keypair, address } = ctx;

    // 3. Read world-contracts config from chain
    await hydrateWorldConfig(ctx);

    // 4. Query AdminCap, ExtensionConfig object IDs from chain
    const { builderPackageId, adminCapId, extensionConfigId } =
        await resolveSmartGateExtensionIds(client, address);

    const tx = new Transaction();

    // 5. Set tribe rule (tribe=100, valid for 1 hour)
    tx.moveCall({
        target: `${builderPackageId}::tribe_permit::set_tribe_config`,
        arguments: [
            tx.object(extensionConfigId),
            tx.object(adminCapId),
            tx.pure.u32(100),           // Allowed tribe ID
            tx.pure.u64(3600000),       // Validity: 1 hour (milliseconds)
        ],
    });

    // 6. Set bounty rule (item type_id=ITEM_A_TYPE_ID, valid for 1 hour)
    tx.moveCall({
        target: `${builderPackageId}::corpse_gate_bounty::set_bounty_config`,
        arguments: [
            tx.object(extensionConfigId),
            tx.object(adminCapId),
            tx.pure.u64(ITEM_A_TYPE_ID),  // Corpse item's type_id
            tx.pure.u64(3600000),
        ],
    });

    // 7. Submit transaction
    const result = await client.signAndExecuteTransaction({
        transaction: tx,
        signer: keypair,
        options: { showEffects: true, showObjectChanges: true },
    });

    console.log("Transaction digest:", result.digest);
}

What Structure Is Most Worth Keeping in This Type of Script?

It’s this clear chain:

1. Read environment
2. Initialize context
3. Resolve key on-chain objects
4. Assemble PTB
5. Submit and record digest

As long as you maintain this skeleton when adding new scripts in the future, the engineering will be much more stable.

Modifying Rule Parameters

Common modification points:

// Change to allow tribe ID = 3 (corresponding to your game world's tribe config)
tx.pure.u32(3),

// Change to 24-hour validity period
tx.pure.u64(24 * 60 * 60 * 1000),

// ITEM_A_TYPE_ID is defined in utils/constants.ts, adjust according to actual items

4. Utility Function Analysis: utils/helper.ts

This is the shared base component for all scripts:

import { getEnvConfig, initializeContext, hydrateWorldConfig } from "../utils/helper";

// getEnvConfig(): Read .env and validate necessary fields
const env = getEnvConfig();
// → { network, rpcUrl, packageId, adminExportedKey, tenant }

// initializeContext(): Create Sui RPC client and Ed25519 keypair
const ctx = initializeContext(env.network, env.adminExportedKey);
// → { client, keypair, address, config, network }

// hydrateWorldConfig(): Read world config from chain (ObjectRegistry, AdminACL and other object IDs)
await hydrateWorldConfig(ctx);
// Afterwards can access all world object IDs via ctx.config

Key Utilities

utils/
├── helper.ts           # Environment config, context initialization, world config reading
├── config.ts           # Network types, WorldConfig interface, RPC URL mapping
├── constants.ts        # TENANT, ITEM_A_TYPE_ID and other constants
├── derive-object-id.ts # Derive Sui object ID from game item_id (deterministic)
└── proof.ts            # Generate LocationProof (for location verification testing)

Why Is helper.ts Both Important and Dangerous?

Because it naturally becomes the central file that all scripts depend on.

Important because:

• It unifies network, client, and config reading
• It reduces duplicate code

Dangerous because:

• It can easily expand infinitely
• Eventually absorbing a bunch of business logic too

So a more stable principle is: helper.ts should only do “common infrastructure”, not “specific business strategy”.

5. resolve-extension-ids.ts: Automatically Query Object IDs

// No need to manually query object IDs! Script will automatically find AdminCap and ExtensionConfig from chain
export async function resolveSmartGateExtensionIds(client, ownerAddress) {
    // Find AdminCap object belonging to ownerAddress
    const adminCapId = await findObjectByType(
        client,
        ownerAddress,
        `${builderPackageId}::config::AdminCap`,
    );

    // Find shared ExtensionConfig object
    const extensionConfigId = await findSharedObjectByType(
        client,
        `${builderPackageId}::config::ExtensionConfig`,
    );

    return { builderPackageId, adminCapId, extensionConfigId };
}

6. Adding Scripts for Custom Contracts

Using the toll_gate example from Chapter 6, add a configure-toll.ts:

// ts-scripts/smart_gate/configure-toll.ts
import "dotenv/config";
import { Transaction } from "@mysten/sui/transactions";
import { getEnvConfig, initializeContext, hydrateWorldConfig } from "../utils/helper";
import { resolveSmartGateExtensionIds } from "./extension-ids";

async function main() {
    const env = getEnvConfig();
    const ctx = initializeContext(env.network, env.adminExportedKey);
    await hydrateWorldConfig(ctx);
    const { client, keypair } = ctx;

    const { builderPackageId, adminCapId, extensionConfigId } =
        await resolveSmartGateExtensionIds(client, ctx.address);

    const tx = new Transaction();

    tx.moveCall({
        target: `${builderPackageId}::toll_gate::set_toll_config`,
        arguments: [
            tx.object(extensionConfigId),
            tx.object(adminCapId),
            tx.pure.u64(1_000_000_000),   // Toll: 1 SUI = 10^9 MIST
            tx.pure.u64(3600000),          // Valid for 1 hour
        ],
    });

    const result = await client.signAndExecuteTransaction({
        transaction: tx,
        signer: keypair,
        options: { showEffects: true },
    });

    console.log("Toll config set! Digest:", result.digest);
}

main();

Then add to package.json:

"scripts": {
    "configure-toll": "tsx ts-scripts/smart_gate/configure-toll.ts"
}

7. dApp Template: Quick Start

cd dapps
pnpm install
cp .envsample .env       # Fill in VITE_ITEM_ID and other variables
pnpm dev                 # Start dev server: http://localhost:5173

Tech Stack

Provider Architecture (main.tsx)

// src/main.tsx
ReactDOM.createRoot(document.getElementById("root")!).render(
    <EveFrontierProvider queryClient={queryClient}>
        {/* One Provider combines all necessary Contexts */}
        {/* QueryClientProvider → DAppKitProvider → VaultProvider → SmartObjectProvider → NotificationProvider */}
        <App />
    </EveFrontierProvider>,
);

8. Core Hooks Reference

Wallet Connection (App.tsx)

import { abbreviateAddress, useConnection } from "@evefrontier/dapp-kit";
import { useCurrentAccount } from "@mysten/dapp-kit-react";

// Connect/disconnect wallet
const { handleConnect, handleDisconnect, isConnected, walletAddress } = useConnection();

// Read current account
const account = useCurrentAccount();

// Display abbreviated address (e.g., 0x1234...5678)
<span>{abbreviateAddress(account?.address ?? "")}</span>

Read Smart Object (Assembly Data)

import { useSmartObject } from "@evefrontier/dapp-kit";

// Pass in-game item_id (from URL params or env)
const { assembly, character, loading, error, refetch } = useSmartObject({
    itemId: VITE_ITEM_ID,
});

// assembly contains: name, typeId, state, id, owner character
// character contains: holder character info

Execute Transaction (WalletStatus.tsx)

import { useDAppKit } from "@mysten/dapp-kit-react";
import { Transaction } from "@mysten/sui/transactions";

const { signAndExecuteTransaction } = useDAppKit();

async function callMyContract() {
    const tx = new Transaction();
    tx.moveCall({
        target: `${PACKAGE_ID}::tribe_permit::issue_jump_permit`,
        arguments: [/* ... */],
    });

    const result = await signAndExecuteTransaction({ transaction: tx });
    await refetch();  // Refresh assembly state
}

9. Practice: Issue Tribal Pass in dApp

// src/components/IssuePermit.tsx
import { useSmartObject, useConnection } from "@evefrontier/dapp-kit";
import { useDAppKit } from "@mysten/dapp-kit-react";
import { Transaction } from "@mysten/sui/transactions";

export function IssuePermit({ gateItemId }: { gateItemId: string }) {
    const { assembly } = useSmartObject({ itemId: gateItemId });
    const { isConnected } = useConnection();
    const { signAndExecuteTransaction } = useDAppKit();

    const handleIssuePermit = async () => {
        const tx = new Transaction();
        tx.moveCall({
            target: `${import.meta.env.VITE_BUILDER_PACKAGE_ID}::tribe_permit::issue_jump_permit`,
            arguments: [
                tx.object(import.meta.env.VITE_EXTENSION_CONFIG_ID),
                tx.object(SOURCE_GATE_ID),
                tx.object(DEST_GATE_ID),
                tx.object(CHARACTER_ID),
                tx.object("0x6"),  // Clock object (Sui system object fixed ID)
            ],
        });

        const result = await signAndExecuteTransaction({ transaction: tx });
        console.log("JumpPermit issued!", result.digest);
    };

    return (
        <button
            onClick={handleIssuePermit}
            disabled={!isConnected || !assembly}
        >
            {assembly ? `Apply for ${assembly.name}` : "Loading..."}
        </button>
    );
}

10. Sponsored Transactions (Sponsored TX)

For Builders wanting to hide gas fees, dapp-kit supports sponsored transactions:

import { useSponsoredTransaction } from "@evefrontier/dapp-kit";

const { sponsoredSignAndExecute } = useSponsoredTransaction();

// Player doesn't need to pay gas — Builder's server pays for them
await sponsoredSignAndExecute({ transaction: tx });

// Note: Only EVE Vault wallet supports this feature
// If user uses other wallets, need to catch WalletSponsoredTransactionNotSupportedError

11. GraphQL Data Query (Advanced)

When useSmartObject isn’t sufficient, you can use GraphQL directly:

import { executeGraphQLQuery, getAssemblyWithOwner } from "@evefrontier/dapp-kit";

// Query Gate's complete data (including owner character)
const gateData = await getAssemblyWithOwner({ itemId: gateItemId });

// Execute custom GraphQL query
const result = await executeGraphQLQuery(`
    query GetMyGates($owner: SuiAddress!) {
        objects(filter: { type: "${PACKAGE_ID}::smart_gate::Gate", owner: $owner }) {
            nodes {
                address
                contents { json }
            }
        }
    }
`, { owner: address });

12. Complete Project Setup Flow Summary

1. Clone builder-scaffold
2. Clone world-contracts (Docker users: on host, automatically visible in container)
3. Choose workflow: Docker or Host
4. Start local chain (docker compose run or sui start)
5. Deploy world-contracts (refer to docs/builder-flow-docker.md)
6. Compile smart_gate: sui move build -e testnet
7. Deploy smart_gate: sui client test-publish --pubfile-path ...
8. Fill .env file (BUILDER_PACKAGE_ID + WORLD_PACKAGE_ID + ADMIN_KEY)
9. Run pnpm configure-rules → pnpm authorise-gate → pnpm issue-tribe-jump-permit
10. Start dApp: cd dapps && pnpm dev

Chapter Summary

These two chapters cover the complete chain from local setup to contract deployment, script interaction, and frontend development for Builder Scaffold. Combined with previous World contract chapters, you now have all the knowledge to independently build an end-to-end EVE Frontier Builder application.

Chapter 8: Sponsored Transactions & Server-Side Integration

Goal: Deeply understand EVE Frontier’s sponsored transaction mechanism, master how to build backend services for business logic validation and Gas payment on behalf of players, achieving frictionless gameplay experiences.

Status: Engineering chapter. Main content focuses on sponsored transactions, server-side validation, and on-chain/off-chain coordination.

8.1 What are Sponsored Transactions?

In regular Sui transactions, the sender and gas owner are the same person. Sponsored transactions allow these two roles to be separated:

Regular transaction:  Player signs + Player pays Gas
Sponsored transaction:  Player signs intent + Server validates + Server pays Gas

Critical for EVE Frontier because:

• Certain operations require game server validation (such as proximity proofs, distance checks)
• Lowers player entry barrier (no need to pre-fund SUI for Gas)
• Enables business-level risk control: Server can reject invalid requests

The real key here isn’t simply “who pays Gas for whom,” but rather:

Sponsored transactions break down a player action into three stages: “user intent + server review + on-chain execution.”

This makes many product experiences possible that were previously very difficult:

• Players don’t need to prepare SUI in advance
• Server can make business judgments before going on-chain
• Risk control can happen before signing, rather than remedying after asset incidents

But the cost is also clear: your system is no longer just frontend + contract, but formally becomes a “on-chain/off-chain coordinated system.”

8.2 AdminACL: Game Server’s Permission Object

EVE Frontier uses the AdminACL shared object to manage which server addresses are authorized as sponsors:

GovernorCap
    └──(manages) AdminACL (shared object)
                └── sponsors: vector<address>
                    ├── Game Server 1 address
                    ├── Game Server 2 address
                    └── ...

Operations requiring server participation (like jumping) have checks like this in the contract:

public fun verify_sponsor(admin_acl: &AdminACL, ctx: &TxContext) {
    // tx_context::sponsor() returns the Gas payer's address
    let sponsor = ctx.sponsor().unwrap(); // aborts if no sponsor
    assert!(
        vector::contains(&admin_acl.sponsors, &sponsor),
        EUnauthorizedSponsor,
    );
}

This means: even if a player constructs a valid transaction themselves, calling functions like jump_with_permit will abort without an authorized server signature.

What does AdminACL really express?

It doesn’t express “this server can technically sign,” but rather:

This server is officially trusted by the world rules to vouch for certain sensitive actions.

This is fundamentally different from regular backend services. In many Web applications, the backend just helps you make business judgments; here, the backend is part of the on-chain permission model itself.

So once AdminACL management becomes chaotic, it affects not a single interface, but the entire chain of trust:

• Who can sponsor payments
• Who can vouch for proximity proofs
• Who can initiate certain restricted actions

8.3 Complete Sponsored Transaction Flow

   Player                    Your Backend Service                   Sui Network
    │                          │                            │
    │── 1. Build Transaction ──►│                            │
    │   (setSender = player addr)│                            │
    │                          │                            │
    │◄── 2. Backend validates ──│                            │
    │   (check proximity, balance, etc.)                     │
    │                          │                            │
    │── 3. Player signs (Sender)──►│                            │
    │                          │                            │
    │                          │── 4. Server signs (Gas) ───►│
    │                          │   (setGasOwner = server)   │
    │                          │                            │
    │◄─────────────────────────┼── 5. Transaction result ───│

What does each segment in this chain protect against?

• Player builds transaction Prevents server from arbitrarily fabricating intent on user’s behalf
• Backend validates business logic Prevents requests that don’t meet conditions from going directly on-chain
• Player signature Proves this is indeed a user-authorized action
• Server signature Proves the platform is willing to sponsor and vouch for this action

All four segments are indispensable. Missing one leads to typical problems:

• No player signature: platform can send on behalf of users arbitrarily
• No backend validation: anyone can freeload sponsorship
• No server signature: restricted on-chain entry points fail directly

8.4 Building a Simple Backend Sponsorship Service

Project Structure

backend/
├── src/
│   ├── server.ts          # Express server
│   ├── sponsor.ts          # Sponsorship transaction logic
│   ├── validators.ts       # Business validation
│   └── config.ts           # Configuration
└── package.json

sponsor.ts: Core Sponsorship Logic

// src/sponsor.ts
import { SuiClient } from "@mysten/sui/client";
import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
import { Transaction } from "@mysten/sui/transactions";
import { fromBase64 } from "@mysten/sui/utils";

const client = new SuiClient({
  url: process.env.SUI_RPC_URL ?? "https://fullnode.testnet.sui.io:443",
});

// Server signing key (securely stored in environment variables)
const serverKeypair = Ed25519Keypair.fromSecretKey(
  fromBase64(process.env.SERVER_PRIVATE_KEY!)
);

export interface SponsoredTxRequest {
  txBytes: string;         // Player-built transaction (base64)
  playerSignature: string; // Player's signature on txBytes (base64)
  playerAddress: string;
}

export async function sponsorAndExecute(req: SponsoredTxRequest) {
  // 1. Deserialize player's transaction
  const txBytes = fromBase64(req.txBytes);

  // 2. Server sets Gas payer
  //    This modifies the transaction to make the server address the Gas payer
  const tx = Transaction.from(txBytes);
  tx.setGasOwner(serverKeypair.getPublicKey().toSuiAddress());

  // 3. Server signs (as Gas payer)
  const sponsoredBytes = await tx.build({ client });
  const serverSig = await serverKeypair.signTransaction(sponsoredBytes);

  // 4. Execute: submit both player signature and server signature
  const result = await client.executeTransactionBlock({
    transactionBlock: sponsoredBytes,
    signature: [
      req.playerSignature,  // Player's signature as Sender
      serverSig.signature,  // Server's signature as Gas Owner
    ],
    options: { showEvents: true, showEffects: true },
  });

  return result;
}

What the server needs to guard against most isn’t “request failure” but “request abuse”

A truly usable sponsorship service should at least consider these risk control points:

• Same player repeating requests in short time
• Same transaction being submitted repeatedly
• Certain high-cost operations being batch-scraped
• Players sneaking in transactions that shouldn’t be sponsored

So in real projects, sponsorship services usually also add:

• Request rate limiting
• Transaction whitelists or entry whitelists
• Budget limits per action
• Request logging and audit trails

validators.ts: Business Validation Logic

// src/validators.ts
import { SuiClient } from "@mysten/sui/client";

const client = new SuiClient({ url: process.env.SUI_RPC_URL! });

// Validate proximity (simplified: check if two components' game coordinates are close enough)
export async function validateProximity(
  playerAddress: string,
  assemblyId: string,
): Promise<boolean> {
  // In real scenarios, this would query game server or on-chain location hash
  // This is just an example implementation
  try {
    const assembly = await client.getObject({
      id: assemblyId,
      options: { showContent: true },
    });

    // Check if player is near component (game physics rule validation)
    // Real implementation needs to communicate with game server
    return true; // Simplified
  } catch {
    return false;
  }
}

// Validate if player meets conditions (e.g., holds specific NFT)
export async function validatePlayerCondition(
  playerAddress: string,
  requiredNftType: string,
): Promise<boolean> {
  const objects = await client.getOwnedObjects({
    owner: playerAddress,
    filter: { StructType: requiredNftType },
  });

  return objects.data.length > 0;
}

Why shouldn’t validation logic be mixed with execution logic?

Because these two things change at different rates:

• Validation rules iterate frequently
• Execution pathways need to remain as stable as possible

By separating them, you get several direct benefits:

• Risk control rules are easier to update independently
• Easier to compose different validators for different actions
• Easier to do gradual rollouts and replay analysis

server.ts: REST API Server

// src/server.ts
import express from "express";
import { sponsorAndExecute, SponsoredTxRequest } from "./sponsor";
import { validateProximity, validatePlayerCondition } from "./validators";

const app = express();
app.use(express.json());

// Sponsor jump request
app.post("/api/sponsor/jump", async (req, res) => {
  const { txBytes, playerSignature, playerAddress, gateId } = req.body;

  try {
    // 1. Validate proximity (player must be near stargate)
    const isNear = await validateProximity(playerAddress, gateId);
    if (!isNear) {
      return res.status(400).json({ error: "Player not near stargate" });
    }

    // 2. Execute sponsored transaction
    const result = await sponsorAndExecute({
      txBytes,
      playerSignature,
      playerAddress,
    });

    res.json({ success: true, digest: result.digest });
  } catch (err: any) {
    res.status(500).json({ error: err.message });
  }
});

// Sponsor general action (with custom validation)
app.post("/api/sponsor/action", async (req, res) => {
  const { txBytes, playerSignature, playerAddress, actionType, metadata } = req.body;

  try {
    // Different validation based on actionType
    switch (actionType) {
      case "deposit_ore": {
        // Validate near storage box
        const ok = await validateProximity(playerAddress, metadata.ssuId);
        if (!ok) return res.status(400).json({ error: "Not nearby" });
        break;
      }
      case "special_gate": {
        // Validate holding VIP NFT
        const hasNft = await validatePlayerCondition(
          playerAddress,
          `${process.env.MY_PACKAGE}::vip_pass::VipPass`
        );
        if (!hasNft) return res.status(403).json({ error: "VIP pass required" });
        break;
      }
    }

    const result = await sponsorAndExecute({ txBytes, playerSignature, playerAddress });
    res.json({ success: true, digest: result.digest });
  } catch (err: any) {
    res.status(500).json({ error: err.message });
  }
});

app.listen(3001, () => console.log("Sponsorship service running on :3001"));

Idempotency is the most easily overlooked issue in sponsorship services

Player network jitter, frontend retries, users frantically clicking buttons—all can cause the same request to be sent multiple times.

If your backend doesn’t have idempotency design, you’ll see:

• Same business request being sponsored repeatedly
• Users think they clicked once, but two transactions went on-chain
• Budgets and statistics all become distorted

In real projects, you should at least give each business action a stable request ID and record server-side whether “this request has already been processed.”

8.5 Frontend Integration with Sponsored Transactions

// src/hooks/useSponsoredAction.ts
import { useWallet } from "@mysten/dapp-kit-react";
import { Transaction } from "@mysten/sui/transactions";
import { toBase64 } from "@mysten/sui/utils";

const BACKEND_URL = import.meta.env.VITE_BACKEND_URL ?? "http://localhost:3001";

export function useSponsoredAction() {
  const wallet = useWallet();

  const executeSponsoredJump = async (
    tx: Transaction,
    gateId: string,
  ) => {
    if (!wallet.currentAccount) throw new Error("Please connect wallet");

    const playerAddress = wallet.currentAccount.address;

    // 1. Player only signs, doesn't submit
    const txBytes = await tx.build({ client: suiClient });
    const { signature: playerSig } = await wallet.signTransaction({
      transaction: tx,
    });

    // 2. Send to backend, let server validate and sponsor Gas
    const response = await fetch(`${BACKEND_URL}/api/sponsor/jump`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        txBytes: toBase64(txBytes),
        playerSignature: playerSig,
        playerAddress,
        gateId,
      }),
    });

    if (!response.ok) {
      const { error } = await response.json();
      throw new Error(error);
    }

    return response.json();
  };

  return { executeSponsoredJump };
}

8.6 Security Considerations for Sponsored Transactions

8.7 @evefrontier/dapp-kit Built-in Sponsorship Support

The official SDK has built-in support for sponsored transactions:

import { signAndExecuteSponsoredTransaction } from "@evefrontier/dapp-kit";

// SDK automatically communicates with EVE Frontier backend to complete sponsorship
const result = await signAndExecuteSponsoredTransaction({
  transaction: tx,
  // No need to manually handle signatures and backend communication
});

Applicable scenarios: Official game operations (like component online/offline, warehouse transfers) can typically use the official sponsorship service.

When you need to build your own backend: When your extension contracts need custom business validation (like checking NFT holdings, in-game conditions), you need to deploy your own sponsorship service.

Summary

Further Reading

• Interfacing with the World
• Sui Sponsored Transactions Documentation
• ownership-model.md

Chapter 9: Off-chain Indexing & GraphQL Advanced Usage

Goal: Master the complete toolkit for off-chain data querying, including GraphQL, gRPC, event subscriptions, and custom indexers, to build high-performance data-driven dApps.

Status: Engineering chapter. Main content focuses on GraphQL, events, and indexer design.

9.1 Read-Write Separation Principle

The golden rule of EVE Frontier development:

Write operations (modify on-chain state) → Submit via Transaction → Consume Gas
Read operations (query on-chain state) → Via GraphQL/gRPC/SuiClient → Completely free

Design Guidance: Move all possible logic to off-chain reads, and only submit transactions when you truly need to change state.

This principle seems simple, but it actually determines your entire system cost structure:

• The more you write on-chain, the higher the Gas and the greater the failure surface
• The better you read off-chain, the faster the frontend and the lighter the interaction

So a mature Builder system typically doesn’t “stuff everything on-chain,” but clearly divides into three layers:

• On-chain objects Store state that must be trustworthy
• On-chain events Store actions that have occurred
• Off-chain indexes Store the views that the frontend actually needs to consume

If these three layers aren’t separated, your frontend will eventually become a bunch of expensive and hard-to-maintain real-time RPC calls.

9.2 SuiClient Basic Reading

import { SuiClient } from "@mysten/sui/client";

const client = new SuiClient({ url: "https://fullnode.testnet.sui.io:443" });

// ❶ Read a single object
const gate = await client.getObject({
  id: "0x...",
  options: { showContent: true, showOwner: true, showType: true },
});
console.log(gate.data?.content);

// ❲ Batch read multiple objects (one request)
const objects = await client.multiGetObjects({
  ids: ["0x...gate1", "0x...gate2", "0x...ssu"],
  options: { showContent: true },
});

// ❸ Query all objects owned by an address
const ownedObjects = await client.getOwnedObjects({
  owner: "0xALICE",
  filter: { StructType: `${WORLD_PKG}::gate::Gate` },
  options: { showContent: true },
});

// ❹ Paginated query (handling large amounts of data)
let cursor: string | null = null;
const allGates: any[] = [];

do {
  const page = await client.getOwnedObjects({
    owner: "0xALICE",
    cursor,
    limit: 50,
  });
  allGates.push(...page.data);
  cursor = page.nextCursor ?? null;
} while (cursor);

What is SuiClient best suited for?

It’s best suited for:

• Single object reads
• Small-scale batch reads
• Debugging and script validation
• Lightweight queries for the frontend

It may not be directly suitable for:

• Large-scale leaderboards
• Aggregated views across multiple object types
• High-frequency complex filtering

Once your query needs start requiring “sorting, aggregation, joining across objects,” it’s time to consider GraphQL or a custom indexing layer.

9.3 Deep GraphQL Usage

Sui’s GraphQL interface is more powerful than JSON-RPC, supporting complex filtering, nested queries, and cursor pagination.

Connecting to GraphQL

import { SuiGraphQLClient, graphql } from "@mysten/sui/graphql";

const graphqlClient = new SuiGraphQLClient({
  url: "https://graphql.testnet.sui.io/graphql",
});

Query all objects of a certain type

const GET_ALL_GATES = graphql(`
  query GetAllGates($type: String!, $after: String) {
    objects(filter: { type: $type }, first: 50, after: $after) {
      pageInfo {
        hasNextPage
        endCursor
      }
      nodes {
        address
        asMoveObject {
          contents {
            json  # Return fields in JSON format
          }
        }
      }
    }
  }
`);

async function getAllGates(): Promise<any[]> {
  const results: any[] = [];
  let after: string | null = null;

  do {
    const data = await graphqlClient.query({
      query: GET_ALL_GATES,
      variables: {
        type: `${WORLD_PKG}::gate::Gate`,
        after,
      },
    });

    const objects = data.data?.objects;
    if (!objects) break;

    results.push(...objects.nodes.map(n => n.asMoveObject?.contents?.json));
    after = objects.pageInfo.hasNextPage ? objects.pageInfo.endCursor : null;
  } while (after);

  return results;
}

The real value of GraphQL isn’t just “more elegant syntax”

Its more important value is allowing you to organize queries according to frontend views, rather than being led by single-object RPC interfaces.

This is very important in actual products, because pages often don’t need “what a certain object originally looks like,” but rather:

• Current object + associated object summary
• A page list + pagination information
• Multiple object types combined into one dashboard

GraphQL is not omnipotent either

If you treat it like a database and fetch data without limits, you’ll still run into problems:

• Queries too large, frontend first screen becomes slow
• Too many nested objects in one page, debugging becomes difficult
• Complex queries change once, both frontend and backend explode together

So the best use of GraphQL is usually:

• Split queries by page
• Each query serves only one clear view type
• When aggregation statistics are needed, let custom indexers take on more responsibility

Query multiple related objects (nested)

// Query star gate and its associated network node information
const GET_GATE_WITH_NODE = graphql(`
  query GetGateWithNode($gateId: SuiAddress!) {
    object(address: $gateId) {
      address
      asMoveObject {
        contents { json }
      }
    }
  }
`);

// Batch: query multiple different types at once
const GET_ASSEMBLY_OVERVIEW = graphql(`
  query AssemblyOverview($gateId: SuiAddress!, $ssuId: SuiAddress!) {
    gate: object(address: $gateId) {
      asMoveObject { contents { json } }
    }
    ssu: object(address: $ssuId) {
      asMoveObject { contents { json } }
    }
  }
`);

Query by dynamic field (Table content)

// Query specific entry in Market's listings Table
const GET_LISTING = graphql(`
  query GetListing($marketId: SuiAddress!, $typeId: String!) {
    object(address: $marketId) {
      dynamicField(name: { type: "u64", bcs: $typeId }) {
        value {
          ... on MoveValue {
            json
          }
        }
      }
    }
  }
`);

Why are dynamic field queries more troublesome than normal object fields?

Because dynamic fields are naturally closer to “index structures that grow at runtime” rather than fixed schemas.

This means:

• You must be very clear about the key encoding method
• Frontend and indexing layer must use the same key rules
• Once the key design changes, the read path will fail entirely

So the design of dynamic fields is not just an internal contract issue, it will directly spill over to the query and frontend layers.

9.4 Real-time Event Subscription

import { SuiClient } from "@mysten/sui/client";

const client = new SuiClient({ url: "https://fullnode.testnet.sui.io:443" });

// Subscribe to all events from a specific package
const unsubscribe = await client.subscribeEvent({
  filter: { Package: MY_PACKAGE },
  onMessage: (event) => {
    switch (event.type) {
      case `${MY_PACKAGE}::toll_gate_ext::GateJumped`:
        handleGateJump(event.parsedJson);
        break;

      case `${MY_PACKAGE}::market::ItemSold`:
        handleItemSold(event.parsedJson);
        break;
    }
  },
});

// Unsubscribe after 90 seconds
setTimeout(unsubscribe, 90_000);

// Query historical events (with filtering)
const history = await client.queryEvents({
  query: {
    And: [
      { MoveEventType: `${MY_PACKAGE}::toll_gate_ext::GateJumped` },
      { Sender: "0xPlayerAddress..." },
    ],
  },
  order: "descending",
  limit: 100,
});

What problems are event subscriptions best suited to solve?

Best suited for:

• Real-time notifications
• Activity streams
• Lightweight incremental updates
• Indexer consuming new transactions

Not suitable as:

• The sole source of current state
• Complete business list interface
• Highly reliable historical database

Because event streams naturally have two real-world issues:

• You might disconnect and miss messages
• You always need a historical backfill mechanism

So mature indexers usually:

• First replay history
• Then subscribe to incremental changes
• Periodically perform consistency checks

9.5 gRPC: High-throughput Data Streams

For scenarios requiring processing large amounts of real-time data (such as leaderboards, full network state snapshots), gRPC is more efficient than GraphQL:

// Use gRPC to stream read latest Checkpoints
import { SuiHTTPTransport } from "@mysten/sui/client";

// gRPC is suitable for monitoring state changes across the entire chain
// For example: each Checkpoint contains a summary of all transactions during that period
// Advanced usage: used when building custom indexers

When is it worth using gRPC instead of continuing to pile on RPC / GraphQL?

When you start encountering these scenarios:

• Need to consume checkpoints long-term
• Need to maintain your own near real-time index
• Need high-throughput, low-latency on-chain data streams

If you’re just building a regular dApp page, you usually don’t need to start with gRPC. It’s more like an “infrastructure building tool,” not a page query tool.

9.6 Building Custom Off-chain Indexers

For complex query needs (such as leaderboards, aggregate statistics), you can build your own indexing service:

// server/indexer.ts
import { SuiClient } from "@mysten/sui/client";

const client = new SuiClient({ url: process.env.SUI_RPC! });

// In-memory index (small scale; use Redis or PostgreSQL for production)
const jumpLeaderboard = new Map<string, number>(); // address → jump count

// Start indexer: listen to events and update local state
async function startIndexer() {
  console.log("Indexer starting...");

  // First load historical data
  await loadHistoricalEvents();

  // Then subscribe to new events
  await client.subscribeEvent({
    filter: { Package: MY_PACKAGE },
    onMessage: (event) => {
      if (event.type.includes("GateJumped")) {
        const { character_id } = event.parsedJson as any;
        const count = jumpLeaderboard.get(character_id) ?? 0;
        jumpLeaderboard.set(character_id, count + 1);
      }
    },
  });
}

async function loadHistoricalEvents() {
  let cursor = null;
  do {
    const page = await client.queryEvents({
      query: { MoveEventType: `${MY_PACKAGE}::toll_gate_ext::GateJumped` },
      cursor,
      limit: 200,
    });

    for (const event of page.data) {
      const { character_id } = event.parsedJson as any;
      const count = jumpLeaderboard.get(character_id) ?? 0;
      jumpLeaderboard.set(character_id, count + 1);
    }

    cursor = page.nextCursor;
  } while (cursor && !cursor.startsWith("0x00")); // Simplified termination condition
}

// API: Provide leaderboard data
import express from "express";
const app = express();

app.get("/api/leaderboard", (req, res) => {
  const sorted = [...jumpLeaderboard.entries()]
    .sort((a, b) => b[1] - a[1])
    .slice(0, 50)
    .map(([address, count], rank) => ({ rank: rank + 1, address, count }));

  res.json(sorted);
});

startIndexer().then(() => app.listen(3002));

9.7 Efficiently Displaying On-chain Data in dApps

Using React Query for Caching & Auto-refresh

// src/hooks/useLeaderboard.ts
import { useQuery } from "@tanstack/react-query";

export function useLeaderboard() {
  return useQuery({
    queryKey: ["leaderboard"],
    queryFn: async () => {
      const res = await fetch("/api/leaderboard");
      return res.json();
    },
    refetchInterval: 30_000,  // Refresh every 30 seconds
    staleTime: 25_000,        // Don't re-request within 25 seconds
  });
}

// Usage
function Leaderboard() {
  const { data, isLoading } = useLeaderboard();

  return (
    <table>
      <thead><tr><th>#</th><th>Player</th><th>Jump Count</th></tr></thead>
      <tbody>
        {data?.map(({ rank, address, count }) => (
          <tr key={address}>
            <td>{rank}</td>
            <td>{address.slice(0, 8)}...</td>
            <td>{count}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}

Chapter Summary

Further Reading

• Interfacing with the World
• Sui GraphQL Documentation
• Sui Events Documentation

Chapter 10: EVE Vault & dApp Integration Practices

Learning Objectives: Master the complete process of integrating EVE Vault into Builder dApps—account discovery, connection, transaction signing, sponsored transactions, and handling zkLogin-specific Epoch refresh and disconnection scenarios.

Status: Teaching example. API descriptions in the text are based on current dependency versions and example dApps in this repository. Verify against local package versions during actual integration.

Minimal Call Chain

dApp Provider initialization -> useConnection wallet discovery -> Build PTB -> EVE Vault approval/signing -> On-chain execution -> dApp refresh object state

Wallet Capability Matrix

This table isn’t for advertising, but to remind you: the integration layer must first detect wallet capabilities, then decide whether to show sponsored transaction entry points.

The real awareness this chapter should establish is:

Wallet integration isn’t just “connect and done,” but requires designing complete interaction fallback paths according to wallet capability differences.

In other words, your dApp cannot assume all wallets are equivalent.

Exception Handling Sequence

When users report “wallet connects but transactions won’t send,” check in this order:

1. First confirm if the current wallet supports Sponsored Tx
2. Then confirm network, package id, and object IDs are consistent
3. Then confirm if zkLogin proof has expired, if maxEpoch needs refresh
4. Finally check if frontend correctly handles disconnection and state recovery after reconnection

Corresponding Code Directories

• builder-scaffold/dapps
• book/src/code/example-17/dapp
• evevault

1. dApp Integration Overview

Because EVE Vault implements the complete Sui Wallet Standard, any dApp using @mysten/dapp-kit or @evefrontier/dapp-kit can discover and connect to EVE Vault with zero configuration.

Meanwhile, EVE Vault also implements EVE Frontier’s proprietary sponsored transaction extension, allowing Builders to pay Gas for players.

So the integration layer typically needs to answer at least three things:

• Is there currently a wallet?
• Is it currently EVE Vault?
• Does the current operation require Sponsored Tx capability?

2. Install Dependencies

# EVE Frontier dedicated SDK (recommended, includes EVE Vault sponsored transaction support)
npm install @evefrontier/dapp-kit

# Or Mysten official SDK (basic Wallet Standard, no sponsored transactions)
npm install @mysten/dapp-kit

3. Provider Configuration

// src/main.tsx
import { EveFrontierProvider } from "@evefrontier/dapp-kit";
import { QueryClient } from "@tanstack/react-query";
import ReactDOM from "react-dom/client";

const queryClient = new QueryClient();

ReactDOM.createRoot(document.getElementById("root")!).render(
    <EveFrontierProvider queryClient={queryClient}>
        <App />
    </EveFrontierProvider>,
);

EveFrontierProvider automatically initializes:

• QueryClientProvider (React Query)
• DAppKitProvider (Sui client + Wallet)
• VaultProvider (EVE Vault connection state)
• SmartObjectProvider (Game object GraphQL queries)
• NotificationProvider (On-chain operation notifications)

The key to Provider here isn’t “how many layers are wrapped,” but capability ordering.

Your later connection, signing, object queries, and notification experience all depend on this initialization order being correct.

4. Connect Wallet

import { useConnection, abbreviateAddress } from "@evefrontier/dapp-kit";
import { useCurrentAccount } from "@mysten/dapp-kit-react";

function ConnectButton() {
    const { handleConnect, handleDisconnect, isConnected, walletAddress, hasEveVault } = useConnection();
    const account = useCurrentAccount();

    if (!isConnected) {
        return (
            <div>
                <button onClick={handleConnect}>Connect EVE Vault</button>
                {!hasEveVault && (
                    <p style={{ color: "orange" }}>
                        Please install <a href="https://github.com/evefrontier/evevault/releases/latest/download/eve-vault-chrome.zip">EVE Vault extension</a>
                    </p>
                )}
            </div>
        );
    }

    return (
        <div>
            <span>Connected: {abbreviateAddress(account?.address ?? "")}</span>
            <button onClick={handleDisconnect}>Disconnect</button>
        </div>
    );
}

Meaning of hasEveVault

When hasEveVault is true, it means the EVE Vault extension is installed and discovered in the wallet list. This lets you provide download link guidance to users who haven’t installed it.

The most easily overlooked issue in the connection flow isn’t “can the button light up,” but whether the page switches to the correct state immediately after connecting:

• Is the current address refreshed?
• Are needed object queries refetched?
• Do buttons that depend on wallet capabilities switch display?

5. Send Transaction (Regular Signing)

import { useDAppKit } from "@mysten/dapp-kit-react";
import { Transaction } from "@mysten/sui/transactions";
import { useConnection } from "@evefrontier/dapp-kit";

function SendTxButton() {
    const { signAndExecuteTransaction } = useDAppKit();
    const { isConnected } = useConnection();

    const handleSend = async () => {
        const tx = new Transaction();

        // Call Builder contract
        tx.moveCall({
            target: `${PACKAGE_ID}::tribe_permit::issue_jump_permit`,
            arguments: [
                tx.object(EXTENSION_CONFIG_ID),
                tx.object(SOURCE_GATE_ID),
                tx.object(DEST_GATE_ID),
                tx.object(CHARACTER_ID),
                tx.object("0x6"),  // Sui Clock (fixed object ID)
            ],
        });

        try {
            const result = await signAndExecuteTransaction({ transaction: tx });
            console.log("Transaction successful, Digest:", result.digest);
        } catch (err) {
            // EVE Vault approval popup closed by user
            if (err.message?.includes("User rejected")) {
                alert("Transaction cancelled by user");
            }
        }
    };

    return <button onClick={handleSend} disabled={!isConnected}>Issue Permit</button>;
}

The key to regular signing flow isn’t that the code can call, but that users can understand what they’re signing.

So before transaction buttons, it’s best to explain as clearly as possible:

• Target object
• Key costs
• Expected results

Rather than leaving everything to the wallet approval page.

6. Sponsored Transaction (Sponsored TX)—Most Important Feature

EVE Vault is the only Sui wallet that implements sign_sponsored_transaction. This means Builder’s server can pay Gas for players, so players don’t need to hold SUI to use the dApp.

import { useSponsoredTransaction, WalletSponsoredTransactionNotSupportedError } from "@evefrontier/dapp-kit";
import { Transaction } from "@mysten/sui/transactions";

function SponsoredTxButton() {
    const { sponsoredSignAndExecute } = useSponsoredTransaction();

    const handleSponsoredTx = async () => {
        const tx = new Transaction();
        tx.moveCall({
            target: `${PACKAGE_ID}::my_extension::some_action`,
            arguments: [/* ... */],
        });

        try {
            // Player signs, Gas sponsored by Builder server
            const result = await sponsoredSignAndExecute({ transaction: tx });
            console.log("Sponsored transaction successful!", result.digest);
        } catch (err) {
            if (err instanceof WalletSponsoredTransactionNotSupportedError) {
                // User using non-EVE Vault wallet, fallback to regular transaction
                console.warn("Current wallet doesn't support sponsored transactions, please use EVE Vault");
                // Can fallback to signAndExecuteTransaction
            }
        }
    };

    return <button onClick={handleSponsoredTx}>Gas-free Operation (EVE Vault Sponsored)</button>;
}

Builder Server-side Sponsorship Configuration

Sponsored transactions require Builder to configure a Gas sponsor account on the server side:

// Builder backend (Node.js)
import { SuiClient } from "@mysten/sui/client";
import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
import { Transaction } from "@mysten/sui/transactions";

const sponsorKeypair = Ed25519Keypair.fromSecretKey(SPONSOR_PRIVATE_KEY);

// Receive player's PTB, add Gas and sign back
app.post("/sponsor-tx", async (req, res) => {
    const { serializedTx } = req.body;

    const tx = Transaction.from(serializedTx);

    // Set Gas sponsor
    tx.setSender(playerAddress);
    tx.setGasOwner(sponsorKeypair.getPublicKey().toSuiAddress());

    const sponsorSignature = await tx.sign({ signer: sponsorKeypair, client });

    res.json({ sponsorSignature, serializedTx: tx.serialize() });
});

The key to Sponsored Tx integration isn’t “saving Gas,” but “frontend-backend coordination.”

It requires at least three layers working correctly together:

• Frontend can identify wallet capabilities
• Backend can correctly supplement Gas and signatures
• Wallet can complete corresponding approval process

As long as one layer’s calibration is inconsistent, users will see “can connect but can’t send anything out.”

7. Read Game Object (Smart Object)

import { useSmartObject } from "@evefrontier/dapp-kit";

function GateStatus({ gateItemId }: { gateItemId: string }) {
    const { assembly, character, loading, error, refetch } = useSmartObject({
        itemId: gateItemId,
    });

    if (loading) return <div>Loading...</div>;
    if (error) return <div>Error: {error.message}</div>;
    if (!assembly) return <div>Gate not found</div>;

    return (
        <div>
            <h2>{assembly.name}</h2>
            <p>Type ID: {assembly.typeId}</p>
            <p>Status: {assembly.state}</p>
            <p>Owner: {character?.name ?? "Unknown"}</p>
            <button onClick={refetch}>Refresh</button>
        </div>
    );
}

8. zkLogin Epoch Refresh Handling

zkLogin’s temporary keypair is bound to Sui Epoch (approximately 24 hours). When Epoch expires, keys and ZK Proof need to be regenerated:

import { useConnection } from "@evefrontier/dapp-kit";
import { useDAppKit } from "@mysten/dapp-kit-react";

function TransactionButton() {
    const { isConnected, walletAddress } = useConnection();
    const { signAndExecuteTransaction } = useDAppKit();

    const handleTransaction = async () => {
        const tx = new Transaction();
        // ...build transaction...

        try {
            await signAndExecuteTransaction({ transaction: tx });
        } catch (err) {
            const errMsg = err?.message ?? "";

            if (errMsg.includes("ZK proof") || errMsg.includes("maxEpoch")) {
                // Epoch expired, ZK Proof invalid
                // EVE Vault will automatically pop up re-verification guidance
                alert("Your login has expired, please refresh login status in EVE Vault");
            } else if (errMsg.includes("User rejected")) {
                // User cancelled transaction on approval page
                console.log("User cancelled operation");
            } else {
                console.error("Transaction failed:", errMsg);
            }
        }
    };

    return <button onClick={handleTransaction} disabled={!isConnected}>Execute Operation</button>;
}

9. Listen for Network Switching

EVE Vault supports users switching between Devnet/Testnet. dApp needs to respond to this change:

import { useCurrentAccount } from "@mysten/dapp-kit-react";
import { useEffect } from "react";

function NetworkAwareComponent() {
    const account = useCurrentAccount();

    useEffect(() => {
        if (!account) return;

        // account.chains contains chains current wallet supports
        const currentChain = account.chains[0]; // "sui:testnet" or "sui:devnet"
        console.log("Current network:", currentChain);

        // Switch API endpoints or contract addresses based on network
    }, [account]);

    // ...
}

10. Message Signing (Personal Message)

import { useDAppKit } from "@mysten/dapp-kit-react";
import { toBase64 } from "@mysten/sui/utils";

function SignMessageButton() {
    const { signPersonalMessage } = useDAppKit();

    const handleSign = async () => {
        const message = new TextEncoder().encode("EVE Frontier Builder Auth: " + Date.now());

        const { bytes, signature } = await signPersonalMessage({
            message,
        });

        console.log("Message signature:", signature);
        // Can send signature to server to verify user identity (link game account to builder system)
    };

    return <button onClick={handleSign}>Verify Identity with EVE Vault</button>;
}

11. Complete Example: Gate Extension dApp

Here’s a minimal complete example integrating all features:

// src/App.tsx
import { useConnection, useSmartObject, abbreviateAddress } from "@evefrontier/dapp-kit";
import { useDAppKit } from "@mysten/dapp-kit-react";
import { useSponsoredTransaction } from "@evefrontier/dapp-kit";
import { Transaction } from "@mysten/sui/transactions";

const GATE_ITEM_ID = import.meta.env.VITE_GATE_ITEM_ID;
const PACKAGE_ID = import.meta.env.VITE_BUILDER_PACKAGE_ID;
const EXTENSION_CONFIG_ID = import.meta.env.VITE_EXTENSION_CONFIG_ID;

export function App() {
    const { handleConnect, handleDisconnect, isConnected, hasEveVault } = useConnection();
    const { assembly, loading } = useSmartObject({ itemId: GATE_ITEM_ID });
    const { signAndExecuteTransaction } = useDAppKit();
    const { sponsoredSignAndExecute } = useSponsoredTransaction();

    const requestJumpPermit = async () => {
        const tx = new Transaction();
        tx.moveCall({
            target: `${PACKAGE_ID}::tribe_permit::issue_jump_permit`,
            arguments: [tx.object(EXTENSION_CONFIG_ID), /* ... */],
        });
        await signAndExecuteTransaction({ transaction: tx });
    };

    const requestFreeJump = async () => {
        // Sponsored transaction version (Builder pays Gas)
        const tx = new Transaction();
        tx.moveCall({ /* same as above */ });
        await sponsoredSignAndExecute({ transaction: tx });
    };

    return (
        <div>
            {/* Top bar */}
            <header>
                <h1>Star Gate Manager</h1>
                <button onClick={isConnected ? handleDisconnect : handleConnect}>
                    {isConnected ? "Disconnect Wallet" : "Connect EVE Vault"}
                </button>
            </header>

            {/* Gate status card */}
            {!loading && assembly && (
                <div>
                    <h2>{assembly.name}</h2>
                    <p>Current status: {assembly.state}</p>
                </div>
            )}

            {/* Action buttons */}
            {isConnected && (
                <div>
                    <button onClick={requestJumpPermit}>Request Permit (Pay Gas)</button>
                    <button onClick={requestFreeJump}>Free Request (Sponsored Transaction)</button>
                </div>
            )}

            {/* EVE Vault not installed prompt */}
            {!hasEveVault && (
                <div style={{ background: "#fff3cd", padding: 12, borderRadius: 8 }}>
                    ⚠️ Please install{" "}
                    <a href="https://github.com/evefrontier/evevault/releases/latest/download/eve-vault-chrome.zip">
                        EVE Vault extension
                    </a>{" "}
                    to connect your EVE Frontier account
                </div>
            )}
        </div>
    );
}

12. Common Integration Issues

Chapter Summary

Further Reading

• EVE Vault GitHub
• Sui zkLogin Official Documentation
• Enoki Documentation
• Sui Wallet Standard
• @evefrontier/dapp-kit SDK Documentation

You now have mastered the complete knowledge system of the EVE Frontier Builder course: from Move 2024 basics to deep analysis of World contracts, from Builder Scaffold engineering practices to EVE Vault wallet integration. It’s time to leave your mark in the stars.

Example 4: Quest Unlock System (On-Chain Quests + Conditional Gate)

Goal: Build an on-chain quest system: players complete specified quests, on-chain records completion status; gate extension reads quest status, only allows players who completed quests to jump. Also provides quest publishing and verification dApp.

Status: Mapped to local code directory. Main content focuses on decoupling quest state and conditional gate, suitable for permission-based gameplay entry.

Code Directory

• example-04
• example-04/dapp

Minimal Call Chain

Register quest -> Player completes quest -> On-chain records status -> Gate reads quest status -> Allow or deny

Requirements Analysis

Scenario: You operate a gate leading to a high-value mining area. Players must first complete a series of “membership tests” to enter:

• 📋 Quest 1: Donate 100 units of ore to your storage box (verifiable on-chain)
• 🔑 Quest 2: Obtain on-chain certification issued by alliance Leader
• 🚪 Complete all quests → Can pass through the gate to enter mining area

Design Features:

• Quest status is entirely on-chain, cannot be forged
• Quest system and gate system are decoupled, easy to upgrade independently
• dApp provides quest progress tracking and one-click jump application

Part 1: Quest System Contract

quest_registry.move

module quest_system::registry;

use sui::object::{Self, UID, ID};
use sui::table::{Self, Table};
use sui::event;
use sui::tx_context::TxContext;
use sui::transfer;

/// Quest types (using u8 enum)
const QUEST_DONATE_ORE: u8 = 0;
const QUEST_LEADER_CERT: u8 = 1;

/// Quest completion status (bit flags)
/// bit 0: QUEST_DONATE_ORE completed
/// bit 1: QUEST_LEADER_CERT completed
const QUEST_ALL_COMPLETE: u64 = 0b11;

/// Quest Registry (shared object)
public struct QuestRegistry has key {
    id: UID,
    gate_id: ID,                          // Which gate this corresponds to
    completions: Table<address, u64>,     // address → completion bit flags
}

/// Quest admin credential
public struct QuestAdminCap has key, store {
    id: UID,
    registry_id: ID,
}

/// Events
public struct QuestCompleted has copy, drop {
    registry_id: ID,
    player: address,
    quest_type: u8,
    all_done: bool,
}

/// Deploy: Create quest registry
public fun create_registry(
    gate_id: ID,
    ctx: &mut TxContext,
) {
    let registry = QuestRegistry {
        id: object::new(ctx),
        gate_id,
        completions: table::new(ctx),
    };

    let admin_cap = QuestAdminCap {
        id: object::new(ctx),
        registry_id: object::id(&registry),
    };

    transfer::share_object(registry);
    transfer::transfer(admin_cap, ctx.sender());
}

/// Admin marks quest complete (called by alliance Leader or management script)
public fun mark_quest_complete(
    registry: &mut QuestRegistry,
    cap: &QuestAdminCap,
    player: address,
    quest_type: u8,
    ctx: &TxContext,
) {
    assert!(cap.registry_id == object::id(registry), ECapMismatch);

    // Initialize player entry
    if !table::contains(&registry.completions, player) {
        table::add(&mut registry.completions, player, 0u64);
    };

    let flags = table::borrow_mut(&mut registry.completions, player);
    *flags = *flags | (1u64 << (quest_type as u64));

    let all_done = *flags == QUEST_ALL_COMPLETE;

    event::emit(QuestCompleted {
        registry_id: object::id(registry),
        player,
        quest_type,
        all_done,
    });
}

/// Query if player completed all quests
public fun is_all_complete(registry: &QuestRegistry, player: address): bool {
    if !table::contains(&registry.completions, player) {
        return false
    }
    *table::borrow(&registry.completions, player) == QUEST_ALL_COMPLETE
}

/// Query which quests player completed
public fun get_completion_flags(registry: &QuestRegistry, player: address): u64 {
    if !table::contains(&registry.completions, player) {
        return 0
    }
    *table::borrow(&registry.completions, player)
}

const ECapMismatch: u64 = 0;

quest_gate.move (Gate Extension)

module quest_system::quest_gate;

use quest_system::registry::{Self, QuestRegistry};
use world::gate::{Self, Gate};
use world::character::Character;
use sui::clock::Clock;
use sui::tx_context::TxContext;

/// Gate extension Witness
public struct QuestGateAuth has drop {}

/// Request jump permit after completing quests
public fun quest_jump(
    source_gate: &Gate,
    dest_gate: &Gate,
    character: &Character,
    quest_registry: &QuestRegistry,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    // Verify caller completed all quests
    assert!(
        registry::is_all_complete(quest_registry, ctx.sender()),
        EQuestsNotComplete,
    );

    // Issue jump permit (valid for 30 minutes)
    let expires_at = clock.timestamp_ms() + 30 * 60 * 1000;

    gate::issue_jump_permit(
        source_gate,
        dest_gate,
        character,
        QuestGateAuth {},
        expires_at,
        ctx,
    );
}

const EQuestsNotComplete: u64 = 0;

Part 2: Quest Verification Logic (Quest 1: Donate Ore)

Quest 1 (donate ore) requires off-chain monitoring of SSU storage events, then admin manually (or script automatically) marks completion.

// scripts/auto-quest-monitor.ts
import { SuiClient } from "@mysten/sui/client"
import { Transaction } from "@mysten/sui/transactions"
import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519"

const QUEST_PACKAGE = "0x_QUEST_PACKAGE_"
const REGISTRY_ID = "0x_REGISTRY_ID_"
const QUEST_ADMIN_CAP_ID = "0x_QUEST_ADMIN_CAP_"
const STORAGE_UNIT_ID = "0x_SSU_ID_"
const DONATE_ORE_TYPE_ID = 12345 // Ore item type ID

const client = new SuiClient({ url: "https://fullnode.testnet.sui.io:443" })
const adminKeypair = Ed25519Keypair.fromSecretKey(/* ... */)

// Monitor SSU donation events
async function monitorDonations() {
  await client.subscribeEvent({
    filter: {
      MoveEventType: `${"0x_WORLD_PACKAGE_"}::storage_unit::ItemDeposited`,
    },
    onMessage: async (event) => {
      const { depositor, storage_unit_id, item_type_id } = event.parsedJson as any

      // Check if it's our SSU and specified item
      if (
        storage_unit_id === STORAGE_UNIT_ID &&
        Number(item_type_id) === DONATE_ORE_TYPE_ID
      ) {
        console.log(`Player ${depositor} donated ore, marking quest complete...`)
        await markQuestComplete(depositor, 0) // quest_type = 0 (QUEST_DONATE_ORE)
      }
    },
  })
}

async function markQuestComplete(player: string, questType: number) {
  const tx = new Transaction()
  tx.moveCall({
    target: `${QUEST_PACKAGE}::registry::mark_quest_complete`,
    arguments: [
      tx.object(REGISTRY_ID),
      tx.object(QUEST_ADMIN_CAP_ID),
      tx.pure.address(player),
      tx.pure.u8(questType),
    ],
  })

  const result = await client.signAndExecuteTransaction({
    signer: adminKeypair,
    transaction: tx,
  })
  console.log(`Quest marked successfully: ${result.digest}`)
}

monitorDonations()

Part 3: Quest Tracker dApp

// src/QuestTrackerApp.tsx
import { useState, useEffect } from 'react'
import { useConnection, getObjectWithJson } from '@evefrontier/dapp-kit'
import { useDAppKit } from '@mysten/dapp-kit-react'
import { Transaction } from '@mysten/sui/transactions'
import { SuiClient } from '@mysten/sui/client'

const QUEST_PACKAGE = "0x_QUEST_PACKAGE_"
const REGISTRY_ID = "0x_REGISTRY_ID_"
const SOURCE_GATE_ID = "0x..."
const DEST_GATE_ID = "0x..."
const CHARACTER_ID = "0x..."

const QUEST_NAMES = [
  { id: 0, name: 'Donate Ore', description: 'Deposit 100 units of ore into alliance storage' },
  { id: 1, name: 'Get Certified', description: 'Contact alliance Leader to issue on-chain certification' },
]

export function QuestTrackerApp() {
  const { isConnected, handleConnect, currentAddress } = useConnection()
  const dAppKit = useDAppKit()
  const [flags, setFlags] = useState<number>(0)
  const [isJumping, setIsJumping] = useState(false)
  const [status, setStatus] = useState('')

  const allComplete = flags === 0b11

  // Load quest completion status
  useEffect(() => {
    if (!currentAddress) return

    const loadFlags = async () => {
      // Read player entry in table via GraphQL
      const client = new SuiClient({ url: 'https://fullnode.testnet.sui.io:443' })
      const obj = await client.getDynamicFieldObject({
        parentId: REGISTRY_ID,
        name: {
          type: 'address',
          value: currentAddress,
        },
      })

      if (obj.data?.content?.dataType === 'moveObject') {
        setFlags(Number((obj.data.content.fields as any).value))
      } else {
        setFlags(0) // Player has no record yet
      }
    }

    loadFlags()
  }, [currentAddress])

  const handleJump = async () => {
    if (!allComplete) {
      setStatus('❌ Please complete all quests first')
      return
    }

    setIsJumping(true)
    setStatus('⏳ Requesting jump permit...')

    try {
      const tx = new Transaction()
      tx.moveCall({
        target: `${QUEST_PACKAGE}::quest_gate::quest_jump`,
        arguments: [
          tx.object(SOURCE_GATE_ID),
          tx.object(DEST_GATE_ID),
          tx.object(CHARACTER_ID),
          tx.object(REGISTRY_ID),
          tx.object('0x6'), // Clock
        ],
      })

      await dAppKit.signAndExecuteTransaction({ transaction: tx })
      setStatus('🚀 Jump permit obtained, enjoy the mining area!')
    } catch (e: any) {
      setStatus(`❌ ${e.message}`)
    } finally {
      setIsJumping(false)
    }
  }

  return (
    <div className="quest-tracker">
      <h1>🌟 Alliance Membership Test</h1>

      {!isConnected ? (
        <button onClick={handleConnect}>Connect Wallet</button>
      ) : (
        <>
          <div className="quest-list">
            {QUEST_NAMES.map(quest => {
              const done = (flags & (1 << quest.id)) !== 0
              return (
                <div key={quest.id} className={`quest-item ${done ? 'done' : 'pending'}`}>
                  <span className="quest-icon">{done ? '✅' : '⬜'}</span>
                  <div>
                    <strong>{quest.name}</strong>
                    <p>{quest.description}</p>
                  </div>
                </div>
              )
            })}
          </div>

          <div className="progress">
            Completion Progress: {Object.keys(QUEST_NAMES)
              .filter(i => (flags & (1 << Number(i))) !== 0).length} / {QUEST_NAMES.length}
          </div>

          <button
            className={`jump-btn ${allComplete ? 'active' : 'locked'}`}
            onClick={handleJump}
            disabled={!allComplete || isJumping}
          >
            {allComplete
              ? (isJumping ? '⏳ Requesting...' : '🚀 Enter Mining Area')
              : '🔒 Complete all quests to enter'
            }
          </button>

          {status && <p className="status">{status}</p>}
        </>
      )}
    </div>
  )
}

🎯 Complete Review

Contract Layer
├── quest_registry.move
│   ├── QuestRegistry (shared object, stores player completion bit flags)
│   ├── QuestAdminCap (admin credential)
│   ├── mark_quest_complete() ← Admin calls
│   └── is_all_complete()     ← Gate contract calls
│
└── quest_gate.move
    ├── QuestGateAuth (gate extension Witness)
    └── quest_jump()          ← Player calls
        ├── registry::is_all_complete() → Verify quest completion
        └── gate::issue_jump_permit()   → Issue permit

Off-Chain Monitoring
└── auto-quest-monitor.ts
    ├── Subscribe to SSU ItemDeposited events
    └── Automatically call mark_quest_complete()

dApp Layer
└── QuestTrackerApp.tsx
    ├── Display quest progress (decode bit flags)
    └── One-click jump permit request

🔧 Extension Exercises

1. Quest Expiration: Quests valid for 7 days after completion, expired need re-completion (store timestamp alongside bit flags)
2. On-Chain Quest 1 (no off-chain needed): Player actively calls donate_ore() function, directly transfers item, contract automatically marks quest complete
3. Quest Points: Each quest has different point weight, unlock gate when total reaches threshold

📚 Related Documentation

• Chapter 11: OwnerCap & Keychain
• Chapter 12: Bit Flags & Table
• Smart Gate Documentation

Practical Case 11: Item Rental System (Rent Instead of Sell)

Objective: Build an on-chain item rental marketplace—item owners rent out instead of selling equipment, renters have usage rights during the validity period, and items are automatically returned after expiration (or can be redeemed).

Status: Teaching example. The main text explains the core business flow, complete directory is based on local book/src/code/example-11/.

Corresponding Code Directory

• example-11
• example-11/dapp

Minimal Call Chain

Create listing -> User rents -> Contract mints RentalPass -> Expiration or early return -> Fund settlement

Test Loop

• Listing creation: Confirm is_available == true, and can be correctly queried by frontend
• Successful rental: Confirm renter receives RentalPass, owner receives 70% rent
• Early return: Confirm refund is calculated based on remaining days, remaining deposit correctly flows to owner
• Expiration reclaim: Confirm reclaim fails before expiration, succeeds after expiration

Requirements Analysis

Scenario: High-end ship modules are expensive, most players can’t afford them, but can rent them:

• Owner locks module into rental contract, sets daily rent and maximum rental period
• Renter pays rent, receives temporary usage rights credential NFT (RentalPass)
• Usage rights credential carries expiration timestamp, contract verifies validity when used
• After expiration, owner can reclaim the module (or renew)
• If renter returns early, refund remaining days’ rent

Part One: Rental Contract

module rental::equipment_rental;

use sui::object::{Self, UID, ID};
use sui::table::{Self, Table};
use sui::clock::Clock;
use sui::coin::{Self, Coin};
use sui::sui::SUI;
use sui::balance::{Self, Balance};
use sui::transfer;
use sui::event;
use std::string::String;

// ── Constants ──────────────────────────────────────────────────

const DAY_MS: u64 = 86_400_000;

// ── Data Structures ───────────────────────────────────────────────

/// Rental listing (locks item)
public struct RentalListing has key {
    id: UID,
    item_id: ID,              // Rented item object ID
    item_name: String,
    owner: address,
    daily_rate_sui: u64,      // Daily rent (MIST)
    max_days: u64,            // Maximum rental period
    deposited_balance: Balance<SUI>, // Owner's pre-deposited security deposit (optional)
    is_available: bool,
    current_renter: option::Option<address>,
    lease_expires_ms: u64,
}

/// Rental pass NFT (held by renter)
public struct RentalPass has key, store {
    id: UID,
    listing_id: ID,
    item_name: String,
    renter: address,
    expires_ms: u64,
    prepaid_days: u64,
    refundable_balance: Balance<SUI>, // Refundable balance (for early return)
}

// ── Events ──────────────────────────────────────────────────

public struct ItemRented has copy, drop {
    listing_id: ID,
    renter: address,
    days: u64,
    total_paid: u64,
    expires_ms: u64,
}

public struct ItemReturned has copy, drop {
    listing_id: ID,
    renter: address,
    early: bool,
    refund_amount: u64,
}

// ── Owner Operations ────────────────────────────────────────────

/// Create rental listing
public fun create_listing(
    item_name: vector<u8>,
    tracked_item_id: ID,       // Item's Object ID (contract tracks, actual item in SSU)
    daily_rate_sui: u64,
    max_days: u64,
    ctx: &mut TxContext,
) {
    let listing = RentalListing {
        id: object::new(ctx),
        item_id: tracked_item_id,
        item_name: std::string::utf8(item_name),
        owner: ctx.sender(),
        daily_rate_sui,
        max_days,
        deposited_balance: balance::zero(),
        is_available: true,
        current_renter: option::none(),
        lease_expires_ms: 0,
    };
    transfer::share_object(listing);
}

/// Delist (can only withdraw when item is not rented)
public fun delist(
    listing: &mut RentalListing,
    ctx: &TxContext,
) {
    assert!(listing.owner == ctx.sender(), ENotOwner);
    assert!(listing.is_available, EItemCurrentlyRented);
    listing.is_available = false;
}

// ── Renter Operations ────────────────────────────────────────────

/// Rent item
public fun rent_item(
    listing: &mut RentalListing,
    days: u64,
    mut payment: Coin<SUI>,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    assert!(listing.is_available, ENotAvailable);
    assert!(days >= 1 && days <= listing.max_days, EInvalidDays);

    let total_cost = listing.daily_rate_sui * days;
    assert!(coin::value(&payment) >= total_cost, EInsufficientPayment);

    let expires_ms = clock.timestamp_ms() + days * DAY_MS;

    // Deduct rent
    let rent_payment = payment.split(total_cost, ctx);
    // Send 70% to owner, remaining 30% locked in RentalPass as deposit (refunded on early return)
    let owner_share = rent_payment.split(total_cost * 70 / 100, ctx);
    transfer::public_transfer(owner_share, listing.owner);

    // Update listing state
    listing.is_available = false;
    listing.current_renter = option::some(ctx.sender());
    listing.lease_expires_ms = expires_ms;

    // Issue RentalPass NFT
    let pass = RentalPass {
        id: object::new(ctx),
        listing_id: object::id(listing),
        item_name: listing.item_name,
        renter: ctx.sender(),
        expires_ms,
        prepaid_days: days,
        refundable_balance: coin::into_balance(rent_payment), // Remaining 30%
    };

    // Return change
    if coin::value(&payment) > 0 {
        transfer::public_transfer(payment, ctx.sender());
    } else { coin::destroy_zero(payment); }

    transfer::public_transfer(pass, ctx.sender());

    event::emit(ItemRented {
        listing_id: object::id(listing),
        renter: ctx.sender(),
        days,
        total_paid: total_cost,
        expires_ms,
    });
}

/// Verify rental validity when using item
public fun verify_rental(
    pass: &RentalPass,
    listing_id: ID,
    clock: &Clock,
): bool {
    pass.listing_id == listing_id
        && clock.timestamp_ms() <= pass.expires_ms
}

/// Early return (refund deposit)
public fun return_early(
    listing: &mut RentalListing,
    mut pass: RentalPass,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    assert!(pass.listing_id == object::id(listing), EWrongListing);
    assert!(pass.renter == ctx.sender(), ENotRenter);
    assert!(clock.timestamp_ms() < pass.expires_ms, EAlreadyExpired);

    // Calculate refund for remaining days
    let remaining_ms = pass.expires_ms - clock.timestamp_ms();
    let remaining_days = remaining_ms / DAY_MS;
    let refund = if remaining_days > 0 {
        balance::value(&pass.refundable_balance) * remaining_days / pass.prepaid_days
    } else { 0 };

    // Refund
    if refund > 0 {
        let refund_coin = coin::take(&mut pass.refundable_balance, refund, ctx);
        transfer::public_transfer(refund_coin, ctx.sender());
    };

    // Destroy remaining deposit to owner
    let remaining_bal = balance::withdraw_all(&mut pass.refundable_balance);
    if balance::value(&remaining_bal) > 0 {
        transfer::public_transfer(coin::from_balance(remaining_bal, ctx), listing.owner);
    } else { balance::destroy_zero(remaining_bal); }

    // Return listing availability
    listing.is_available = true;
    listing.current_renter = option::none();

    let RentalPass { id, refundable_balance, .. } = pass;
    balance::destroy_zero(refundable_balance);
    id.delete();

    event::emit(ItemReturned {
        listing_id: object::id(listing),
        renter: ctx.sender(),
        early: true,
        refund_amount: refund,
    });
}

/// After rental expires, owner reclaims control
public fun reclaim_after_expiry(
    listing: &mut RentalListing,
    clock: &Clock,
    ctx: &TxContext,
) {
    assert!(listing.owner == ctx.sender(), ENotOwner);
    assert!(!listing.is_available, EAlreadyAvailable);
    assert!(clock.timestamp_ms() > listing.lease_expires_ms, ELeaseNotExpired);

    listing.is_available = true;
    listing.current_renter = option::none();
}

// ── Error Codes ────────────────────────────────────────────────
const ENotOwner: u64 = 0;
const EItemCurrentlyRented: u64 = 1;
const ENotAvailable: u64 = 2;
const EInvalidDays: u64 = 3;
const EInsufficientPayment: u64 = 4;
const EWrongListing: u64 = 5;
const ENotRenter: u64 = 6;
const EAlreadyExpired: u64 = 7;
const EAlreadyAvailable: u64 = 8;
const ELeaseNotExpired: u64 = 9;

Part Two: Rental Market dApp

// src/RentalMarket.tsx
import { useState } from 'react'
import { useCurrentClient } from '@mysten/dapp-kit-react'
import { useQuery } from '@tanstack/react-query'
import { Transaction } from '@mysten/sui/transactions'
import { useDAppKit } from '@mysten/dapp-kit-react'

const RENTAL_PKG = "0x_RENTAL_PACKAGE_"

interface Listing {
  id: string
  item_name: string
  owner: string
  daily_rate_sui: string
  max_days: string
  is_available: boolean
  lease_expires_ms: string
}

function DaysLeftBadge({ expireMs }: { expireMs: number }) {
  const remaining = Math.max(0, expireMs - Date.now())
  const days = Math.ceil(remaining / 86400000)
  if (days === 0) return <span className="badge badge--expired">Expired</span>
  return <span className="badge badge--active">{days} days remaining</span>
}

export function RentalMarket() {
  const client = useCurrentClient()
  const dAppKit = useDAppKit()
  const [rentDays, setRentDays] = useState(1)
  const [status, setStatus] = useState('')

  const { data: listings } = useQuery({
    queryKey: ['rental-listings'],
    queryFn: async () => {
      // Teaching example: directly read current listing objects.
      // Real projects should maintain "rentable listing" view through indexer, rather than reverse listing from rental events.
      const objects = await client.getOwnedObjects({
        owner: '0x_RENTAL_REGISTRY_OWNER_',
        filter: { StructType: `${RENTAL_PKG}::equipment_rental::RentalListing` },
        options: { showContent: true },
      })
      return objects.data.map(obj => (obj.data?.content as any)?.fields).filter(Boolean) as Listing[]
    },
  })

  const handleRent = async (listingId: string, dailyRate: number) => {
    const tx = new Transaction()
    const totalCost = BigInt(dailyRate * rentDays)
    const [payment] = tx.splitCoins(tx.gas, [tx.pure.u64(totalCost)])

    tx.moveCall({
      target: `${RENTAL_PKG}::equipment_rental::rent_item`,
      arguments: [
        tx.object(listingId),
        tx.pure.u64(rentDays),
        payment,
        tx.object('0x6'),
      ],
    })

    try {
      setStatus('Submitting rental transaction...')
      await dAppKit.signAndExecuteTransaction({ transaction: tx })
      setStatus('Rental successful! RentalPass sent to your wallet')
    } catch (e: any) {
      setStatus(`${e.message}`)
    }
  }

  return (
    <div className="rental-market">
      <h1>Equipment Rental Market</h1>
      <p className="subtitle">Rent instead of buy, flexibly use high-end equipment</p>

      <div className="rent-days-selector">
        <label>Rental Period:</label>
        {[1, 3, 7, 14, 30].map(d => (
          <button
            key={d}
            className={rentDays === d ? 'selected' : ''}
            onClick={() => setRentDays(d)}
          >
            {d} days
          </button>
        ))}
      </div>

      <div className="listings-grid">
        {listings?.map(listing => (
          <div key={listing.id} className="listing-card">
            <h3>{listing.item_name}</h3>
            <div className="listing-meta">
              <span>{Number(listing.daily_rate_sui) / 1e9} SUI/day</span>
              <span>Max {listing.max_days} days</span>
            </div>
            <div className="listing-cost">
              Rent {rentDays} days total: <strong>{Number(listing.daily_rate_sui) * rentDays / 1e9} SUI</strong>
            </div>
            {listing.is_available ? (
              <button
                className="rent-btn"
                onClick={() => handleRent(listing.id, Number(listing.daily_rate_sui))}
              >
                Rent Now
              </button>
            ) : (
              <DaysLeftBadge expireMs={Number(listing.lease_expires_ms)} />
            )}
          </div>
        ))}
      </div>

      {status && <p className="status">{status}</p>}
    </div>
  )
}

Key Design Highlights

Related Documentation

• Chapter 12: Dynamic Fields and Balance Management
• Chapter 14: Economic System Design

Chapter 11: Deep Dive into Ownership Model

Objective: Deeply understand EVE Frontier’s capability object system, master the complete lifecycle of OwnerCap, and learn to design secure delegation authorization and ownership transfer schemes.

Status: Advanced design chapter. Text focuses on OwnerCap, delegation, and ownership lifecycle.

11.1 Why Have a Dedicated Ownership Model?

When many newcomers first design a permission system, the intuition is:

• Record an owner address
• Check if the caller is this address for every operation

This approach is convenient in the short term, but once entering EVE Frontier’s world of “facilities that can be operated, transferred, delegated, and composed,” problems quickly emerge:

• Not delegable It’s hard to safely hand over partial power temporarily to others
• Not composable Permission rules scattered across functions, system becomes increasingly chaotic
• Cannot express fine-grained control Hard to express “can operate this turret, but not that gate”
• Not naturally transferable Once facilities, characters, and operating rights migrate, hardcoded addresses become fragile

EVE Frontier uses Sui’s native Capability object system. Its core idea isn’t “who are you,” but:

What permission object are you holding.

This transforms ownership from “account attribute” to “composable, transferable, verifiable on-chain entity.”

11.2 Permission Hierarchy Structure

GovernorCap (deployer holds — highest permission)
    │
    └── AdminACL (shared object — authorized server address list)
            │
            └── OwnerCap<T> (player holds — operation rights for specific objects)

GovernorCap: Game Operation Layer

GovernorCap is created during contract deployment, held by CCP Games (game operators). It can:

• Add/remove server authorization addresses to AdminACL
• Execute global configuration changes

As a Builder, you don’t need to worry about GovernorCap.

AdminACL: Server Authorization Layer

AdminACL is a shared object containing a list of authorized game server addresses.

Certain operations (like proximity proof, jump verification) require game server as sponsor to sign transactions:

// Verify if caller is authorized sponsor
public fun verify_sponsor(admin_acl: &AdminACL, ctx: &TxContext) {
    assert!(
        admin_acl.sponsors.contains(ctx.sponsor().unwrap()),
        EUnauthorizedSponsor
    );
}

This means: certain sensitive operations cannot be completed by players alone, must go through game server verification.

OwnerCap: Player Operation Layer

public struct OwnerCap<phantom T> has key {
    id: UID,
    authorized_object_id: ID,  // Only valid for this specific object
}

phantom T makes OwnerCap<Gate> and OwnerCap<StorageUnit> completely different types that cannot be mixed—this is type system level security guarantee.

Why Separate These Three Permission Layers?

You can think of them as three completely different responsibilities:

• GovernorCap Solves “world-level rules and global governance”
• AdminACL Solves “which servers or backend processes are trusted”
• OwnerCap Solves “which specific business entity can operate which facility”

Separating them has the biggest advantage: the system won’t mix “global governance rights” with “single facility operation rights” into one pot.

Otherwise you easily get this bad structure:

• One address is both server authorizer
• And all facility administrator
• And executor of certain temporary business

Once this address has problems, the entire system’s permission boundaries collapse.

11.3 Character as Keychain

All player’s OwnerCap are stored in the Character object, not sent directly to wallet address.

Player wallet address
    └── Character (shared object, mapped to wallet address)
            ├── OwnerCap<NetworkNode>  → Network node 0x...a1
            ├── OwnerCap<Gate>         → Gate 0x...b2
            ├── OwnerCap<StorageUnit>  → Storage box 0x...c3
            └── OwnerCap<Gate>         → Gate 0x...d4 (second gate)

Why this design?

• All asset ownership concentrated in Character, transferring Character equals transferring all assets
• Even if player changes wallet address, Character remains, assets aren’t lost
• Cooperates with alliance mechanisms for collective ownership management

One thing to note here:

Character isn’t just a simple wallet mapping layer, but a true permission container.

It organizes “people, characters, facilities, permissions” together across these dimensions:

• Wallet is signing entry
• Character is business entity
• OwnerCap is specific facility permissions
• Facility objects are controlled assets

The benefit of this is when you later do:

• Account migration
• Multi-sig control
• Alliance trusteeship
• Character transfer

You don’t need to rewrite an entire permission system, but make changes around the Character layer.

11.4 Complete Borrow-Use-Return Pattern

Executing any operation requiring OwnerCap must follow the “borrow → use → return” three-step atomic transaction:

// Character module provided interface
public fun borrow_owner_cap<T: key>(
    character: &mut Character,
    owner_cap_ticket: Receiving<OwnerCap<T>>,  // Use Receiving pattern
    ctx: &TxContext,
): (OwnerCap<T>, ReturnOwnerCapReceipt)        // Return Cap + hot potato receipt

public fun return_owner_cap<T: key>(
    character: &Character,
    owner_cap: OwnerCap<T>,
    receipt: ReturnOwnerCapReceipt,             // Must consume receipt
)

ReturnOwnerCapReceipt is a hot potato (no Abilities), ensuring OwnerCap must be returned, cannot be lost outside transaction.

What Does This Pattern Really Prevent?

It’s not simply for “elegant writing,” but prevents several very real risks:

• High-privilege objects intercepted mid-transaction
• Scripts forget to return permissions, leaving dangling state
• Extension logic brings permission objects into wrong paths
• In multi-step operations, permission boundaries become no longer auditable

Forcing borrow -> use -> return into the same transaction is like adding a hard constraint to high-privilege operations:

You can temporarily use it to do things, but cannot take it away.

Why Pair with Hot Potato Receipt?

Because relying only on “developer consciously calling return” isn’t enough.

As long as the type system allows you to skip the return step, someone will eventually:

• Forget in scripts
• Delete during refactoring
• Directly return in error branches

After adding receipt, compiler and type system will force you to complete the process together.

Complete TypeScript Call Example

import { Transaction } from "@mysten/sui/transactions";

const WORLD_PKG = "0x...";

async function bringGateOnline(
  tx: Transaction,
  characterId: string,
  ownerCapId: string,
  gateId: string,
  networkNodeId: string,
) {
  // ① Borrow OwnerCap
  const [ownerCap, receipt] = tx.moveCall({
    target: `${WORLD_PKG}::character::borrow_owner_cap`,
    typeArguments: [`${WORLD_PKG}::gate::Gate`],
    arguments: [
      tx.object(characterId),
      tx.receivingRef({ objectId: ownerCapId, version: "...", digest: "..." }),
    ],
  });

  // ② Use OwnerCap: bring gate online
  tx.moveCall({
    target: `${WORLD_PKG}::gate::online`,
    arguments: [
      tx.object(gateId),
      tx.object(networkNodeId),
      tx.object(ENERGY_CONFIG_ID),
      ownerCap,
    ],
  });

  // ③ Return OwnerCap (receipt consumed, hot potato makes this step unskippable)
  tx.moveCall({
    target: `${WORLD_PKG}::character::return_owner_cap`,
    arguments: [tx.object(characterId), ownerCap, receipt],
  });
}

11.5 Ownership Transfer Scenarios

Scenario 1: Transfer Control of Single Component

If you want to hand over control of one gate to an ally (but keep your Character and other facilities), you can transfer only the corresponding OwnerCap:

// Extract OwnerCap from your Character, send to ally
const tx = new Transaction();

// Extract OwnerCap (note this isn't borrowing, but transferring)
// Specific API subject to world contract, this is just conceptual
tx.moveCall({
  target: `${WORLD_PKG}::character::transfer_owner_cap`,
  typeArguments: [`${WORLD_PKG}::gate::Gate`],
  arguments: [
    tx.object(myCharacterId),
    tx.object(ownerCapId),
    tx.pure.address(allyAddress),  // Ally's Character address
  ],
});

Scenario 2: Transfer Complete Character (All Assets Packaged Transfer)

Transferring entire Character object allows corresponding wallet address to control all bound assets. Suitable for alliance overall asset handover, account trading scenarios.

Need to distinguish three actions that sound similar but are completely different:

• Transfer single OwnerCap Only hand over control of one facility
• Transfer Character Hand over entire chain of permissions and assets
• Delegate operation Don’t transfer ownership, only give limited operation capability

If these three aren’t separated, your product design will quickly become messy.

For example, alliance treasury scenario:

• Property rights may belong to alliance entity
• Daily operation rights may belong to on-duty members
• Emergency shutdown rights may belong only to core administrators

This requires you can’t just use “one owner” to express all relationships.

Scenario 3: Delegate Operation (Without Transferring Ownership)

By writing extension contracts, you can allow specific addresses to operate your facilities in limited scope without transferring OwnerCap:

// In your extension contract, maintain an operator whitelist
public struct OperatorRegistry has key {
    id: UID,
    operators: Table<address, bool>,
}

public fun delegated_action(
    registry: &OperatorRegistry,
    ctx: &TxContext,
) {
    // Verify caller is in operator list
    assert!(registry.operators.contains(ctx.sender()), ENotOperator);
    // ... execute operation
}

Easiest Pitfall in Delegation

Many people’s first delegation treats whitelist as “weakened ownership.” This isn’t enough.

A secure delegation design needs to answer at least:

• What actions can delegatee do, what can’t they do?
• Does delegation have time limits?
• Can delegation be revoked?
• Is delegation only valid for one facility?
• Can delegatee re-delegate?

If these boundaries aren’t written clearly, delegation becomes “invisible gifting rights” from “flexible authorization.”

11.6 OwnerCap Security Boundaries

Each OwnerCap Only Valid for One Object

public fun verify_owner_cap<T: key>(
    obj: &T,
    owner_cap: &OwnerCap<T>,
) {
    // authorized_object_id ensures this OwnerCap can only be used for corresponding object
    assert!(
        owner_cap.authorized_object_id == object::id(obj),
        EOwnerCapMismatch
    );
}

This means if you have two gates, you have two OwnerCap<Gate>, they cannot be used interchangeably.

Why is authorized_object_id So Critical?

Because phantom T only solves “object categories cannot mix,” but hasn’t solved “same category different instances cannot mix.”

For example:

• OwnerCap<Gate> can only be used for Gate, no problem
• But without authorized_object_id Your one Gate permission might incorrectly operate another Gate

So complete security boundaries are actually two layers:

1. Type boundary Gate and StorageUnit cannot mix
2. Instance boundary This Gate and that Gate also cannot mix

Losing OwnerCap Means Losing Control

If Character containing OwnerCap is transferred, you lose control of all facilities. Please safeguard your Character object’s ownership private key.

From operational perspective, more accurately, you need to protect not “some button permission,” but the entire business control chain:

• Wallet signing rights
• Character control rights
• OwnerCap collection inside Character
• Critical delegation configurations and multi-sig settings

Once this chain breaks, recovery cost is very high.

11.7 Advanced: Multi-sig & Alliance Co-ownership

Through Sui’s multisig functionality, an alliance can jointly control critical facilities:

# Create 2/3 multi-sig address (requires 2 out of 3 members to agree to operate)
sui keytool multi-sig-address \
  --pks <pk1> <pk2> <pk3> \
  --weights 1 1 1 \
  --threshold 2

Set Character’s control address to multi-sig address, alliance critical assets require multiple signatures to operate.

What’s Multi-sig Suitable For, What’s Not?

Multi-sig is very suitable for:

• Alliance treasury
• Ultra-high value infrastructure
• Critical parameter adjustments
• Upgrades & emergency shutdowns

Multi-sig not necessarily suitable for:

• High-frequency daily operations
• Player interactions requiring second-level response
• Large numbers of small repetitive management actions

So realistic practice usually isn’t “put everything on multi-sig,” but layer it:

• Core control rights on multi-sig
• Daily operational permissions released to execution layer through limited delegation

This is closer to real organizational structure.

Chapter Summary

Further Reading

• Ownership Model Documentation
• Smart Character Documentation
• character.move Source Code
• Sui Multi-sig Documentation
• Receiving Object Pattern

Chapter 12: Advanced Move — Generics, Dynamic Fields, and Event Systems

Goal: Master generics programming in Move, dynamic field storage, Table/VecMap data structures, and event systems, enabling you to independently design complex on-chain data models.

Status: Advanced design chapter. Main content focuses on generics, dynamic fields, events, and Table/VecMap.

12.1 Generics

Generics allow your code to work with multiple types while maintaining type safety. This is widely used in EVE Frontier’s OwnerCap.

Basic Generic Syntax

// T is a type parameter, similar to <T> in other languages
public struct Box<T: store> has key, store {
    id: UID,
    value: T,
}

// Generic function
public fun wrap<T: store>(value: T, ctx: &mut TxContext): Box<T> {
    Box { id: object::new(ctx), value }
}

public fun unwrap<T: store>(box: Box<T>): T {
    let Box { id, value } = box;
    id.delete();
    value
}

Phantom Type Parameters

phantom T doesn’t actually hold a value of type T, only used for type distinction:

// T is not actually used, but creates type distinction
public struct OwnerCap<phantom T> has key {
    id: UID,
    authorized_object_id: ID,
}

// These two are completely different types, the system won't confuse them
let gate_cap: OwnerCap<Gate> = ...;
let ssu_cap: OwnerCap<StorageUnit> = ...;

Generics with Constraints

// T must have both key and store abilities
public fun transfer_to_object<T: key + store, Container: key>(
    container: &mut Container,
    value: T,
) { ... }

// T must have copy and drop (temporary value, not an asset)
public fun log_value<T: copy + drop>(value: T) { ... }

Why Are Generics Particularly Important in Move?

Because many safety designs in Move don’t rely on “passing a string to identify the type,” but instead put the type itself into the interface.

The advantages of this approach:

• Type mismatches can be detected at compile time
• Permissions and object categories can be tightly bound
• You don’t need to manually write fragile type checks at runtime

What Does phantom Really Solve?

When you first see phantom T, it’s easy to think it’s just a syntax trick. Actually, it solves:

“I don’t need to actually store a T, but I need this type identity to participate in security boundaries.”

This is especially common in permission objects, because what permissions really care about is often not the data itself, but “who this permission card is for.”

When Should You Use Generics, and When Shouldn’t You?

Scenarios suitable for generics:

• Permission objects
• Generic containers
• Same logic serving multiple object types
• The type itself carries security meaning

Scenarios not suitable for over-genericization:

• Business semantics are already very specific
• Only one or two fixed object types
• Generics would significantly increase interface reading cost

In other words, generics aren’t for “looking advanced,” but for clearly expressing “this logic is naturally generic.”

12.2 Dynamic Fields

Sui has a powerful feature: Dynamic Fields, which allow you to add arbitrary key-value pairs to objects at runtime, without needing to define all fields at compile time.

Why Do We Need Dynamic Fields?

Suppose your storage box needs to support any type of item, and the item types are unknown at compile time:

// ❌ Inflexible way: fixed fields
public struct Inventory has key {
    id: UID,
    fuel: Option<u64>,
    ore: Option<u64>,
    // Adding new item types requires modifying the contract...
}

// ✅ Flexible way: dynamic fields
public struct Inventory has key {
    id: UID,
    // No predefined fields, use dynamic fields for storage
}

Dynamic Fields API

use sui::dynamic_field as df;
use sui::dynamic_object_field as dof;

// Add dynamic field (value is not an object type)
df::add(&mut inventory.id, b"fuel_amount", 1000u64);

// Read dynamic field
let fuel: &u64 = df::borrow(&inventory.id, b"fuel_amount");
let fuel_mut: &mut u64 = df::borrow_mut(&mut inventory.id, b"fuel_amount");

// Check if exists
let exists = df::exists_(&inventory.id, b"fuel_amount");

// Remove dynamic field
let old_value: u64 = df::remove(&mut inventory.id, b"fuel_amount");

// Dynamic object field (value itself is an object with independent ObjectID)
dof::add(&mut storage.id, item_type_id, item_object);
let item = dof::borrow<u64, Item>(&storage.id, item_type_id);
let item = dof::remove<u64, Item>(&mut storage.id, item_type_id);

Real Application in EVE Frontier

The Ephemeral Inventory in storage units is implemented using dynamic fields:

// Create ephemeral inventory for a specific character (using character OwnerCap ID as key)
df::add(
    &mut storage_unit.id,
    owner_cap_id,      // Use character's OwnerCap ID as key
    EphemeralInventory::new(ctx),
);

// Character accesses their own ephemeral inventory
let my_inventory = df::borrow_mut<ID, EphemeralInventory>(
    &mut storage_unit.id,
    my_owner_cap_id,
);

The Real Value of Dynamic Fields

Its greatest value isn’t “avoiding struct definition changes,” but:

Allowing objects to grow new sub-states at runtime, without having to hardcode all slots in advance.

This is especially critical for game-type systems, because many states are naturally open sets:

• A warehouse might contain many types of items
• A facility might serve many characters
• A market might have continuously new listings

If you write them all as fixed fields, your structure will quickly lose control.

When to Use dynamic_field vs dynamic_object_field?

A very practical decision criterion:

• Value is just a simple value or ordinary struct Use dynamic_field
• Value itself should also be an independent object Use dynamic_object_field

The latter is more suitable for:

• Needs independent object ID
• Needs to be transferred, referenced, or deleted separately
• May be operated on separately by other logic later

Most Common Mistakes with Dynamic Fields

1. Treating it as a “universal database”

Dynamic fields are very flexible, but not infinitely free. They bring:

• Higher read/write costs
• More complex index paths
• Higher debugging difficulty

2. Key design is too casual

If key design is unstable, you’ll encounter later:

• Can’t find original data for the same business entity
• Inconsistent mapping rules between off-chain and on-chain
• Data seems to be written successfully, but can’t be read back

3. Putting frequently traversed large collections directly in

Dynamic fields are suitable for locating by key, not naturally suited for high-frequency full traversal. As long as your business often needs to “scan all entries,” you need to start considering index and pagination strategies.

12.3 Table and VecMap: On-chain Collection Types

Table: Key-Value Mapping

use sui::table::{Self, Table};

public struct Registry has key {
    id: UID,
    members: Table<address, MemberInfo>,
}

// Add
table::add(&mut registry.members, member_addr, MemberInfo { ... });

// Query
let info = table::borrow(&registry.members, member_addr);
let info_mut = table::borrow_mut(&mut registry.members, member_addr);

// Existence check
let is_member = table::contains(&registry.members, member_addr);

// Remove
let old_info = table::remove(&mut registry.members, member_addr);

// Length
let count = table::length(&registry.members);

⚠️ Note: Each entry in a Table is an independent dynamic field on-chain, and each access has a separate cost. A transaction can access at most 1024 dynamic fields.

VecMap: Small-scale Ordered Mapping

use sui::vec_map::{Self, VecMap};

// VecMap is stored in object fields (not dynamic fields), suitable for small datasets
public struct Config has key {
    id: UID,
    toll_settings: VecMap<u64, u64>,  // zone_id -> toll_amount
}

// Operations
vec_map::insert(&mut config.toll_settings, zone_id, amount);
let amount = vec_map::get(&config.toll_settings, &zone_id);
vec_map::remove(&mut config.toll_settings, &zone_id);

Selection Recommendations

What Essentially Is Table?

It’s essentially not a “hash table in memory,” but an on-chain collection abstraction built on dynamic fields.

So when using Table, you should always remember three things:

• Each read/write has real on-chain cost
• The more entries, the more strategy needed for operations and troubleshooting
• It’s more like an “extensible index structure,” not a local container to use casually

Why Is VecMap Suitable for Small-scale Configuration?

Because it stores data directly in object fields, usually more suitable for:

• Small number of configuration items
• Needs full reading
• Needs traversal by insertion order or small scale

Typical examples include:

• Fee tier tables
• Small-scale whitelists
• Mode switch configurations

What to Really Ask When Choosing Types

Don’t just ask “can this container store it,” but ask:

1. How large will this collection grow?
2. Am I doing exact key lookups, or frequently traversing all?
3. Are the values independent objects?
4. Will I need to do pagination and indexing on it in the future?

Once these four questions are answered, container selection usually won’t be too off.

12.4 Event Systems

Events are the bridge between on-chain contracts and off-chain applications. Events are not stored in on-chain state, but are attached to transaction records and can be captured by indexers.

Defining and Emitting Events

use sui::event;

// Event struct: only needs copy + drop
public struct GateJumped has copy, drop {
    gate_id: ID,
    character_id: ID,
    destination_gate_id: ID,
    timestamp_ms: u64,
    toll_paid: u64,
}

public struct ItemSold has copy, drop {
    storage_unit_id: ID,
    seller: address,
    buyer: address,
    item_type_id: u64,
    price: u64,
}

// Emit event in function
public fun process_purchase(
    storage_unit: &mut StorageUnit,
    buyer: &Character,
    payment: Coin<SUI>,
    item_type_id: u64,
    ctx: &mut TxContext,
): Item {
    let price = coin::value(&payment);
    // ... process purchase logic ...

    // Emit event (no gas consumption difference, emission is free index recording)
    event::emit(ItemSold {
        storage_unit_id: object::id(storage_unit),
        seller: storage_unit.owner_address,
        buyer: ctx.sender(),
        item_type_id,
        price,
    });

    // ... return item ...
}

The most easily misunderstood aspect of events:

It’s a record of “what happened in the transaction,” not the source of truth for “what the current system state is.”

This sentence is very important. Because many frontend or index design problems start from treating events as state.

What Are Events Suitable for Expressing?

Most suitable for expressing:

• Something just happened
• Who triggered it
• What were the key parameters at the time
• What should off-chain systems do based on this subscription or notification

For example:

• Transaction records
• Jump records
• Claim triggers
• Authorization changes

What Should Events Not Independently Bear?

Not suitable for independently bearing:

• Current inventory truth
• Whether the current object is online
• Complete business state of a current facility

Because events are naturally timelines, not current state snapshots.

Listening to Events in TypeScript

import { SuiClient } from "@mysten/sui/client";

const client = new SuiClient({ url: "https://fullnode.testnet.sui.io:443" });

// Query historical events
const events = await client.queryEvents({
  query: {
    MoveEventType: `${MY_PACKAGE}::toll_gate_ext::GateJumped`,
  },
  limit: 50,
});

events.data.forEach(event => {
  const fields = event.parsedJson as {
    gate_id: string;
    character_id: string;
    toll_paid: string;
  };
  console.log(`Jump: ${fields.character_id} paid ${fields.toll_paid}`);
});

// Real-time subscription (WebSocket)
const unsubscribe = await client.subscribeEvent({
  filter: { Package: MY_PACKAGE },
  onMessage: (event) => {
    console.log("New event:", event.type, event.parsedJson);
  },
});

// Stop subscription
setTimeout(() => unsubscribe(), 60_000);

When Designing Events, How to Think About Fields?

A good event should at least answer:

1. Who did it
2. On which object
3. What did they do
4. What are the key business parameters
5. How should off-chain systems locate related objects based on this

If there are too few fields, off-chain is hard to consume; too many fields will bloat the event and blur semantics.

A Very Practical Combination Principle

Mature on-chain systems usually adopt this combination:

• Objects Store current state
• Events Store historical actions
• Index layer Reorganize objects and events into data views that are easy for frontends to use

This is also why when you read GraphQL, indexer, and dApp chapters later, you’ll always see “object queries + event queries” appearing together.

Driving dApp Real-time Updates with Events

// src/hooks/useGateEvents.ts
import { useEffect, useState } from 'react'
import { SuiClient } from '@mysten/sui/client'

interface JumpEvent {
  gate_id: string
  character_id: string
  toll_paid: string
  timestamp_ms: string
}

export function useGateEvents(packageId: string) {
  const [events, setEvents] = useState<JumpEvent[]>([])

  useEffect(() => {
    const client = new SuiClient({ url: 'https://fullnode.testnet.sui.io:443' })

    const subscribe = async () => {
      await client.subscribeEvent({
        filter: { MoveEventType: `${packageId}::toll_gate_ext::GateJumped` },
        onMessage: (event) => {
          setEvents(prev => [event.parsedJson as JumpEvent, ...prev.slice(0, 49)])
        },
      })
    }

    subscribe()
  }, [packageId])

  return events
}

12.5 Dynamic Fields vs Events Use Cases

12.6 Practice: Designing a Trackable Auction State Machine

Integrating the knowledge from this chapter, design a complex auction state object:

module my_auction::auction;

use sui::object::{Self, UID, ID};
use sui::table::{Self, Table};
use sui::event;
use sui::clock::Clock;

/// Auction status enumeration (represented by u8)
const STATUS_OPEN: u8 = 0;
const STATUS_ENDED: u8 = 1;
const STATUS_CANCELLED: u8 = 2;

/// Auction object
public struct Auction<phantom ItemType: key + store> has key {
    id: UID,
    status: u8,
    min_bid: u64,
    current_bid: u64,
    current_winner: Option<address>,
    end_time_ms: u64,
    bid_history_count: u64,
    // Bid history stored with dynamic fields (avoid large objects)
}

/// Bid event
public struct BidPlaced has copy, drop {
    auction_id: ID,
    bidder: address,
    amount: u64,
    timestamp_ms: u64,
}

/// Bid function
public fun place_bid<T: key + store>(
    auction: &mut Auction<T>,
    payment: Coin<SUI>,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    let bid_amount = coin::value(&payment);
    let now = clock.timestamp_ms();

    // Verification
    assert!(auction.status == STATUS_OPEN, EAuctionNotOpen);
    assert!(now < auction.end_time_ms, EAuctionEnded);
    assert!(bid_amount > auction.current_bid, EBidTooLow);

    // Refund previous bidder's bid (simplified version)
    // ...

    // Update auction state
    auction.current_bid = bid_amount;
    auction.current_winner = option::some(ctx.sender());

    // Record bid history (using dynamic fields)
    let bid_key = auction.bid_history_count;
    auction.bid_history_count = bid_key + 1;
    df::add(&mut auction.id, bid_key, BidRecord {
        bidder: ctx.sender(),
        amount: bid_amount,
        timestamp_ms: now,
    });

    // Emit event (for dApp real-time display)
    event::emit(BidPlaced {
        auction_id: object::id(auction),
        bidder: ctx.sender(),
        amount: bid_amount,
        timestamp_ms: now,
    });
}

🔖 Chapter Summary

📚 Further Reading

• Sui Dynamic Fields Documentation
• Move Book: Generics
• Sui Events Documentation
• inventory.move

Chapter 13: NFT Design & Metadata Management

Goal: Master Sui’s NFT standard (Display), design evolvable dynamic NFTs, and apply NFTs as permission credentials, achievement badges, and game assets in the EVE Frontier ecosystem.

Status: Advanced design chapter. Main content focuses on NFT standards, dynamic metadata, and Collection patterns.

13.1 Sui’s NFT Model

On Sui, an NFT is simply a unique object with the key ability. There’s no special “NFT contract” - any object with a unique ObjectID is naturally an NFT:

// Simplest NFT
public struct Badge has key, store {
    id: UID,
    name: vector<u8>,
    description: vector<u8>,
    image_url: vector<u8>,
}

The most important understanding isn’t “NFTs can display images,” but rather:

An NFT on Sui is first an object, and second a collectible or display item.

This means you can naturally use NFTs in three different scenarios:

• Pure display Badges, memorabilia, achievement proofs
• Permission-based Passes, membership cards, whitelist credentials
• Functional Upgradeable ships, equipment, subscriptions, rental certificates

The design priorities for these three types of NFTs are completely different.

Four questions to ask before designing an NFT

1. Is it primarily a display item, permission card, or operational asset?
2. Is it transferable?
3. Will its metadata change?
4. Should frontends and markets treat it as a “tradable commodity”?

If these four questions aren’t answered clearly, the subsequent Display, Collection, and TransferPolicy will be easy to misalign.

13.2 Sui Display Standard: Making NFTs Display Correctly Everywhere

The Display object tells wallets and markets how to display your NFT:

module my_nft::space_badge;

use sui::display;
use sui::package;
use std::string::utf8;

// One-time witness (create Publisher)
public struct SPACE_BADGE has drop {}

public struct SpaceBadge has key, store {
    id: UID,
    name: String,
    tier: u8,           // 1=Bronze, 2=Silver, 3=Gold
    earned_at_ms: u64,
    image_url: String,
}

fun init(witness: SPACE_BADGE, ctx: &mut TxContext) {
    // 1. Use OTW to create Publisher (prove package author identity)
    let publisher = package::claim(witness, ctx);

    // 2. Create Display (define how to display SpaceBadge)
    let mut display = display::new_with_fields<SpaceBadge>(
        &publisher,
        // Field name   // Template value ({field_name} will be replaced by actual field value)
        vector[
            utf8(b"name"),
            utf8(b"description"),
            utf8(b"image_url"),
            utf8(b"project_url"),
        ],
        vector[
            utf8(b"{name}"),                                          // NFT name
            utf8(b"EVE Frontier Builder Badge - Tier {tier}"),        // Description
            utf8(b"{image_url}"),                                     // Image URL
            utf8(b"https://evefrontier.com"),                         // Project link
        ],
        ctx,
    );

    // 3. Submit Display (freeze version, make it externally visible)
    display::update_version(&mut display);

    // 4. Transfer (Publisher to deployer, Display shared or frozen)
    transfer::public_transfer(publisher, ctx.sender());
    transfer::public_freeze_object(display);
}

What does Display really solve?

It solves the interpretation layer problem between “on-chain object fields” and “wallet and market display content.”

Without this layer:

• Wallets can only see raw fields
• Markets have difficulty uniformly displaying name, description, image
• The same type of NFT will display inconsistently across different frontends

So Display isn’t decoration, it’s part of the NFT product experience.

Most common mistakes when designing Display

1. Stuffing all display semantics into on-chain fields

Not all display copy needs to be mutable on-chain fields. Some stable descriptions are better suited for templates, while some dynamic state is better suited for fields.

2. Over-relying on external image URLs

If image resource paths are unstable, the NFT itself still exists, but the user-visible experience will collapse.

3. Field naming disconnected from frontend understanding

If on-chain fields are named too internally, the frontend and wallet layer will have difficulty interpreting them stably.

13.3 Dynamic NFTs: Evolving Metadata

EVE Frontier’s game state changes in real-time, and your NFT metadata can change along with it:

module my_nft::evolving_ship;

/// Evolvable ship NFT
public struct EvolvingShip has key, store {
    id: UID,
    name: String,
    hull_class: u8,        // 0=Frigate, 1=Cruiser, 2=Battleship
    combat_score: u64,     // Combat points (increase with battles)
    kills: u64,            // Kill count
    image_url: String,     // Changes based on hull_class
}

/// Record combat result (called by turret contract)
public fun record_kill(
    ship: &mut EvolvingShip,
    ctx: &TxContext,
) {
    ship.kills = ship.kills + 1;
    ship.combat_score = ship.combat_score + 100;

    // Upgrade ship level (evolution)
    if ship.combat_score >= 10_000 && ship.hull_class < 2 {
        ship.hull_class = ship.hull_class + 1;
        // Update image URL (point to higher-level asset)
        ship.image_url = get_image_url(ship.hull_class);
    }
}

fun get_image_url(class: u8): String {
    let base = b"https://assets.evefrontier.com/ships/";
    let suffix = if class == 0 { b"frigate.png" }
                 else if class == 1 { b"cruiser.png" }
                 else { b"battleship.png" };
    // Concatenate URL (string operations in Move use sui::string)
    let mut url = std::string::utf8(base);
    url.append(std::string::utf8(suffix));
    url
}

Display template auto-updates: Since Display renders using current values of fields like {hull_class} and {image_url}, when fields change, the NFT’s display in wallets also updates immediately.

What are dynamic NFTs suited for and not suited for?

Suited for:

• Growth-oriented assets
• Items whose value is affected by state
• In-game combat records, achievements, proficiency mappings

Not necessarily suited for:

• Collectibles emphasizing static scarcity narratives
• Assets where the secondary market heavily relies on fixed metadata

Because once metadata is mutable, you’ve introduced new product issues by default:

• Who can modify it?
• Are changes auditable?
• When players buy in, are they buying the current state or a potentially changing future state?

Key boundaries of dynamic metadata design

• Is state change traceable on-chain Best to have event records
• Are modification permissions clear Not just any module can arbitrarily modify
• Can the frontend correctly reflect changes Otherwise on-chain changes while user interface stays on old image

13.4 Collection Pattern

module my_nft::badge_collection;

/// Badge series collection (meta-object, describes this NFT series)
public struct BadgeCollection has key {
    id: UID,
    name: String,
    total_supply: u64,
    minted_count: u64,
    admin: address,
}

/// Individual badge
public struct AllianceBadge has key, store {
    id: UID,
    collection_id: ID,      // Which collection it belongs to
    serial_number: u64,     // Series number (nth minted)
    tier: u8,
    attributes: vector<NFTAttribute>,
}

public struct NFTAttribute has store, copy, drop {
    trait_type: String,
    value: String,
}

/// Mint badge (track number and total)
public fun mint_badge(
    collection: &mut BadgeCollection,
    recipient: address,
    tier: u8,
    attributes: vector<NFTAttribute>,
    ctx: &mut TxContext,
) {
    assert!(ctx.sender() == collection.admin, ENotAdmin);
    assert!(collection.minted_count < collection.total_supply, ESoldOut);

    collection.minted_count = collection.minted_count + 1;

    let badge = AllianceBadge {
        id: object::new(ctx),
        collection_id: object::id(collection),
        serial_number: collection.minted_count,
        tier,
        attributes,
    };

    transfer::public_transfer(badge, recipient);
}

The value of Collection isn’t just “categorizing a batch of NFTs,” but making series management clear:

• Supply control
• Number tracking
• Official series identity
• Frontend aggregated display

What problems are Collections best suited to solve?

• Whether a certain series is sold out
• Which series does asset #N belong to
• Whether a badge comes from that official issuance system

Without this collection layer, doing these later becomes much harder:

• Series pages
• Rarity statistics
• Official certification

13.5 NFTs as Access Control Credentials

In EVE Frontier, NFTs are the most natural permission carriers:

// Using NFTs to check permissions
public fun enter_restricted_zone(
    gate: &Gate,
    character: &Character,
    badge: &AllianceBadge,   // Must hold badge to call
    clock: &Clock,
    ctx: &mut TxContext,
) {
    // Verify badge tier (need gold badge to enter)
    assert!(badge.tier >= 3, EInsufficientBadgeTier);
    // Verify badge belongs to correct collection (prevent forgery)
    assert!(badge.collection_id == OFFICIAL_COLLECTION_ID, EWrongCollection);
    // ...
}

This is one of the most practical NFT use cases in EVE Builder, because it makes “permission” into an object that players can actually hold and understand.

Why are permission NFTs often better than address whitelists?

Because they’re more flexible and product-oriented:

• Can be transferred
• Can be revoked
• Can have tiers
• Can have expiration times
• Frontend can intuitively display them

But you must be careful of one thing:

As long as it’s transferable, the permission flows with it.

So you must first decide whether this permission NFT should be:

• A transferable market asset
• Or a non-transferable identity credential

13.6 NFT Transfer Policies

Sui supports flexible NFT transfer policies:

// Default: anyone can transfer (public_transfer)
transfer::public_transfer(badge, recipient);

// Lock-up: NFT can only be moved by specific contracts (via TransferPolicy)
use sui::transfer_policy;

// Establish TransferPolicy during package initialization (restrict transfer conditions)
fun init(witness: SPACE_BADGE, ctx: &mut TxContext) {
    let publisher = package::claim(witness, ctx);
    let (policy, policy_cap) = transfer_policy::new<SpaceBadge>(&publisher, ctx);

    // Add custom rules (such as royalty payments)
    // royalty_rule::add(&mut policy, &policy_cap, 200, 0); // 2% royalty

    transfer::public_share_object(policy);
    transfer::public_transfer(policy_cap, ctx.sender());
    transfer::public_transfer(publisher, ctx.sender());
}

Transfer policy essentially defines “the social attributes of this NFT”

• Free transfer More like a commodity
• Restricted transfer More like a permit with rules
• Non-transferable More like identity or achievement

This isn’t a technical detail, it’s product positioning.

If your NFT is:

• Membership status
• Real-name credential
• Alliance internal identity card

Then default free transfer often isn’t a good idea.

13.7 Embedding NFTs in EVE Frontier Assets (Object Owns Object)

// Ship equipment NFT (owned by ship object)
public struct Equipment has key, store {
    id: UID,
    name: String,
    stat_bonus: u64,
}

public struct Ship has key {
    id: UID,
    // Equipment embedded in Ship object (object owns object)
    equipped_items: vector<Equipment>,
}

// Equip item to ship
public fun equip(
    ship: &mut Ship,
    equipment: Equipment,  // Equipment moves from player wallet into Ship
    ctx: &TxContext,
) {
    vector::push_back(&mut ship.equipped_items, equipment);
}

Object-owns-object design is especially natural for game assets, because it allows you to express:

• A ship owns multiple pieces of equipment
• A character owns a set of certificates
• A container holds multiple special assets

When should NFTs exist independently vs. be embedded?

Suited for independent existence:

• Need to trade separately
• Need to display separately
• Need to authorize or transfer separately

Suited for embedding into other objects:

• Mainly as a component of a larger object
• Don’t need frequent independent circulation
• More emphasis on combined overall state

This is essentially balancing “tradability” and “compositional expressiveness.”

Chapter Summary

Further Reading

• Sui Display Standard
• Sui NFT Guide
• Move Book: Object Owns Object

Chapter 14: On-chain Economic System Design

Goal: Learn to design and implement complete on-chain economic systems in EVE Frontier, including custom token issuance, decentralized markets, dynamic pricing, and vault management.

Status: Advanced design chapter. Main content focuses on tokens, markets, vaults, and pricing mechanisms.

14.1 EVE Frontier’s Economic System

EVE Frontier itself already has two official currencies:

As a Builder, you can:

1. Accept LUX/SUI as payment methods (directly use official Coin types)
2. Issue your own alliance token (custom Coin module)
3. Build markets and trading mechanisms (based on SSU extensions)

The most important thing here isn’t the capabilities themselves of “being able to issue tokens and charge fees,” but first distinguishing:

What is your economic system actually selling, why would anyone continue to pay, and under what circumstances will it be arbitraged or drained.

Many on-chain economic designs fail not because the code was wrong, but because they never figured out these things from the start:

• Are you selling one-time items, ongoing services, or access qualifications?
• Is revenue settled immediately or distributed long-term?
• Who determines the price? Fixed, algorithmic, auction, or manual operation?
• Why would players keep assets in your system rather than use and leave?

First distinguish four most common Builder fee models

Before designing an economic system, you’d better first clarify which category you belong to. Because they correspond to completely different object models, event designs, and risk controls.

14.2 Issuing Custom Tokens (Custom Coin)

Sui’s token (Coin) model is very standardized. Through the sui::coin module, you can create any Fungible Token:

module my_alliance::alliance_token;

use sui::coin::{Self, Coin, TreasuryCap};
use sui::object::UID;
use sui::transfer;
use sui::tx_context::TxContext;

/// Token's "One-Time Witness"
/// Must match module name (all caps), can only be created during init
public struct ALLIANCE_TOKEN has drop {}

/// Token metadata (name, symbol, decimals)
fun init(witness: ALLIANCE_TOKEN, ctx: &mut TxContext) {
    let (treasury_cap, coin_metadata) = coin::create_currency(
        witness,
        6,                            // Decimals
        b"ALLY",                      // Token symbol
        b"Alliance Token",            // Token full name
        b"The official token of Alliance X",  // Description
        option::none(),               // Icon URL (optional)
        ctx,
    );

    // Transfer TreasuryCap to deployer (minting rights)
    transfer::public_transfer(treasury_cap, ctx.sender());
    // Share CoinMetadata (for DEX, wallet display)
    transfer::public_share_object(coin_metadata);
}

/// Mint tokens (only holder of TreasuryCap can call)
public fun mint(
    treasury: &mut TreasuryCap<ALLIANCE_TOKEN>,
    amount: u64,
    recipient: address,
    ctx: &mut TxContext,
) {
    let coin = coin::mint(treasury, amount, ctx);
    transfer::public_transfer(coin, recipient);
}

/// Burn tokens (reduce total supply)
public fun burn(
    treasury: &mut TreasuryCap<ALLIANCE_TOKEN>,
    coin: Coin<ALLIANCE_TOKEN>,
) {
    coin::burn(treasury, coin);
}

Issuing tokens is technically simple, but economically most easily misused.

Three questions to ask before issuing tokens

1. Why does this token exist?

Common reasonable uses include:

• Alliance internal accounting and incentives
• Protocol internal discounts, revenue sharing, or voting credentials
• Some service quota or access layer

If the answer is just “everyone has tokens, so I’ll issue one too,” it’s probably not worth doing.

2. Does this token really need on-chain circulation?

Some points-based systems don’t actually need an independent coin, better suited for:

• On-chain scoring objects
• Non-transferable badges
• Vault share records

Because once you make it a truly transferable Coin, you’ve introduced by default:

• Secondary markets
• Hoarding and speculation
• Liquidity expectations
• Higher compliance and operational burden

3. Who controls supply, how does supply grow?

TreasuryCap technically represents minting rights, economically represents monetary sovereignty. As long as the supply strategy is vague, it’s easy to evolve into:

• Builder arbitrarily inflating
• Early users being diluted
• Price and expectations rapidly collapsing

What does One-Time Witness solve and not solve?

It solves:

• Coin type creation identity uniqueness
• Initialization path standardization
• Metadata and TreasuryCap creation process security

It doesn’t solve:

• Whether your supply curve is reasonable
• Whether the coin has demand
• Whether the coin price is stable

In other words, the language ensures “coins won’t be randomly forged,” but won’t ensure “you issued a good coin.”

14.3 Building Decentralized Markets

Based on Smart Storage Unit, you can build decentralized item markets:

module my_market::item_market;

use world::storage_unit::{Self, StorageUnit};
use world::character::Character;
use world::inventory::Item;
use sui::coin::{Self, Coin};
use sui::sui::SUI;
use sui::table::{Self, Table};
use sui::object::{Self, ID};
use sui::event;

/// Market extension Witness
public struct MarketAuth has drop {}

/// Item listing information
public struct Listing has store {
    seller: address,
    item_type_id: u64,
    price: u64,           // In MIST (SUI's smallest unit)
    expiry_ms: u64,       // 0 = never expires
}

/// Market registry
public struct Market has key {
    id: UID,
    storage_unit_id: ID,
    listings: Table<u64, Listing>,  // item_type_id -> Listing
    fee_rate_bps: u64,              // Fee (basis points, 100 bps = 1%)
    fee_balance: Balance<SUI>,
}

/// Events
public struct ItemListed has copy, drop {
    market_id: ID,
    seller: address,
    item_type_id: u64,
    price: u64,
}

public struct ItemSold has copy, drop {
    market_id: ID,
    buyer: address,
    seller: address,
    item_type_id: u64,
    price: u64,
    fee: u64,
}

/// List item
public fun list_item(
    market: &mut Market,
    storage_unit: &mut StorageUnit,
    character: &Character,
    item_type_id: u64,
    price: u64,
    expiry_ms: u64,
    ctx: &mut TxContext,
) {
    // Withdraw item from storage box, store in market's dedicated temporary warehouse
    // (Implementation detail: use MarketAuth{} to call SSU's withdraw_item)
    // ...

    // Record listing information
    table::add(&mut market.listings, item_type_id, Listing {
        seller: ctx.sender(),
        item_type_id,
        price,
        expiry_ms,
    });

    event::emit(ItemListed {
        market_id: object::id(market),
        seller: ctx.sender(),
        item_type_id,
        price,
    });
}

/// Buy item
public fun buy_item(
    market: &mut Market,
    storage_unit: &mut StorageUnit,
    character: &Character,
    item_type_id: u64,
    mut payment: Coin<SUI>,
    clock: &Clock,
    ctx: &mut TxContext,
): Item {
    let listing = table::borrow(&market.listings, item_type_id);

    // Check expiration
    if listing.expiry_ms > 0 {
        assert!(clock.timestamp_ms() < listing.expiry_ms, EListingExpired);
    }

    // Verify payment amount
    assert!(coin::value(&payment) >= listing.price, EInsufficientPayment);

    // Deduct fee
    let fee = listing.price * market.fee_rate_bps / 10_000;
    let seller_amount = listing.price - fee;

    // Split coins: fee + seller revenue + change
    let fee_coin = payment.split(fee, ctx);
    let seller_coin = payment.split(seller_amount, ctx);
    let change = payment;  // Remaining change

    balance::join(&mut market.fee_balance, coin::into_balance(fee_coin));
    transfer::public_transfer(seller_coin, listing.seller);
    transfer::public_transfer(change, ctx.sender());

    let seller_addr = listing.seller;
    let price = listing.price;

    // Remove listing record
    table::remove(&mut market.listings, item_type_id);

    event::emit(ItemSold {
        market_id: object::id(market),
        buyer: ctx.sender(),
        seller: seller_addr,
        item_type_id,
        price,
        fee,
    });

    // Withdraw item from SSU to buyer
    storage_unit::withdraw_item(
        storage_unit, character, MarketAuth {}, item_type_id, ctx,
    )
}

This market example already illustrates the basic structure, but for real design you need to think through a few more things.

What are the minimum four layers a market contains?

1. Order layer What seller provides, what price, when expires
2. Custody layer Who holds items and funds, when are they actually transferred
3. Settlement layer How are fees, seller revenue, change distributed
4. Index layer How does frontend query current buyable list, not just historical events

Missing any of these four layers, you can “write code” but can’t write a stable market.

Most easily missed boundaries in market design

1. When listing, is the item actually locked?

If only Listing is recorded, but the item itself isn’t securely held:

• Seller might have already moved the item
• Frontend still shows “available for purchase”
• Buyer pays and finds out delivery is impossible

2. Are payment and delivery in the same atomic transaction?

If payment succeeds but delivery fails, or delivery succeeds but payment fails, both cause serious experience and asset issues. One core value of on-chain markets is putting these two actions into the same atomic transaction.

3. Are delist, expiration, re-listing paths closed?

Many markets don’t have problems with listing and purchasing, but rather:

• Expired entries still in list
• Inventory doesn’t return after delisting
• Re-listing causes state confusion

14.4 Dynamic Pricing Strategies

Strategy One: Fixed Price

Simplest pricing, Owner sets price, players buy at price (like the market example above).

Strategy Two: Dutch Auction (Decreasing Price)

public fun get_current_price(
    start_price: u64,
    end_price: u64,
    start_time_ms: u64,
    duration_ms: u64,
    clock: &Clock,
): u64 {
    let elapsed = clock.timestamp_ms() - start_time_ms;
    if elapsed >= duration_ms {
        return end_price  // Reached minimum price
    }

    // Linear decrease
    let price_drop = (start_price - end_price) * elapsed / duration_ms;
    start_price - price_drop
}

Strategy Three: Supply-Demand Dynamic Pricing (AMM Style)

Based on constant product formula x * y = k:

public struct LiquidityPool has key {
    id: UID,
    reserve_sui: Balance<SUI>,
    reserve_item_count: u64,
    k_constant: u64,  // x * y = k
}

/// Calculate how much SUI is needed to buy n items
public fun get_buy_price(pool: &LiquidityPool, buy_count: u64): u64 {
    let new_item_count = pool.reserve_item_count - buy_count;
    let new_sui_reserve = pool.k_constant / new_item_count;
    new_sui_reserve - balance::value(&pool.reserve_sui)
}

Strategy Four: Member Discounts

public fun calculate_price(
    base_price: u64,
    buyer: address,
    member_registry: &Table<address, MemberTier>,
): u64 {
    if table::contains(member_registry, buyer) {
        let tier = table::borrow(member_registry, buyer);
        match (tier) {
            MemberTier::Gold => base_price * 80 / 100,   // 20% off
            MemberTier::Silver => base_price * 90 / 100, // 10% off
            _ => base_price,
        }
    } else {
        base_price
    }
}

Choosing pricing strategy is essentially balancing three things:

• Revenue maximization
• User predictability
• Anti-manipulation capability

Why will fixed pricing never go out of style?

Because it’s easiest to understand and easiest to operate.

Suited for:

• Low-frequency goods
• Services with stable price expectations
• Products just launched, haven’t grasped real demand curve yet

Many Builders want to implement complex pricing from the start, but actually the more stable path is usually:

1. First use fixed pricing to establish real demand
2. Then decide based on data whether to introduce dynamic mechanisms

What is Dutch auction suited for?

It’s suited for:

• Scarce resource initial sale
• You’re uncertain of market psychological price point
• Want price to automatically fall back over time

But you must accept one reality:

• It’s better suited for “single sale”
• Not necessarily suited for long-term stable operating stores

Why is AMM style both dangerous and powerful?

Powerful because:

• Continuously tradable
• Doesn’t depend on manual individual listings
• Price can automatically respond to inventory changes

Dangerous because:

• Players will be amplified by slippage and curve effects
• Easy to be arbitraged when parameters aren’t stable
• When pool depth is insufficient, price will look very bad

So if you’re not building a system that truly needs “continuous liquidity curves,” you don’t necessarily need AMM.

14.5 Vault Management Patterns

Every commercial facility should have a vault to manage revenue:

module my_finance::vault;

use sui::balance::{Self, Balance};
use sui::coin::{Self, Coin};
use sui::sui::SUI;

/// Multi-asset vault
public struct MultiVault has key {
    id: UID,
    sui_balance: Balance<SUI>,
    total_deposited: u64,   // Historical total deposited
    total_withdrawn: u64,   // Historical total withdrawn
}

/// Deposit funds
public fun deposit(vault: &mut MultiVault, coin: Coin<SUI>) {
    let amount = coin::value(&coin);
    vault.total_deposited = vault.total_deposited + amount;
    balance::join(&mut vault.sui_balance, coin::into_balance(coin));
}

/// Distribute proportionally to multiple addresses
public fun distribute(
    vault: &mut MultiVault,
    recipients: vector<address>,
    shares: vector<u64>,  // Shares (percentage, total must equal 100)
    ctx: &mut TxContext,
) {
    assert!(vector::length(&recipients) == vector::length(&shares), EMismatch);

    let total = balance::value(&vault.sui_balance);
    let len = vector::length(&recipients);
    let mut i = 0;

    while (i < len) {
        let share = *vector::borrow(&shares, i);
        let payout = total * share / 100;
        let coin = coin::take(&mut vault.sui_balance, payout, ctx);
        transfer::public_transfer(coin, *vector::borrow(&recipients, i));
        vault.total_withdrawn = vault.total_withdrawn + payout;
        i = i + 1;
    };
}

The focus of vault design has never been “putting money in,” but rather:

How revenue settles, who can move it, when to distribute, can you still audit after distribution.

A stable vault must answer at least these questions

1. What asset is revenue denominated in?
2. Are funds distributed in real-time or first settled then allocated?
3. Who can withdraw? Who can pause? Who can change revenue share ratios?
4. How to handle remainders and rounding errors during distribution?
5. In case of disputes, can on-chain records be traced?

Trade-offs between “immediate distribution” and “vault first then settlement”

Immediate distribution

Pros:

• Logic intuitive
• Revenue immediately to all parties

Cons:

• Each transaction heavier
• More revenue paths, larger failure surface

Vault first then settlement

Pros:

• Main transaction lighter
• Revenue sharing, withdrawal, auditing easier to separate

Cons:

• Need to additionally handle withdrawal permissions and settlement timing

In most real products, the latter will be more stable.

14.6 Economic System Design Principles

Three more most underestimated principles

Attack surfaces you must proactively ask about during design

• Can players trade with themselves to farm rewards?
• Can whales instantly drain liquidity or manipulate prices?
• Can discounts and rebates be arbitraged in loops?
• During vault revenue distribution, can it be front-run or claimed multiple times?

If you write these questions out during the design phase, many vulnerabilities won’t make it into code.

Chapter Summary

Further Reading

• Sui Coin Standard
• Move Book: Coin Module
• EVE Frontier Economic Design
• Chapter 12: Table & Dynamic Fields

Chapter 15: Cross-contract Composability

Goal: Master how to design externally friendly contract interfaces, and how to safely call contracts published by other Builders, building a composable EVE Frontier ecosystem.

Status: Advanced design chapter. Main content focuses on cross-contract interfaces and composability.

15.1 The Value of Composability

One of EVE Frontier’s most exciting features: Your contract can directly call others’ contracts, without any intermediary.

Builder A: Issued ALLY Token + price oracle
Builder B: Calls A's price oracle, prices items in ALLY Token for sale
Builder C: Lists on B's market, accepts both A's ALLY and SUI payment

This creates a truly open economic protocol stack.

The real power of composability isn’t the slogan “everyone can call each other,” but rather:

Once your protocol is clear enough, others can treat it as building blocks, not as a black box.

This directly changes Builder thinking:

• You’re no longer just building a single-point function
• You’re deciding whether to become a “terminal product” or “underlying capability”

Many of the most valuable protocols don’t do everything themselves, but make a certain capability into a module others are willing to repeatedly integrate.

15.2 Designing Externally Friendly Move Interfaces

Good Move interface design should follow:

module my_protocol::oracle;

// ── Public view functions (read-only, free to call) ──────────────────────

/// Get ALLY/SUI exchange rate (in MIST)
public fun get_ally_price(oracle: &PriceOracle): u64 {
    oracle.ally_per_sui
}

/// Check if price is within validity period
public fun is_price_fresh(oracle: &PriceOracle, clock: &Clock): bool {
    clock.timestamp_ms() - oracle.last_updated_ms < PRICE_TTL_MS
}

// ── Public composable functions (callable by other contracts) ───────────────────

/// Convert SUI amount to ALLY quantity
public fun sui_to_ally_amount(
    oracle: &PriceOracle,
    sui_amount: u64,
    clock: &Clock,
): u64 {
    assert!(is_price_fresh(oracle, clock), EPriceStale);
    sui_amount * oracle.ally_per_sui / 1_000_000_000
}

Design Principles

Standards for good interfaces aren’t just “others can call through”

A truly externally friendly interface should at least allow external integrators to quickly answer these questions:

1. Will this function modify state?
2. What objects and permissions must be prepared before calling?
3. What are the most common reasons for call failure?
4. What do return values and events each represent?

If these aren’t clear, others can “theoretically call” but integration costs will be absurdly high.

Three most common mistakes in interface design

1. Directly exposing internal implementation details as external dependencies

Once your interface heavily depends on internal object layout, every refactoring will drag external integrators down with you.

2. Read interfaces and write interfaces mixed too closely

Read-only queries should be as simple and stable as possible. Writable entry points should clearly mark permissions and side effects. When the two are mixed together, integrators easily misuse.

3. Error boundaries unclear

If a function might fail due to:

• Insufficient permissions
• Stale data
• Invalid price
• Object state mismatch

Then these preconditions should ideally be exposed through documentation, naming, or auxiliary read-only interfaces.

15.3 Calling Other Builders’ Contracts

Adding External Dependencies in Move.toml

[dependencies]
# Depend on packages already published by other Builders (via Git)
AllyOracle = {
  git = "https://github.com/builder-alice/ally-oracle",
  subdir = "contracts",
  rev = "v1.0.0"
}

# Or directly specify on-chain address (for published packages)
AllyOracleOnChain = { local = "../ally-oracle" }  # For local testing

Calling in Move Code

module my_market::ally_market;

// Import other Builder's modules (need to declare dependency in Move.toml)
use ally_oracle::oracle::{Self, PriceOracle};
use ally_dao::ally_token::ALLY_TOKEN;

public fun buy_with_ally(
    storage_unit: &mut world::storage_unit::StorageUnit,
    character: &Character,
    price_oracle: &PriceOracle,     // External Builder A's price oracle
    ally_payment: Coin<ALLY_TOKEN>, // External Builder A's token
    item_type_id: u64,
    clock: &Clock,
    ctx: &mut TxContext,
): Item {
    // Call external contract's view function
    let price_in_sui = oracle::sui_to_ally_amount(
        price_oracle,
        ITEM_BASE_PRICE_SUI,
        clock,
    );

    assert!(coin::value(&ally_payment) >= price_in_sui, EInsufficientPayment);

    // Process ALLY Token payment (transfer to alliance vault, etc.)
    // ...

    // Withdraw item from own SSU
    storage_unit::withdraw_item(
        storage_unit, character, MyMarketAuth {}, item_type_id, ctx,
    )
}

When depending on others’ contracts, what are you really binding to?

Not as simple as “a Git repository address,” but simultaneously binding to:

• Their interface stability
• Their upgrade strategy
• Their economic and governance choices
• Your own failure radius

In other words, every external protocol you introduce equals outsourcing part of your stability to others.

So ask four questions before integrating external protocols

1. Are this protocol’s core interfaces stable?
2. Will it break my current usage when upgrading?
3. If it pauses or fails, do I have a fallback path?
4. Can I converge key dependencies to read-only interfaces, rather than deep write coupling?

15.4 Interface Versioning & Protocol Standards

When your contract is widely used, upgrading interfaces must ensure backward compatibility:

module my_protocol::market_v2;

// Use types to mark versions
public struct V1 has drop {}
public struct V2 has drop {}

// V1 interface (always preserved)
public fun get_price_v1(market: &Market, _: V1): u64 {
    market.price
}

// V2 interface (new, supports dynamic pricing)
public fun get_price_v2(
    market: &Market,
    clock: &Clock,
    _: V2,
): u64 {
    calculate_dynamic_price(market, clock)
}

Defining Cross-contract Interface Standards (Similar to ERC Standards)

In the EVE Frontier ecosystem, interface standards can be agreed upon through documentation, allowing multiple Builders’ contracts to be compatible:

// ── Unofficial "Market Interface" Standard Proposal ────────────────────────────
// Any Builder's contract wanting to integrate into aggregated markets should implement the following interfaces:

/// List items: return currently selling item types and prices
public fun list_items(market: &T): vector<(u64, u64)>  // (type_id, price_sui)

/// Query whether specific item is available for purchase
public fun is_available(market: &T, item_type_id: u64): bool

/// Purchase (return item)
public fun purchase<Auth: drop>(
    market: &mut T,
    buyer: &Character,
    item_type_id: u64,
    payment: &mut Coin<SUI>,
    auth: Auth,
    ctx: &mut TxContext,
): Item

Why must version control be considered from the first version?

Because once others start depending on you, “changing interfaces” is no longer just your internal matter.

You must simultaneously consider:

• Whether old callers can still survive
• Whether new features can be gradually introduced
• Whether frontends, scripts, aggregators need to migrate synchronously

Many protocols don’t die from insufficient features, but from “version two breaking everything in version one.”

Where standardized interfaces are most valuable

Not looking professional, but catalyzing secondary ecosystems:

• Aggregators easier to integrate
• Price comparison tools easier to build
• Third-party frontends easier to reuse
• Other Builders more willing to build on top of you

15.5 Practice: Aggregated Price Comparator

// Aggregate multiple Builders' market prices in dApp
async function getAggregatedPrices(
  itemTypeId: number,
  marketIds: string[],
  client: SuiClient,
): Promise<Array<{ marketId: string; price: number; builder: string }>> {

  // Batch read all market states
  const markets = await client.multiGetObjects({
    ids: marketIds,
    options: { showContent: true },
  });

  const prices = markets
    .map((market, i) => {
      const fields = (market.data?.content as any)?.fields;
      if (!fields) return null;

      // Read price from listings Table (simplified)
      const listing = fields.listings?.fields?.contents?.find(
        (entry: any) => Number(entry.fields?.key) === itemTypeId
      );

      if (!listing) return null;

      return {
        marketId: marketIds[i],
        price: Number(listing.fields.value.fields.price),
        builder: fields.owner ?? "Unknown",
      };
    })
    .filter(Boolean)
    .sort((a, b) => a!.price - b!.price); // Sort by price ascending

  return prices as any[];
}

This example is well-suited to illustrate one reality:

The value of composability is often amplified off-chain.

In other words, as long as on-chain protocols design interfaces and events clearly, off-chain can create:

• Price comparators
• Aggregators
• Recommendation routing
• Strategy orchestration

So when designing contracts, don’t just think about “whether another on-chain contract will call me,” also think “whether off-chain tools will be willing to consume me.”

15.6 Composability Risks & Defense

Three more very common risks in real projects

Composition isn’t better the deeper it goes

The deeper the composition layers, the more capabilities you gain, but also the harder to maintain.

A practical principle is:

• Prioritize depending on stable, read-only, verifiable external capabilities
• Cautiously depend on deeply coupled, strong state-writing external processes

Because when the former breaks, it’s usually just “data gets worse,” when the latter breaks it might directly interrupt your core business chain.

Chapter Summary

Further Reading

• EVE World Explainer
• Move Book: Package System

Chapter 16: Location and Proximity Systems

Goal: Understand EVE Frontier’s on-chain location privacy design, master how to build location-based game logic using the proximity system, and explore future ZK proof directions.

Status: Educational chapter. Main focus on location privacy, server proofs, and future ZK directions.

16.1 On-Chain Challenges for Spatial Games

In a traditional MMORPG, location information is managed centrally by game servers. On-chain, this creates two contradictions:

1. Transparency: On-chain data is publicly viewable; if coordinates are stored in plaintext, all players’ hidden base locations are immediately exposed
2. Trustworthiness: If locations are reported by clients, players can forge them (“I’m right next to you!”)

EVE Frontier’s solution: Hashed locations + trusted game server signatures.

What’s most important here isn’t memorizing the phrase “hashed location,” but first understanding what it’s balancing:

• Privacy Cannot expose base, facility, or player locations directly
• Verifiability Must allow certain distance-related actions to be proven
• Usability Cannot design the system so slowly that it’s unplayable

So the location system is essentially an engineering trade-off between “privacy, trust, and real-time performance.”

16.2 Hashed Locations: Protecting Coordinate Privacy

What’s stored on-chain isn’t plaintext coordinates, but hash values:

Storage: hash(x, y, salt) → chain.location_hash
Query: Anyone can only see the hash, cannot reverse-engineer coordinates
Verification: Players prove to the server "I know the coordinates for this hash"

// location.move (simplified)
public struct Location has store {
    location_hash: vector<u8>,  // Hash of coordinates, not plaintext
}

/// Update location (requires game server signature authorization)
public fun update_location(
    assembly: &mut Assembly,
    new_location_hash: vector<u8>,
    admin_acl: &AdminACL,  // Must be authorized server as sponsor
    ctx: &TxContext,
) {
    verify_sponsor(admin_acl, ctx);
    assembly.location.location_hash = new_location_hash;
}

What Can Hashed Locations Protect, and What Can’t They?

They can protect:

• Plaintext coordinates aren’t exposed on-chain
• Normal observers cannot directly see real locations from object fields

They cannot automatically protect against:

• Reverse-engineering risks from weak hashes or enumerable spaces
• Off-chain interfaces leaking real locations
• Frontend or logs accidentally exposing mapping relationships

In other words, hashing is one layer of the privacy system, not the whole thing.

16.3 Proximity Verification: Server Signature Pattern

When verifying “A is near B” (e.g., picking up items, jumping), the current approach uses server signatures:

① Player requests game server: "Prove I'm near stargate 0x..."
② Server queries player's actual game coordinates
③ Server verifies player is indeed near the stargate (<20km)
④ Server signs a statement "Player A is near Stargate B" with private key
⑤ Player attaches this signature to the transaction
⑥ On-chain contract verifies signature is from authorized server (AdminACL)

The most critical trust boundary in this design is:

The chain doesn’t know the real coordinates; it only trusts “the authorized server has already judged this for it.”

This means system security depends not only on strict on-chain validation, but also on:

• Whether the game server is honest
• Whether the signature payload is complete
• Whether time windows and nonces are designed correctly

// Distance verification when linking stargates
public fun link_gates(
    gate_a: &mut Gate,
    gate_b: &mut Gate,
    owner_cap_a: &OwnerCap<Gate>,
    distance_proof: vector<u8>,  // Server-signed proof of "distance > 20km between gates"
    admin_acl: &AdminACL,
    ctx: &TxContext,
) {
    // Verify server signature (simplified; actual implementation verifies ed25519 signature)
    verify_sponsor(admin_acl, ctx);
    // ...
}

16.3.1 Recommended Minimal Proof Message Body

Don’t make “proximity proof” a black box byte string that only the server understands. The minimal viable payload should bind at least these fields:

{
  "proof_type": "assembly_proximity",
  "player": "0xPLAYER",
  "assembly_id": "0xASSEMBLY",
  "location_hash": "0xHASH",
  "max_distance_m": 20000,
  "issued_at_ms": 1735689600000,
  "expires_at_ms": 1735689660000,
  "nonce": "4d2f1c..."
}

Each field’s responsibility:

• player: Prevents other players from reusing the proof
• assembly_id: Prevents using proof from stargate A to call stargate B
• location_hash: Binds current on-chain location state into the proof
• issued_at_ms / expires_at_ms: Limits replay window
• nonce: Prevents multiple replays within the same window

16.3.2 Minimal Loop Between Server-Side Signing and On-Chain Validation

Off-chain services must do at least two things: first verify real coordinate relationships, then sign an explicit payload.

type ProximityProofPayload = {
  proofType: "assembly_proximity";
  player: string;
  assemblyId: string;
  locationHash: string;
  maxDistanceM: number;
  issuedAtMs: number;
  expiresAtMs: number;
  nonce: string;
};

async function issueProximityProof(input: {
  player: string;
  assemblyId: string;
  expectedHash: string;
}) {
  const location = await getPlayerLocationFromGameServer(input.player);
  const assembly = await getAssemblyLocation(input.assemblyId);

  assert(hash(location) === input.expectedHash);
  assert(distance(location, assembly) <= 20_000);

  const payload: ProximityProofPayload = {
    proofType: "assembly_proximity",
    player: input.player,
    assemblyId: input.assemblyId,
    locationHash: input.expectedHash,
    maxDistanceM: 20_000,
    issuedAtMs: Date.now(),
    expiresAtMs: Date.now() + 60_000,
    nonce: crypto.randomUUID(),
  };

  return signPayload(payload);
}

On-chain side must validate at least four layers:

// Simplified pseudocode: real implementation should deserialize payload and compare field by field
public fun verify_proximity_proof(
    assembly_id: ID,
    expected_player: address,
    expected_hash: vector<u8>,
    proof_bytes: vector<u8>,
    admin_acl: &AdminACL,
    clock: &Clock,
    ctx: &TxContext,
) {
    verify_sponsor(admin_acl, ctx);

    let payload = decode_proximity_payload(proof_bytes);
    assert!(payload.assembly_id == assembly_id, EWrongAssembly);
    assert!(payload.player == expected_player, EWrongPlayer);
    assert!(payload.location_hash == expected_hash, EWrongLocationHash);
    assert!(clock.timestamp_ms() <= payload.expires_at_ms, EProofExpired);
    assert!(check_and_consume_nonce(payload.nonce), EReplay);
}

What’s truly important here is: verify_sponsor(admin_acl, ctx) only proves “this transaction came from an authorized server,” which isn’t enough to prove “this location statement itself is for the current object, current player, current time window.”

So What’s the Most Common Mistake in Location Proofs?

Not “getting the signature algorithm wrong,” but incomplete payload binding.

Once the payload misses binding one item, classic reuse problems emerge:

• Bound player but not object Player can use proof from A to call B
• Bound object but not time window Old proofs can be repeatedly replayed
• Bound time but not current location hash Old location can impersonate new location

16.4 Strategic Design Around Location Systems

Even though locations are hashed, Builders can still design many location-based mechanics:

Strategy One: Location Locking (Asset Bound to Location)

// Asset is only valid at specific location hash
public fun claim_resource(
    claim: &mut ResourceClaim,
    claimant_location_hash: vector<u8>,  // Server-proven location
    admin_acl: &AdminACL,
    ctx: &mut TxContext,
) {
    verify_sponsor(admin_acl, ctx);
    // Verify player location hash matches resource point
    assert!(
        claimant_location_hash == claim.required_location_hash,
        EWrongLocation,
    );
    // Grant resource
}

What’s truly interesting about location systems is: you don’t need to know plaintext coordinates to design very strong spatial rules.

This means Builders at the upper business layer usually don’t care about “exactly where you are in the universe,” but rather:

• Whether you’re near a certain facility
• Whether you’re within a certain region
• Whether you meet entry, extraction, activation conditions

This makes many mechanics feel more like “conditional access control” rather than “map rendering systems.”

Strategy Two: Base Zone Control

public struct BaseZone has key {
    id: UID,
    center_hash: vector<u8>,   // Base center location hash
    owner: address,
    zone_nft_ids: vector<ID>,  // List of friendly NFTs in this zone
}

// Authorize component only for players within base range
public fun base_service(
    zone: &BaseZone,
    service: &mut StorageUnit,
    player_in_zone_proof: vector<u8>,  // Server proof "player is within base range"
    admin_acl: &AdminACL,
    ctx: &mut TxContext,
) {
    verify_sponsor(admin_acl, ctx);
    // ...provide service
}

Strategy Three: Movement Path Tracking (Off-chain + On-chain Combined)

// Off-chain: Listen to player location update events
client.subscribeEvent({
  filter: { MoveEventType: `${WORLD_PKG}::location::LocationUpdated` },
  onMessage: (event) => {
    const { assembly_id, new_hash } = event.parsedJson as any;
    // Update local path records
    locationHistory.push({ assembly_id, hash: new_hash, time: Date.now() });
  },
});

// On-chain: Only store hash, parse path off-chain

16.5 Future Direction: Zero-Knowledge Proofs Replacing Server Trust

Official documentation mentions future plans to use ZK proofs to replace current server signatures:

Now:
  Player → Server (where are you?) → Server signature → On-chain signature verification

Future (ZK):
  Player → Local computation of ZK proof ("I know coordinates satisfying this hash, and < 20km")
         → On-chain ZK verifier (no server involvement)

Advantages of ZK Proofs:

• Fully decentralized, doesn’t depend on server honesty
• Players can prove “I’m here” without exposing exact coordinates
• Can theoretically prove arbitrarily complex spatial relationships

Practical Development Recommendations:

• During current phase, when integrating with servers, design payload structure, time windows, nonce, and object binding clearly (see Chapter 8)
• AdminACL.verify_sponsor() can only serve as one layer of “source verification,” cannot replace payload validation
• When ZK goes live in the future, try to only replace “proof mechanism,” don’t rewrite upper business state machines

Why Design Now for “Future Proof Mechanism Replaceability”?

Because what should really be stable is upper business semantics, not today’s proof implementation details.

In other words, you should split the system into two layers:

• Upper Business Rules E.g., “can only withdraw items when nearby”
• Lower Proof Mechanism E.g., today it’s server signatures, future might switch to ZK

This way when upgrading in the future, you’re replacing “how to prove,” not rewriting the entire business state machine.

16.5.1 Failure Scenarios and Defense Checklist

Another Commonly Overlooked Failure Scenario: Off-Chain Cache Staleness

If the server gets an old location cache, it might sign a “formally legal, business-wise incorrect” proof.

So in real systems, you also need to consider:

• Whether server location data source is fresh enough
• Whether location sampling and on-chain state have significant delays
• Whether certain actions need shorter proof validity periods

16.6 Displaying Location Information in dApps

// Location information not directly readable to Builders (hashed), but can display in-game coordinates
// (by interfacing with game server API for decryption)

interface AssemblyDisplayInfo {
  id: string
  name: string
  systemName: string    // Star system name (from server API)
  constellation: string // Constellation
  region: string        // Region
  onlineStatus: string
}

async function getAssemblyDisplayInfo(assemblyId: string): Promise<AssemblyDisplayInfo> {
  // 1. Read hashed location from chain
  const obj = await suiClient.getObject({
    id: assemblyId,
    options: { showContent: true },
  });
  const locationHash = (obj.data?.content as any)?.fields?.location?.fields?.location_hash;

  // 2. Query star system name via game server API using hash
  const geoRes = await fetch(`${GAME_API}/location?hash=${locationHash}`);
  const geoInfo = await geoRes.json();

  return {
    id: assemblyId,
    name: (obj.data?.content as any)?.fields?.name,
    systemName: geoInfo.system_name,
    constellation: geoInfo.constellation,
    region: geoInfo.region,
    onlineStatus: (obj.data?.content as any)?.fields?.status,
  };
}

When Displaying Locations in Frontend, Most Important Isn’t “How Detailed,” But “Not Leaking Unauthorized Information”

So frontends are usually better suited to display:

• Star system name
• Constellation
• Region
• Online status

Rather than carelessly displaying:

• Overly granular internal coordinates
• Debug fields that can be used to reverse-engineer precise locations

This is why location systems must be designed together with the off-chain display layer, not just considering hashing in contracts and calling it done.

🔖 Chapter Summary

📚 Further Reading

• EVE World Explainer - Privacy
• Sui ZK Login (Related ZK Tech Background)
• Constraints Documentation

Chapter 17: Testing, Debugging, and Security Auditing

Goal: Write comprehensive unit tests for Move contracts, identify common security vulnerabilities, and formulate contract upgrade strategies.

Status: Engineering assurance chapter. Main focus on testing, security, and upgrade risk control.

17.1 Why Security Testing is Critical?

Once on-chain contracts are deployed, assets are real. Here are common loss scenarios:

• Price calculation overflow, leading to items sold at 0 price
• Missing permission checks, anyone can call “Owner only” functions
• Reentrancy vulnerabilities (less common in Move but still needs attention)
• Upgrade failures cause old data to be unreadable by new contracts

Defense Strategy: Test first, then publish.

The most valuable concept to establish here isn’t the platitude “testing is important,” but:

The goal of on-chain contract testing isn’t to prove it can run, but to prove it won’t lose control under wrong inputs, wrong sequences, and wrong permissions.

Many beginners write tests only verifying “normal path succeeds.” But real asset losses usually come from three other types of paths:

• Calls that shouldn’t succeed but do
• Boundary value inputs that push the system into abnormal states
• After upgrades or maintenance, old objects and new logic are no longer compatible

So for Builders, testing isn’t finishing work, it’s part of design work.

17.2 Move Unit Testing Basics

Move has a built-in testing framework, test code is written in the same .move file, marked with #[test] annotation:

module my_package::my_module;

// ... normal contract code ...

// Test module: only compiled in test environment
#[test_only]
module my_package::my_module_tests;

use my_package::my_module;
use sui::test_scenario::{Self, Scenario};
use sui::coin;
use sui::sui::SUI;
use sui::clock;

// ── Basic Test ─────────────────────────────────────────────

#[test]
fun test_deposit_and_withdraw() {
    // Initialize test scenario (simulates blockchain state)
    let mut scenario = test_scenario::begin(@0xALICE);

    // Test step 1: Alice deploys contract
    {
        let ctx = scenario.ctx();
        my_module::init_for_testing(ctx);  // Test-specific init
    };

    // Test step 2: Alice deposits item
    scenario.next_tx(@0xALICE);
    {
        let mut vault = scenario.take_shared<my_module::Vault>();
        let ctx = scenario.ctx();

        my_module::deposit(&mut vault, 100, ctx);
        assert!(my_module::balance(&vault) == 100, 0);

        test_scenario::return_shared(vault);
    };

    // Test step 3: Bob tries to withdraw (should fail)
    scenario.next_tx(@0xBOB);
    {
        let mut vault = scenario.take_shared<my_module::Vault>();
        // Expect this call to fail (abort)
        // Use #[test, expected_failure] to test failure paths
        test_scenario::return_shared(vault);
    };

    scenario.end();
}

// ── Test Failure Paths ────────────────────────────────────────

#[test]
#[expected_failure(abort_code = my_module::ENotOwner)]
fun test_unauthorized_withdraw_fails() {
    let mut scenario = test_scenario::begin(@0xALICE);

    // Deploy
    { my_module::init_for_testing(scenario.ctx()); };

    // Bob tries to operate as Alice (should abort)
    scenario.next_tx(@0xBOB);
    {
        let mut vault = scenario.take_shared<my_module::Vault>();
        my_module::owner_withdraw(&mut vault, scenario.ctx()); // should abort
        test_scenario::return_shared(vault);
    };

    scenario.end();
}

// ── Test Time-Related Logic with Clock ─────────────────────────

#[test]
fun test_time_based_pricing() {
    let mut scenario = test_scenario::begin(@0xALICE);
    let mut clock = clock::create_for_testing(scenario.ctx());

    // Set current time
    clock.set_for_testing(1_000_000);

    {
        let price = my_module::get_dutch_price(
            1000,  // starting price
            100,   // minimum price
            0,     // start time
            2_000_000,  // duration (2 seconds)
            &clock,
        );
        // After half the time, price should be middle value
        assert!(price == 550, 0);
    };

    clock.destroy_for_testing();
    scenario.end();
}

Running tests:

# Run all tests
sui move test

# Run only specific test
sui move test test_deposit_and_withdraw

# Show verbose output
sui move test --verbose

When Writing Tests, First Categorize into Four Scenarios

A practical test stratification is:

1. Normal Path Under valid inputs, does the system complete as expected
2. Permission Failure Path Without permissions, does it stably abort
3. Boundary Value Path Are 0, max value, expiry, empty collection, last entry scenarios correct
4. State Evolution Path After completing one step, then the next, is the system still consistent

If your tests only have the first type, it’s not really enough to be called “tested.”

What is test_scenario Really Suited For?

It’s best suited to simulate:

• Multiple addresses taking turns initiating transactions
• Shared object state changes across multiple transactions
• Behavior changes after time progression
• Complete lifecycle of object creation, retrieval, return

This happens to be exactly where EVE Builder projects’ most common risk concentrations are.

Tests Aren’t Better When More Fragmented

Some tests are too fragmented, ultimately only proving “small functions work literally,” but don’t cover real business loops.

A more valuable approach is usually:

• Keep a few key unit tests
• Then write several end-to-end business scenario tests

For example, in a rental system, rather than only testing calc_refund(), more important is testing:

1. Create listing
2. Successfully rent
3. Return early
4. Expire and reclaim

Whether this complete chain is closed.

17.3 Common Security Vulnerabilities and Defenses

Vulnerability One: Integer Overflow/Underflow

// ❌ Dangerous: u64 subtraction underflow will abort, but if logic is wrong might calculate huge value
fun unsafe_calc(a: u64, b: u64): u64 {
    a - b  // If b > a, directly aborts (Move checks)
}

// ✅ Safe: Check before operating
fun safe_calc(a: u64, b: u64): u64 {
    assert!(a >= b, EInsufficientBalance);
    a - b
}

// ✅ For intentionally allowed underflow, use checked calculation
fun safe_pct(total: u64, bps: u64): u64 {
    // bps max 10000, prevent total * bps overflow
    assert!(bps <= 10_000, EInvalidBPS);
    total * bps / 10_000  // Move u64 max 1.8e19, need to watch large numbers
}

✅ Move’s Advantage: Move checks u64 operation overflow by default, aborts on overflow rather than silently returning wrong values (unlike early Solidity versions).

But note, Move solves “machine-level overflow safety” for you, not “business math correctness.”

For example, these problems the type system won’t think about for you:

• Should fees be calculated then deducted, or deducted then profit-shared
• Should percentages round down or round to nearest
• After multi-address profit sharing, should remainder stay in vault or return to user

Many economic bugs ultimately aren’t “hacker-level vulnerabilities,” but settlement caliber itself designed wrong.

Vulnerability Two: Missing Permission Checks

// ❌ Dangerous: Doesn't verify caller
public fun withdraw_all(treasury: &mut Treasury, ctx: &mut TxContext) {
    let all = coin::take(&mut treasury.balance, balance::value(&treasury.balance), ctx);
    transfer::public_transfer(all, ctx.sender()); // Anyone can withdraw funds!
}

// ✅ Safe: Require OwnerCap
public fun withdraw_all(
    treasury: &mut Treasury,
    _cap: &TreasuryOwnerCap,  // Check caller holds OwnerCap
    ctx: &mut TxContext,
) {
    let all = coin::take(&mut treasury.balance, balance::value(&treasury.balance), ctx);
    transfer::public_transfer(all, ctx.sender());
}

The easiest mistake in permission checks is only verifying “some permission exists,” but not verifying:

• Is this permission for this object
• Is this call allowed in the current scenario
• Should this permission only be used in certain time periods or certain paths

Vulnerability Three: Capability Not Properly Bound

// ❌ Dangerous: OwnerCap doesn't verify corresponding object ID
public fun admin_action(vault: &mut Vault, _cap: &OwnerCap) {
    // Any OwnerCap can control any Vault!
}

// ✅ Safe: Verify OwnerCap and object binding relationship
public fun admin_action(vault: &mut Vault, cap: &OwnerCap) {
    assert!(cap.authorized_object_id == object::id(vault), ECapMismatch);
    // ...
}

Vulnerability Four: Timestamp Manipulation

// ❌ Not recommended: Directly rely on ctx.epoch() as precise time
// epoch granularity is about 24 hours, not suitable for fine granularity timing

// ✅ Recommended: Use Clock object
public fun check_expiry(expiry_ms: u64, clock: &Clock): bool {
    clock.timestamp_ms() < expiry_ms
}

Vulnerability Five: Shared Object Race Conditions

Shared objects can be accessed by multiple transactions concurrently. When multiple transactions simultaneously rush to buy the same item:

// ❌ Has race condition problem: Two transactions might both pass check
public fun buy_item(market: &mut Market, ...) {
    let listing = table::borrow(&market.listings, item_type_id);
    assert!(listing.amount > 0, EOutOfStock);
    // ← Another TX might pass the same check here
    // ... then both execute purchase, causing overselling
}

// ✅ Sui's solution: Write locks on shared objects ensure serialization
// Sui's Move executor guarantees: transactions writing to the same shared object execute sequentially
// So the above code is actually safe on Sui! But ensure your logic correctly handles negative stock
public fun buy_item(market: &mut Market, ...) {
    // This check is atomic, other TXs will wait
    assert!(table::contains(&market.listings, item_type_id), ENotListed);
    let listing = table::remove(&mut market.listings, item_type_id);  // Atomic removal
    // ...
}

Although Sui serializes writes to shared objects, this doesn’t mean you can ignore business race conditions.

You still need to test:

• Same item purchased in rapid succession
• Object delisted then purchased
• Price updates and purchases happening in adjacent transactions

In other words, the underlying executor solves part of concurrent safety for you, but doesn’t design complete business consistency.

17.4 Using Move Prover for Formal Verification

Move Prover is a formal verification tool that can mathematically prove certain properties always hold:

// spec block: formal specification
spec fun total_supply_conserved(treasury: TreasuryCap<TOKEN>): bool {
    // Declare: total supply increases by exact amount after minting
    ensures result == old(total_supply(treasury)) + amount;
}

#[verify_only]
spec module {
    // Invariant: vault balance never exceeds a certain limit
    invariant forall vault: Vault:
        balance::value(vault.balance) <= MAX_VAULT_SIZE;
}

Running verification:

sui move prove

When Is Move Prover Worth It?

Not all projects need to do formal verification from the start. A more practical strategy is usually:

• Normal cases and small-medium projects: First get unit tests and failure path coverage done well
• High-value vaults, liquidation, permission systems: Then introduce Prover to prove key invariants

Most suitable places for Prover usually include:

• Total supply conservation
• Balance never goes negative
• Certain permissions cannot be exceeded
• A certain state machine won’t jump to illegal states

17.5 Contract Upgrade Strategies

Move packages once published are immutable, but can publish new versions through upgrade mechanism:

# First publish
sui client publish
# Get UpgradeCap object (upgrade capability)

# Upgrade (requires UpgradeCap)
sui client upgrade \
  --upgrade-capability <UPGRADE_CAP_ID> \

Upgrade Compatibility Rules

What’s Really Hard About Upgrades Isn’t the Command, But Data Staying Alive

Many people doing upgrades for the first time focus on “how to publish new package.” But what users really care about is:

• Can old objects still be used
• Can old frontend still read
• How to interpret old events and new objects together

In other words, upgrades are essentially maintaining a still-running system, not restarting the server.

Four Questions You Must Ask Before Upgrading

1. Can old objects still be safely read by the new version?
2. Does the new version require additional migration scripts?
3. Does the frontend need to synchronously update field parsing?
4. Once upgraded, if issues are found, is there a rollback or damage control path?

Data Migration Patterns

When needing to change data structures, use “old-new coexistence” strategy:

// v1: Old storage structure
public struct MarketV1 has key {
    id: UID,
    price: u64,
}

// v2: New version adds fields (cannot directly modify V1)
// Instead use dynamic fields to extend
public fun get_expiry_v2(market: &MarketV1): Option<u64> {
    if df::exists_(&market.id, b"expiry") {
        option::some(*df::borrow<vector<u8>, u64>(&market.id, b"expiry"))
    } else {
        option::none()
    }
}

// Add new field to old object (migration script)
public fun migrate_add_expiry(
    market: &mut MarketV1,
    expiry_ms: u64,
    ctx: &mut TxContext,
) {
    df::add(&mut market.id, b"expiry", expiry_ms);
}

17.6 EVE Frontier-Specific Security Constraints

Quoting key constraints from official documentation:

Don’t just treat these constraints as “documentation knowledge points.” They will directly affect your modeling approach.

For example:

• Objects have size limits, you can’t stuff all state into one giant object
• Dynamic fields have access limits, you can’t assume one transaction can scan the entire market
• Some operations depend on server signatures, you can’t design the system as purely user-driven

17.7 Security Checklist

Before publishing contracts, check each item:

Permission Control
✅ Do all write functions have permission verification?
✅ Does OwnerCap verify authorized_object_id?
✅ Do AdminACL-protected functions have sponsor verification?

Math Operations
✅ Can all multiplications overflow? (u64 max about 1.8 × 10^19)
✅ Do percentage calculations use bps (basis points) to avoid precision loss?
✅ Is a >= b checked before subtraction?

State Consistency
✅ Are deposit and withdrawal logic completely symmetric?
✅ Are hot potato objects always consumed?
✅ Are atomic operations on shared objects correct?

Upgrade Compatibility
✅ Is UpgradeCap storage planned securely?
✅ Is future data migration path designed?

Test Coverage
✅ Are normal paths tested?
✅ Are all assert failure paths tested?
✅ Are boundary values tested (0, max value)?

More Practical Checking Order

Each time before publishing, recommend going through in this order:

1. Permissions Who can call, call what, what changes after calling
2. Money Where money comes from, where it goes, can it possibly get lost along the way
3. State After success and failure, do objects still maintain consistency
4. Upgrade If this version needs changes later, will it lock itself up

This is more useful than purely checking off checklist items, because it forces you to re-examine design according to real risk surfaces.

🔖 Chapter Summary

📚 Further Reading

• Builder Constraints Documentation
• Move Prover
• Sui Package Upgrade Guide
• Move Testing Framework

Example 3: On-Chain Auction House (Smart Storage Unit + Dutch Auction)

Goal: Transform a Smart Storage Unit into a Dutch auction (price decreases over time), items automatically transfer to bidders, fully implementing auction contract + bidder dApp + Owner management panel.

Status: Includes contract, dApp, and Move test files. The main content is nearly a complete example, suitable as a “pricing strategy + frontend countdown” demonstration.

Code Directory

• example-03
• example-03/dapp

Minimal Call Chain

Owner creates auction -> Price decreases over time -> Buyer pays current price -> Auction settles -> Item transfers

Requirements Analysis

Scenario: You control a smart storage box containing rare ore. Instead of a fixed price, you want to maximize sales revenue through a Dutch auction (price descends from high to low) with more transparent price discovery:

• 🕐 Auction starts at 5000 LUX
• 📉 Drops 500 LUX every 10 minutes
• 🏆 Minimum price is 500 LUX, price stops dropping
• ⚡ Anyone can buy at the current price at any time, item immediately transfers
• 📊 dApp displays real-time countdown and current price

Part 1: Move Contract

Directory Structure

dutch-auction/
├── Move.toml
└── sources/
    ├── dutch_auction.move    # Dutch auction logic
    └── auction_manager.move  # Auction management (create/end)

Core Contract: dutch_auction.move

module dutch_auction::auction;

use world::storage_unit::{Self, StorageUnit};
use world::character::Character;
use world::inventory::Item;
use sui::coin::{Self, Coin};
use sui::sui::SUI;
use sui::balance::{Self, Balance};
use sui::clock::Clock;
use sui::object::{Self, UID, ID};
use sui::event;
use sui::transfer;

/// SSU Extension Witness
public struct AuctionAuth has drop {}

/// Auction State
public struct DutchAuction has key {
    id: UID,
    storage_unit_id: ID,        // Bound storage box
    item_type_id: u64,          // Item type being auctioned
    start_price: u64,           // Starting price (MIST)
    end_price: u64,             // Minimum price
    start_time_ms: u64,         // Auction start time
    price_drop_interval_ms: u64, // Price drop interval (milliseconds)
    price_drop_amount: u64,     // Price drop amount per interval
    is_active: bool,            // Whether still ongoing
    proceeds: Balance<SUI>,     // Auction proceeds
    owner: address,             // Auction creator
}

/// Events
public struct AuctionCreated has copy, drop {
    auction_id: ID,
    item_type_id: u64,
    start_price: u64,
    end_price: u64,
}

public struct AuctionSettled has copy, drop {
    auction_id: ID,
    winner: address,
    final_price: u64,
    item_type_id: u64,
}

// ── Calculate Current Price ─────────────────────────────────────────

public fun current_price(auction: &DutchAuction, clock: &Clock): u64 {
    if !auction.is_active {
        return auction.end_price
    }

    let elapsed_ms = clock.timestamp_ms() - auction.start_time_ms;
    let drops = elapsed_ms / auction.price_drop_interval_ms;
    let total_drop = drops * auction.price_drop_amount;

    if total_drop >= auction.start_price - auction.end_price {
        auction.end_price  // Already at minimum price
    } else {
        auction.start_price - total_drop
    }
}

/// Calculate time remaining until next price drop (milliseconds)
public fun ms_until_next_drop(auction: &DutchAuction, clock: &Clock): u64 {
    let elapsed = clock.timestamp_ms() - auction.start_time_ms;
    let interval = auction.price_drop_interval_ms;
    let next_drop_at = (elapsed / interval + 1) * interval;
    next_drop_at - elapsed
}

// ── Create Auction ─────────────────────────────────────────────

public fun create_auction(
    storage_unit: &StorageUnit,
    item_type_id: u64,
    start_price: u64,
    end_price: u64,
    price_drop_interval_ms: u64,
    price_drop_amount: u64,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    assert!(start_price > end_price, EInvalidPricing);
    assert!(price_drop_amount > 0, EInvalidDropAmount);
    assert!(price_drop_interval_ms >= 60_000, EIntervalTooShort); // Minimum 1 minute

    let auction = DutchAuction {
        id: object::new(ctx),
        storage_unit_id: object::id(storage_unit),
        item_type_id,
        start_price,
        end_price,
        start_time_ms: clock.timestamp_ms(),
        price_drop_interval_ms,
        price_drop_amount,
        is_active: true,
        proceeds: balance::zero(),
        owner: ctx.sender(),
    };

    event::emit(AuctionCreated {
        auction_id: object::id(&auction),
        item_type_id,
        start_price,
        end_price,
    });

    transfer::share_object(auction);
}

// ── Bid: Pay Current Price to Get Item ──────────────────────────

public fun buy_now(
    auction: &mut DutchAuction,
    storage_unit: &mut StorageUnit,
    character: &Character,
    mut payment: Coin<SUI>,
    clock: &Clock,
    ctx: &mut TxContext,
): Item {
    assert!(auction.is_active, EAuctionEnded);

    let price = current_price(auction, clock);
    assert!(coin::value(&payment) >= price, EInsufficientPayment);

    // Return overpayment
    let change_amount = coin::value(&payment) - price;
    if change_amount > 0 {
        let change = payment.split(change_amount, ctx);
        transfer::public_transfer(change, ctx.sender());
    }

    // Revenue goes to auction treasury
    balance::join(&mut auction.proceeds, coin::into_balance(payment));
    auction.is_active = false;

    event::emit(AuctionSettled {
        auction_id: object::id(auction),
        winner: ctx.sender(),
        final_price: price,
        item_type_id: auction.item_type_id,
    });

    // Withdraw item from SSU
    storage_unit::withdraw_item(
        storage_unit,
        character,
        AuctionAuth {},
        auction.item_type_id,
        ctx,
    )
}

// ── Owner: Withdraw Auction Proceeds ──────────────────────────────────

public fun withdraw_proceeds(
    auction: &mut DutchAuction,
    ctx: &mut TxContext,
) {
    assert!(ctx.sender() == auction.owner, ENotOwner);
    assert!(!auction.is_active, EAuctionStillActive);

    let amount = balance::value(&auction.proceeds);
    let coin = coin::take(&mut auction.proceeds, amount, ctx);
    transfer::public_transfer(coin, ctx.sender());
}

// ── Owner: Cancel Auction ──────────────────────────────────────

public fun cancel_auction(
    auction: &mut DutchAuction,
    storage_unit: &mut StorageUnit,
    character: &Character,
    ctx: &mut TxContext,
): Item {
    assert!(ctx.sender() == auction.owner, ENotOwner);
    assert!(auction.is_active, EAuctionAlreadyEnded);

    auction.is_active = false;

    // Return item to Owner
    storage_unit::withdraw_item(
        storage_unit, character, AuctionAuth {}, auction.item_type_id, ctx,
    )
}

// Error codes
const EInvalidPricing: u64 = 0;
const EInvalidDropAmount: u64 = 1;
const EIntervalTooShort: u64 = 2;
const EAuctionEnded: u64 = 3;
const EInsufficientPayment: u64 = 4;
const EAuctionStillActive: u64 = 5;
const EAuctionAlreadyEnded: u64 = 6;
const ENotOwner: u64 = 7;

Part 2: Unit Tests

#[test_only]
module dutch_auction::auction_tests;

use dutch_auction::auction;
use sui::test_scenario;
use sui::clock;
use sui::coin;
use sui::sui::SUI;

#[test]
fun test_price_decreases_over_time() {
    let mut scenario = test_scenario::begin(@0xOwner);
    let mut clock = clock::create_for_testing(scenario.ctx());

    // Set to time 0
    clock.set_for_testing(0);

    // Create mock auction object to test price calculation
    let auction = auction::create_test_auction(
        5000,   // start_price
        500,    // end_price
        600_000, // 10 minutes (ms)
        500,    // Drop 500 each time
        &clock,
        scenario.ctx(),
    );

    // Time 0: Price should be 5000
    assert!(auction::current_price(&auction, &clock) == 5000, 0);

    // After 10 minutes: Price should be 4500
    clock.set_for_testing(600_000);
    assert!(auction::current_price(&auction, &clock) == 4500, 0);

    // After 90 minutes (9 drops × 500 = 4500, but minimum 500): Price should be 500
    clock.set_for_testing(5_400_000);
    assert!(auction::current_price(&auction, &clock) == 500, 0);

    clock.destroy_for_testing();
    auction.destroy_test_auction();
    scenario.end();
}

#[test]
#[expected_failure(abort_code = auction::EInsufficientPayment)]
fun test_underpayment_fails() {
    // ...Test failure path when payment is insufficient
}

Part 3: Bidder dApp

// src/AuctionApp.tsx
import { useState, useEffect, useCallback } from 'react'
import { useConnection, getObjectWithJson } from '@evefrontier/dapp-kit'
import { useDAppKit } from '@mysten/dapp-kit-react'
import { Transaction } from '@mysten/sui/transactions'

const DUTCH_PACKAGE = "0x_DUTCH_PACKAGE_"
const AUCTION_ID = "0x_AUCTION_ID_"
const STORAGE_UNIT_ID = "0x..."
const CHARACTER_ID = "0x..."
const CLOCK_OBJECT_ID = "0x6"

interface AuctionState {
  start_price: string
  end_price: string
  start_time_ms: string
  price_drop_interval_ms: string
  price_drop_amount: string
  is_active: boolean
  item_type_id: string
}

function calculateCurrentPrice(state: AuctionState): number {
  if (!state.is_active) return Number(state.end_price)

  const now = Date.now()
  const elapsed = now - Number(state.start_time_ms)
  const drops = Math.floor(elapsed / Number(state.price_drop_interval_ms))
  const totalDrop = drops * Number(state.price_drop_amount)
  const maxDrop = Number(state.start_price) - Number(state.end_price)

  if (totalDrop >= maxDrop) return Number(state.end_price)
  return Number(state.start_price) - totalDrop
}

function msUntilNextDrop(state: AuctionState): number {
  const now = Date.now()
  const elapsed = now - Number(state.start_time_ms)
  const interval = Number(state.price_drop_interval_ms)
  return interval - (elapsed % interval)
}

export function AuctionApp() {
  const { isConnected, handleConnect } = useConnection()
  const dAppKit = useDAppKit()
  const [auctionState, setAuctionState] = useState<AuctionState | null>(null)
  const [currentPrice, setCurrentPrice] = useState(0)
  const [countdown, setCountdown] = useState(0)
  const [status, setStatus] = useState('')
  const [isBuying, setIsBuying] = useState(false)

  // Load auction state
  const loadAuction = useCallback(async () => {
    const obj = await getObjectWithJson(AUCTION_ID)
    if (obj?.content?.dataType === 'moveObject') {
      const fields = obj.content.fields as AuctionState
      setAuctionState(fields)
    }
  }, [])

  useEffect(() => {
    loadAuction()
  }, [loadAuction])

  // Update price countdown every second
  useEffect(() => {
    if (!auctionState) return
    const timer = setInterval(() => {
      setCurrentPrice(calculateCurrentPrice(auctionState))
      setCountdown(msUntilNextDrop(auctionState))
    }, 1000)
    return () => clearInterval(timer)
  }, [auctionState])

  const handleBuyNow = async () => {
    if (!isConnected) { setStatus('Please connect wallet first'); return }
    setIsBuying(true)
    setStatus('⏳ Submitting transaction...')

    try {
      const tx = new Transaction()
      const [paymentCoin] = tx.splitCoins(tx.gas, [
        tx.pure.u64(currentPrice + 1_000) // Slightly more than current price, prevent last-second price changes
      ])

      tx.moveCall({
        target: `${DUTCH_PACKAGE}::auction::buy_now`,
        arguments: [
          tx.object(AUCTION_ID),
          tx.object(STORAGE_UNIT_ID),
          tx.object(CHARACTER_ID),
          paymentCoin,
          tx.object(CLOCK_OBJECT_ID),
        ],
      })

      const result = await dAppKit.signAndExecuteTransaction({ transaction: tx })
      setStatus(`🏆 Bid successful! Tx: ${result.digest.slice(0, 12)}...`)
      await loadAuction()
    } catch (e: any) {
      setStatus(`❌ ${e.message}`)
    } finally {
      setIsBuying(false)
    }
  }

  const countdownSec = Math.ceil(countdown / 1000)
  const priceInSui = (currentPrice / 1e9).toFixed(2)
  const nextPriceSui = (
    Math.max(Number(auctionState?.end_price ?? 0), currentPrice - Number(auctionState?.price_drop_amount ?? 0)) / 1e9
  ).toFixed(2)

  return (
    <div className="auction-app">
      <header>
        <h1>🔨 Dutch Auction House</h1>
        {!isConnected
          ? <button onClick={handleConnect}>Connect Wallet</button>
          : <span className="connected">✅ Connected</span>
        }
      </header>

      {auctionState ? (
        <div className="auction-board">
          <div className="current-price">
            <span className="label">Current Price</span>
            <span className="price">{priceInSui} SUI</span>
          </div>

          <div className="countdown">
            <span className="label">⏳ Drops to {nextPriceSui} SUI in {countdownSec}s</span>
            <span className="next-price">{nextPriceSui} SUI</span>
          </div>

          <div className="info-row">
            <span>Starting Price: {(Number(auctionState.start_price) / 1e9).toFixed(2)} SUI</span>
            <span>Minimum Price: {(Number(auctionState.end_price) / 1e9).toFixed(2)} SUI</span>
          </div>

          {auctionState.is_active ? (
            <button
              className="buy-btn"
              onClick={handleBuyNow}
              disabled={isBuying || !isConnected}
            >
              {isBuying ? '⏳ Buying...' : `💰 Buy Now ${priceInSui} SUI`}
            </button>
          ) : (
            <div className="sold-banner">🎉 Sold</div>
          )}

          {status && <p className="tx-status">{status}</p>}
        </div>
      ) : (
        <div>Loading auction info...</div>
      )}
    </div>
  )
}

🎯 Complete Review

Contract Layer
├── create_auction() → Creates shared DutchAuction object
├── current_price()  → Calculates current price based on time (pure calculation, no state modification)
├── buy_now()        → Payment → Revenue to treasury → Withdraw item from SSU → Emit event
├── cancel_auction() → Owner cancels, returns item
└── withdraw_proceeds() → Owner withdraws auction proceeds

dApp Layer
├── Recalculates price every second (pure frontend, no Gas consumption)
├── Countdown display for next price drop
└── One-click purchase, automatically attaches current price

🔧 Extension Exercises

1. Support batch auctions: Auction multiple item types simultaneously, each with independent countdown
2. Scheduled purchase: Players set target price, automatically trigger purchase when reached (off-chain monitoring + scheduled submission)
3. Transaction history: Monitor AuctionSettled events to display recent transaction data

📚 Related Documentation

• Chapter 12: Event System
• Chapter 14: Pricing Strategies
• Smart Storage Unit

Example 6: Dynamic NFT Equipment System (Evolving Spaceship Weapons)

Goal: Create a spaceship weapon NFT system where attributes automatically upgrade based on combat results; utilize Sui Display standard to ensure NFTs display latest status in real-time across all wallets and marketplaces.

Status: Teaching example. Main content focuses on dynamic NFT and Display updates, complete directory at book/src/code/example-06/.

Code Directory

• example-06
• example-06/dapp

Minimal Call Chain

Player holds weapon NFT -> Kill events accumulate -> Reaches threshold to upgrade -> Display metadata updates -> Wallet/marketplace displays new appearance

Requirements Analysis

Scenario: You designed a “growth weapon” system - players obtain a PlasmaRifle, initially an ordinary weapon, automatically upgrades appearance and attributes as kills accumulate:

• ⚪ Basic (0-9 kills): Plasma Rifle Mk.1, base damage
• 🔵 Elite (10-49 kills): Plasma Rifle Mk.2, image changes to elite version, damage +30%
• 🟡 Legendary (50+ kills): Plasma Rifle Mk.3 “Inferno”, image changes to legendary version, special effects

Part 1: NFT Contract

module dynamic_nft::plasma_rifle;

use sui::object::{Self, UID};
use sui::display;
use sui::package;
use sui::transfer;
use sui::event;
use std::string::{Self, String, utf8};

// ── One-Time Witness ─────────────────────────────────────────────

public struct PLASMA_RIFLE has drop {}

// ── Weapon Tier Constants ───────────────────────────────────────────

const TIER_BASIC: u8 = 1;
const TIER_ELITE: u8 = 2;
const TIER_LEGENDARY: u8 = 3;

const KILLS_FOR_ELITE: u64 = 10;
const KILLS_FOR_LEGENDARY: u64 = 50;

// ── Data Structures ───────────────────────────────────────────────

public struct PlasmaRifle has key, store {
    id: UID,
    name: String,
    tier: u8,
    kills: u64,
    damage_bonus_pct: u64,   // Damage bonus (percentage)
    image_url: String,
    description: String,
    owner_history: u64,      // Historical transfer count
}

public struct ForgeAdminCap has key, store {
    id: UID,
}

// ── Events ──────────────────────────────────────────────────

public struct RifleEvolved has copy, drop {
    rifle_id: ID,
    from_tier: u8,
    to_tier: u8,
    total_kills: u64,
}

// ── Initialization ────────────────────────────────────────────────

fun init(witness: PLASMA_RIFLE, ctx: &mut TxContext) {
    let publisher = package::claim(witness, ctx);

    let keys = vector[
        utf8(b"name"),
        utf8(b"description"),
        utf8(b"image_url"),
        utf8(b"attributes"),
        utf8(b"project_url"),
    ];

    let values = vector[
        utf8(b"{name}"),
        utf8(b"{description}"),
        utf8(b"{image_url}"),
        // attributes concatenates multiple fields
        utf8(b"[{\"trait_type\":\"Tier\",\"value\":\"{tier}\"},{\"trait_type\":\"Kills\",\"value\":\"{kills}\"},{\"trait_type\":\"Damage Bonus\",\"value\":\"{damage_bonus_pct}%\"}]"),
        utf8(b"https://evefrontier.com/weapons"),
    ];

    let mut display = display::new_with_fields<PlasmaRifle>(
        &publisher, keys, values, ctx,
    );
    display::update_version(&mut display);

    let admin_cap = ForgeAdminCap { id: object::new(ctx) };

    transfer::public_transfer(publisher, ctx.sender());
    transfer::public_freeze_object(display);
    transfer::public_transfer(admin_cap, ctx.sender());
}

// ── Forge Initial Weapon ──────────────────────────────────────────

public fun forge_rifle(
    _admin: &ForgeAdminCap,
    recipient: address,
    ctx: &mut TxContext,
) {
    let rifle = PlasmaRifle {
        id: object::new(ctx),
        name: utf8(b"Plasma Rifle Mk.1"),
        tier: TIER_BASIC,
        kills: 0,
        damage_bonus_pct: 0,
        image_url: utf8(b"https://assets.example.com/weapons/plasma_mk1.png"),
        description: utf8(b"A standard-issue plasma rifle. Prove yourself in combat."),
        owner_history: 0,
    };

    transfer::public_transfer(rifle, recipient);
}

// ── Record Kill (called by turret extension)────────────────────────

public fun record_kill(
    rifle: &mut PlasmaRifle,
    ctx: &TxContext,
) {
    rifle.kills = rifle.kills + 1;
    check_and_evolve(rifle);
}

fun check_and_evolve(rifle: &mut PlasmaRifle) {
    let old_tier = rifle.tier;

    if rifle.kills >= KILLS_FOR_LEGENDARY && rifle.tier < TIER_LEGENDARY {
        rifle.tier = TIER_LEGENDARY;
        rifle.name = utf8(b"Plasma Rifle Mk.3 \"Inferno\"");
        rifle.damage_bonus_pct = 60;
        rifle.image_url = utf8(b"https://assets.example.com/weapons/plasma_legendary.png");
        rifle.description = utf8(b"This weapon has bathed in the fires of a thousand battles. Its plasma burns with legendary fury.");
    } else if rifle.kills >= KILLS_FOR_ELITE && rifle.tier < TIER_ELITE {
        rifle.tier = TIER_ELITE;
        rifle.name = utf8(b"Plasma Rifle Mk.2");
        rifle.damage_bonus_pct = 30;
        rifle.image_url = utf8(b"https://assets.example.com/weapons/plasma_mk2.png");
        rifle.description = utf8(b"Battle-hardened and upgraded. The plasma cells burn hotter than standard.");
    };

    if old_tier != rifle.tier {
        event::emit(RifleEvolved {
            rifle_id: object::id(rifle),
            from_tier: old_tier,
            to_tier: rifle.tier,
            total_kills: rifle.kills,
        });
    }
}

// ── Getter Functions ──────────────────────────────────────────────

public fun get_tier(rifle: &PlasmaRifle): u8 { rifle.tier }
public fun get_kills(rifle: &PlasmaRifle): u64 { rifle.kills }
public fun get_damage_bonus(rifle: &PlasmaRifle): u64 { rifle.damage_bonus_pct }

// ── Transfer Tracking (optional) ─────────────────────────────────────

// If using TransferPolicy, can track transfer count
// Simplified here via event monitoring

Part 2: Turret Extension - Combat Result Reports to Weapon

module dynamic_nft::turret_combat;

use dynamic_nft::plasma_rifle::{Self, PlasmaRifle};
use world::turret::{Self, Turret};
use world::character::Character;

public struct CombatAuth has drop {}

/// Turret kill event (called by turret extension)
public fun on_kill(
    turret: &Turret,
    killer: &Character,
    weapon: &mut PlasmaRifle,       // Player's weapon
    ctx: &TxContext,
) {
    // Verify legitimate turret extension call (requires CombatAuth)
    turret::verify_extension(turret, CombatAuth {});

    // Record kill to weapon
    plasma_rifle::record_kill(weapon, ctx);
}

Part 3: Frontend Weapon Display dApp

// src/WeaponDisplay.tsx
import { useState, useEffect } from 'react'
import { useCurrentClient } from '@mysten/dapp-kit-react'
import { useRealtimeEvents } from './hooks/useRealtimeEvents'

const DYNAMIC_NFT_PKG = "0x_DYNAMIC_NFT_PACKAGE_"

interface RifleData {
  name: string
  tier: string
  kills: string
  damage_bonus_pct: string
  image_url: string
  description: string
}

const TIER_COLORS = {
  '1': '#9CA3AF',  // Gray (basic)
  '2': '#3B82F6',  // Blue (elite)
  '3': '#F59E0B',  // Gold (legendary)
}

const TIER_LABELS = { '1': 'Basic', '2': 'Elite', '3': 'Legendary' }

export function WeaponDisplay({ rifleId }: { rifleId: string }) {
  const client = useCurrentClient()
  const [rifle, setRifle] = useState<RifleData | null>(null)
  const [justEvolved, setJustEvolved] = useState(false)

  const loadRifle = async () => {
    const obj = await client.getObject({
      id: rifleId,
      options: { showContent: true },
    })
    if (obj.data?.content?.dataType === 'moveObject') {
      setRifle(obj.data.content.fields as RifleData)
    }
  }

  useEffect(() => { loadRifle() }, [rifleId])

  // Monitor evolution events
  const evolutions = useRealtimeEvents<{
    rifle_id: string; from_tier: string; to_tier: string; total_kills: string
  }>(`${DYNAMIC_NFT_PKG}::plasma_rifle::RifleEvolved`)

  useEffect(() => {
    const myEvolution = evolutions.find(e => e.rifle_id === rifleId)
    if (myEvolution) {
      setJustEvolved(true)
      loadRifle() // Reload latest data
      setTimeout(() => setJustEvolved(false), 5000)
    }
  }, [evolutions])

  if (!rifle) return <div className="loading">Loading weapon data...</div>

  const tierColor = TIER_COLORS[rifle.tier as keyof typeof TIER_COLORS]
  const tierLabel = TIER_LABELS[rifle.tier as keyof typeof TIER_LABELS]
  const killsForNextTier = rifle.tier === '1'
    ? 10 : rifle.tier === '2' ? 50 : null
  const progress = killsForNextTier
    ? Math.min(100, (Number(rifle.kills) / killsForNextTier) * 100) : 100

  return (
    <div className="weapon-card" style={{ borderColor: tierColor }}>
      {justEvolved && (
        <div className="evolution-banner">
          ✨ Weapon Evolved!
        </div>
      )}

      <div className="weapon-image-container">
        <img
          src={rifle.image_url}
          alt={rifle.name}
          className={`weapon-image tier-${rifle.tier}`}
        />
        <span className="tier-badge" style={{ background: tierColor }}>
          {tierLabel}
        </span>
      </div>

      <div className="weapon-info">
        <h2>{rifle.name}</h2>
        <p className="description">{rifle.description}</p>

        <div className="stats">
          <div className="stat">
            <span>⚔️ Kills</span>
            <strong>{rifle.kills}</strong>
          </div>
          <div className="stat">
            <span>💥 Damage Bonus</span>
            <strong>+{rifle.damage_bonus_pct}%</strong>
          </div>
        </div>

        {killsForNextTier && (
          <div className="evolution-progress">
            <span>Evolution Progress: {rifle.kills} / {killsForNextTier} kills</span>
            <div className="progress-bar">
              <div
                className="progress-fill"
                style={{ width: `${progress}%`, background: tierColor }}
              />
            </div>
          </div>
        )}

        {!killsForNextTier && (
          <div className="max-tier-badge">👑 Max Tier Reached</div>
        )}
      </div>
    </div>
  )
}

🎯 Complete Review

Contract Layer
├── plasma_rifle.move
│   ├── PlasmaRifle (NFT object, fields update with combat)
│   ├── Display (template references fields → wallet auto-syncs display)
│   ├── forge_rifle()    ← Owner mints and distributes
│   ├── record_kill()    ← Turret contract calls
│   └── check_and_evolve() ← Internal: check threshold, upgrade fields + emit event
│
└── turret_combat.move
    └── on_kill()         ← Turret kill triggers weapon upgrade

dApp Layer
└── WeaponDisplay.tsx
    ├── Subscribe to RifleEvolved event (refresh immediately on evolution)
    ├── Dynamic color theme (by tier)
    └── Evolution progress bar

🔧 Extension Exercises

1. Weapon Durability: Each use decreases durability field, quality degrades and damage reduces when low (needs repair)
2. Special Attributes: Legendary tier randomly gains special affixes (using random numbers + dynamic fields)
3. Weapon Fusion: Two Elite weapons destroyed → mint one Legendary (material consumption upgrade)

📚 Related Documentation

• Chapter 13: NFT Design & Display Standard
• Chapter 12: Event System
• Sui Display Documentation

Example 7: Gate Logistics Network (Multi-Hop Routing System)

Goal: Build a logistics network where an alliance owns multiple gates, supporting “A → B → C” multi-hop routing, off-chain calculates optimal path, on-chain atomically executes multiple jumps; with route planning dApp.

Status: Teaching example. Current example focuses on multi-hop routing and off-chain planning architecture, emphasizing unified interfaces rather than individual Move contracts.

Code Directory

• example-07
• example-07/dapp

Minimal Call Chain

Off-chain calculates optimal route -> Builds multi-hop PTB -> On-chain atomically executes all jumps -> All succeed or all rollback

Requirements Analysis

Scenario: Your alliance controls 5 interconnected gates, forming the following topology:

Mining Area ──[Gate1]──► Hub Alpha ──[Gate2]──► Trade Hub
                              │
                         [Gate3]
                              │
                         Refinery ──[Gate4]──► Manufacturing
                              │
                         [Gate5]
                              │
                         Safe Harbor

Requirements:

• Players can purchase “multi-hop passes” in one transaction, completing composite routes like A→Hub Alpha→Trade Hub
• Route calculation done off-chain (saves Gas)
• On-chain atomic execution: all jumps succeed or all rollback
• dApp provides visual route planner

Part 1: Multi-Hop Routing Contract

module logistics::multi_hop;

use world::gate::{Self, Gate};
use world::character::Character;
use sui::coin::{Self, Coin};
use sui::sui::SUI;
use sui::clock::Clock;
use sui::object::{Self, ID};
use sui::event;

public struct LogisticsAuth has drop {}

/// Purchase multi-hop route in one transaction
public fun purchase_route(
    source_gate: &Gate,
    hop1_dest: &Gate,       // First hop destination
    hop2_source: &Gate,     // Second hop source (= hop1_dest's linked gate)
    hop2_dest: &Gate,       // Second hop destination
    character: &Character,
    mut payment: Coin<SUI>,  // Payment for both hops' total toll
    clock: &Clock,
    ctx: &mut TxContext,
) {
    // Verify route continuity: hop1_dest and hop2_source must be linked gates
    assert!(
        gate::are_linked(hop1_dest, hop2_source),
        ERouteDiscontinuous,
    );

    // Calculate and deduct toll for each hop
    let hop1_toll = get_toll(source_gate);
    let hop2_toll = get_toll(hop2_source);
    let total_toll = hop1_toll + hop2_toll;

    assert!(coin::value(&payment) >= total_toll, EInsufficientPayment);

    // Return change
    let change = payment.split(coin::value(&payment) - total_toll, ctx);
    if coin::value(&change) > 0 {
        transfer::public_transfer(change, ctx.sender());
    } else { coin::destroy_zero(change); }

    // Issue two JumpPermits (valid for 1 hour)
    let expires = clock.timestamp_ms() + 60 * 60 * 1000;

    gate::issue_jump_permit(
        source_gate, hop1_dest, character, LogisticsAuth {}, expires, ctx,
    );
    gate::issue_jump_permit(
        hop2_source, hop2_dest, character, LogisticsAuth {}, expires, ctx,
    );

    // Collect tolls
    let hop1_coin = payment.split(hop1_toll, ctx);
    let hop2_coin = payment;
    collect_toll(source_gate, hop1_coin, ctx);
    collect_toll(hop2_source, hop2_coin, ctx);

    event::emit(RouteTicketIssued {
        character_id: object::id(character),
        gates: vector[object::id(source_gate), object::id(hop1_dest), object::id(hop2_dest)],
        total_toll,
    });
}

/// General N-hop routing (accepts variable-length routes)
public fun purchase_route_n_hops(
    gates: vector<&Gate>,          // Gate list [A, B, C, D, ...]
    character: &Character,
    mut payment: Coin<SUI>,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    let n = vector::length(&gates);
    assert!(n >= 2, ETooFewGates);
    assert!(n <= 6, ETooManyHops); // Prevent overly large transactions

    // Verify route continuity (each adjacent destination/source pair must be linked)
    let mut i = 1;
    while (i < n - 1) {
        assert!(
            gate::are_linked(vector::borrow(&gates, i), vector::borrow(&gates, i)),
            ERouteDiscontinuous,
        );
        i = i + 1;
    };

    // Calculate total toll
    let mut total: u64 = 0;
    let mut j = 0;
    while (j < n - 1) {
        total = total + get_toll(vector::borrow(&gates, j));
        j = j + 1;
    };

    assert!(coin::value(&payment) >= total, EInsufficientPayment);

    // Issue all Permits
    let expires = clock.timestamp_ms() + 60 * 60 * 1000;
    let mut k = 0;
    while (k < n - 1) {
        gate::issue_jump_permit(
            vector::borrow(&gates, k),
            vector::borrow(&gates, k + 1),
            character,
            LogisticsAuth {},
            expires,
            ctx,
        );
        k = k + 1;
    };

    // Refund change
    let change = payment.split(coin::value(&payment) - total, ctx);
    if coin::value(&change) > 0 {
        transfer::public_transfer(change, ctx.sender());
    } else { coin::destroy_zero(change); }
    // Process payment to each gate treasury...
}

fun get_toll(gate: &Gate): u64 {
    // Read toll from gate's extension data (dynamic field)
    // Simplified version: fixed rate
    10_000_000_000 // 10 SUI
}

fun collect_toll(gate: &Gate, coin: Coin<SUI>, ctx: &TxContext) {
    // Transfer coin to gate's corresponding Treasury
    // ...
}

public struct RouteTicketIssued has copy, drop {
    character_id: ID,
    gates: vector<ID>,
    total_toll: u64,
}

const ERouteDiscontinuous: u64 = 0;
const EInsufficientPayment: u64 = 1;
const ETooFewGates: u64 = 2;
const ETooManyHops: u64 = 3;

Part 2: Off-Chain Path Planning (Dijkstra)

// lib/routePlanner.ts

interface Gate {
  id: string
  name: string
  linkedGates: string[]  // Linked gate ID list
  tollAmount: number     // Toll (SUI)
}

interface Route {
  gateIds: string[]
  totalToll: number
  hops: number
}

// Dijkstra shortest path (weighted by toll)
export function findCheapestRoute(
  gateMap: Map<string, Gate>,
  fromId: string,
  toId: string,
): Route | null {
  const dist = new Map<string, number>()
  const prev = new Map<string, string | null>()
  const unvisited = new Set(gateMap.keys())

  for (const id of gateMap.keys()) {
    dist.set(id, Infinity)
    prev.set(id, null)
  }
  dist.set(fromId, 0)

  while (unvisited.size > 0) {
    // Find unvisited node with minimum distance
    let current: string | null = null
    let minDist = Infinity
    for (const id of unvisited) {
      if ((dist.get(id) ?? Infinity) < minDist) {
        minDist = dist.get(id)!
        current = id
      }
    }

    if (!current || current === toId) break
    unvisited.delete(current)

    const gate = gateMap.get(current)!
    for (const neighborId of gate.linkedGates) {
      const neighbor = gateMap.get(neighborId)
      if (!neighbor || !unvisited.has(neighborId)) continue

      const newDist = (dist.get(current) ?? 0) + neighbor.tollAmount
      if (newDist < (dist.get(neighborId) ?? Infinity)) {
        dist.set(neighborId, newDist)
        prev.set(neighborId, current)
      }
    }
  }

  if (dist.get(toId) === Infinity) return null // Unreachable

  // Reconstruct path
  const path: string[] = []
  let cur: string | null = toId
  while (cur) {
    path.unshift(cur)
    cur = prev.get(cur) ?? null
  }

  return {
    gateIds: path,
    totalToll: dist.get(toId) ?? 0,
    hops: path.length - 1,
  }
}

Part 3: Route Planner dApp

// src/RoutePlannerApp.tsx
import { useState, useEffect } from 'react'
import { useConnection } from '@evefrontier/dapp-kit'
import { useDAppKit } from '@mysten/dapp-kit-react'
import { findCheapestRoute } from '../lib/routePlanner'
import { Transaction } from '@mysten/sui/transactions'

const LOGISTICS_PKG = "0x_LOGISTICS_PACKAGE_"

// Gate network topology (usually read from on-chain)
const GATE_NETWORK = new Map([
  ['gate_mining', { id: 'gate_mining', name: 'Mining Entry', linkedGates: ['gate_hub_alpha'], tollAmount: 5 }],
  ['gate_hub_alpha', { id: 'gate_hub_alpha', name: 'Hub Alpha', linkedGates: ['gate_mining', 'gate_trade', 'gate_refinery'], tollAmount: 3 }],
  ['gate_trade', { id: 'gate_trade', name: 'Trade Hub', linkedGates: ['gate_hub_alpha'], tollAmount: 8 }],
  ['gate_refinery', { id: 'gate_refinery', name: 'Refinery', linkedGates: ['gate_hub_alpha', 'gate_manufacturing', 'gate_harbor'], tollAmount: 4 }],
  ['gate_manufacturing', { id: 'gate_manufacturing', name: 'Manufacturing', linkedGates: ['gate_refinery'], tollAmount: 6 }],
  ['gate_harbor', { id: 'gate_harbor', name: 'Safe Harbor', linkedGates: ['gate_refinery'], tollAmount: 2 }],
])

export function RoutePlannerApp() {
  const { isConnected, handleConnect } = useConnection()
  const dAppKit = useDAppKit()
  const [from, setFrom] = useState('')
  const [to, setTo] = useState('')
  const [route, setRoute] = useState<{gateIds: string[]; totalToll: number; hops: number} | null>(null)
  const [status, setStatus] = useState('')

  const planRoute = () => {
    if (!from || !to) return
    const result = findCheapestRoute(GATE_NETWORK, from, to)
    setRoute(result)
  }

  const purchaseRoute = async () => {
    if (!route || route.gateIds.length < 2) return

    const tx = new Transaction()

    // Prepare payment (total toll + 5% buffer to prevent price changes)
    const totalSui = Math.ceil(route.totalToll * 1.05) * 1e9
    const [paymentCoin] = tx.splitCoins(tx.gas, [tx.pure.u64(totalSui)])

    // Build gate parameter list
    const gateArgs = route.gateIds.map(id => tx.object(id))

    // Call multi-hop routing contract
    if (route.hops === 2) {
      tx.moveCall({
        target: `${LOGISTICS_PKG}::multi_hop::purchase_route`,
        arguments: [
          gateArgs[0], gateArgs[1], gateArgs[1], gateArgs[2],
          tx.object('CHARACTER_ID'),
          paymentCoin,
          tx.object('0x6'),
        ],
      })
    }

    try {
      setStatus('⏳ Purchasing route pass...')
      const result = await dAppKit.signAndExecuteTransaction({ transaction: tx })
      setStatus(`✅ Route purchased successfully! Tx: ${result.digest.slice(0, 12)}...`)
    } catch (e: any) {
      setStatus(`❌ ${e.message}`)
    }
  }

  return (
    <div className="route-planner">
      <h1>🗺 Gate Logistics Route Planner</h1>

      <div className="planner-inputs">
        <div>
          <label>Departure Gate</label>
          <select value={from} onChange={e => setFrom(e.target.value)}>
            <option value="">Select departure...</option>
            {[...GATE_NETWORK.values()].map(g => (
              <option key={g.id} value={g.id}>{g.name}</option>
            ))}
          </select>
        </div>

        <div className="arrow">→</div>

        <div>
          <label>Destination Gate</label>
          <select value={to} onChange={e => setTo(e.target.value)}>
            <option value="">Select destination...</option>
            {[...GATE_NETWORK.values()].map(g => (
              <option key={g.id} value={g.id}>{g.name}</option>
            ))}
          </select>
        </div>

        <button onClick={planRoute} disabled={!from || !to || from === to}>
          📍 Plan Route
        </button>
      </div>

      {route && (
        <div className="route-result">
          <h3>Optimal Route (Lowest Cost)</h3>
          <div className="route-path">
            {route.gateIds.map((id, i) => (
              <>
                <span key={id} className="gate-node">
                  {GATE_NETWORK.get(id)?.name}
                </span>
                {i < route.gateIds.length - 1 && (
                  <span className="arrow-icon">→</span>
                )}
              </>
            ))}
          </div>
          <div className="route-stats">
            <span>🔀 Jumps: {route.hops}</span>
            <span>💰 Total Cost: {route.totalToll} SUI</span>
          </div>
          <button
            className="purchase-btn"
            onClick={purchaseRoute}
            disabled={!isConnected}
          >
            {isConnected ? '🚀 One-Click Purchase Full Route Pass' : 'Please Connect Wallet'}
          </button>
        </div>
      )}

      {route === null && from && to && from !== to && (
        <p className="no-route">⚠️ No route found from {from} to {to}</p>
      )}

      {status && <p className="status">{status}</p>}
    </div>
  )
}

🎯 Complete Review

Contract Layer
├── multi_hop.move
│   ├── purchase_route()      → Two-hop quick version (specifies 4 gate parameters)
│   ├── purchase_route_n_hops() → N-hop general version (vector parameters, max 6 hops)
│   └── LogisticsAuth {}      → Gate extension Witness

Off-Chain Path Planning
└── routePlanner.ts
    └── findCheapestRoute()   → Dijkstra, weighted by toll

dApp Layer
└── RoutePlannerApp.tsx
    ├── Dropdown select departure/destination
    ├── Call Dijkstra to display optimal route
    └── One-click purchase full route pass

🔧 Extension Exercises

1. Shortest Hop Routing: Implement second mode (prioritize reducing hops rather than cost)
2. Real-Time Congestion Awareness: Monitor GateJumped events, calculate last 5 minutes traffic per gate, route to avoid congestion
3. Item Escort Insurance: Can purchase additional “item loss insurance” NFT when buying route, compensate on failure

📚 Related Documentation

• Smart Gate API
• Chapter 21: Batch Transactions
• Chapter 9: Off-Chain Indexing

Example 9: Cross-Builder Protocol Aggregator Market

Goal: Design a “protocol adapter” layer allowing users to access multiple different Builder-published market contracts (despite varying interfaces) in one dApp, achieving DEX aggregator-like experience.

Status: Teaching example. Current example focuses on aggregator architecture and adapter layering, emphasizing unified interfaces rather than individual Move contracts.

Code Directory

• example-09/dapp

Minimal Call Chain

Frontend queries multiple markets -> Adapter normalizes quotes -> Select optimal market -> Submit purchase per corresponding protocol

Requirements Analysis

Scenario: EVE Frontier ecosystem already has 3 different Builder market contracts:

Players want to find which market has the cheapest item and buy with one click.

Part 1: Off-Chain Adapter Layer (TypeScript)

Since different contracts have different interfaces, adapters run off-chain, encapsulating differences into a unified interface:

// lib/marketAdapters.ts
import { Transaction } from "@mysten/sui/transactions"
import { SuiClient } from "@mysten/sui/client"

export interface MarketListing {
  marketId: string
  builder: string
  itemTypeId: number
  price: number        // SUI
  adapterName: string
}

// ── Adapter Interface ─────────────────────────────────────────────

export interface MarketAdapter {
  name: string
  packageId: string
  // Query item price in this market
  getPrice(client: SuiClient, itemTypeId: number): Promise<number | null>
  // Build purchase transaction
  buildBuyTx(
    tx: Transaction,
    itemTypeId: number,
    characterId: string,
    paymentCoin: any
  ): void
}

// ── Adapter A: Builder Alice's Market ────────────────────────

export const AliceMarketAdapter: MarketAdapter = {
  name: "Alice's Market",
  packageId: "0xAAA...",

  async getPrice(client, itemTypeId) {
    // Alice's market uses Table to store listings, key is item_id
    const obj = await client.getDynamicFieldObject({
      parentId: "0xAAA_MARKET_ID",
      name: { type: "u64", value: itemTypeId.toString() },
    })
    const fields = (obj.data?.content as any)?.fields
    return fields ? Number(fields.price) / 1e9 : null
  },

  buildBuyTx(tx, itemTypeId, characterId, paymentCoin) {
    tx.moveCall({
      target: `0xAAA...::market::buy_item`,
      arguments: [
        tx.object("0xAAA_MARKET_ID"),
        tx.object(characterId),
        tx.pure.u64(itemTypeId),
        paymentCoin,
      ],
    })
  },
}

// ── Adapter B: Builder Bob's Market ──────────────────────────

export const BobMarketAdapter: MarketAdapter = {
  name: "Bob's Depot",
  packageId: "0xBBB...",

  async getPrice(client, itemTypeId) {
    // Bob's market uses different struct, price field named 'cost'
    const obj = await client.getObject({
      id: "0xBBB_STORAGE_ID",
      options: { showContent: true },
    })
    const listings = (obj.data?.content as any)?.fields?.listings?.fields?.contents
    const found = listings?.find((e: any) => Number(e.fields?.key) === itemTypeId)
    return found ? Number(found.fields.value.fields.cost) / 1e9 : null
  },

  buildBuyTx(tx, itemTypeId, characterId, paymentCoin) {
    tx.moveCall({
      target: `0xBBB...::depot::purchase`,
      arguments: [
        tx.object("0xBBB_STORAGE_ID"),
        tx.object(characterId),
        tx.pure.u64(itemTypeId),
        paymentCoin,
      ],
    })
  },
}

// ── Adapter C: Your Own Market ────────────────────────────────

export const MyMarketAdapter: MarketAdapter = {
  name: "Your Market",
  packageId: "0xYYY...",

  async getPrice(client, itemTypeId) {
    // Your market has complete documentation, most straightforward reading
    const obj = await client.getDynamicFieldObject({
      parentId: "0xYYY_MARKET_ID",
      name: { type: "u64", value: itemTypeId.toString() },
    })
    const fields = (obj.data?.content as any)?.fields
    return fields ? Number(fields.value.fields.price) / 1e9 : null
  },

  buildBuyTx(tx, itemTypeId, characterId, paymentCoin) {
    tx.moveCall({
      target: `0xYYY...::market::buy_item_v2`,
      arguments: [
        tx.object("0xYYY_MARKET_ID"),
        tx.object(characterId),
        tx.pure.u64(itemTypeId),
        paymentCoin,
        tx.object("0x6"), // Clock (V2 adds this parameter)
      ],
    })
  },
}

// ── Aggregate Price Query ──────────────────────────────────────────

const ALL_ADAPTERS = [AliceMarketAdapter, BobMarketAdapter, MyMarketAdapter]

export async function aggregatePrices(
  client: SuiClient,
  itemTypeId: number,
): Promise<MarketListing[]> {
  const results = await Promise.all(
    ALL_ADAPTERS.map(async (adapter) => {
      const price = await adapter.getPrice(client, itemTypeId).catch(() => null)
      if (price === null) return null
      return {
        marketId: adapter.packageId,
        builder: adapter.name,
        itemTypeId,
        price,
        adapterName: adapter.name,
      } as MarketListing
    })
  )

  return results
    .filter((r): r is MarketListing => r !== null)
    .sort((a, b) => a.price - b.price) // Sort by price ascending
}

Part 2: Aggregated Purchase dApp

// src/AggregatedMarket.tsx
import { useState, useEffect } from 'react'
import { useConnection } from '@evefrontier/dapp-kit'
import { useDAppKit } from '@mysten/dapp-kit-react'
import { useCurrentClient } from '@mysten/dapp-kit-react'
import { Transaction } from '@mysten/sui/transactions'
import { aggregatePrices, MyMarketAdapter, BobMarketAdapter, AliceMarketAdapter, MarketListing } from '../lib/marketAdapters'

const ADAPTERS_MAP = {
  [AliceMarketAdapter.packageId]: AliceMarketAdapter,
  [BobMarketAdapter.packageId]: BobMarketAdapter,
  [MyMarketAdapter.packageId]: MyMarketAdapter,
}

const ITEM_TYPES = [
  { id: 101, name: 'Rare Ore' },
  { id: 102, name: 'Shield Module' },
  { id: 103, name: 'Thruster' },
]

export function AggregatedMarket() {
  const { isConnected, handleConnect } = useConnection()
  const client = useCurrentClient()
  const dAppKit = useDAppKit()
  const [selectedItem, setSelectedItem] = useState<number | null>(null)
  const [listings, setListings] = useState<MarketListing[]>([])
  const [loading, setLoading] = useState(false)
  const [status, setStatus] = useState('')

  const searchListings = async (itemTypeId: number) => {
    setSelectedItem(itemTypeId)
    setLoading(true)
    try {
      const results = await aggregatePrices(client, itemTypeId)
      setListings(results)
    } finally {
      setLoading(false)
    }
  }

  const buyFromMarket = async (listing: MarketListing) => {
    if (!isConnected) { setStatus('Please connect wallet first'); return }
    setStatus('⏳ Building transaction...')

    const tx = new Transaction()
    const priceMist = BigInt(Math.ceil(listing.price * 1e9))
    const [paymentCoin] = tx.splitCoins(tx.gas, [tx.pure.u64(priceMist)])

    const adapter = ADAPTERS_MAP[listing.marketId]
    adapter.buildBuyTx(tx, listing.itemTypeId, 'CHARACTER_ID', paymentCoin)

    try {
      const result = await dAppKit.signAndExecuteTransaction({ transaction: tx })
      setStatus(`✅ Purchase successful! Tx: ${result.digest.slice(0, 12)}...`)
      searchListings(listing.itemTypeId) // Refresh
    } catch (e: any) {
      setStatus(`❌ ${e.message}`)
    }
  }

  return (
    <div className="aggregated-market">
      <header>
        <h1>🛒 Cross-Market Aggregator</h1>
        <p>Real-time compare prices across multiple Builder markets, buy at lowest price with one click</p>
        {!isConnected && <button onClick={handleConnect}>Connect Wallet</button>}
      </header>

      {/* Item Selection */}
      <div className="item-selector">
        {ITEM_TYPES.map(item => (
          <button
            key={item.id}
            className={`item-btn ${selectedItem === item.id ? 'selected' : ''}`}
            onClick={() => searchListings(item.id)}
          >
            {item.name}
          </button>
        ))}
      </div>

      {/* Price List */}
      {loading && <div className="loading">🔍 Querying market prices...</div>}

      {!loading && listings.length > 0 && (
        <div className="listings">
          <h3>
            {ITEM_TYPES.find(i => i.id === selectedItem)?.name} — Price Comparison
            <span className="badge">Lowest Price First</span>
          </h3>
          {listings.map((listing, i) => (
            <div
              key={listing.marketId}
              className={`listing-row ${i === 0 ? 'best-price' : ''}`}
            >
              <span className="rank">#{i + 1}</span>
              <span className="builder">{listing.builder}</span>
              <span className="price">
                {listing.price.toFixed(2)} SUI
                {i === 0 && <span className="best-badge">Lowest</span>}
              </span>
              <button
                className="buy-btn"
                onClick={() => buyFromMarket(listing)}
                disabled={!isConnected}
              >
                Buy Now
              </button>
            </div>
          ))}
        </div>
      )}

      {!loading && listings.length === 0 && selectedItem && (
        <div className="empty">No listings for this item in all markets</div>
      )}

      {status && <div className="status">{status}</div>}
    </div>
  )
}

🎯 Complete Review

Architecture Layers
├── Contract Layer: Each Builder publishes separately, different interfaces
│   ├── Alice: buy_item(market, char, item_id, coin)
│   ├── Bob: purchase(storage, char, type_id, payment, ctx)
│   └── You: buy_item_v2(market, char, id, coin, clock, ctx)
│
├── Adapter Layer (TypeScript, off-chain)
│   ├── MarketAdapter interface unified
│   ├── AliceMarketAdapter: Encapsulates Alice's read/write differences
│   ├── BobMarketAdapter: Encapsulates Bob's read/write differences
│   └── MyMarketAdapter: Encapsulates your own read/write
│
└── Aggregator dApp Layer
    ├── aggregatePrices(): Parallel read all markets
    ├── Sort and display
    └── buyFromMarket(): Call corresponding adapter to build transaction

🔧 Extension Exercises

1. On-Chain Adapter Registry: Maintain verified adapter list on-chain (prevent malicious Builders with fake prices to gain trust)
2. Slippage Protection: Verify latest on-chain price before order, abort if change exceeds 5%
3. Batch Purchase: Buy different items from multiple markets in one transaction

📚 Related Documentation

• Chapter 15: Cross-Contract Composability
• Chapter 9: Off-Chain Indexing
• Chapter 19: Full-Stack dApp Architecture

Practical Case 13: Subscription Pass (Monthly Unlimited Jumps)

Objective: Establish a subscription pass system—players pay a fixed SUI monthly for unlimited jumping rights in your alliance stargate network, no need to purchase tickets each time.

Status: Teaching example. The main text focuses on subscription model, complete directory is based on book/src/code/example-13/.

Corresponding Code Directory

• example-13
• example-13/dapp

Minimal Call Chain

Select plan -> Pay subscription fee -> Mint/update GatePassNFT -> Stargate verifies pass validity

Requirements Analysis

Scenario: Your alliance controls 5 stargates and wants to establish a monthly membership system:

• Monthly Pass: 30 SUI/month, unlimited jumps through all stargates
• Quarterly Pass: 80 SUI/quarter, with discount
• After expiration, renewal required, otherwise downgrade to pay-per-use
• Subscription NFT is transferable (players can trade on secondary market)

Contract

module subscription::gate_pass;

use sui::object::{Self, UID, ID};
use sui::clock::Clock;
use sui::coin::{Self, Coin};
use sui::sui::SUI;
use sui::balance::{Self, Balance};
use sui::transfer;
use sui::event;
use std::string::String;

// ── Constants ──────────────────────────────────────────────────

const MONTH_MS: u64 = 30 * 24 * 60 * 60 * 1000;

/// Plan types
const PLAN_MONTHLY: u8 = 0;
const PLAN_QUARTERLY: u8 = 1;

// ── Data Structures ───────────────────────────────────────────────

/// Subscription manager (shared object)
public struct SubscriptionManager has key {
    id: UID,
    monthly_price: u64,     // Monthly plan price (MIST)
    quarterly_price: u64,   // Quarterly plan price
    revenue: Balance<SUI>,
    admin: address,
    total_subscribers: u64,
}

/// Subscription NFT (transferable, holding grants permission)
public struct GatePassNFT has key, store {
    id: UID,
    plan: u8,
    valid_until_ms: u64,
    subscriber: address,  // Original subscriber
    serial_number: u64,
}

// ── Events ──────────────────────────────────────────────────

public struct PassPurchased has copy, drop {
    pass_id: ID,
    buyer: address,
    plan: u8,
    valid_until_ms: u64,
}

public struct PassRenewed has copy, drop {
    pass_id: ID,
    new_expiry_ms: u64,
}

// ── Initialization ────────────────────────────────────────────────

fun init(ctx: &mut TxContext) {
    transfer::share_object(SubscriptionManager {
        id: object::new(ctx),
        monthly_price: 30_000_000_000,   // 30 SUI
        quarterly_price: 80_000_000_000, // 80 SUI (10 SUI cheaper than 3 months)
        revenue: balance::zero(),
        admin: ctx.sender(),
        total_subscribers: 0,
    });
}

// ── Purchase Subscription ──────────────────────────────────────────────

public fun purchase_pass(
    mgr: &mut SubscriptionManager,
    plan: u8,
    mut payment: Coin<SUI>,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    let (price, duration_ms) = if plan == PLAN_MONTHLY {
        (mgr.monthly_price, MONTH_MS)
    } else if plan == PLAN_QUARTERLY {
        (mgr.quarterly_price, 3 * MONTH_MS)
    } else abort EInvalidPlan;

    assert!(coin::value(&payment) >= price, EInsufficientPayment);

    let pay = payment.split(price, ctx);
    balance::join(&mut mgr.revenue, coin::into_balance(pay));

    if coin::value(&payment) > 0 {
        transfer::public_transfer(payment, ctx.sender());
    } else { coin::destroy_zero(payment); }

    mgr.total_subscribers = mgr.total_subscribers + 1;
    let valid_until_ms = clock.timestamp_ms() + duration_ms;

    let pass = GatePassNFT {
        id: object::new(ctx),
        plan,
        valid_until_ms,
        subscriber: ctx.sender(),
        serial_number: mgr.total_subscribers,
    };
    let pass_id = object::id(&pass);

    transfer::public_transfer(pass, ctx.sender());

    event::emit(PassPurchased {
        pass_id,
        buyer: ctx.sender(),
        plan,
        valid_until_ms,
    });
}

/// Renew (extend validity period of existing Pass)
public fun renew_pass(
    mgr: &mut SubscriptionManager,
    pass: &mut GatePassNFT,
    mut payment: Coin<SUI>,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    let (price, duration_ms) = if pass.plan == PLAN_MONTHLY {
        (mgr.monthly_price, MONTH_MS)
    } else {
        (mgr.quarterly_price, 3 * MONTH_MS)
    };

    assert!(coin::value(&payment) >= price, EInsufficientPayment);

    let pay = payment.split(price, ctx);
    balance::join(&mut mgr.revenue, coin::into_balance(pay));
    if coin::value(&payment) > 0 {
        transfer::public_transfer(payment, ctx.sender());
    } else { coin::destroy_zero(payment); }

    // If already expired, start from now, otherwise stack on original expiry time
    let base = if pass.valid_until_ms < clock.timestamp_ms() {
        clock.timestamp_ms()
    } else { pass.valid_until_ms };

    pass.valid_until_ms = base + duration_ms;

    event::emit(PassRenewed {
        pass_id: object::id(pass),
        new_expiry_ms: pass.valid_until_ms,
    });
}

/// Stargate extension: verify Pass validity
public fun is_pass_valid(pass: &GatePassNFT, clock: &Clock): bool {
    clock.timestamp_ms() <= pass.valid_until_ms
}

/// Stargate jump (unlimited jumps with valid Pass)
public fun subscriber_jump(
    gate: &Gate,
    dest_gate: &Gate,
    character: &Character,
    pass: &GatePassNFT,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    assert!(is_pass_valid(pass, clock), EPassExpired);
    gate::issue_jump_permit(
        gate, dest_gate, character, SubscriberAuth {},
        clock.timestamp_ms() + 30 * 60 * 1000, ctx,
    );
}

public struct SubscriberAuth has drop {}

/// Admin withdraw revenue
public fun withdraw_revenue(
    mgr: &mut SubscriptionManager,
    amount: u64,
    ctx: &TxContext,
) {
    assert!(ctx.sender() == mgr.admin, ENotAdmin);
    let coin = coin::take(&mut mgr.revenue, amount, ctx);
    transfer::public_transfer(coin, mgr.admin);
}

const EInvalidPlan: u64 = 0;
const EInsufficientPayment: u64 = 1;
const EPassExpired: u64 = 2;
const ENotAdmin: u64 = 3;

dApp

// PassShop.tsx
import { useState } from 'react'
import { Transaction } from '@mysten/sui/transactions'
import { useDAppKit } from '@mysten/dapp-kit-react'

const SUB_PKG = "0x_SUBSCRIPTION_PACKAGE_"
const MGR_ID = "0x_MANAGER_ID_"

const PLANS = [
  { id: 0, name: 'Monthly Plan', price: 30, duration: '30 days', badge: 'Standard' },
  { id: 1, name: 'Quarterly Plan', price: 80, duration: '90 days', badge: 'Save 10 SUI', popular: true },
]

export function PassShop() {
  const dAppKit = useDAppKit()
  const [status, setStatus] = useState('')

  const purchase = async (plan: number, priceInSUI: number) => {
    const tx = new Transaction()
    const [payment] = tx.splitCoins(tx.gas, [tx.pure.u64(priceInSUI * 1e9)])
    tx.moveCall({
      target: `${SUB_PKG}::gate_pass::purchase_pass`,
      arguments: [tx.object(MGR_ID), tx.pure.u8(plan), payment, tx.object('0x6')],
    })
    try {
      setStatus('Purchasing...')
      await dAppKit.signAndExecuteTransaction({ transaction: tx })
      setStatus('Subscription successful! GatePassNFT sent to your wallet')
    } catch (e: any) { setStatus(`${e.message}`) }
  }

  return (
    <div className="pass-shop">
      <h1>Stargate Subscription Pass</h1>
      <p>Unlimited jumps through all alliance stargates with valid pass</p>
      <div className="plan-grid">
        {PLANS.map(plan => (
          <div key={plan.id} className={`plan-card ${plan.popular ? 'popular' : ''}`}>
            {plan.popular && <div className="popular-badge">Recommended</div>}
            <h3>{plan.name}</h3>
            <div className="plan-price">
              <span className="price">{plan.price}</span>
              <span className="unit">SUI</span>
            </div>
            <div className="plan-duration">Valid for {plan.duration}</div>
            <div className="plan-badge">{plan.badge}</div>
            <button className="buy-btn" onClick={() => purchase(plan.id, plan.price)}>
              Purchase {plan.name}
            </button>
          </div>
        ))}
      </div>
      {status && <p className="status">{status}</p>}
    </div>
  )
}

Related Documentation

• Chapter 13: NFT Design and TransferPolicy
• Example 2: Stargate Toll Station

Practical Case 14: NFT Collateral Lending Protocol

Objective: Build an on-chain lending protocol—players use NFTs or high-value items as collateral to borrow SUI liquidity; collateral is liquidated and auctioned to the highest bidder if loan is not repaid on time.

Status: Teaching example. The main text covers core lending process, complete directory is based on book/src/code/example-14/.

Corresponding Code Directory

• example-14
• example-14/dapp

Minimal Call Chain

Lender injects liquidity -> Borrower collateralizes NFT -> Contract issues SUI -> Repayment on time or liquidation triggered

Requirements Analysis

Scenario: Player holds a “rare shield” worth 1000 SUI but urgently needs SUI to buy mining machines. They pledge the shield, borrow 600 SUI (60% LTV), and must return 618 SUI within 30 days (including 3% monthly interest), otherwise the shield is liquidated.

Contract

module lending::collateral_loan;

use sui::object::{Self, UID, ID};
use sui::clock::Clock;
use sui::coin::{Self, Coin};
use sui::sui::SUI;
use sui::balance::{Self, Balance};
use sui::transfer;
use sui::dynamic_field as df;
use sui::event;

// ── Constants ──────────────────────────────────────────────────

const MONTH_MS: u64 = 30 * 24 * 60 * 60 * 1000;
const LTV_BPS: u64 = 6_000;            // 60% loan-to-value
const MONTHLY_INTEREST_BPS: u64 = 300; // 3% monthly interest
const LIQUIDATION_BONUS_BPS: u64 = 500; // 5% liquidator reward

// ── Data Structures ───────────────────────────────────────────────

/// Lending pool (shared object, stores lender's SUI)
public struct LendingPool has key {
    id: UID,
    liquidity: Balance<SUI>,
    total_loaned: u64,
    admin: address,
}

/// Single loan
public struct Loan has key {
    id: UID,
    borrower: address,
    collateral_id: ID,    // Collateral ObjectID
    collateral_value: u64, // Evaluated value at lending time (SUI)
    loan_amount: u64,      // Actual borrowed amount
    interest_amount: u64,  // Interest due
    repay_by_ms: u64,      // Repayment deadline
    is_active: bool,
}

// ── Events ──────────────────────────────────────────────────

public struct LoanCreated has copy, drop {
    loan_id: ID,
    borrower: address,
    loan_amount: u64,
    repay_by_ms: u64,
}

public struct LoanRepaid has copy, drop {
    loan_id: ID,
    repaid: u64,
}

public struct LoanLiquidated has copy, drop {
    loan_id: ID,
    liquidator: address,
    collateral_id: ID,
}

// ── Initialize Lending Pool ──────────────────────────────────────────

public fun create_pool(ctx: &mut TxContext) {
    transfer::share_object(LendingPool {
        id: object::new(ctx),
        liquidity: balance::zero(),
        total_loaned: 0,
        admin: ctx.sender(),
    });
}

/// Lender deposits liquidity into pool
public fun deposit_liquidity(
    pool: &mut LendingPool,
    coin: Coin<SUI>,
    _ctx: &TxContext,
) {
    balance::join(&mut pool.liquidity, coin::into_balance(coin));
}

// ── Borrow (with NFT as collateral) ────────────────────────────────

/// Created by Oracle/Admin with evaluation
/// (In real scenarios, collateral_value needs to be determined by off-chain price oracle)
public fun create_loan<T: key + store>(
    pool: &mut LendingPool,
    collateral: T,
    collateral_value_sui: u64,    // Valuation confirmed by price oracle or Admin
    clock: &Clock,
    ctx: &mut TxContext,
) {
    let loan_amount = collateral_value_sui * LTV_BPS / 10_000; // 60% LTV
    let interest = loan_amount * MONTHLY_INTEREST_BPS / 10_000;
    assert!(balance::value(&pool.liquidity) >= loan_amount, EInsufficientLiquidity);

    let collateral_id = object::id(&collateral);

    let mut loan = Loan {
        id: object::new(ctx),
        borrower: ctx.sender(),
        collateral_id,
        collateral_value: collateral_value_sui,
        loan_amount,
        interest_amount: interest,
        repay_by_ms: clock.timestamp_ms() + MONTH_MS,
        is_active: true,
    };

    // Lock collateral in Loan object (dynamic field)
    df::add(&mut loan.id, b"collateral", collateral);

    // Issue loan
    let loan_coin = coin::take(&mut pool.liquidity, loan_amount, ctx);
    pool.total_loaned = pool.total_loaned + loan_amount;

    transfer::public_transfer(loan_coin, ctx.sender());

    event::emit(LoanCreated {
        loan_id: object::id(&loan),
        borrower: ctx.sender(),
        loan_amount,
        repay_by_ms: loan.repay_by_ms,
    });

    transfer::share_object(loan);
}

// ── Repayment (return loan + interest, retrieve collateral) ──────────────────

public fun repay_loan<T: key + store>(
    pool: &mut LendingPool,
    loan: &mut Loan,
    mut repayment: Coin<SUI>,
    ctx: &mut TxContext,
) {
    assert!(loan.borrower == ctx.sender(), ENotBorrower);
    assert!(loan.is_active, ELoanInactive);

    let total_due = loan.loan_amount + loan.interest_amount;
    assert!(coin::value(&repayment) >= total_due, EInsufficientRepayment);

    // Repayment to pool
    let repay_coin = repayment.split(total_due, ctx);
    balance::join(&mut pool.liquidity, coin::into_balance(repay_coin));
    pool.total_loaned = pool.total_loaned - loan.loan_amount;

    if coin::value(&repayment) > 0 {
        transfer::public_transfer(repayment, ctx.sender());
    } else { coin::destroy_zero(repayment); }

    // Retrieve collateral
    let collateral: T = df::remove(&mut loan.id, b"collateral");
    transfer::public_transfer(collateral, ctx.sender());

    loan.is_active = false;

    event::emit(LoanRepaid {
        loan_id: object::id(loan),
        repaid: total_due,
    });
}

// ── Liquidation (overdue, liquidator takes collateral) ──────────────────

public fun liquidate<T: key + store>(
    pool: &mut LendingPool,
    loan: &mut Loan,
    mut liquidation_payment: Coin<SUI>, // Liquidator pays collateral_value * 95%
    clock: &Clock,
    ctx: &mut TxContext,
) {
    assert!(loan.is_active, ELoanInactive);
    assert!(clock.timestamp_ms() > loan.repay_by_ms, ENotYetExpired);

    // Liquidator must pay 95% of collateral valuation (5% as reward)
    let liquidation_price = loan.collateral_value * (10_000 - LIQUIDATION_BONUS_BPS) / 10_000;
    assert!(coin::value(&liquidation_payment) >= liquidation_price, EInsufficientPayment);

    let pay = liquidation_payment.split(liquidation_price, ctx);
    // Repay principal + interest to pool, remainder to liquidator as reward
    balance::join(&mut pool.liquidity, coin::into_balance(pay));

    if coin::value(&liquidation_payment) > 0 {
        transfer::public_transfer(liquidation_payment, ctx.sender());
    } else { coin::destroy_zero(liquidation_payment); }

    // Liquidator receives collateral
    let collateral: T = df::remove(&mut loan.id, b"collateral");
    transfer::public_transfer(collateral, ctx.sender());

    loan.is_active = false;

    event::emit(LoanLiquidated {
        loan_id: object::id(loan),
        liquidator: ctx.sender(),
        collateral_id: loan.collateral_id,
    });
}

const EInsufficientLiquidity: u64 = 0;
const ENotBorrower: u64 = 1;
const ELoanInactive: u64 = 2;
const EInsufficientRepayment: u64 = 3;
const ENotYetExpired: u64 = 4;
const EInsufficientPayment: u64 = 5;

dApp Interface (Lending Dashboard)

// LendingDashboard.tsx
import { useQuery } from '@tanstack/react-query'
import { useCurrentClient } from '@mysten/dapp-kit-react'

const LENDING_PKG = "0x_LENDING_PACKAGE_"
const POOL_ID = "0x_POOL_ID_"

export function LendingDashboard() {
  const client = useCurrentClient()

  const { data: pool } = useQuery({
    queryKey: ['lending-pool'],
    queryFn: async () => {
      const obj = await client.getObject({ id: POOL_ID, options: { showContent: true } })
      return (obj.data?.content as any)?.fields
    },
    refetchInterval: 15_000,
  })

  const availableLiquidity = Number(pool?.liquidity?.fields?.value ?? 0) / 1e9
  const totalLoaned = Number(pool?.total_loaned ?? 0) / 1e9
  const utilization = totalLoaned / (availableLiquidity + totalLoaned) * 100

  return (
    <div className="lending-dashboard">
      <h1>NFT Collateral Lending</h1>

      <div className="pool-stats">
        <div className="stat">
          <span>Available Liquidity</span>
          <strong>{availableLiquidity.toFixed(2)} SUI</strong>
        </div>
        <div className="stat">
          <span>Total Loaned</span>
          <strong>{totalLoaned.toFixed(2)} SUI</strong>
        </div>
        <div className="stat">
          <span>Utilization Rate</span>
          <strong>{utilization.toFixed(1)}%</strong>
        </div>
        <div className="stat">
          <span>Monthly Interest</span>
          <strong>3%</strong>
        </div>
      </div>

      <div className="loan-info">
        <h3>Loan Terms</h3>
        <ul>
          <li>Loan-to-Value (LTV): 60%</li>
          <li>Monthly Interest: 3% (fixed)</li>
          <li>Maximum Term: 30 days</li>
          <li>Overdue Liquidation: Collateral acquired by liquidator at 95% valuation</li>
        </ul>
      </div>
    </div>
  )
}

Related Documentation

• Chapter 12: Dynamic Fields
• Chapter 14: Economic System
• Chapter 15: Cross-contract Composition

Practical Case 16: NFT Crafting and Disassembly System

Objective: Build a material crafting system—destroy multiple low-level NFTs to craft one high-level NFT (probabilistic), also support disassembling high-level NFTs into materials; use on-chain randomness to ensure fair results.

Status: Teaching example. The main text explains crafting/disassembly and random number integration, complete directory is based on book/src/code/example-16/.

Corresponding Code Directory

• example-16
• example-16/dapp

Minimal Call Chain

User selects materials -> Contract reads random number -> Execute craft/fail return -> Emit event -> Frontend refreshes results

Requirements Analysis

Scenario: You’ve designed a three-tier equipment system:

• Material Fragment: Common, random drops
• Refined Component: 3 fragments → 60% chance to craft
• Ancient Artifact: 3 refined components → 30% chance to craft, returns 1 component on failure

Contract

module crafting::forge;

use sui::object::{Self, UID, ID};
use sui::random::{Self, Random};
use sui::transfer;
use sui::event;
use std::string::{Self, String, utf8};

// ── Constants ──────────────────────────────────────────────────

const TIER_FRAGMENT: u8 = 0;
const TIER_COMPONENT: u8 = 1;
const TIER_ARTIFACT: u8 = 2;

// Crafting success rates (BPS)
const FRAGMENT_TO_COMPONENT_BPS: u64 = 6_000; // 60%
const COMPONENT_TO_ARTIFACT_BPS: u64 = 3_000; // 30%

// ── Data Structures ───────────────────────────────────────────────

public struct ForgeItem has key, store {
    id: UID,
    tier: u8,
    name: String,
    image_url: String,
    power: u64,    // Attribute value (higher tier = stronger)
}

public struct ForgeAdminCap has key, store { id: UID }

// ── Events ──────────────────────────────────────────────────

public struct CraftAttempted has copy, drop {
    crafter: address,
    input_tier: u8,
    success: bool,
    result_tier: u8,
}

public struct ItemDisassembled has copy, drop {
    crafter: address,
    from_tier: u8,
    fragments_returned: u64,
}

// ── Initialization ────────────────────────────────────────────────

fun init(ctx: &mut TxContext) {
    transfer::public_transfer(ForgeAdminCap { id: object::new(ctx) }, ctx.sender());
}

/// Mint base fragment (Admin only, e.g., quest reward)
public fun mint_fragment(
    _cap: &ForgeAdminCap,
    recipient: address,
    ctx: &mut TxContext,
) {
    let item = ForgeItem {
        id: object::new(ctx),
        tier: TIER_FRAGMENT,
        name: utf8(b"Plasma Fragment"),
        image_url: utf8(b"https://assets.example.com/fragment.png"),
        power: 10,
    };
    transfer::public_transfer(item, recipient);
}

// ── Crafting: 3 low-level → 1 high-level (with random success rate) ────────────

public fun craft(
    input1: ForgeItem,
    input2: ForgeItem,
    input3: ForgeItem,
    random: &Random,
    ctx: &mut TxContext,
) {
    // Three inputs must be same tier
    assert!(input1.tier == input2.tier && input2.tier == input3.tier, EMismatchedTier);
    let input_tier = input1.tier;
    assert!(input_tier < TIER_ARTIFACT, EMaxTierReached);

    let target_tier = input_tier + 1;

    // Get on-chain random number (0-9999)
    let mut rng = random::new_generator(random, ctx);
    let roll = rng.generate_u64() % 10_000;

    let success_threshold = if target_tier == TIER_COMPONENT {
        FRAGMENT_TO_COMPONENT_BPS
    } else {
        COMPONENT_TO_ARTIFACT_BPS
    };

    // Destroy all three inputs regardless of success
    let ForgeItem { id: id1, .. } = input1;
    let ForgeItem { id: id2, .. } = input2;
    let ForgeItem { id: id3, .. } = input3;
    id1.delete(); id2.delete(); id3.delete();

    let success = roll < success_threshold;

    if success {
        let (name, image_url, power) = get_tier_info(target_tier);
        let result = ForgeItem {
            id: object::new(ctx),
            tier: target_tier,
            name,
            image_url,
            power,
        };
        transfer::public_transfer(result, ctx.sender());
    } else if target_tier == TIER_ARTIFACT {
        // Consolation prize on artifact craft failure: return 1 refined component
        let (name, image_url, power) = get_tier_info(TIER_COMPONENT);
        let consolation = ForgeItem {
            id: object::new(ctx),
            tier: TIER_COMPONENT,
            name,
            image_url,
            power,
        };
        transfer::public_transfer(consolation, ctx.sender());
    };
    // No return on component craft failure (60% success rate, risk is player's)

    event::emit(CraftAttempted {
        crafter: ctx.sender(),
        input_tier,
        success,
        result_tier: if success { target_tier } else { input_tier },
    });
}

// ── Disassembly: 1 high-level → multiple low-level ────────────────────────────

public fun disassemble(
    item: ForgeItem,
    ctx: &mut TxContext,
) {
    assert!(item.tier > TIER_FRAGMENT, ECannotDisassembleFragment);

    let target_tier = item.tier - 1;
    let fragments_to_return = 2u64; // Disassembly only returns 2 (lossy)
    let item_tier = item.tier;

    let ForgeItem { id, .. } = item;
    id.delete();

    let (name, image_url, power) = get_tier_info(target_tier);
    let mut i = 0;
    while (i < fragments_to_return) {
        let fragment = ForgeItem {
            id: object::new(ctx),
            tier: target_tier,
            name,
            image_url,
            power,
        };
        transfer::public_transfer(fragment, ctx.sender());
        i = i + 1;
    };

    event::emit(ItemDisassembled {
        crafter: ctx.sender(),
        from_tier: item_tier,
        fragments_returned: fragments_to_return,
    });
}

fun get_tier_info(tier: u8): (String, String, u64) {
    if tier == TIER_FRAGMENT {
        (utf8(b"Plasma Fragment"), utf8(b"https://assets.example.com/fragment.png"), 10)
    } else if tier == TIER_COMPONENT {
        (utf8(b"Refined Component"), utf8(b"https://assets.example.com/component.png"), 100)
    } else {
        (utf8(b"Ancient Artifact"), utf8(b"https://assets.example.com/artifact.png"), 1000)
    }
}

const EMismatchedTier: u64 = 0;
const EMaxTierReached: u64 = 1;
const ECannotDisassembleFragment: u64 = 2;

dApp (Forging Station Interface)

// ForgingStation.tsx
import { useState } from 'react'
import { useCurrentClient, useCurrentAccount } from '@mysten/dapp-kit-react'
import { useQuery } from '@tanstack/react-query'
import { Transaction } from '@mysten/sui/transactions'
import { useDAppKit } from '@mysten/dapp-kit-react'

const CRAFTING_PKG = "0x_CRAFTING_PACKAGE_"
const TIER_NAMES = ['Fragment', 'Refined Component', 'Ancient Artifact']
const CRAFT_RATES = ['60%', '30%', '—']

export function ForgingStation() {
  const client = useCurrentClient()
  const dAppKit = useDAppKit()
  const account = useCurrentAccount()
  const [selected, setSelected] = useState<string[]>([])
  const [status, setStatus] = useState('')
  const [lastCraft, setLastCraft] = useState<{success: boolean; tier: string} | null>(null)

  const { data: userItems, refetch } = useQuery({
    queryKey: ['forge-items', account?.address],
    queryFn: async () => {
      if (!account) return []
      const objs = await client.getOwnedObjects({
        owner: account.address,
        filter: { StructType: `${CRAFTING_PKG}::forge::ForgeItem` },
        options: { showContent: true },
      })
      return objs.data.map(obj => ({
        id: obj.data!.objectId,
        tier: Number((obj.data!.content as any).fields.tier),
        name: (obj.data!.content as any).fields.name,
        power: (obj.data!.content as any).fields.power,
      }))
    },
    enabled: !!account,
  })

  const toggleSelect = (id: string) => {
    setSelected(prev =>
      prev.includes(id) ? prev.filter(i => i !== id) : prev.length < 3 ? [...prev, id] : prev
    )
  }

  const handleCraft = async () => {
    if (selected.length !== 3) return
    const tx = new Transaction()
    tx.moveCall({
      target: `${CRAFTING_PKG}::forge::craft`,
      arguments: [
        tx.object(selected[0]),
        tx.object(selected[1]),
        tx.object(selected[2]),
        tx.object('0x8'), // Random system object
      ],
    })
    try {
      setStatus('Crafting (on-chain random determination)...')
      const result = await dAppKit.signAndExecuteTransaction({ transaction: tx })
      // Read craft result from event
      const craftEvent = result.events?.find(e => e.type.includes('CraftAttempted'))
      if (craftEvent) {
        const { success, result_tier } = craftEvent.parsedJson as any
        setLastCraft({ success, tier: TIER_NAMES[Number(result_tier)] })
        setStatus(success ? `Craft successful! Obtained ${TIER_NAMES[Number(result_tier)]}` : 'Craft failed')
      }
      setSelected([])
      refetch()
    } catch (e: any) { setStatus(`${e.message}`) }
  }

  const selectedTier = selected.length > 0 && userItems
    ? userItems.find(i => i.id === selected[0])?.tier
    : null

  return (
    <div className="forging-station">
      <h1>Mysterious Forge</h1>

      {lastCraft && (
        <div className={`craft-result ${lastCraft.success ? 'success' : 'fail'}`}>
          {lastCraft.success ? 'Craft Successful!' : 'Craft Failed'} → {lastCraft.tier}
        </div>
      )}

      <div className="craft-info">
        <div>Fragment × 3 → Refined Component (success rate {CRAFT_RATES[0]})</div>
        <div>Refined Component × 3 → Ancient Artifact (success rate {CRAFT_RATES[1]})</div>
      </div>

      <h3>Select 3 same-tier items to craft</h3>
      <div className="items-grid">
        {userItems?.map(item => (
          <div
            key={item.id}
            className={`item-slot ${selected.includes(item.id) ? 'selected' : ''}`}
            onClick={() => toggleSelect(item.id)}
          >
            <div className="tier-badge">{TIER_NAMES[item.tier]}</div>
            <div className="power">Power: {item.power}</div>
          </div>
        ))}
      </div>

      <button
        className="craft-btn"
        disabled={selected.length !== 3}
        onClick={handleCraft}
      >
        Start Crafting ({selected.length}/3 selected)
      </button>

      {status && <p className="status">{status}</p>}
    </div>
  )
}

Related Documentation

• Sui On-chain Randomness
• Chapter 13: NFT Design
• Chapter 35: Future Outlook

Practical Case 18: Inter-Alliance Diplomatic Treaty (Ceasefire and Resource Treaties)

Objective: Build an on-chain diplomatic contract—two alliances can sign treaties (ceasefire, resource sharing, trade agreements), treaties take effect when co-signed by both Leaders, violations can be proven on-chain, and enforcement is mandatory during validity period.

Status: Teaching example. The main text covers treaty state machine, complete directory is based on book/src/code/example-18/.

Corresponding Code Directory

• example-18
• example-18/dapp

Minimal Call Chain

One party initiates proposal -> Both parties deposit and sign -> Treaty takes effect -> Violation/termination occurs -> Penalty deduction or deposit refund

Test Loop

• Initiate proposal: Confirm TreatyProposal created successfully with event emitted
• Co-signing takes effect: Confirm effective_at_ms written, both deposits equal
• Advance notice and termination: Confirm cannot terminate before notice matures, deposits refunded after maturity
• Report violation: Confirm penalty deducted from violating party’s deposit and transferred to other party

Requirements Analysis

Scenario: Alliance Alpha and Alliance Beta erupted in conflict, both sides decide to negotiate:

1. Ceasefire Agreement: Both alliance turrets do not fire on opposing members for 72 hours
2. Passage Agreement: Alpha members can use Beta’s stargates for free (and vice versa)
3. Resource Sharing: Both sides transfer 100 WAR Token to each other daily
4. Either party can unilaterally terminate treaty (requires 24-hour advance notice on-chain)
5. Violations (such as illegal turret firing) can be reported via server signature, penalty deposit confiscated

Contract

module diplomacy::treaty;

use sui::object::{Self, UID, ID};
use sui::clock::Clock;
use sui::coin::{Self, Coin};
use sui::sui::SUI;
use sui::balance::{Self, Balance};
use sui::transfer;
use sui::event;
use std::string::{Self, String, utf8};

// ── Constants ──────────────────────────────────────────────────

const NOTICE_PERIOD_MS: u64 = 24 * 60 * 60 * 1000;  // 24-hour advance termination notice
const BREACH_FINE: u64 = 100_000_000_000;             // 100 SUI violation fine (from deposit)

// Treaty types
const TREATY_CEASEFIRE: u8 = 0;       // Ceasefire agreement
const TREATY_PASSAGE: u8 = 1;         // Passage rights agreement
const TREATY_RESOURCE_SHARE: u8 = 2;  // Resource sharing

// ── Data Structures ───────────────────────────────────────────────

/// Diplomatic treaty (shared object)
public struct Treaty has key {
    id: UID,
    treaty_type: u8,
    party_a: address,          // Alliance A's Leader address
    party_b: address,          // Alliance B's Leader address
    party_a_signed: bool,
    party_b_signed: bool,
    effective_at_ms: u64,      // Effective time (after co-signing)
    expires_at_ms: u64,        // Expiration time (0 = indefinite)
    termination_notice_ms: u64, // Termination notice time (0 = not notified)
    party_a_deposit: Balance<SUI>,  // Party A deposit (for violation compensation)
    party_b_deposit: Balance<SUI>,  // Party B deposit
    breach_count_a: u64,
    breach_count_b: u64,
    description: String,
}

/// Treaty proposal (initiated by one party, awaiting other party's signature)
public struct TreatyProposal has key {
    id: UID,
    proposed_by: address,
    counterparty: address,
    treaty_type: u8,
    duration_days: u64,        // Duration (days), 0 = indefinite
    deposit_required: u64,      // Required deposit from each party
    description: String,
}

// ── Events ──────────────────────────────────────────────────

public struct TreatyProposed has copy, drop { proposal_id: ID, proposer: address, counterparty: address }
public struct TreatySigned has copy, drop { treaty_id: ID, party: address }
public struct TreatyEffective has copy, drop { treaty_id: ID, treaty_type: u8 }
public struct TreatyTerminated has copy, drop { treaty_id: ID, terminated_by: address }
public struct BreachReported has copy, drop { treaty_id: ID, breaching_party: address, fine: u64 }

// ── Initiate Treaty Proposal ──────────────────────────────────────────

public fun propose_treaty(
    counterparty: address,
    treaty_type: u8,
    duration_days: u64,
    deposit_required: u64,
    description: vector<u8>,
    ctx: &mut TxContext,
) {
    let proposal = TreatyProposal {
        id: object::new(ctx),
        proposed_by: ctx.sender(),
        counterparty,
        treaty_type,
        duration_days,
        deposit_required,
        description: utf8(description),
    };
    let proposal_id = object::id(&proposal);
    transfer::share_object(proposal);
    event::emit(TreatyProposed {
        proposal_id,
        proposer: ctx.sender(),
        counterparty,
    });
}

// ── Accept Proposal (Proposer signs + deposit) ────────────────────────

public fun accept_and_sign_a(
    proposal: &TreatyProposal,
    mut deposit: Coin<SUI>,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    assert!(ctx.sender() == proposal.proposed_by, ENotParty);

    let deposit_amt = coin::value(&deposit);
    assert!(deposit_amt >= proposal.deposit_required, EInsufficientDeposit);

    let deposit_coin = deposit.split(proposal.deposit_required, ctx);
    if coin::value(&deposit) > 0 {
        transfer::public_transfer(deposit, ctx.sender());
    } else { coin::destroy_zero(deposit); }

    let expires = if proposal.duration_days > 0 {
        clock.timestamp_ms() + proposal.duration_days * 86_400_000
    } else { 0 };

    let treaty = Treaty {
        id: object::new(ctx),
        treaty_type: proposal.treaty_type,
        party_a: proposal.proposed_by,
        party_b: proposal.counterparty,
        party_a_signed: true,
        party_b_signed: false,
        effective_at_ms: 0,
        expires_at_ms: expires,
        termination_notice_ms: 0,
        party_a_deposit: coin::into_balance(deposit_coin),
        party_b_deposit: balance::zero(),
        breach_count_a: 0,
        breach_count_b: 0,
        description: proposal.description,
    };
    let treaty_id = object::id(&treaty);
    transfer::share_object(treaty);
    event::emit(TreatySigned { treaty_id, party: ctx.sender() });
}

/// Counterparty alliance signs (treaty officially takes effect)
public fun countersign(
    treaty: &mut Treaty,
    mut deposit: Coin<SUI>,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    assert!(ctx.sender() == treaty.party_b, ENotParty);
    assert!(treaty.party_a_signed, ENotYetSigned);
    assert!(!treaty.party_b_signed, EAlreadySigned);

    let required = balance::value(&treaty.party_a_deposit); // Equal deposit
    assert!(coin::value(&deposit) >= required, EInsufficientDeposit);

    let dep = deposit.split(required, ctx);
    balance::join(&mut treaty.party_b_deposit, coin::into_balance(dep));
    if coin::value(&deposit) > 0 {
        transfer::public_transfer(deposit, ctx.sender());
    } else { coin::destroy_zero(deposit); }

    treaty.party_b_signed = true;
    treaty.effective_at_ms = clock.timestamp_ms();

    event::emit(TreatyEffective { treaty_id: object::id(treaty), treaty_type: treaty.treaty_type });
    event::emit(TreatySigned { treaty_id: object::id(treaty), party: ctx.sender() });
}

// ── Verify treaty is in effect (called by turret/stargate extensions) ───────────────

public fun is_treaty_active(treaty: &Treaty, clock: &Clock): bool {
    if !treaty.party_a_signed || !treaty.party_b_signed { return false };
    if treaty.expires_at_ms > 0 && clock.timestamp_ms() > treaty.expires_at_ms { return false };
    // Treaty still valid during termination notice period
    true
}

/// Check if address is protected by treaty
public fun is_protected_by_treaty(
    treaty: &Treaty,
    protected_member: address, // Protected alliance member (verified through FactionNFT.owner or member list)
    aggressor_faction: address,
    clock: &Clock,
): bool {
    is_treaty_active(treaty, clock)
    // Real scenario requires additional verification of member-alliance association
}

// ── Submit Termination Notice (takes effect after 24 hours) ───────────────────────

public fun give_termination_notice(
    treaty: &mut Treaty,
    clock: &Clock,
    ctx: &TxContext,
) {
    assert!(ctx.sender() == treaty.party_a || ctx.sender() == treaty.party_b, ENotParty);
    assert!(is_treaty_active(treaty, clock), ETreatyNotActive);
    treaty.termination_notice_ms = clock.timestamp_ms();
    event::emit(TreatyTerminated { treaty_id: object::id(treaty), terminated_by: ctx.sender() });
}

/// Officially terminate treaty after notice period matures, both parties retrieve deposits
public fun finalize_termination(
    treaty: &mut Treaty,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    assert!(treaty.termination_notice_ms > 0, ENoNoticeGiven);
    assert!(
        clock.timestamp_ms() >= treaty.termination_notice_ms + NOTICE_PERIOD_MS,
        ENoticeNotMature,
    );
    // Refund deposits
    let a_dep = balance::withdraw_all(&mut treaty.party_a_deposit);
    let b_dep = balance::withdraw_all(&mut treaty.party_b_deposit);
    if balance::value(&a_dep) > 0 {
        transfer::public_transfer(coin::from_balance(a_dep, ctx), treaty.party_a);
    } else { balance::destroy_zero(a_dep); }
    if balance::value(&b_dep) > 0 {
        transfer::public_transfer(coin::from_balance(b_dep, ctx), treaty.party_b);
    } else { balance::destroy_zero(b_dep); }
}

// ── Report Violation (verified and signed by game server) ──────────────────

public fun report_breach(
    treaty: &mut Treaty,
    breaching_party: address,  // Violating alliance's Leader address
    admin_acl: &AdminACL,
    ctx: &mut TxContext,
) {
    verify_sponsor(admin_acl, ctx);  // Server proves violation event actually occurred

    let fine = BREACH_FINE;

    if breaching_party == treaty.party_a {
        treaty.breach_count_a = treaty.breach_count_a + 1;
        // Deduct fine from A's deposit and transfer to B
        if balance::value(&treaty.party_a_deposit) >= fine {
            let fine_coin = coin::take(&mut treaty.party_a_deposit, fine, ctx);
            transfer::public_transfer(fine_coin, treaty.party_b);
        }
    } else if breaching_party == treaty.party_b {
        treaty.breach_count_b = treaty.breach_count_b + 1;
        if balance::value(&treaty.party_b_deposit) >= fine {
            let fine_coin = coin::take(&mut treaty.party_b_deposit, fine, ctx);
            transfer::public_transfer(fine_coin, treaty.party_a);
        }
    } else abort ENotParty;

    event::emit(BreachReported {
        treaty_id: object::id(treaty),
        breaching_party,
        fine,
    });
}

const ENotParty: u64 = 0;
const EInsufficientDeposit: u64 = 1;
const ENotYetSigned: u64 = 2;
const EAlreadySigned: u64 = 3;
const ETreatyNotActive: u64 = 4;
const ENoNoticeGiven: u64 = 5;
const ENoticeNotMature: u64 = 6;

dApp (Diplomacy Center)

// DiplomacyCenter.tsx
import { useState } from 'react'
import { useCurrentClient } from '@mysten/dapp-kit-react'
import { useQuery } from '@tanstack/react-query'

const DIP_PKG = "0x_DIPLOMACY_PACKAGE_"

const TREATY_TYPES = [
  { id: 0, name: 'Ceasefire Agreement', desc: 'Both parties must not attack during validity period' },
  { id: 1, name: 'Passage Rights Agreement', desc: 'Members can use opposing stargates for free' },
  { id: 2, name: 'Resource Sharing Agreement', desc: 'Periodic mutual resource transfer' },
]

export function DiplomacyCenter() {
  const client = useCurrentClient()
  const [proposing, setProposing] = useState(false)

  const { data: treaties } = useQuery({
    queryKey: ['active-treaties'],
    queryFn: async () => {
      const events = await client.queryEvents({
        query: { MoveEventType: `${DIP_PKG}::treaty::TreatyEffective` },
        limit: 20,
      })
      return events.data
    },
    refetchInterval: 30_000,
  })

  return (
    <div className="diplomacy-center">
      <header>
        <h1>Inter-Alliance Diplomacy Center</h1>
        <p>Sign legally binding alliance treaties on-chain</p>
      </header>

      <section className="treaty-types">
        <h3>Available Treaty Types</h3>
        <div className="types-grid">
          {TREATY_TYPES.map(t => (
            <div key={t.id} className="type-card">
              <h4>{t.name}</h4>
              <p>{t.desc}</p>
            </div>
          ))}
        </div>
      </section>

      <section className="active-treaties">
        <h3>Currently Active Treaties</h3>
        {treaties?.length === 0 && <p>No treaties</p>}
        {treaties?.map(e => {
          const { treaty_id, treaty_type } = e.parsedJson as any
          const type = TREATY_TYPES[Number(treaty_type)]
          return (
            <div key={treaty_id} className="treaty-card">
              <span className="treaty-type">{type?.name}</span>
              <span className="treaty-id">{treaty_id.slice(0, 12)}...</span>
              <span className="treaty-status active">Active</span>
            </div>
          )
        })}
      </section>

      <button className="propose-btn" onClick={() => setProposing(true)}>
        Propose New Treaty
      </button>
    </div>
  )
}

Key Design Highlights

Related Documentation

• Chapter 8: AdminACL and Server Verification
• Chapter 11: Ownership and OwnerCap
• Example 12: Alliance Recruitment

Chapter 18: Multi-Tenant Architecture and Game Server Integration

Goal: Understand EVE Frontier’s multi-tenant world contract design, master how to build platform-level contracts serving multiple alliances, and how to bidirectionally integrate with game servers.

Status: Architecture chapter. Main focus on multi-tenant design and Registry patterns.

18.1 What Are Multi-Tenant Contracts?

Single-tenant: One contract serves only one Owner (your alliance).

Multi-tenant: One contract after deployment can simultaneously serve multiple unrelated Owners (multiple alliances), with isolated data.

Single-tenant example (Example 1-5 pattern):
  Contract → Dedicated TollGate (only your stargate)

Multi-tenant example:
  Contract → Register Alliance A's stargate toll configuration
        → Register Alliance B's stargate toll configuration
        → Register Alliance C's storage box market configuration
        → (Each alliance isolated, data independent)

Use Cases: Building a “SaaS”-level tool that can be used by multiple alliances. Examples: universal auction platform, royalty market infrastructure, quest system framework.

Multi-tenancy is most easily misunderstood as “cramming many users into one contract.” What it really needs to solve is:

How to let many mutually untrusting operators share the same protocol capabilities, but without cross-contamination, unauthorized access, or data pollution.

So the core of multi-tenant design isn’t “saving deployment times,” but three things:

• Isolation Tenant A cannot touch Tenant B’s state
• Reuse Same logic doesn’t need to be repackaged for each alliance
• Operability Platform can continue maintenance, upgrades, and billing

18.2 Multi-Tenant Contract Design Pattern

module platform::multi_toll;

use sui::table::{Self, Table};
use sui::object::{Self, ID};

/// Platform registry (shared object, used by all tenants)
public struct TollPlatform has key {
    id: UID,
    registrations: Table<ID, TollConfig>,  // gate_id → toll configuration
}

/// Each tenant's (stargate's) independent configuration
public struct TollConfig has store {
    owner: address,          // Owner of this configuration (stargate owner)
    toll_amount: u64,
    fee_recipient: address,
    total_collected: u64,
}

/// Tenant registration (any Builder can register their stargate)
public fun register_gate(
    platform: &mut TollPlatform,
    gate: &Gate,
    owner_cap: &OwnerCap<Gate>,          // Prove you're this stargate's Owner
    toll_amount: u64,
    fee_recipient: address,
    ctx: &TxContext,
) {
    // Verify OwnerCap and Gate correspondence
    assert!(owner_cap.authorized_object_id == object::id(gate), ECapMismatch);

    let gate_id = object::id(gate);
    assert!(!table::contains(&platform.registrations, gate_id), EAlreadyRegistered);

    table::add(&mut platform.registrations, gate_id, TollConfig {
        owner: ctx.sender(),
        toll_amount,
        fee_recipient,
        total_collected: 0,
    });
}

/// Adjust tenant configuration (only can modify your own configuration)
public fun update_toll(
    platform: &mut TollPlatform,
    gate: &Gate,
    owner_cap: &OwnerCap<Gate>,
    new_toll_amount: u64,
    ctx: &TxContext,
) {
    assert!(owner_cap.authorized_object_id == object::id(gate), ECapMismatch);

    let config = table::borrow_mut(&mut platform.registrations, object::id(gate));
    assert!(config.owner == ctx.sender(), ENotConfigOwner);

    config.toll_amount = new_toll_amount;
}

/// Multi-tenant jump (toll logic reused, but configurations independently isolated)
public fun multi_tenant_jump(
    platform: &mut TollPlatform,
    source_gate: &Gate,
    dest_gate: &Gate,
    character: &Character,
    mut payment: Coin<SUI>,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    // Read this stargate's dedicated toll configuration
    let gate_id = object::id(source_gate);
    assert!(table::contains(&platform.registrations, gate_id), EGateNotRegistered);

    let config = table::borrow_mut(&mut platform.registrations, gate_id);
    assert!(coin::value(&payment) >= config.toll_amount, EInsufficientPayment);

    // Transfer to respective fee_recipient
    let toll = payment.split(config.toll_amount, ctx);
    transfer::public_transfer(toll, config.fee_recipient);
    config.total_collected = config.total_collected + config.toll_amount;

    // Return change
    if coin::value(&payment) > 0 {
        transfer::public_transfer(payment, ctx.sender());
    } else {
        coin::destroy_zero(payment);
    };

    // Issue jump permit
    gate::issue_jump_permit(
        source_gate, dest_gate, character, MultiTollAuth {}, clock.timestamp_ms() + 15 * 60 * 1000, ctx,
    );
}

public struct MultiTollAuth has drop {}
const ECapMismatch: u64 = 0;
const EAlreadyRegistered: u64 = 1;
const ENotConfigOwner: u64 = 2;
const EGateNotRegistered: u64 = 3;
const EInsufficientPayment: u64 = 4;

What Multi-Tenant Design Really Needs to Decide First Is “What Is the Tenant Key”

In this example, gate_id serves as the tenant boundary. In reality, common tenant keys include:

• A certain assembly_id
• A certain character_id
• An alliance object ID
• A normalized business primary key

This choice is very critical, because it determines:

• How data is isolated
• How permissions are validated
• How frontend and indexing layers retrieve

If the tenant key is chosen unstably, you’ll frequently encounter dirty boundary problems like “is this one tenant or two.”

Three Most Common Types of Accidents in Multi-Tenant Contracts

1. Incomplete Isolation

Looks like multi-tenant, but certain paths still use global shared parameters, causing different alliances to affect each other.

2. Platform Parameters and Tenant Parameters Mixed Together

Result is:

• Some configurations should be globally unified
• But were privately changed by a tenant

Or vice versa:

• Fee rates that should be independent per tenant
• Made into global single values

3. Query Model Didn’t Keep Up

On-chain wrote multi-tenant structure, but frontend and indexing layers still only know how to read by “single object” thinking, ultimately the platform is unusable.

18.3 Game Server Integration Patterns

Pattern One: Server as Event Listener

// game-server/event-listener.ts
// Game server listens to on-chain events, updates game state

import { SuiClient } from "@mysten/sui/client";

const client = new SuiClient({ url: process.env.SUI_RPC! });

// Listen to player achievements, trigger in-game rewards
await client.subscribeEvent({
  filter: { Package: MY_PACKAGE },
  onMessage: async (event) => {
    if (event.type.includes("AchievementUnlocked")) {
      const { player, achievement_type } = event.parsedJson as any;

      // Game server handles: grant in-game items to player
      await gameServerAPI.grantItemToPlayer(player, achievement_type);
    }

    if (event.type.includes("GateJumped")) {
      const { character_id, destination_gate_id } = event.parsedJson as any;

      // Game server handles: teleport player to destination system
      await gameServerAPI.teleportCharacter(character_id, destination_gate_id);
    }
  },
});

Pattern Two: Server as Data Provider

// game-server/api.ts
// Game server provides off-chain data, dApp calls

import express from "express";

const app = express();

// Provide star system name (decrypt location hash)
app.get("/api/location/:hash", async (req, res) => {
  const { hash } = req.params;
  const geoInfo = await locationDB.getByHash(hash);
  res.json(geoInfo);
});

// Verify proximity (for Sponsor service to call)
app.post("/api/proximity/verify", async (req, res) => {
  const { player_id, assembly_id, max_distance_km } = req.body;

  const playerPos = await getPlayerPosition(player_id);
  const assemblyPos = await getAssemblyPosition(assembly_id);
  const distance = calculateDistance(playerPos, assemblyPos);

  res.json({
    is_near: distance <= max_distance_km,
    distance_km: distance,
  });
});

// Get player real-time game status
app.get("/api/character/:id/status", async (req, res) => {
  const status = await gameServerAPI.getCharacterStatus(req.params.id);
  res.json({
    online: status.online,
    system: status.current_system,
    ship: status.current_ship,
    fleet: status.fleet_id,
  });
});

Pattern Three: Bidirectional State Synchronization

On-chain events ──────────────► Game server
(NFT minting, quest completion)     (Update game world state)

Game server ──────────────► On-chain transactions
(Physics verification, sponsor signatures)      (Record results, grant rewards)

Don’t Mix These Three Patterns Into One Pot

While all called “server integration,” their responsibilities are completely different:

• Event Listener Consumer-oriented, syncs on-chain results back to game world
• Data Provider Query-oriented, provides off-chain interpretation layer for frontend and backend
• Bidirectional Sync Collaboration-oriented, lets on-chain and game server mutually drive state changes

If you don’t layer them, you’ll easily end up with:

• One service managing listening, sponsoring, and all queries
• When problems occur, completely don’t know which chain broke

Most Critical Between Game Server and On-Chain Isn’t “Connectivity,” But “Calibration Consistency”

For example:

• Are on-chain recognized assembly_id and game server recognized facility IDs the same thing
• Do location hashes and off-chain map coordinates have one-to-one correspondence
• Are character IDs in events and character primary keys in game database stably mapped

Once these mappings drift, system surface still works, but business slowly becomes distorted.

18.4 ObjectRegistry: Global Query Table

When your contract has multiple shared objects, need a registry for other contracts and dApps to find them:

module platform::registry;

/// Global registry (like DNS)
public struct ObjectRegistry has key {
    id: UID,
    entries: Table<String, ID>,  // name → ObjectID
}

/// Register a named object
public fun register(
    registry: &mut ObjectRegistry,
    name: vector<u8>,
    object_id: ID,
    _admin_cap: &AdminCap,
    ctx: &TxContext,
) {
    table::add(
        &mut registry.entries,
        std::string::utf8(name),
        object_id,
    );
}

/// Query
public fun resolve(registry: &ObjectRegistry, name: String): ID {
    *table::borrow(&registry.entries, name)
}

// Query Treasury ID through registry
const registry = await getObjectWithJson(REGISTRY_ID);
const treasuryId = registry?.entries?.["alliance_treasury"];

Registry’s value isn’t just “conveniently lookup an ID,” but unifying “scattered object discovery logic.”

This will directly improve three things:

• Frontend doesn’t need to hardcode a bunch of object addresses
• Other contracts know where to find key objects
• After upgrades or migrations, can do smooth transitions through registry

But Registry Also Has Boundaries

Don’t treat it as a universal database. It’s best suited for:

• Name resolution
• Core object entry discovery
• Small amount of stable mappings

Not suited for:

• High-frequency changing large lists
• Heavy business statistics
• Large-scale time series data

🔖 Chapter Summary

📚 Further Reading

• Chapter 8: Sponsored Transactions
• EVE World Explainer

Chapter 19: Full-Stack dApp Architecture Design

Goal: Design and implement production-grade EVE Frontier dApps, covering state management, real-time data updates, error handling, responsive design, and CI/CD automated deployment.

Status: Architecture chapter. Main focus on full-stack dApp organization, state management, and deployment.

19.1 Full-Stack Architecture Overview

┌─────────────────────────────────────────────────────┐
│                    User Browser                      │
│  ┌──────────────────────────────────────────────┐   │
│  │              React / Next.js dApp             │   │
│  │  ┌──────────┐  ┌──────────┐  ┌────────────┐  │   │
│  │  │ EVE Vault│  │React     │  │ Tanstack   │  │   │
│  │  │ Wallet   │  │ dapp-kit │  │ Query      │  │   │
│  │  └──────────┘  └──────────┘  └────────────┘  │   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────┬───────────────────────────────┘
                      │
          ┌───────────┼────────────┐
          ▼           ▼            ▼
     Sui Full Node  Your Backend  Game Server
     GraphQL        Sponsor Svc   Location/Verify API
     Event Stream   Index Svc

What this diagram should convey most isn’t “there are many tech stacks,” but:

A truly usable EVE dApp is never a single-page frontend, but an entire layered collaborative system.

Each layer in this system solves different problems:

• Browser handles interaction and state feedback
• Wallet handles signing and identity
• Full node and GraphQL provide on-chain truth
• Backend handles sponsoring, risk control, aggregation
• Game server provides off-chain world interpretation and verification

If these responsibilities aren’t layered, system surface can run, but will become increasingly difficult to maintain.

19.2 Project Structure (Next.js Example)

dapp/
├── app/                          # Next.js App Router
│   ├── layout.tsx                # Global layout (Provider)
│   ├── page.tsx                  # Homepage
│   ├── gate/[id]/page.tsx        # Stargate detail page
│   └── dashboard/page.tsx        # Management panel
├── components/
│   ├── common/
│   │   ├── WalletButton.tsx
│   │   ├── TxStatus.tsx
│   │   └── LoadingSpinner.tsx
│   ├── gate/
│   │   ├── GateCard.tsx
│   │   ├── JumpPanel.tsx
│   │   └── TollInfo.tsx
│   └── market/
│       ├── ItemGrid.tsx
│       └── BuyButton.tsx
├── hooks/
│   ├── useGate.ts                # Stargate data
│   ├── useMarket.ts              # Market data
│   ├── useSponsoredAction.ts     # Sponsored transactions
│   └── useEvents.ts              # Real-time events
├── lib/
│   ├── sui.ts                    # SuiClient instance
│   ├── contracts.ts              # Contract constants
│   ├── queries.ts                # GraphQL queries
│   └── config.ts                 # Environment config
├── store/
│   └── useAppStore.ts            # Zustand global state
└── .env.local

The Real Purpose of Directory Structure Isn’t “Looking Good,” But Preventing Responsibility Sprawl

Most common way to lose control is:

• Components directly stuffing on-chain requests
• Hooks directly writing business rules
• Pages directly assembling transaction details
• Global store stuffing all state

Short-term can run, long-term will be very difficult to change.

A more stable boundary is usually:

• components/ handles display and interaction
• hooks/ handles page-level data flow
• lib/ handles underlying client and query encapsulation
• store/ only puts truly cross-page shared local UI state