# Table of Contents - [Why Build on EVE Frontier? | Builder Documentation](#why-build-on-eve-frontier-builder-documentation) - [Environment Setup | Builder Documentation](#environment-setup-builder-documentation) - [EVE Frontier World Explainer | Builder Documentation](#eve-frontier-world-explainer-builder-documentation) - [Sui & Move Fundamentals | Builder Documentation](#sui-move-fundamentals-builder-documentation) - [Smart Infrastructure | Builder Documentation](#smart-infrastructure-builder-documentation) - [Introduction to Smart Contracts | Builder Documentation](#introduction-to-smart-contracts-builder-documentation) - [Object Model | Builder Documentation](#object-model-builder-documentation) - [Move Patterns in Frontier | Builder Documentation](#move-patterns-in-frontier-builder-documentation) - [Introduction to Modding Smart Assemblies | Builder Documentation](#introduction-to-modding-smart-assemblies-builder-documentation) - [Ownership Model | Builder Documentation](#ownership-model-builder-documentation) - [Storage Unit | Builder Documentation](#storage-unit-builder-documentation) - [Network Node | Builder Documentation](#network-node-builder-documentation) - [Smart Character | Builder Documentation](#smart-character-builder-documentation) - [Build | Builder Documentation](#build-builder-documentation) - [Turret | Builder Documentation](#turret-builder-documentation) - [Build | Builder Documentation](#build-builder-documentation) - [Gate | Builder Documentation](#gate-builder-documentation) - [Build | Builder Documentation](#build-builder-documentation) - [Connecting In-Game | Builder Documentation](#connecting-in-game-builder-documentation) - [Connecting from an External Browser | Builder Documentation](#connecting-from-an-external-browser-builder-documentation) - [Customizing External dApps | Builder Documentation](#customizing-external-dapps-builder-documentation) - [Wallets & Identity | Builder Documentation](#wallets-identity-builder-documentation) - [Wallet Game Setup | Builder Documentation](#wallet-game-setup-builder-documentation) - [Introduction to EVE Vault | Builder Documentation](#introduction-to-eve-vault-builder-documentation) - [Browser Extension | Builder Documentation](#browser-extension-builder-documentation) - [Interfacing with the EVE Frontier World | Builder Documentation](#interfacing-with-the-eve-frontier-world-builder-documentation) - [efctl (community) | Builder Documentation](#efctl-community-builder-documentation) - [dApp kit | Builder Documentation](#dapp-kit-builder-documentation) - [Player | Builder Documentation](#player-builder-documentation) - [Sandbox Access | Builder Documentation](#sandbox-access-builder-documentation) - [Builder | Builder Documentation](#builder-builder-documentation) - [Debugging Tools | Builder Documentation](#debugging-tools-builder-documentation) - [Wallet | Builder Documentation](#wallet-builder-documentation) - [A Work In Progress | Builder Documentation](#a-work-in-progress-builder-documentation) - [How to Contribute | Builder Documentation](#how-to-contribute-builder-documentation) - [dApps Quick Start | Builder Documentation](#dapps-quick-start-builder-documentation) - [Why Build on EVE Frontier? | Builder Documentation](#why-build-on-eve-frontier-builder-documentation) - [Introduction to Smart Contracts | Builder Documentation](#introduction-to-smart-contracts-builder-documentation) - [Environment Setup | Builder Documentation](#environment-setup-builder-documentation) - [Introduction to Modding Smart Assemblies | Builder Documentation](#introduction-to-modding-smart-assemblies-builder-documentation) - [dApps Quick Start | Builder Documentation](#dapps-quick-start-builder-documentation) - [Wallets & Identity | Builder Documentation](#wallets-identity-builder-documentation) - [Builder | Builder Documentation](#builder-builder-documentation) - [Interfacing with the EVE Frontier World | Builder Documentation](#interfacing-with-the-eve-frontier-world-builder-documentation) - [A Work In Progress | Builder Documentation](#a-work-in-progress-builder-documentation) --- # Why Build on EVE Frontier? | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close ![](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252FCcrQJliZ4OPw3WXFPHV3%252Fbanner_gate.png%3Falt%3Dmedia%26token%3Dd010ecbe-6c44-404f-a266-1c93b9efe17e&width=768&dpr=3&quality=100&sign=9f7a985d&sv=2) In **EVE Frontier**, survival is only the starting point. What truly defines this next generation sandbox is the unprecedented agency it gives to Builders, creators, and developers. Frontier expands on decades of EVE design philosophy, player-driven economies, emergent gameplay, and systemic depth, and pushes it into a new era of openness, modularity, and community-driven evolution. [hashtag](https://docs.evefrontier.com/#a-sandbox-where-builders-shape-the-universe) A Sandbox Where Builders Shape the Universe ------------------------------------------------------------------------------------------------------------------------------------- At the core of Frontier are **Smart Assemblies**, physical and programmable structures anchored in space. These are not just buildings, they are the foundation of a living infrastructure layer that players can design, modify, automate, and optimize. Turrets, markets, storage facilities, refineries, logistics hubs, and defensive networks become active components of your strategy. Your constructions do not just exist in the world, they act within it. Frontier is designed as a true open environment. The world evolves not only through player actions, but also through server-side, real-time modding by the community. This is a game where builders can directly influence the systems that govern it. [hashtag](https://docs.evefrontier.com/#construct-to-expand-program-to-dominate) Construct to Expand, Program to Dominate ------------------------------------------------------------------------------------------------------------------------------ Building in Frontier is not cosmetic, it is strategic. ### [hashtag](https://docs.evefrontier.com/#build-infrastructure-to-expand-your-influence) Build Infrastructure to Expand Your Influence Every structure you place expands your agency in the Frontier. Bases become footholds, networks become territory, and entire playstyles emerge from how you design your industrial, logistical, or defensive footprint. ### [hashtag](https://docs.evefrontier.com/#program-functionality-to-master-the-sandbox) Program Functionality to Master the Sandbox Through the programmable layer of Smart Assemblies, you could for example: * automate defenses * create dynamic trade systems * build custom logistics pipelines * design specialized utility structures * script unique gameplay interactions The more you build, and the smarter your assemblies are, the more control you gain over your environment. [hashtag](https://docs.evefrontier.com/#a-fully-open-economic-sandbox) A Fully Open Economic Sandbox --------------------------------------------------------------------------------------------------------- Frontier embraces a **community-driven, open in-game economy**. Builders can create: * custom currencies * decentralized markets * trading networks * service economies * reputation-based systems Every tool exists for players to shape the economic landscape, not just participate in it. [hashtag](https://docs.evefrontier.com/#powered-by-eve-frontier-world-smart-contracts) Powered by Eve Frontier World Smart Contracts ----------------------------------------------------------------------------------------------------------------------------------------- The **World Contracts** extend Frontier's programmability far beyond structures. Any in-game entity can be represented on-chain and edited by player-written code, including: * characters * assemblies * items * killmails * and more This creates a composable and extensible universe where emergent gameplay is not just allowed, it is inevitable. [hashtag](https://docs.evefrontier.com/#building-on-blockchain-a-foundation-for-player-ownership) Building on Blockchain: A Foundation for Player Ownership ---------------------------------------------------------------------------------------------------------------------------------------------------------------- * **True ownership of your creations** — your assets are verifiably yours, not stored on a centralized server that can be shut down. * **A persistent universe** — your contributions endure on-chain, creating a living history that outlasts any single play session, update, or game cycle. * **An open, composable economy** — player-built systems, markets, and tools can interact with each other, enabling a co-created world rather than a developer-dictated one. [hashtag](https://docs.evefrontier.com/#why-sui-built-for-a-universe-of-this-scale) Why Sui: Built for a Universe of This Scale ------------------------------------------------------------------------------------------------------------------------------------ Frontier's integration with [**Sui**arrow-up-right](https://www.sui.io/intro-to-sui) is not a cosmetic technical choice — it directly enables the kind of world Frontier is designed to be. * **Objects, not accounts** — Sui treats every asset as an individual object with its own identity, history, and ownership record. * **Safe player modding at scale** — Smart Assemblies let anyone deploy code into a shared universe. Sui's Move language makes entire categories of exploits structurally impossible, so player creativity doesn't come at the cost of world stability. * **Systems that talk to each other** — player-built structures, contracts, and tools can natively compose and extend one another, meaning what you build can plug into what others build. * **No wallet, no gas, no friction** — Sui's zkLogin lets you sign in with your account credentials, and sponsored transactions mean you never need to buy tokens just to play. The blockchain is there, but you don't have to think about it. * **Speed that matches gameplay** — sub-second transaction finality and parallel execution mean on-chain actions feel instant, not like waiting for a confirmation screen. [hashtag](https://docs.evefrontier.com/#build-the-future-of-the-eve-universe) Build the Future of the EVE Universe ----------------------------------------------------------------------------------------------------------------------- By stepping into the Frontier ecosystem, you join a community empowered to shape the world at every level, from infrastructure to economics to systemic gameplay. Whether you are programming advanced Smart Assemblies, designing tools for other players, or building vast industrial complexes, Frontier gives you both the freedom and the framework to bring your ideas to life. **EVE Frontier is open, collaborative, and powered by the creativity of its builders.** Together, we can define what it truly means to build in the EVE universe. To start building refer [Modding](https://docs.evefrontier.com/smart-assemblies/introduction) [NextSmart Infrastructurechevron-right](https://docs.evefrontier.com/welcome/smart-infrastructure) Last updated 4 days ago This site uses cookies to deliver its service and to analyze traffic. By browsing this site, you accept the [privacy policy](https://www.ccpgames.com/privacy-policy) . close AcceptReject --- # Environment Setup | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close To start building on EVE Frontier, follow the steps below to set up your local development tools. If you already have the tools, make sure they are the correct version to avoid difficulties building. [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#community-tool-efctl-one-command-setup) Community tool: efctl (one-command setup) ---------------------------------------------------------------------------------------------------------------------------------------------------------- The community CLI [**efctl**arrow-up-right](https://frontier.scetrov.live/links/efctl/) automates the full local setup. * * * [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#recommended-docker-any-os) Recommended: Docker (any OS) -------------------------------------------------------------------------------------------------------------------------------- The fastest way to get a Sui local development environment is with Docker. This works on Windows, Linux, and macOS with a single prerequisite. **Prerequisite:** [Dockerarrow-up-right](https://docs.docker.com/get-docker/) installed and running. Use the EVE Frontier builder-scaffold localnet setup: 1. Clone the builder-scaffold repo and navigate to the Docker setup: Copy mkdir -p workspace && cd workspace git clone https://github.com/evefrontier/builder-scaffold.git cd builder-scaffold/docker 1. Follow the instructions in the [localnet-setup/dockerarrow-up-right](https://github.com/evefrontier/builder-scaffold/blob/main/docker/readme.md) directory. This gives you a pre-configured Sui localnet and development environment without installing Sui CLI, WSL, or platform-specific tools. * * * [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#manual-setup-by-os) Manual setup by OS --------------------------------------------------------------------------------------------------------------- If you prefer to install tools directly on your system, follow the steps for your OS below. Windows Linux macOS This guide is for **Windows** users. [suiuparrow-up-right](https://github.com/MystenLabs/suiup) is a native Windows executable. Run commands in PowerShell, Command Prompt, or **Git Bash** (recommended if you prefer using the bash install script). ### [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#step-1-install-git) Step 1: Install Git Install [Git for Windowsarrow-up-right](https://git-scm.com/download/win) if you haven't already. Git Bash (included with the install) lets you run the suiup bash install script directly without needing to download the binary manually: Copy curl -sSfL https://raw.githubusercontent.com/MystenLabs/suiup/main/install.sh | sh Then continue from Step 3 below. If you prefer the manual binary install, follow Steps 2–3 instead. ### [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#step-2-install-suiup) Step 2: Install suiup suiup is the recommended way to install and manage Sui CLI. It is a cross-compiled native executable for Windows. 1. **Download** the latest Windows release from [suiup releasesarrow-up-right](https://github.com/MystenLabs/suiup/releases) . Choose the archive for Windows x86\_64 (e.g. `suiup-vX.X.X-windows-x86_64.zip`). 2. **Unzip** the archive. You'll get a folder containing the `suiup.exe` executable. 3. **Add suiup to your PATH** — choose one: **Option A — Use a dedicated bin folder (recommended)** * Create `%LOCALAPPDATA%\bin` if it doesn't exist (on most systems this is `C:\Users\\AppData\Local\bin`). * Move `suiup.exe` into that folder. * Add this folder to your user PATH in Environment Variables: **Option B — Use the extracted folder** * Leave `suiup.exe` in the folder where you unzipped it. * Add that folder to your user PATH using the same steps as Option A (Environment Variables → Path → New). 4. **Restart** your terminal (PowerShell or Command Prompt) so the updated PATH is picked up. Test with `suiup --version`. ### [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#step-3-install-sui-cli) Step 3: Install Sui CLI Copy suiup install sui@testnet Verify: Copy sui --version suiup installs binaries to `%LOCALAPPDATA%\bin`. Ensure this folder is on your `PATH`. ### [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#step-4-optional-node.js-and-pnpm) Step 4 (Optional): Node.js and PNPM For interaction using the TypeScript SDK, install [Node.jsarrow-up-right](https://nodejs.org/) (LTS) and then: Copy npm install -g pnpm This guide is for **Linux** users. Supported: Ubuntu 22.04 or newer. ### [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#step-1-install-git-1) Step 1: Install Git Copy sudo apt-get install git curl ### [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#step-2-install-sui-cli-via-suiup) Step 2: Install Sui CLI via suiup [suiuparrow-up-right](https://github.com/MystenLabs/suiup) is the recommended installer for Sui. Copy curl -sSfL https://raw.githubusercontent.com/MystenLabs/suiup/main/install.sh | sh Restart your shell, then install Sui for testnet: Copy suiup install sui@testnet Verify: Copy sui --version ### [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#step-3-optional-node.js-and-pnpm) Step 3 (Optional): Node.js and PNPM For interaction using typescript sdk: Copy curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash && . ~/.bashrc && nvm install 24 npm install -g pnpm This guide is for **macOS** users. Supported: macOS Tahoe or newer. ### [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#step-1-install-homebrew-if-needed) Step 1: Install Homebrew (if needed) Copy /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" Add brew to your path: Copy export PATH="/opt/homebrew/bin:$PATH" ### [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#step-2-install-git) Step 2: Install Git Copy brew install git ### [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#step-3-install-sui-cli-1) Step 3: Install Sui CLI **Option A — suiup (recommended):** Copy curl -sSfL https://raw.githubusercontent.com/MystenLabs/suiup/main/install.sh | sh Restart your shell, then: Copy suiup install sui@testnet **Option B — Homebrew:** Copy brew install sui Verify: Copy sui --version ### [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#step-4-optional-node.js-and-pnpm-1) Step 4 (Optional): Node.js and PNPM For interaction using typescript sdk: Copy brew install node@24 npm install -g pnpm [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#configure-sui-client) Configure Sui Client ------------------------------------------------------------------------------------------------------------------- Installing Sui does not configure the client. To use `sui` commands: 1. [Configure the Sui clientarrow-up-right](https://docs.sui.io/guides/developer/getting-started/configure-sui-client) to create an address and connect to a network. 2. [Get SUI from the faucetarrow-up-right](https://docs.sui.io/guides/developer/getting-started/get-coins) for testnet. [hashtag](https://docs.evefrontier.com/quickstart/environment-setup#next-steps) Next Steps ----------------------------------------------------------------------------------------------- You are ready to build on EVE Frontier. If you learn by doing, head to [Smart Assemblies](https://docs.evefrontier.com/smart-assemblies/storage-unit) . To understand concepts first, see [Introduction to Smart Contracts](https://docs.evefrontier.com/smart-contracts/introduction-to-smart-contracts) . [PreviousSui & Move Fundamentalschevron-left](https://docs.evefrontier.com/welcome/sui-and-move-fundamentals) [NextIntroduction to Smart Contractschevron-right](https://docs.evefrontier.com/smart-contracts/introduction-to-smart-contracts) Last updated 4 days ago --- # EVE Frontier World Explainer | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close ![](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252Fa2qYo3yTUUDAE3FYkeb8%252Fbanner4.png%3Falt%3Dmedia%26token%3D0b3b7825-bba3-4ec6-945c-00f6a55fc4ce&width=768&dpr=3&quality=100&sign=31457fac&sv=2) The EVE Frontier world runs on [Suiarrow-up-right](https://sui.io/) as Move smart contracts that define in-game structures, physics, and rules. The design stresses **composition over inheritance**: small building blocks combine into assemblies, which players can extend with custom logic. * * * [hashtag](https://docs.evefrontier.com/smart-contracts/eve-frontier-world-explainer#the-three-layer-architecture) The Three-Layer Architecture --------------------------------------------------------------------------------------------------------------------------------------------------- The world contracts use a three-layer architecture: spinner **Layer 1: Primitives** — Low-level Move modules that implement the "digital physics" of the game. They are small, focused, and designed for reusability without circular dependencies. Examples: `location.move`, `inventory.move`, `fuel.move`, `status.move`, `network_node.move`. **Layer 2: Assemblies** — Composed structures that players interact with (Storage Unit, Gate, Turret). Each assembly is a Sui shared object, enabling concurrent access by the game server and players. Assemblies combine primitives and expose public functions protected by capabilities or witnesses. **Layer 3: Player Extensions** — Custom smart contracts built by players that extend assembly behavior. Extensions register with assemblies via the typed authentication witness pattern and are authorized by type identity. Assemblies compose primitives. Player extensions authenticate via the [typed witness patternarrow-up-right](https://move-book.com/programmability/witness-pattern) when calling Layer 2. * * * [hashtag](https://docs.evefrontier.com/smart-contracts/eve-frontier-world-explainer#layer-1-primitives) Layer 1: Primitives -------------------------------------------------------------------------------------------------------------------------------- Primitives are small, focused Move modules that implement basic mechanics: * `**location.move**` — Spatial positioning and hashed location storage (for privacy). * `**inventory.move**` — Item storage and transfers. * `**fuel.move**` — Energy and resource consumption mechanics. * `**status.move**` — Lifecycle of assembly (Anchored, Online, Offline). * `**energy.move**` — Power generation and reservation. Primitives expose `public(package)` functions, so only modules in the same package can mutate them. Players do not call primitives directly; assemblies use them internally. Primitive access is restricted to Frontier-designed assemblies. **How assemblies use primitives** (example: Storage Unit): spinner Other assemblies compose subsets of these primitives (e.g., Gate = status + location + fuel + network\_node). * * * [hashtag](https://docs.evefrontier.com/smart-contracts/eve-frontier-world-explainer#layer-2-smart-assemblies) Layer 2: Smart Assemblies -------------------------------------------------------------------------------------------------------------------------------------------- Assemblies are in-game structures (storage units, gates and turrets) that players deploy and interact with. Each assembly is a **Sui shared object**, allowing concurrent access by the game and multiple players. **Storage Unit** — Programmable on-chain storage. Supports extensions (via typed witness) and direct owner access. **Gate (Stargate)** — Handles traversal between gates. Supports extensions (via typed witness). **Turret** — Programmable structure for defense and targeting. Supports extensions (via typed witness). Assemblies orchestrate primitives, enforce "digital physics" (e.g., proximity checks before withdraw), and expose public functions. * * * [hashtag](https://docs.evefrontier.com/smart-contracts/eve-frontier-world-explainer#layer-3-player-extensions-moddability) Layer 3: Player Extensions (Moddability) ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Players extend assembly behavior by deploying custom Move packages that register with assemblies through a **typed authentication witness** pattern. The assembly keeps an allowlist of registered extension `TypeName`s. A builder registers their witness type; only that module can create instances of it, so only that extension can call the assembly's authenticated entry points. **Flow:** 1. Owner registers a witness type (e.g., `Builder::Auth`) from the builder's package. 2. Assembly adds the `TypeName` to its allowlist. 3. Builder's module calls assembly functions by passing its witness; the assembly verifies the type is registered. Copy // World: assembly maintains allowlist of registered extension types module world::assembly { public struct Assembly has key { id: UID, allowed_extensions: Option, // ... other fields } public fun perform_op(assembly: &mut Assembly, _auth: Auth) { // Verify Auth type is registered in allowed_extensions // ... business logic } public fun register_extension(assembly: &mut Assembly, owner_cap: &OwnerCap) { // Add extension_type to allowed_extensions } } // Builder: custom extension defines a witness type module builder::custom_extension { public struct Auth has drop {} // Witness type — only this module can create it public entry fun swap_items(assembly: &mut world::assembly::Assembly) { world::assembly::perform_op(assembly, Auth {}) } } // Owner registers the extension type (requires owner_cap) assembly::register_extension(assembly, owner_cap); // Players can then call the custom extension's entry points builder::custom_extension::swap_items(assembly); **Benefits:** Type-based authorization; dynamic registration without redeploying assemblies; builders add custom logic while assemblies enforce authorization by type identity. * * * [hashtag](https://docs.evefrontier.com/smart-contracts/eve-frontier-world-explainer#privacy-location-obfuscation) Privacy: Location Obfuscation ---------------------------------------------------------------------------------------------------------------------------------------------------- To support mechanics that require information asymmetry (e.g., hidden bases): * **Hashed locations** — On-chain locations are stored as cryptographic hashes, not cleartext coordinates. * **Proximity verification** — Interactions require proof that entities are at the same or adjacent locations. Current implementation uses signatures from a trusted game server; future implementations may use zero-knowledge proofs. * * * [hashtag](https://docs.evefrontier.com/smart-contracts/eve-frontier-world-explainer#security-model) Security Model ----------------------------------------------------------------------------------------------------------------------- * **AdminACL operations** — Require the transaction to be sponsored by a authorised server. * **Owner operations** — Require ownership certificates (e.g., `OwnerCap`) for assembly-specific changes. * **Extension operations** — Use the witness type's `TypeName` to ensure calls come from registered third-party modules. * * * [hashtag](https://docs.evefrontier.com/smart-contracts/eve-frontier-world-explainer#next-steps) Next Steps --------------------------------------------------------------------------------------------------------------- **Learn more (Smart Contracts)** : * [Object Model](https://docs.evefrontier.com/smart-contracts/object-model) - how objects are derived and shared. * [Ownership Model](https://docs.evefrontier.com/smart-contracts/ownership-model) — understand access control. * [Move Patterns in Frontier](https://docs.evefrontier.com/smart-contracts/move-patterns-in-frontier) — Key patterns used in the world contracts. **Start Building** : * Assembly-specific build guides: [Storage Unit](https://docs.evefrontier.com/smart-assemblies/storage-unit) , [Gate](https://docs.evefrontier.com/smart-assemblies/gate) , [Turret](https://docs.evefrontier.com/smart-assemblies/turret) * [Interfacing with the EVE Frontier World](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world) — How to read and write on-chain state. **Reference** * [World Contractsarrow-up-right](https://github.com/evefrontier/world-contracts) * [ADRarrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/docs/architechture.md) [PreviousIntroduction to Smart Contractschevron-left](https://docs.evefrontier.com/smart-contracts/introduction-to-smart-contracts) [NextObject Modelchevron-right](https://docs.evefrontier.com/smart-contracts/object-model) Last updated 4 days ago --- # Sui & Move Fundamentals | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close EVE Frontier runs on the [Suiarrow-up-right](https://sui.io/) blockchain, leveraging the power and security of the [Movearrow-up-right](https://docs.sui.io/concepts/sui-move-concepts) programming language. Understanding Sui’s architecture and Move’s unique features will unlock the full potential of developing Smart Assemblies and interactive systems for players. * * * [hashtag](https://docs.evefrontier.com/welcome/sui-and-move-fundamentals#what-is-sui) What is Sui? ------------------------------------------------------------------------------------------------------- **Sui** is a high-performance, Layer 1 blockchain designed for secure, scalable, and low-latency digital asset ownership and transfer. It is optimized for real-time, dynamic applications — like games and social platforms — where transaction throughput and parallelism matter. **Key Sui Features:** * **Low Latency:** Extremely fast transaction finality, suitable for real-time interactions. * **High Throughput:** Scales horizontally by processing transactions in parallel, not just one at a time. * **Object-Centric Model:** Every asset is a unique on-chain object with its own identity, ownership, and history. * **Native Support for Games:** Built with composability and upgradability in mind. Learn more: [Sui Documentationarrow-up-right](https://docs.sui.io/concepts) — [Understanding Sui's architecturearrow-up-right](https://docs.sui.io/concepts/architecture) * * * [hashtag](https://docs.evefrontier.com/welcome/sui-and-move-fundamentals#what-is-move) What is Move? --------------------------------------------------------------------------------------------------------- **Move** is a smart contract language originally built for blockchain applications and now integral to the Sui ecosystem. Move prioritizes security, resource management, and flexibility, making it ideal for complex interactions in games. **Key Move Features:** * **Resource-Oriented Programming:** Assets are treated as first-class resources. They can’t be duplicated or accidentally destroyed, preventing common bugs in digital asset management. * **Modules and Scripts:** Logic is organized into reusable modules, while scripts interact with those modules to perform actions. * **Strong Typing:** Move enforces strict type and ownership checks at compile-time and runtime. * **Upgradeable and Composable:** Contracts can be designed for modular upgrades and extensibility. New to Move? Start with the [Hello World examplearrow-up-right](https://docs.sui.io/guides/developer/getting-started/hello-world) * * * [hashtag](https://docs.evefrontier.com/welcome/sui-and-move-fundamentals#getting-started) Getting Started -------------------------------------------------------------------------------------------------------------- * [Learn Sui basicsarrow-up-right](https://docs.sui.io/concepts) * [Try Move tutorialsarrow-up-right](https://docs.sui.io/guides/developer/getting-started/) * [Explore Sui Dev Toolsarrow-up-right](https://docs.sui.io/references/sui-sdks) [PreviousSmart Infrastructurechevron-left](https://docs.evefrontier.com/welcome/smart-infrastructure) [NextEnvironment Setupchevron-right](https://docs.evefrontier.com/quickstart/environment-setup) Last updated 4 days ago --- # Smart Infrastructure | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close ![](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252FvvqKYsOxokKiKv3IWvnq%252Fbanner5.png%3Falt%3Dmedia%26token%3Df6ef4e91-2b67-414d-9dbc-0bedac4d7981&width=768&dpr=3&quality=100&sign=afd82251&sv=2) **Smart Infrastructure** in EVE Frontier transforms the game world into a truly programmable sandbox. As a builder, you’re empowered to create, extend, and customize persistent in-game structures (Smart Assemblies) using modern on-chain technology—centered now on the Sui blockchain and its language, Move. [hashtag](https://docs.evefrontier.com/welcome/smart-infrastructure#what-are-smart-assemblies) What Are Smart Assemblies? ------------------------------------------------------------------------------------------------------------------------------ Smart Assemblies are special in-game infrastructure: programmable, player-built structures anchored to specific locations within the EVE Frontier universe. Each assembly can serve a unique mechanical purpose and exposes configurable interfaces for builders to innovate far beyond default gameplay features. Key examples include: * **Smart Storage Unit**: Storage and dispensing of items. * **Smart Turret**: Automated defense of zones and assets. * **Smart Gate**: Transportation or access control. * ...and many more to be designed, upgraded, and customized as the game continues to evolve. [hashtag](https://docs.evefrontier.com/welcome/smart-infrastructure#builder-agency-and-expression) Builder Agency and Expression ------------------------------------------------------------------------------------------------------------------------------------- Smart Assemblies are at the heart of EVE Frontier’s open-world philosophy. Every base, turret, shop, or gate can be programmed with new logic, interfaces, and behaviors. As a builder, you can evolve a storage unit into a real-time marketplace, a quest dispensing kiosk, or a mini-game terminal. The underlying rules are transparent, verifiable, and persistent—once deployed, your innovations become part of the simulation and its history. What can you enable? * **New game mechanics** (trading, missions, rewards) * **Advanced asset management** (locking, dispensing, tokenization) * **Player-driven economies** and custom rulesets * **Automation** and real-time reactions to world events * **Composable systems that extend other builders' creations** — your marketplace can use someone else's currency, your gate can reference another player's access list * **External dApps and tools** that interact with the game world from outside the client * ...and much, much more. [hashtag](https://docs.evefrontier.com/welcome/smart-infrastructure#the-technology-sui-and-move) The Technology: Sui and Move ---------------------------------------------------------------------------------------------------------------------------------- Smart Assemblies are built and managed on the Sui blockchain, leveraging its unique features for developer access, composability, and security. Programming is done in [Movearrow-up-right](https://move-language.github.io/move/) , a language designed for safe, flexible on-chain interactions. > **Note:** You do not need to be a Move expert to get started. Many tools, templates, and builder guides simplify the process, letting you focus on gameplay, not boilerplate. [hashtag](https://docs.evefrontier.com/welcome/smart-infrastructure#ready-to-begin) Ready to Begin? -------------------------------------------------------------------------------------------------------- Check out the available Smart Assemblies for inspiration, or dive into tutorials on creating your own. Explore: * [Smart Storage Unit](https://docs.evefrontier.com/smart-assemblies/storage-unit) — store, automate, trade * [Smart Turret](https://docs.evefrontier.com/smart-assemblies/turret) — defend, alert, customize * [Smart Gate](https://docs.evefrontier.com/smart-assemblies/gate) — transport, restrict, innovate [PreviousWhy Build on EVE Frontier?chevron-left](https://docs.evefrontier.com/) [NextSui & Move Fundamentalschevron-right](https://docs.evefrontier.com/welcome/sui-and-move-fundamentals) Last updated 4 days ago --- # Introduction to Smart Contracts | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close [hashtag](https://docs.evefrontier.com/smart-contracts/introduction-to-smart-contracts#what-are-smart-contracts) What are Smart Contracts? ----------------------------------------------------------------------------------------------------------------------------------------------- Smart contracts are programs that execute on the blockchain. They enforce persistent rules, manage assets, automate actions, and run shared logic in a secure, deterministic, and verifiable way. In EVE Frontier, smart contracts are the foundation for Smart Assembly functionality and on-chain business logic. Contracts are written in [Movearrow-up-right](https://docs.sui.io/concepts/sui-move-concepts) and deployed to [Suiarrow-up-right](https://sui.io/) . Sui validators compile and verify Move modules, execute transactions on the Move VM, and persist the resulting state on-chain. This ensures that all business logic runs deterministically and that any participant can verify correctness. [hashtag](https://docs.evefrontier.com/smart-contracts/introduction-to-smart-contracts#next-steps) Next Steps ------------------------------------------------------------------------------------------------------------------ * [Move Documentationarrow-up-right](https://move-book.com/concepts/) — Move concepts. * [Move Patterns in Frontier](https://docs.evefrontier.com/smart-contracts/move-patterns-in-frontier) — Key Move patterns used in the world contracts. * [EVE Frontier World Explainer](https://docs.evefrontier.com/smart-contracts/eve-frontier-world-explainer) — Overview of the world architecture. * [World Contractsarrow-up-right](https://github.com/evefrontier/world-contracts) — Source code and examples. [PreviousEnvironment Setupchevron-left](https://docs.evefrontier.com/quickstart/environment-setup) [NextEVE Frontier World Explainerchevron-right](https://docs.evefrontier.com/smart-contracts/eve-frontier-world-explainer) Last updated 4 days ago --- # Object Model | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close All game resources exist both in-game and on-chain. This section explains how in-game items are deterministically mapped to Sui objects. [hashtag](https://docs.evefrontier.com/smart-contracts/object-model#items) Items ------------------------------------------------------------------------------------- Every in-game resource is represented as an item with two key identifiers: * `**item_id**` — unique identifier for the item in-game * `**type_id**` — identifier for the item type (e.g., fuel type, assembly type) A **singleton** item is uniquely identified by `item_id + tenant`. A **non-singleton** item is uniquely identified by `type_id + tenant`. > `tenant` distinguishes different game server instances (e.g., production, testnet, development). [hashtag](https://docs.evefrontier.com/smart-contracts/object-model#deterministic-id-derivation) Deterministic ID Derivation --------------------------------------------------------------------------------------------------------------------------------- On-chain object IDs are derived deterministically from the in-game identifiers using Sui's [derived objectsarrow-up-right](https://docs.sui.io/guides/developer/objects/derived-objects) . This ensures a 1:1 mapping between in-game items and on-chain objects. The derivation key is a `TenantItemId`: Copy public struct TenantItemId has copy, drop, store { item_id: u64, tenant: String, } A single shared `ObjectRegistry` is used to derive all object IDs. Every game asset : characters, assemblies, network nodes derives its object ID from this registry using the same `TenantItemId` key. This guarantees that each in-game item ID can only be used once across all object types. Copy public struct ObjectRegistry has key { id: UID, } When creating an object (e.g., a Character), the ID is derived from the registry: Copy let character_key = in_game_id::create_key(game_character_id as u64, tenant); let character_uid = derived_object::claim(registry.borrow_registry_id(), character_key); Since the derivation is deterministic, the object ID can be **pre-computed** off-chain using the registry's object ID and the `TenantItemId`. [hashtag](https://docs.evefrontier.com/smart-contracts/object-model#shared-objects) Shared Objects ------------------------------------------------------------------------------------------------------- Most on-chain objects (characters, assemblies, network nodes) are [shared objectsarrow-up-right](https://docs.sui.io/concepts/object-ownership/shared) . This allows both the game server (admin) and the character owner to mutate the same object without ownership transfers. **Reference:** * [`object_registry.move`arrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/registry/object_registry.move) * [`in_game_id.move`arrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/primitives/in_game_id.move) [PreviousEVE Frontier World Explainerchevron-left](https://docs.evefrontier.com/smart-contracts/eve-frontier-world-explainer) [NextOwnership Modelchevron-right](https://docs.evefrontier.com/smart-contracts/ownership-model) Last updated 22 days ago --- # Move Patterns in Frontier | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close Key Move patterns used in the EVE Frontier world contracts: * * * [hashtag](https://docs.evefrontier.com/smart-contracts/move-patterns-in-frontier#derived-object-id) Derived object ID -------------------------------------------------------------------------------------------------------------------------- On-chain object IDs are **derived deterministically** from in-game identifiers (`item_id` + `tenant`) using Sui’s [derived objectsarrow-up-right](https://docs.sui.io/guides/developer/objects/derived-objects) . A single `ObjectRegistry` ensures one in-game item maps to one on-chain object across characters, assemblies, and network nodes. **Example:** IDs are claimed from the registry when creating assemblies (e.g. [assembly.movearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/assembly.move) ). **More:** [Object model](https://docs.evefrontier.com/smart-contracts/object-model) — items, `TenantItemId`, and derivation. * * * [hashtag](https://docs.evefrontier.com/smart-contracts/move-patterns-in-frontier#shared-object-model) Shared object model ------------------------------------------------------------------------------------------------------------------------------ Most world objects (characters, assemblies, network nodes) are **shared objects**. The game server (admin) and the object owner can both mutate the same object without transferring ownership. Access is enforced via capabilities, not object ownership. **More:** [Object model](https://docs.evefrontier.com/smart-contracts/object-model) . * * * [hashtag](https://docs.evefrontier.com/smart-contracts/move-patterns-in-frontier#hot-potato) Hot potato ------------------------------------------------------------------------------------------------------------ A **hot potato** is a struct with no `drop` ability. It must be consumed in the same transaction (e.g. by calling a function that takes it and destroys it). Frontier uses this to enforce multi-step flows. **Examples in world contracts:** * **ReturnOwnerCapReceipt** — Returned when borrowing an OwnerCap from a Character; it must be used to either return or transfer the cap, so the cap cannot be dropped or lost. * **OfflineAssemblies** — [`network_node::offline`arrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/network_node/network_node.move) returns a hot potato; the caller must bring all connected assemblies offline and then call `destroy_offline_assemblies` in the same transaction. * * * [hashtag](https://docs.evefrontier.com/smart-contracts/move-patterns-in-frontier#witness-pattern-typed-extension) Witness pattern (typed extension) -------------------------------------------------------------------------------------------------------------------------------------------------------- A **witness** is a one-time type that proves “this call comes from the module that defines this type.” Frontier uses it across **assemblies** so that only a specific extension module can authorize itself on an assembly. Once authorized, that custom contract can change the assembly's behaviour. **Example:** [`gate::authorize_extension`arrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/gate.move) — the gate calls `type_name::with_defining_ids()` and stores that type as its extension. Only the module that defines that type could have produced the witness, so only that module’s logic can be registered. Other assemblies use the same pattern to allow custom contracts to extend their behaviour. * * * [hashtag](https://docs.evefrontier.com/smart-contracts/move-patterns-in-frontier#receiving-as-object-transfer-to-object) Receiving as object (transfer to object) ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- OwnerCaps are **borrowed** from the Character object for a single transaction using Sui’s [transfer to objectarrow-up-right](https://docs.sui.io/guides/developer/objects/transfers/transfer-to-object) (e.g. `Receiving>`). The Character has a `Receiving` slot; the client passes a ticket to materialize the OwnerCap, uses it, then returns it (or transfers it) in the same transaction. **In world contracts:** [character.movearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/character/character.move) — `borrow_owner_cap`, `return_owner_cap`. **More:** [Move book: Transfer to objectarrow-up-right](https://move-book.com/storage/transfer-to-object) ; [Ownership model](https://docs.evefrontier.com/smart-contracts/ownership-model) — borrow-use-return pattern. * * * [hashtag](https://docs.evefrontier.com/smart-contracts/move-patterns-in-frontier#dynamic-fields) Dynamic fields -------------------------------------------------------------------------------------------------------------------- **Dynamic fields** let you attach key–value data to an object without changing the object’s type. Frontier uses them for ephemeral (e.g. temporary inventories) that can be added and removed at runtime. **More:** [Move book: Dynamic fieldsarrow-up-right](https://move-book.com/programmability/dynamic-fields) . * * * [hashtag](https://docs.evefrontier.com/smart-contracts/move-patterns-in-frontier#see-also) See also -------------------------------------------------------------------------------------------------------- * [Object model](https://docs.evefrontier.com/smart-contracts/object-model) * [Ownership model](https://docs.evefrontier.com/smart-contracts/ownership-model) * [EVE Frontier World Explainer](https://docs.evefrontier.com/smart-contracts/eve-frontier-world-explainer) * [World contracts (GitHub)arrow-up-right](https://github.com/evefrontier/world-contracts) [PreviousOwnership Modelchevron-left](https://docs.evefrontier.com/smart-contracts/ownership-model) [NextIntroduction to Modding Smart Assemblieschevron-right](https://docs.evefrontier.com/smart-assemblies/introduction) Last updated 4 days ago --- # Introduction to Modding Smart Assemblies | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close Some EVE Frontier smart assemblies are **programmable** — you can customize their in-game behavior by deploying custom Move contracts. [hashtag](https://docs.evefrontier.com/smart-assemblies/introduction#getting-started) Getting Started ---------------------------------------------------------------------------------------------------------- Prerequisites to customize a smart assembly: 1. **Create a Character** — your on-chain identity that owns all your assemblies. See [Smart Character](https://docs.evefrontier.com/smart-assemblies/smart-character) . 2. **Build a Network Node** — anchor a network node at a Lagrange point. This is the power source for your base. See [Network Node](https://docs.evefrontier.com/smart-assemblies/network-node) . 3. **Deposit Fuel & Go Online** — deposit fuel into the network node and bring it online to start generating energy. 4. **Anchor a Smart Assembly** — create a smart assembly (e.g., Storage Unit, Gate) in your base. It automatically connects to the network node for energy. 5. **Bring the Assembly Online** — the assembly reserves energy from the network node and becomes operational. > For local development and testing, refer to [builder-scaffoldarrow-up-right](https://github.com/evefrontier/builder-scaffold) > so you have everything you need to directly write custom logic for your smart assembly. > For a one-command automated setup, see the community tool [efctlarrow-up-right](https://frontier.scetrov.live/links/efctl/) > ([docs](https://docs.evefrontier.com/tools/efctl) > ). [hashtag](https://docs.evefrontier.com/smart-assemblies/introduction#programmable-assemblies) Programmable Assemblies -------------------------------------------------------------------------------------------------------------------------- Each assembly type has its own extension pattern. Each section has a **concept overview** (how the assembly works and its API) and a **build guide** (step-by-step instructions to write, publish, and test a custom extension): * [Smart Gate](https://docs.evefrontier.com/smart-assemblies/gate) — custom rules for space travel (e.g., toll gates, access lists) · [Build](https://docs.evefrontier.com/smart-assemblies/gate/build) * [Smart Storage Unit](https://docs.evefrontier.com/smart-assemblies/storage-unit) — custom rules for item deposits and withdrawals (e.g., vending machines, trade hubs) · [Build](https://docs.evefrontier.com/smart-assemblies/storage-unit/build) * [Smart Turret](https://docs.evefrontier.com/smart-assemblies/turret) — custom targeting logic · [Build](https://docs.evefrontier.com/smart-assemblies/turret/build) To read and write world state from code (SDK, GraphQL, gRPC), see [Interfacing with the EVE Frontier World](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world) . [PreviousMove Patterns in Frontierchevron-left](https://docs.evefrontier.com/smart-contracts/move-patterns-in-frontier) [NextSmart Characterchevron-right](https://docs.evefrontier.com/smart-assemblies/smart-character) Last updated 4 days ago --- # Ownership Model | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close EVE Frontier uses a **capability-based** access control system. Instead of relying on wallet addresses for ownership, transferable capability objects (`OwnerCap`) grant access to on-chain objects. [hashtag](https://docs.evefrontier.com/smart-contracts/ownership-model#access-hierarchy) Access Hierarchy -------------------------------------------------------------------------------------------------------------- Copy GovernorCap (deployer — top-level authority) └── AdminACL (shared object — authorized sponsor addresses) └── OwnerCap (player — mutates a specific object) * `**GovernorCap**` — created at deploy time. Can add/remove sponsors in `AdminACL`. * `**AdminACL**` — a shared object containing a list of authorized sponsor addresses. Functions protected by `AdminACL` call `verify_sponsor(ctx)`, which checks the transaction sponsor. * `**OwnerCap**` — a typed "keycard" that authorizes mutation of **one specific object**. Copy public struct OwnerCap has key { id: UID, authorized_object_id: ID, } [hashtag](https://docs.evefrontier.com/smart-contracts/ownership-model#character-as-a-keychain) Character as a Keychain ---------------------------------------------------------------------------------------------------------------------------- All `OwnerCap`s are stored inside the player's `Character` object (not in their wallet directly). This is inspired by a real-world **keychain pattern** — a single master key (the character) grants access to many capabilities. Copy User Wallet └── Character (shared object, mapped to user address) ├── OwnerCap ├── OwnerCap ├── OwnerCap └── ... When a Smart Assembly is created, its `OwnerCap` is minted and [transferred to the `Character` objectarrow-up-right](https://docs.sui.io/guides/developer/objects/transfers/transfer-to-object) (transfer to object). If the user has access to the character, they have access to all its capabilities. To discover a character from a wallet address, see [Smart Character — Discovering character from wallet address](https://docs.evefrontier.com/smart-assemblies/smart-character#discovering-character-from-wallet-address) . [hashtag](https://docs.evefrontier.com/smart-contracts/ownership-model#borrow-use-return-pattern) Borrow-Use-Return Pattern -------------------------------------------------------------------------------------------------------------------------------- To use an `OwnerCap`, the player **borrows** it from the character, uses it, and **returns** it all within a single transaction. This uses Sui's [`Receiving`arrow-up-right](https://docs.sui.io/guides/developer/objects/transfers/transfer-to-object) pattern. Copy // 1. Borrow the OwnerCap from the character public fun borrow_owner_cap( character: &mut Character, owner_cap_ticket: Receiving>, ctx: &TxContext, ): (OwnerCap, ReturnOwnerCapReceipt) // 2. Use it (e.g., bring a storage unit online) public fun online( storage_unit: &mut StorageUnit, network_node: &mut NetworkNode, energy_config: &EnergyConfig, owner_cap: &OwnerCap, ) // 3. Return it to the character public fun return_owner_cap( character: &Character, owner_cap: OwnerCap, receipt: ReturnOwnerCapReceipt, ) A [`ReturnOwnerCapReceipt`arrow-up-right](https://github.com/evefrontier/world-contracts/blob/3cc9ffad767cb499bfb31b3c9abe28f653ed5d69/contracts/world/sources/access/access_control.move#L30) (hot potato) ensures the cap is always returned or explicitly transferred, it cannot be silently dropped. ### [hashtag](https://docs.evefrontier.com/smart-contracts/ownership-model#typescript-example) TypeScript Example A typical owner-authenticated call (e.g., bringing a network node online): Copy // 1. Borrow OwnerCap from character const [ownerCap, receipt] = tx.moveCall({ target: `${packageId}::character::borrow_owner_cap`, typeArguments: [`${packageId}::network_node::NetworkNode`], arguments: [tx.object(characterId), tx.object(ownerCapId)], }); // 2. Use OwnerCap to bring network node online tx.moveCall({ target: `${packageId}::network_node::online`, arguments: [tx.object(nwnId), ownerCap, tx.object(CLOCK_OBJECT_ID)], }); // 3. Return OwnerCap to character tx.moveCall({ target: `${packageId}::character::return_owner_cap`, arguments: [tx.object(characterId), ownerCap, receipt], }); [hashtag](https://docs.evefrontier.com/smart-contracts/ownership-model#transferring-ownercap) Transferring OwnerCap ------------------------------------------------------------------------------------------------------------------------ You can transfer an `OwnerCap` to another address instead of returning it to the character (e.g. another player or an object managed by a tribe/corporation) using functions defined in [`access_control.move`arrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/access/access_control.move) . * **Transfer while borrowed** — If you borrowed the cap and have a `ReturnOwnerCapReceipt`, use [`transfer_owner_cap_with_receipt`arrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/access/access_control.move#L126) to send the cap to a new owner in the same transaction. The receipt is consumed; the cap is not returned to the original character. * **Direct transfer** — [`transfer_owner_cap(owner_cap, owner)`arrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/access/access_control.move#L96) sends the cap to a given address or [object IDarrow-up-right](https://docs.sui.io/guides/developer/objects/transfers/transfer-to-object) (e.g. another Character). Only the current owner can call this; the Sui runtime enforces ownership. So you can hand off an assembly access to another player, or to an address that represents a tribe/corporation. The contracts currently transfer to a single address; multi-party access (e.g. a capability shared by a tribe) is planned as a future extension via a capability registry. [hashtag](https://docs.evefrontier.com/smart-contracts/ownership-model#benefits) Benefits ---------------------------------------------------------------------------------------------- * **Centralized ownership** — manage all capabilities from a single character object * **Granular access** — each `OwnerCap` only authorizes one specific object * **Delegatable** — transfer an `OwnerCap` without moving the underlying assembly * **Composable** — the borrow-use-return pattern works within programmable transactions **Reference:** * [Transfer to Object (Sui docs)arrow-up-right](https://docs.sui.io/guides/developer/objects/transfers/transfer-to-object) * [`access_control.move`arrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/access/access_control.move) * [`character.move`arrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/character/character.move) [PreviousObject Modelchevron-left](https://docs.evefrontier.com/smart-contracts/object-model) [NextMove Patterns in Frontierchevron-right](https://docs.evefrontier.com/smart-contracts/move-patterns-in-frontier) Last updated 2 days ago --- # Storage Unit | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close ![](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252FrWAXtAMfdVvGcZnQDh5o%252FSSU.png%3Falt%3Dmedia%26token%3D2950caf6-4371-4e34-ab9c-977a7c2819c4&width=768&dpr=3&quality=100&sign=f2f0a319&sv=2) [hashtag](https://docs.evefrontier.com/smart-assemblies/storage-unit#introduction) Introduction ---------------------------------------------------------------------------------------------------- The Smart Storage Unit (SSU) is a **programmable, on-chain storage structure**. Players can store, withdraw, and manage items and the owner can define custom rules through extension contracts. [hashtag](https://docs.evefrontier.com/smart-assemblies/storage-unit#design) Design ---------------------------------------------------------------------------------------- A storage unit has two types of inventories: * **Primary inventory** — owned by the storage unit owner, accessed via the storage unit's `OwnerCap`. This is the main inventory for the owner's items. * **Ephemeral inventories** — temporary, per-character inventories for players other than the owner. Used for trading, deposits, etc. Ephemeral inventories have a smaller capacity than the primary inventory to prevent abuse of the owner's storage unit. Ephemeral inventories are created on-demand and stored as dynamic fields keyed by the character's `OwnerCap` ID. Each ephemeral inventory is accessed by the interacting character's own `OwnerCap`, like biometric authentication for temporary access. This avoids minting separate `OwnerCap`s just for ephemeral inventory access. Items in inventories are on-chain representations of in-game resources. [hashtag](https://docs.evefrontier.com/smart-assemblies/storage-unit#interacting-with-a-storage-unit) Interacting with a Storage Unit ------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://docs.evefrontier.com/smart-assemblies/storage-unit#id-1.-bridging-items-game-to-chain) 1\. Bridging Items (Game to Chain) For any on-chain interaction, items must first be available on-chain. Players move items from in-game into the chain, and can move them back out to the game. * **Game → Chain** — items are minted on-chain from in-game data. * **Chain → Game** — on-chain items are burned and returned to the game. ### [hashtag](https://docs.evefrontier.com/smart-assemblies/storage-unit#id-2.-owner-deposit-and-withdraw) 2\. Owner Deposit & Withdraw Once items are on-chain, the owner can deposit and withdraw directly using their owner capability. The owner signs the transaction and proves access with their `OwnerCap`; They can perform these actions from a dApp. ### [hashtag](https://docs.evefrontier.com/smart-assemblies/storage-unit#id-3.-custom-logic-via-extensions) 3\. Custom Logic via Extensions The owner can deploy custom rules (a [Move contractarrow-up-right](https://github.com/evefrontier/world-contracts) ) and register it as the storage unit’s extension. After that, the extension controls how items are deposited or withdrawn — for example: * **Vending machine** — players pay (e.g. in tokens) and receive an item from the unit. * **Trade hub** — custom rules for listing, buying, and exchanging items. * **Gated access** — only characters that meet certain conditions can deposit or withdraw. * **Extension-to-owned** — the extension can deposit items into a specific player’s owned inventory (e.g. async delivery, guild hangars, rewards); the recipient does not need to be the transaction sender. The extension uses the same pattern as the [Gate](https://docs.evefrontier.com/smart-assemblies/gate) : the owner authorizes a contract type on the storage unit, and that contract’s logic runs when players interact. For API details and build steps, see the [Storage Unit Build Guide](https://docs.evefrontier.com/smart-assemblies/storage-unit/build) . [hashtag](https://docs.evefrontier.com/smart-assemblies/storage-unit#next-steps) Next Steps ------------------------------------------------------------------------------------------------ Build a custom storage unit extension: [Build Guide](https://docs.evefrontier.com/smart-assemblies/storage-unit/build) **Reference:** * [world-contractsarrow-up-right](https://github.com/evefrontier/world-contracts) — EVE Frontier Sui Move contracts * [storage\_unit.movearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/storage_unit.move) — core storage unit module * [inventory.movearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/primitives/inventory.move) — inventory primitives * [contracts/worldarrow-up-right](https://github.com/evefrontier/world-contracts/tree/main/contracts/world) — world contract package * [world-contracts releasesarrow-up-right](https://github.com/evefrontier/world-contracts/releases) [PreviousNetwork Nodechevron-left](https://docs.evefrontier.com/smart-assemblies/network-node) [NextBuildchevron-right](https://docs.evefrontier.com/smart-assemblies/storage-unit/build) Last updated 3 days ago --- # Network Node | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close The Network Node is the **power source** for a player's base. It burns fuel to produce energy (measured in GJ) which is consumed by all connected smart assemblies. [hashtag](https://docs.evefrontier.com/smart-assemblies/network-node#overview) Overview -------------------------------------------------------------------------------------------- A player anchors a Network Node at a Lagrange point to establish a base. All smart assemblies built in this base connect to the network node to draw energy for their operations. [hashtag](https://docs.evefrontier.com/smart-assemblies/network-node#fuel-system) Fuel System -------------------------------------------------------------------------------------------------- Fuel is deposited into the network node and burned over time. Different fuel types have different **efficiencies** that affect how long they last. ### [hashtag](https://docs.evefrontier.com/smart-assemblies/network-node#fuel-efficiency) Fuel Efficiency Each fuel type has a configurable efficiency (10–100%). The **actual consumption rate** depends on the burn rate and fuel efficiency: Copy actualConsumptionRate = burnRateInMs × (fuelEfficiency / 100) Burn Rate Fuel Efficiency Actual Duration 3600s (1 hour) 100% 60 minutes 3600s (1 hour) 80% 48 minutes 3600s (1 hour) 50% 30 minutes 7200s (2 hours) 70% 84 minutes In-game fuel efficiency is represented by fuel type: Fuel type Efficiency EU-90 Fuel 90% SOF-80 Fuel 80% EU-40 Fuel 40% D2 FUEL 15% ### [hashtag](https://docs.evefrontier.com/smart-assemblies/network-node#fuel-lifecycle) Fuel Lifecycle 1. **Deposit** — add fuel to the network node 2. **Start burning** — when the network node goes online, fuel burning begins and produces energy 3. **Stop burning** — saves remaining elapsed time for the next cycle 4. **Depletion** — when fuel runs out, the network node goes offline and all connected assemblies are forced offline [hashtag](https://docs.evefrontier.com/smart-assemblies/network-node#energy-system) Energy System ------------------------------------------------------------------------------------------------------ When the network node is online and burning fuel, it produces a fixed amount of energy (GJ). Assemblies **reserve** energy when they come online and **release** it when they go offline. Each assembly type requires a fixed amount of energy to operate (configured in `EnergyConfig`): Copy public struct EnergyConfig has key { id: UID, assembly_energy: Table, // assembly_type_id -> energy required (GJ) } ### [hashtag](https://docs.evefrontier.com/smart-assemblies/network-node#example) Example Step Action Available Energy 1 Network node online, producing 100 GJ 100 GJ 2 Storage Unit A connects and goes online (requires 50 GJ) 50 GJ 3 Storage Unit B connects and goes online (requires 50 GJ) 0 GJ 4 Cannot online another assembly — no energy left 0 GJ 5 Storage Unit A goes offline, releases 50 GJ 50 GJ 6 Gate connects and goes online (requires 1 GJ) 49 GJ If the network node runs out of fuel, it goes **offline** — all connected assemblies are automatically brought offline. [hashtag](https://docs.evefrontier.com/smart-assemblies/network-node#assembly-connection) Assembly Connection ------------------------------------------------------------------------------------------------------------------ Assemblies connect to a network node when they are anchored. The network node powers all connected assemblies: ### [hashtag](https://docs.evefrontier.com/smart-assemblies/network-node#hot-potato-pattern) Hot Potato Pattern Critical operations use **hot potato structs** to enforce atomicity within a single transaction: * `**OfflineAssemblies**` — returned when a network node goes offline. Every connected assembly must be offlined in the same transaction. * `**UpdateEnergySources**` — returned when assemblies are connected. Each assembly's energy source must be updated in the same transaction. * `**HandleOrphanedAssemblies**` — returned when a network node is unanchored. All connected assemblies must be handled. **Reference:** * [`network_node.move`arrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/network_node/network_node.move) * [`fuel.move`arrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/primitives/fuel.move) * [`energy.move`arrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/primitives/energy.move) [PreviousSmart Characterchevron-left](https://docs.evefrontier.com/smart-assemblies/smart-character) [NextStorage Unitchevron-right](https://docs.evefrontier.com/smart-assemblies/storage-unit) Last updated 4 days ago --- # Smart Character | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close A Smart Character is the on-chain representation of an in-game character. It serves as the player's **identity on-chain** and the **owner of all assemblies** they create. [hashtag](https://docs.evefrontier.com/smart-assemblies/smart-character#overview) Overview ----------------------------------------------------------------------------------------------- When a player creates a character in-game, a corresponding `Character` object is created on-chain with the same character ID. The character is associated with a **tribe** and mapped to the player's **wallet address**. [hashtag](https://docs.evefrontier.com/smart-assemblies/smart-character#character-as-capability-holder) Character as Capability Holder ------------------------------------------------------------------------------------------------------------------------------------------- The character object acts as a **keychain** — it holds the `OwnerCap` for every object the player owns (network nodes, gates, storage units, etc.). See [Ownership Model](https://docs.evefrontier.com/smart-contracts/ownership-model) for details on the borrow-use-return pattern. [hashtag](https://docs.evefrontier.com/smart-assemblies/smart-character#creation) Creation ----------------------------------------------------------------------------------------------- Characters are created by the game server (admin) with a deterministic object ID derived from the in-game character ID. [hashtag](https://docs.evefrontier.com/smart-assemblies/smart-character#discovering-character-from-wallet-address) Discovering character from wallet address ----------------------------------------------------------------------------------------------------------------------------------------------------------------- The character object is a shared object; you need its object ID to interact with it. To get a character from a **wallet address** (e.g. when a player connects their wallet to your dApp), the game creates a **PlayerProfile** at character creation and [transfers it to the walletarrow-up-right](https://github.com/evefrontier/world-contracts/pull/119) . It contains only `character_id`. Query objects owned by the wallet with type `PlayerProfile` to obtain the character ID, then fetch the `Character` object. For a full GraphQL query and variables, see [Query character by wallet address](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world#query-character-by-wallet-address) . [hashtag](https://docs.evefrontier.com/smart-assemblies/smart-character#access-control) Access Control ----------------------------------------------------------------------------------------------------------- Only the wallet address stored in `character_address` can borrow `OwnerCap`s from the character. This is enforced in the `borrow_owner_cap` function: Copy public fun borrow_owner_cap( character: &mut Character, owner_cap_ticket: Receiving>, ctx: &TxContext, ): (OwnerCap, ReturnOwnerCapReceipt) { assert!(character.character_address == ctx.sender(), ESenderCannotAccessCharacter); // ... } **Reference:** * [`character.move`arrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/character/character.move) [PreviousIntroduction to Modding Smart Assemblieschevron-left](https://docs.evefrontier.com/smart-assemblies/introduction) [NextNetwork Nodechevron-right](https://docs.evefrontier.com/smart-assemblies/network-node) Last updated 2 days ago --- # Build | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close Step-by-step instructions for building a custom Storage Unit extension. For concepts and design, see the [Storage Unit README](https://docs.evefrontier.com/smart-assemblies/storage-unit) . [hashtag](https://docs.evefrontier.com/smart-assemblies/storage-unit/build#prerequisites) Prerequisites ------------------------------------------------------------------------------------------------------------ * Follow [environment-setup](https://docs.evefrontier.com/quickstart/environment-setup) * For typed-witness and publish flow, see the [Gate build guide](https://docs.evefrontier.com/smart-assemblies/gate/build) and [builder-scaffoldarrow-up-right](https://github.com/evefrontier/builder-scaffold) — use them as the source of truth for setup and build steps. [hashtag](https://docs.evefrontier.com/smart-assemblies/storage-unit/build#high-level-steps) High-level steps ------------------------------------------------------------------------------------------------------------------ 1. **Define a witness struct** (e.g. `public struct VendingAuth has drop {}`) in your Move package. 2. **Implement your logic** so it calls the [world storage unit modulearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/storage_unit.move) to deposit or withdraw items using your `Auth` witness (e.g. after checking payment, tribe, or other rules). 3. **Publish** the package and **authorize** it on the storage unit: borrow the storage unit’s `OwnerCap` and call `storage_unit::authorize_extension`. After authorization, only your extension’s logic can perform deposits/withdrawals for non-owner characters; the world module checks the `Auth` type. [hashtag](https://docs.evefrontier.com/smart-assemblies/storage-unit/build#storage-unit-api) Storage Unit API ------------------------------------------------------------------------------------------------------------------ Custom contracts use the **typed witness pattern**: define a witness struct (`Auth`) and register it on the storage unit. **Authorize an extension:** Copy public fun authorize_extension( storage_unit: &mut StorageUnit, owner_cap: &OwnerCap, ) **Extension: deposit / withdraw** (main inventory; your extension calls these with your `Auth` witness): Copy public fun deposit_item( storage_unit: &mut StorageUnit, character: &Character, item: Item, _: Auth, _: &mut TxContext, ) public fun withdraw_item( storage_unit: &mut StorageUnit, character: &Character, _: Auth, type_id: u64, quantity: u32, ctx: &mut TxContext, ): Item **Extension: deposit into a player’s owned inventory** Lets the extension push items into a specific character’s owned inventory; the recipient does not need to be the transaction sender. Use for async delivery, guild hangars, rewards: Copy public fun deposit_to_owned( storage_unit: &mut StorageUnit, character: &Character, item: Item, _: Auth, _: &mut TxContext, ) **Owner deposit / withdraw** (no extension; owner uses `OwnerCap`; sender must be the character). Copy public fun deposit_by_owner( storage_unit: &mut StorageUnit, item: Item, character: &Character, owner_cap: &OwnerCap, ctx: &mut TxContext, ) public fun withdraw_by_owner( storage_unit: &mut StorageUnit, character: &Character, owner_cap: &OwnerCap, type_id: u64, quantity: u32, ctx: &mut TxContext, ): Item Example use cases: vending machine (pay then withdraw), trade hub, gated access. See [builder-scaffold storage unit extensionarrow-up-right](https://github.com/evefrontier/builder-scaffold/tree/main/move-contracts/storage_unit_extension) for a working example. [hashtag](https://docs.evefrontier.com/smart-assemblies/storage-unit/build#reference) Reference ---------------------------------------------------------------------------------------------------- * [world-contractsarrow-up-right](https://github.com/evefrontier/world-contracts) — EVE Frontier Sui Move contracts * [storage\_unit.movearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/storage_unit.move) — core storage unit module * [inventory.movearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/primitives/inventory.move) — inventory primitives * [builder-scaffold storage\_unit\_extensionarrow-up-right](https://github.com/evefrontier/builder-scaffold/tree/main/move-contracts/storage_unit_extension) — example extension * [contracts/worldarrow-up-right](https://github.com/evefrontier/world-contracts/tree/main/contracts/world) — world contract package [PreviousStorage Unitchevron-left](https://docs.evefrontier.com/smart-assemblies/storage-unit) [NextTurretchevron-right](https://docs.evefrontier.com/smart-assemblies/turret) Last updated 3 days ago --- # Turret | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close ![](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252FjkklcTyuUKAuWtxjdoy7%252FTurret.png%3Falt%3Dmedia%26token%3D92b6e722-18c2-468c-8253-63570e054efb&width=768&dpr=3&quality=100&sign=19e03cdd&sv=2) [hashtag](https://docs.evefrontier.com/smart-assemblies/turret#introduction) Introduction ---------------------------------------------------------------------------------------------- A Turret is a **programmable structure** in space that projects offensive or defensive power over a fixed location. It is anchored on a base (grid), draws power from the network node, and automatically engages targets within its proximity. The game continuously evaluates nearby entities and asks _which_ target to shoot and in what order—either using built-in default logic or your custom extension. ### [hashtag](https://docs.evefrontier.com/smart-assemblies/turret#default-behavior) Default Behavior By default (no extension configured), the game uses the built-in logic in the [world turret contractarrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/turret.move) to decide which targets to shoot. Default rules: * **Exclude** — same tribe as owner and not an aggressor; or target **stopped** attacking * **Prioritize** — **started attacking** adds a large weight increment; **entered** proximity adds a smaller weight if different tribe or aggressor * The game shoots the target with the highest priority weight; ties use list order. ### [hashtag](https://docs.evefrontier.com/smart-assemblies/turret#custom-behavior-extension) Custom Behavior (Extension) When the owner configures an extension, the game uses that extension’s logic instead of the default to decide which targets to shoot and in what order. The extension receives the same target information the game uses and returns a custom priority list. 1. The owner deploys custom targeting logic (a [Move contractarrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/extension_examples/sources/turret.move) ) and registers it as the turret’s extension. 2. Whenever the game evaluates targets, it calls that logic and uses the returned list to choose what to shoot. [hashtag](https://docs.evefrontier.com/smart-assemblies/turret#behaviours) Behaviours ------------------------------------------------------------------------------------------ The game calls your extension **whenever target behaviour changes** (e.g. a ship enters range, starts or stops attacking). It sends **exactly one behaviour change per candidate**; if both ENTERED and STARTED\_ATTACK apply, the game sends STARTED\_ATTACK (the higher-priority). Your extension returns which targets to shoot and at what priority weight; the game shoots the highest-weight target, and uses list order to break ties. **Behaviour reasons:** * **ENTERED** — target entered the turret’s proximity * **STARTED\_ATTACK** — target started attacking the base (or someone on grid) * **STOPPED\_ATTACK** — target stopped attacking **Target candidate and return structs** (from the [world turret modulearrow-up-right](https://github.com/evefrontier/world-contracts/blob/3c35d6dce5f107bb8dd286e589330929ac401423/contracts/world/sources/assemblies/turret.move#L82) ): Copy public struct TargetCandidate has copy, drop, store { item_id: u64, type_id: u64, group_id: u64, character_id: u32, character_tribe: u32, hp_ratio: u64, shield_ratio: u64, armor_ratio: u64, is_aggressor: bool, priority_weight: u64, behaviour_change: BehaviourChangeReason, } public struct ReturnTargetPriorityList has copy, drop, store { target_item_id: u64, priority_weight: u64, } **TargetCandidate field meanings:** Field Meaning `item_id` Unique id for the target (ship\_id / npc\_id). `type_id` Target type (ship or NPC). `group_id` Ship group; helps prioritize by ship class. 0 for NPCs. `character_id` Pilot character id; 0 for NPCs. `character_tribe` Character tribe; 0 for NPCs. `hp_ratio`, `shield_ratio`, `armor_ratio` Remaining structure/shield/armor as percentage (0–100). `is_aggressor` True if this target is attacking anyone on grid (structure or player). `priority_weight` Default weight from game; your extension can override via the return list. `behaviour_change` The single reason sent for this candidate (e.g. STARTED\_ATTACK over ENTERED when both apply). **Return list:** the game shoots the target with the highest `priority_weight` in your returned list; if equal, it uses the order in the list. ### [hashtag](https://docs.evefrontier.com/smart-assemblies/turret#ship-groups-and-turret-specialization) Ship groups and turret specialization Turret types in the game are specialized against certain ship groups. You can use `group_id` to prefer targets your turret is good against: Ship class group\_id Shuttle 31 Corvette 237 Frigate 25 Destroyer 420 Cruiser 26 Combat Battlecruiser 419 Turret type type\_id Specialized against (group\_ids) Autocannon 92402 Shuttle (31), Corvette (237) Plasma 92403 Frigate (25), Destroyer (420) Howitzer 92484 Cruiser (26), Combat Battlecruiser (419) [hashtag](https://docs.evefrontier.com/smart-assemblies/turret#next-steps) Next Steps ------------------------------------------------------------------------------------------ Build and test a custom turret extension: [Build Guide](https://docs.evefrontier.com/smart-assemblies/turret/build) **Reference:** * [world-contractsarrow-up-right](https://github.com/evefrontier/world-contracts) — EVE Frontier Sui Move contracts * [turret.movearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/turret.move) — core turret module * [extension\_examples/turret.movearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/extension_examples/sources/turret.move) — example custom turret extension * [contracts/worldarrow-up-right](https://github.com/evefrontier/world-contracts/tree/main/contracts/world) — world contract package [PreviousBuildchevron-left](https://docs.evefrontier.com/smart-assemblies/storage-unit/build) [NextBuildchevron-right](https://docs.evefrontier.com/smart-assemblies/turret/build) Last updated 3 days ago --- # Build | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close Step-by-step instructions for building a custom Turret extension that controls target priority. For concepts and behaviour, see the [Turret README](https://docs.evefrontier.com/smart-assemblies/turret) . [hashtag](https://docs.evefrontier.com/smart-assemblies/turret/build#prerequisites) Prerequisites ------------------------------------------------------------------------------------------------------ * Follow [environment-setup](https://docs.evefrontier.com/quickstart/environment-setup) * For the same typed-witness and publish flow (authorize extension, game calls into your package), see the [Gate build guide](https://docs.evefrontier.com/smart-assemblies/gate/build) and [builder-scaffoldarrow-up-right](https://github.com/evefrontier/builder-scaffold) , use them as the source of truth for setup and build steps. [hashtag](https://docs.evefrontier.com/smart-assemblies/turret/build#high-level-steps) High-level steps ------------------------------------------------------------------------------------------------------------ 1. **Define a witness struct** (e.g. `public struct TurretAuth has drop {}`) in your Move package. 2. **Implement** `**get_target_priority_list**` with the same signature as the [world turret modulearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/turret.move) : * Parameters: `turret`, `owner_character`, BCS target list, `OnlineReceipt` * Return: BCS `vector` * Use `turret::unpack_candidate_list` and `turret::new_return_target_priority_list`; apply your priority rules (e.g. aggressors only, tribe/group filters, behaviour-based weights). 3. **Publish** the package and **authorize** it on the turret: borrow the turret's `OwnerCap` from the character and call `turret::authorize_extension`. After authorization, the game **resolves the package ID** from the authorised type and calls `get_target_priority_list` in your extension package whenever it evaluates targets for that turret. [hashtag](https://docs.evefrontier.com/smart-assemblies/turret/build#turret-api) Turret API ------------------------------------------------------------------------------------------------ Custom contracts use the **typed witness pattern**: define a witness struct (`Auth`) and register it on the turret. **Authorize an extension:** Copy public fun authorize_extension( turret: &mut Turret, owner_cap: &OwnerCap, ) **Extension entry point (game calls this):** Expose a function with the same signature as the [world turret modulearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/turret.move) . * The game deserialises `target_candidate_list` as BCS `vector` and expects BCS `vector` back. * Use `turret::unpack_candidate_list` and `turret::new_return_target_priority_list` / `turret::unpack_return_priority_list` as helpers. If the function’s parameter types or return type do not match exactly, the game may not be able to read the values and the extension will not work correctly. Copy public fun get_target_priority_list( turret: &Turret, owner_character: &Character, target_candidate_list: vector, receipt: OnlineReceipt, ): vector **Verify turret is online (world module):** Copy public fun verify_online(turret: &Turret): OnlineReceipt The game obtains an `OnlineReceipt` before calling `get_target_priority_list`. The receipt is a hot potato and must be consumed: extensions that call the world turret module should use `destroy_online_receipt(receipt, auth)` before returning. For ship group IDs and turret specialization by type, see the [Turret README](https://docs.evefrontier.com/smart-assemblies/turret#ship-groups-and-turret-specialization) . [hashtag](https://docs.evefrontier.com/smart-assemblies/turret/build#reference) Reference ---------------------------------------------------------------------------------------------- * [world-contractsarrow-up-right](https://github.com/evefrontier/world-contracts) — EVE Frontier Sui Move contracts * [turret.movearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/turret.move) — core turret module (API, structs, helpers) * [extension\_examples/turret.movearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/extension_examples/sources/turret.move) — example custom turret extension * [contracts/worldarrow-up-right](https://github.com/evefrontier/world-contracts/tree/main/contracts/world) — world contract package [PreviousTurretchevron-left](https://docs.evefrontier.com/smart-assemblies/turret) [NextGatechevron-right](https://docs.evefrontier.com/smart-assemblies/gate) Last updated 3 days ago --- # Gate | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close ![](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252FgIwSDY7OiCH7cZhQig33%252FGate.png%3Falt%3Dmedia%26token%3D39ff7010-34db-49d6-8d26-031282a61590&width=768&dpr=3&quality=100&sign=614020bd&sv=2) [hashtag](https://docs.evefrontier.com/smart-assemblies/gate#introduction) Introduction -------------------------------------------------------------------------------------------- A Gate is a structure in space that enables travel between locations. Two gates link together to create a transport route. Gates are **programmable** — the owner can deploy custom extension contracts to control who can jump. ### [hashtag](https://docs.evefrontier.com/smart-assemblies/gate#default-behavior) Default Behavior By default (no extension configured), **anyone can jump** through the gate without restrictions. ### [hashtag](https://docs.evefrontier.com/smart-assemblies/gate#custom-behavior-extension) Custom Behavior (Extension) When the owner configures an extension, the gate switches to a **permit-based** model: 1. The owner deploys custom jump rules (a [Move contractarrow-up-right](https://github.com/evefrontier/world-contracts) ) and registers it as the gate’s extension. 2. Players must obtain a **jump permit** from that logic (e.g. by meeting a tribe check, paying a toll, or completing a bounty) before they can travel. 3. The game validates the permit and allows the jump. Permits are tied to a route and an expiry time; a permit for Gate A ↔ Gate B works in both directions. For a full working example, see [builder-scaffold smart\_gatearrow-up-right](https://github.com/evefrontier/builder-scaffold/tree/main/move-contracts/smart_gate) . [hashtag](https://docs.evefrontier.com/smart-assemblies/gate#linking-gates) Linking Gates ---------------------------------------------------------------------------------------------- Two gates must be **linked** before anyone can jump between them. Requirements: * Both gates must be owned by the same character. * Gates must be at least 20 km apart (verified with a server-signed distance proof). * Linking requires an authorized transaction (the game validates this). [hashtag](https://docs.evefrontier.com/smart-assemblies/gate#next-steps) Next Steps ---------------------------------------------------------------------------------------- Build and test a custom smart gate end-to-end: [Build Guide](https://docs.evefrontier.com/smart-assemblies/gate/build) **Reference:** * [world-contractsarrow-up-right](https://github.com/evefrontier/world-contracts) — EVE Frontier Sui Move contracts * [gate.movearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/gate.move) — core gate module * [builder-scaffold smart\_gatearrow-up-right](https://github.com/evefrontier/builder-scaffold/tree/main/move-contracts/smart_gate) — example gate extension * [contracts/worldarrow-up-right](https://github.com/evefrontier/world-contracts/tree/main/contracts/world) — world contract package [PreviousBuildchevron-left](https://docs.evefrontier.com/smart-assemblies/turret/build) [NextBuildchevron-right](https://docs.evefrontier.com/smart-assemblies/gate/build) Last updated 3 days ago --- # Build | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close End-to-end build guide: write a gate extension, publish it, and test the complete jump flow. For concepts and behaviour, see the [Gate README](https://docs.evefrontier.com/smart-assemblies/gate) . [hashtag](https://docs.evefrontier.com/smart-assemblies/gate/build#prerequisites) Prerequisites ---------------------------------------------------------------------------------------------------- * Follow [environment-setup](https://docs.evefrontier.com/quickstart/environment-setup) * Complete step-by-step instructions: [builder-scaffold builder-flowarrow-up-right](https://github.com/evefrontier/builder-scaffold/blob/main/docs/builder-flow.md) [hashtag](https://docs.evefrontier.com/smart-assemblies/gate/build#gate-api) Gate API ------------------------------------------------------------------------------------------ Custom contracts use the **typed witness pattern**: define a witness struct (`Auth`) and register it on the gate. The [world gate modulearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/gate.move) verifies the type at runtime. **Authorize an extension:** Copy public fun authorize_extension( gate: &mut Gate, owner_cap: &OwnerCap, ) **Issue a jump permit (called by your extension):** Copy public fun issue_jump_permit( source_gate: &Gate, destination_gate: &Gate, character: &Character, _: Auth, expires_at_timestamp_ms: u64, ctx: &mut TxContext, ) **Jump with a permit:** Copy public fun jump_with_permit( source_gate: &Gate, destination_gate: &Gate, character: &Character, jump_permit: JumpPermit, admin_acl: &AdminACL, clock: &Clock, ctx: &mut TxContext, ) **JumpPermit** (from the world module): contains `character_id`, `route_hash`, and `expires_at_timestamp_ms`. The `route_hash` is direction-agnostic — a permit for Gate A → Gate B also works for Gate B → Gate A. * * * Below is the high-level understanding: [hashtag](https://docs.evefrontier.com/smart-assemblies/gate/build#id-1.-understand-the-example-contract) 1\. Understand the example contract -------------------------------------------------------------------------------------------------------------------------------------------------- The scaffold includes a working gate extension at `move-contracts/smart_gate/`. It has three modules: `**config.move**` — shared configuration object and the witness type: Copy public struct XAuth has drop {} public struct ExtensionConfig has key { id: UID } public struct AdminCap has key, store { id: UID } `XAuth` is the witness type registered on the gate. `ExtensionConfig` is a shared object where extension modules store their rules as dynamic fields. `AdminCap` controls who can update those rules. `**tribe_permit.move**` — issues jump permits only to characters in a configured tribe: Copy public fun issue_jump_permit( extension_config: &ExtensionConfig, source_gate: &Gate, destination_gate: &Gate, character: &Character, clock: &Clock, ctx: &mut TxContext, ) { // Check character's tribe matches the configured tribe assert!(character.tribe() == tribe_cfg.tribe, ENotStarterTribe); // Issue a time-limited permit via the world gate module gate::issue_jump_permit( source_gate, destination_gate, character, config::x_auth(), expires_at_timestamp_ms, ctx, ); } The key pattern: your module calls `gate::issue_jump_permit` with your witness type. The gate verifies `XAuth` matches the type registered via `authorize_extension`. `**corpse_gate_bounty.move**` — a more advanced example that combines a storage unit interaction with a gate permit. Players deposit a bounty item and receive a jump permit in return. [hashtag](https://docs.evefrontier.com/smart-assemblies/gate/build#id-2.-build-and-publish) 2\. Build and publish ---------------------------------------------------------------------------------------------------------------------- Copy cd move-contracts/smart_gate sui client publish --build-env testnet > For local network, provide the world package path: > > Copy > > sui client publish --build-env testnet --pubfile-path ../../../world-contracts/contracts/world/Pub.localnet.toml From the publish output, note the **package ID** and the **ExtensionConfig object ID**. Set both in your `.env`: Copy BUILDER_PACKAGE_ID=0x... EXTENSION_CONFIG_ID=0x... [hashtag](https://docs.evefrontier.com/smart-assemblies/gate/build#id-3.-configure-extension-rules) 3\. Configure extension rules -------------------------------------------------------------------------------------------------------------------------------------- Set the tribe and expiry parameters on the shared `ExtensionConfig`: Copy pnpm configure-rules This calls `tribe_permit::set_tribe_config` with a tribe ID and permit expiry duration. You can modify `ts-scripts/smart_gate/configure-rules.ts` to change the values. [hashtag](https://docs.evefrontier.com/smart-assemblies/gate/build#id-4.-authorize-the-extension-on-both-gates) 4\. Authorize the extension on both gates -------------------------------------------------------------------------------------------------------------------------------------------------------------- Register your `XAuth` type on each gate so it switches from default (open) to permit-based: Copy pnpm authorise-gate Under the hood this builds a transaction that: 1. Borrows the gate's `OwnerCap` from the character 2. Calls `gate::authorize_extension` on the gate 3. Returns the `OwnerCap` to the character After this, the default `jump` function is disabled — players must use `jump_with_permit`. [hashtag](https://docs.evefrontier.com/smart-assemblies/gate/build#id-5.-issue-a-jump-permit) 5\. Issue a jump permit -------------------------------------------------------------------------------------------------------------------------- Issue a permit to a player character: Copy pnpm issue-tribe-jump-permit This calls `tribe_permit::issue_jump_permit`, which checks the character's tribe and mints a `JumpPermit` object owned by the character. Players can collect/buy permit from a builder dapp. [hashtag](https://docs.evefrontier.com/smart-assemblies/gate/build#id-6.-jump-with-permit) 6\. Jump with permit -------------------------------------------------------------------------------------------------------------------- The player uses their permit to jump through the gate: Copy pnpm jump-with-permit A successful jump emits a `JumpEvent` and consumes the permit. Ideally this flow happens in the game. [hashtag](https://docs.evefrontier.com/smart-assemblies/gate/build#writing-your-own-extension) Writing your own extension ------------------------------------------------------------------------------------------------------------------------------ To create a gate extension from scratch: 1. Define a **witness struct** (e.g., `public struct MyAuth has drop {}`) 2. Write a function that enforces your rules and calls `gate::issue_jump_permit` 3. Publish the contract and authorize it on your gate with `gate::authorize_extension` Here's a minimal toll gate that requires payment before issuing a permit: Copy module custom::toll_gate; public struct TollGateAuth has drop {} public fun buy_pass( source_gate: &Gate, destination_gate: &Gate, character: &Character, payment: Coin, clock: &Clock, ctx: &mut TxContext, ) { // Custom logic: verify payment amount, token type, allowlist, etc. // ... gate::issue_jump_permit( source_gate, destination_gate, character, TollGateAuth {}, clock.timestamp_ms() + 3600_000, // 1 hour expiry ctx, ); } Other ideas: * **Allowlist** — check a stored list of approved characters * **Bounty gate** — require depositing an item to earn passage (see `corpse_gate_bounty.move` in the scaffold) See the [Gate API](https://docs.evefrontier.com/smart-assemblies/gate/build#gate-api) above for the full function signatures. [hashtag](https://docs.evefrontier.com/smart-assemblies/gate/build#reference) Reference -------------------------------------------------------------------------------------------- * [world-contractsarrow-up-right](https://github.com/evefrontier/world-contracts) — EVE Frontier Sui Move contracts * [gate.movearrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/contracts/world/sources/assemblies/gate.move) — core gate module * [builder-scaffold smart\_gatearrow-up-right](https://github.com/evefrontier/builder-scaffold/tree/main/move-contracts/smart_gate) — example gate extension * [contracts/worldarrow-up-right](https://github.com/evefrontier/world-contracts/tree/main/contracts/world) — world contract package [PreviousGatechevron-left](https://docs.evefrontier.com/smart-assemblies/gate) [NextdApps Quick Startchevron-right](https://docs.evefrontier.com/dapps/dapps-quick-start) Last updated 3 days ago --- # Connecting In-Game | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close Every Assembly has a Base dApp. This base dApp lets you configure properties of smart assemblies that you own or interact with, and view aspects of others' Assemblies. 1. In the EVE Frontier game client, navigate to a built Assembly, such as a Network Node. 2. Press **F** to interact. The in-game browser opens, showing the configuration dApp page for Smart Assembly you selected. ![](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252Fgit-blob-9dc6d15e714e99fc238394904815773c3339edea%252Fnetwork-node.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=1b17b130&sv=2) Network Node The dApp displays primitive, view-only information for every Smart Assembly. This includes publicly viewable information about the owner and state. ### [hashtag](https://docs.evefrontier.com/dapps/connecting-in-game#dapp-actions) dApp Actions The owner of an Assembly can use the Smart Assembly Base dApp to set a custom name, description, and URL. These changes are on-chain actions, but are submitted as [sponsored transactionsarrow-up-right](https://sui-docs.evefrontier.com/functions/useSponsoredTransaction.html) so they have no GAS cost to the player. To change a unit's name, description or URL: 1. Click the "Edit unit" button. 2. Make changes accordingly under dApp URL, Unit name or Unit description. 3. Click **Save**. This submits the change to a sponsored transaction endpoint, retrieving the transaction bytes, signing them, and returning them for submission to the chain. **Note**: You must be a unit's owner to set its URL, name or description. ![](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252Fgit-blob-02d6f359f5f0f369b48dbe0e56853ac007cbdade%252Fdapp-update-metadata.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=ade3fc71&sv=2) Edit name and description ### [hashtag](https://docs.evefrontier.com/dapps/connecting-in-game#custom-dapps) Custom dApps Some units may have an associated external URL for website built and maintained by the unit's owner. These associated URLs allow builders to create UIs from which they can configure smart hooks easily. Only unit owners may add or edit URLs. Users can view these custom dApps in-game, but should be aware that these dApps are entirely independent of the CCP safe zone. Any functions called by external dApps are sent as [gas-consuming transactionsarrow-up-right](https://sdk.mystenlabs.com/dapp-kit/react/hooks/use-dapp-kit#transaction-execution) . Users must have SUI in their wallet in order to successfully call any builder functions. A Sui faucet is [available herearrow-up-right](https://faucet.sui.io/) if required. ![](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252Fgit-blob-5d77ade4885bd1e068d0c53c8ba1ecc76327b055%252Fdapp-customdapp.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=e9e30f0d&sv=2) Custom dapp ### [hashtag](https://docs.evefrontier.com/dapps/connecting-in-game#modules) Modules Assemblies are tagged as a Smart Storage Unit, Smart Turret or Smart Gate. These tags are detected in the Smart Assembly dApp, and their respective installed modules are then rendered. #### [hashtag](https://docs.evefrontier.com/dapps/connecting-in-game#inventory-module) Inventory Module An inventory module grants storage capacity and lets players store inventory items in a **Storage Unit**. To interact with on-chain inventory items, users must link them to the chain through depositing them in the _Ephemeral Inventory_ holding area. Once inventory items are deposited to the _Ephemeral Inventory_, they are accessible for on-chain transactions and other interactions. Items in a player's inventory are viewable in the Inventory Module UI of the dApp. ![](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252Fgit-blob-4d18d6dfbc484be83245501906b0965c91df9585%252Fdapp-ssu-inventory.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=9ea741fb&sv=2) Smart Storage Unit Inventory [PreviousCustomizing External dAppschevron-left](https://docs.evefrontier.com/dapps/customizing-external-dapps) [NextWallets & Identitychevron-right](https://docs.evefrontier.com/eve-vault/wallets-and-identity) Last updated 22 hours ago --- # Connecting from an External Browser | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close The dApp uses the [Sui Wallet Standardarrow-up-right](https://docs.sui.io/standards/wallet-standard) to enable discoverability with Sui wallets. The only wallet currently supported with the EVE Frontier dApps is [Eve Vaultarrow-up-right](https://github.com/evefrontier/builder-documentation/blob/main/EveVault/README.md) . Open a browser and connect to [https://dapps.evefrontier.com/?tenant=stillnessarrow-up-right](https://test.dapps.evefrontier.com/?tenant=stillness) (Stillness) or [https://uat.dapps.evefrontier.com/?tenant=utopiaarrow-up-right](https://uat.dapps.evefrontier.com/?tenant=utopia) (Utopia). ![](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252Fgit-blob-ed626ad2530520b7e6e80c5ecf77ffadb6ccacd9%252Fconnect-evevault.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=35e0ab32&sv=2) Eve dApp Connect View Click on Connect with EVE Vault. This will prompt your EVE Vault extension to connect. If EVE Vault is currently locked, you will see a pop-up with a prompt to enter your PIN. ![](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252Fgit-blob-a847b14751fe700f38e9c3120a4e781044501e5e%252Fdapp-evevault-unlock.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=de79c47&sv=2) Eve Vault Unlock Popup ### [hashtag](https://docs.evefrontier.com/dapps/connecting-from-an-external-browser#connected-tenant-and-itemid) Connected tenant and itemId The selected assembly is determined by using query parameters from the URL. `?tenant` and `?itemId` must be defined. ItemId is the in-game game item ID, e.g. `1000000012345`. Your completed URL should look something like `https://dapps.evefrontier.com/?tenant=stillness&itemId=12345...` [PreviousdApps Quick Startchevron-left](https://docs.evefrontier.com/dapps/dapps-quick-start) [NextCustomizing External dAppschevron-right](https://docs.evefrontier.com/dapps/customizing-external-dapps) Last updated 22 hours ago --- # Customizing External dApps | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close [PreviousConnecting from an External Browserchevron-left](https://docs.evefrontier.com/dapps/connecting-from-an-external-browser) [NextConnecting In-Gamechevron-right](https://docs.evefrontier.com/dapps/connecting-in-game) Last updated 22 hours ago --- # Wallets & Identity | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close [hashtag](https://docs.evefrontier.com/eve-vault/wallets-and-identity#introduction) Introduction ----------------------------------------------------------------------------------------------------- Getting started in EVE Frontier begins with securing your wallet and establishing your in-game identity. With the move to Sui, the foundation for your presence, assets, and interactions—inside the game and across third-party dApps—is built around the EVE Vault wallet and browser extension. * * * [hashtag](https://docs.evefrontier.com/eve-vault/wallets-and-identity#eve-vault-your-wallet-and-identity) EVE Vault: Your Wallet and Identity -------------------------------------------------------------------------------------------------------------------------------------------------- **EVE Vault** is the official wallet and inventory manager for all EVE Frontier experiences on Sui. It's available as a web app and as a Chrome browser extension. EVE Vault does more than hold your tokens and assets—it serves as your digital passport, letting you connect securely to both the main game and the wider EVE Frontier dApp ecosystem. * **Wallet:** Secure storage for your Sui-based assets—including currencies, NFTs, and game items. * **Identity:** The EVE Vault extension functions as your authentication hub for dApps, making it easy (and private) to prove who you are without exposing sensitive keys or details. * **Single Sign-On:** Once the extension is installed and authenticated, connecting to dApps or new services is as simple as approving the prompt—no extra accounts or passwords needed. * * * [hashtag](https://docs.evefrontier.com/eve-vault/wallets-and-identity#seamless-onboarding-with-zklogin) Seamless Onboarding with zkLogin --------------------------------------------------------------------------------------------------------------------------------------------- EVE Vault leverages **zkLogin**—a zero-knowledge login protocol native to Sui—to give you effortless, privacy-preserving authentication: * **No Seed Phrases Needed:** Create your EVE Vault wallet using your EVE Frontier SSO account. * **Zero-Knowledge Proof:** zkLogin lets you prove ownership of your account to dApps and the EVE Vault, without the OAuth provider or anyone else learning your blockchain address or secrets. * **Fast & Private:** You get a secure Sui wallet, instantly ready for game and dApp use, with complete privacy and full control. * * * [hashtag](https://docs.evefrontier.com/eve-vault/wallets-and-identity#your-identity-inside-and-outside-the-client) Your Identity Inside and Outside the Client ------------------------------------------------------------------------------------------------------------------------------------------------------------------- * **In-Game:** Log in with EVE Vault to link your character, assets, and progression on-chain. Tokens, and other on chain property are visible and accessible through the wallet. * **Out-of-Game dApps:** The EVE Vault extension allows you to authenticate and interact with external EVE Frontier dApps, marketplaces, community tools, and integrations. Each connection is permissioned, using your wallet as the anchor of your identity, never re-using or exposing your login elsewhere. * * * [hashtag](https://docs.evefrontier.com/eve-vault/wallets-and-identity#high-level-flow) High-Level Flow ----------------------------------------------------------------------------------------------------------- 1. **Install EVE Vault extension** from [evefrontier/evevault/releases/downloadarrow-up-right](https://github.com/evefrontier/evevault/releases/download/v0.0.2/eve-vault-chrome.zip) 2. **Create your wallet** with a single sign on login — no secret phrases or manual backups. 3. **Authorize dApps** and the EVE Frontier game client to interact with your wallet and identity as needed. 4. **Transact, play, and participate** using EVE Vault as your only identity, both in and out of game. * * * [hashtag](https://docs.evefrontier.com/eve-vault/wallets-and-identity#summary) Summary ------------------------------------------------------------------------------------------- * **EVE Vault** is your one wallet and identity for EVE Frontier on Sui. * **zkLogin** provides secure, private onboarding—no seed phrase required. * The **browser extension** acts as your decentralized ID for all dApps and integrations. * Your assets, character, and reputation travel with you, wherever you explore in the EVE Frontier ecosystem. * * * [PreviousConnecting In-Gamechevron-left](https://docs.evefrontier.com/dapps/connecting-in-game) [NextIntroduction to EVE Vaultchevron-right](https://docs.evefrontier.com/eve-vault/introduction-to-eve-vault) Last updated 21 days ago --- # Wallet Game Setup | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close //TODO [PreviousIntroduction to EVE Vaultchevron-left](https://docs.evefrontier.com/eve-vault/introduction-to-eve-vault) [NextBrowser Extensionchevron-right](https://docs.evefrontier.com/eve-vault/browser-extension) Last updated 29 days ago --- # Introduction to EVE Vault | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close **EVE Vault** is the official wallet and inventory manager for EVE Frontier on Sui, available as a [web app and Chrome extensionarrow-up-right](https://github.com/evefrontier/evevault) . For what it is, how to install it, and how wallet and identity work (including zkLogin), see [Wallets & Identity](https://docs.evefrontier.com/eve-vault/wallets-and-identity) . **Features:** * Sui Wallet Standard compliance for fast, safe, cross-dApp integration. * FusionAuth OAuth support for linking your EVE Frontier account and in-game character to your wallet. * Permissioned dApp access: connect to player-made dApps and tools while protecting your infomorph's identity—even if your clone is destroyed. * * * [hashtag](https://docs.evefrontier.com/eve-vault/introduction-to-eve-vault#the-economy-and-currencies) The Economy and Currencies -------------------------------------------------------------------------------------------------------------------------------------- The EVE Frontier economy on Sui supports open, player-powered trading between real-world and in-game value. * **LUX**: Used for most in-game transactions, purchases, trades, and services. * **EVE Token**: A Sui-based utility token for ecosystem participation, modding, and developer rewards; supports dApp onboarding and can be used to acquire special game assets. EVE Vault enables: * Trading and storage of LUX, EVE Token, and other Sui-based assets. * Secure management and transfer of player-generated and alliance-specific currencies. * Integration with markets, trading systems, and configurable infrastructure rewards. **Core advantages:** * Trade assets, currencies, services, and reputation with robust permissions and privacy. * Create, exchange, and use custom currencies—including alliance tokens and specialized mission rewards. * Seamless experience for builders, traders, and players operating across the decentralized EVE Frontier world. * * * [PreviousWallets & Identitychevron-left](https://docs.evefrontier.com/eve-vault/wallets-and-identity) [NextWallet Game Setupchevron-right](https://docs.evefrontier.com/eve-vault/wallet-game-setup) Last updated 4 days ago --- # Browser Extension | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close Install the Eve Vault browser extension to use the vault from Chrome. [hashtag](https://docs.evefrontier.com/eve-vault/browser-extension#download) Download ------------------------------------------------------------------------------------------ Get the latest extension from the release: [**Eve Vault v0.0.5**arrow-up-right](https://github.com/evefrontier/evevault/releases/download/v0.0.5/eve-vault-chrome-v0.0.5.zip) Download the zip asset from the release page. [hashtag](https://docs.evefrontier.com/eve-vault/browser-extension#installation-chrome) Installation (Chrome) ------------------------------------------------------------------------------------------------------------------ 1. **Unzip** the downloaded file to a folder on your computer (e.g. `evevault-extension`). 2. Open Chrome and go to **chrome://extensions/**. 3. Turn on **Developer mode** (toggle in the top-right). 4. Click **Load unpacked**. 5. Select the folder where you unzipped the extension. 6. The Eve Vault extension will appear in your extensions list and in the Chrome toolbar. [hashtag](https://docs.evefrontier.com/eve-vault/browser-extension#sign-in) Sign in ---------------------------------------------------------------------------------------- After installing, open the extension and sign in with your credentials for the Utopia server. Follow these steps: ### [hashtag](https://docs.evefrontier.com/eve-vault/browser-extension#id-1.-create-a-6-digit-pin) 1\. Create a 6-digit PIN When you open the extension for the first time, you’ll be asked to create a **6-digit PIN**. This PIN is used to unlock the vault on this device. ![Create PIN](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252Fgit-blob-fef53d17fe63ba0fda84f6d935ce278848279f20%252Fcreate-pin.jpg%3Falt%3Dmedia&width=300&dpr=3&quality=100&sign=123aa964&sv=2) ### [hashtag](https://docs.evefrontier.com/eve-vault/browser-extension#id-2.-open-the-sign-in-flow) 2\. Open the sign-in flow On the sign-in screen, click **Log in**. This opens the Eve Frontier sign-in flow. ![Sign in](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252Fgit-blob-77d7862e9b5f9d12dbee265e2e62c37f42e13e4c%252Fsign-in.png%3Falt%3Dmedia&width=300&dpr=3&quality=100&sign=54197c0f&sv=2) ### [hashtag](https://docs.evefrontier.com/eve-vault/browser-extension#id-3.-sign-in-with-your-utopia-credentials) 3\. Sign in with your Utopia credentials Use your **Utopia server credentials** (Eve Frontier account) to sign in. Enter your email and password when prompted. ### [hashtag](https://docs.evefrontier.com/eve-vault/browser-extension#id-4.-use-the-dashboard) 4\. Use the dashboard After signing in successfully, you’ll see the **Eve Vault dashboard**, where you can manage your wallet and transactions. ![Dashboard](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252Fgit-blob-b98aabfe8eaac7a8acb0041e3930c79cbf29b293%252Fdashboard.jpg%3Falt%3Dmedia&width=300&dpr=3&quality=100&sign=3ac2a8f1&sv=2) * * * For source code and more releases, see the [evevault repositoryarrow-up-right](https://github.com/evefrontier/evevault) . [PreviousWallet Game Setupchevron-left](https://docs.evefrontier.com/eve-vault/wallet-game-setup) [NextInterfacing with the EVE Frontier Worldchevron-right](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world) Last updated 1 day ago --- # Interfacing with the EVE Frontier World | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close [hashtag](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world#overview) Overview ------------------------------------------------------------------------------------------------------------ You interact with the EVE Frontier world in two ways: * **Write path** — Submit transactions to Move public functions to mutate on-chain state (create assemblies, bring them online, deposit items, etc.). * **Read path** — Query on-chain state and events via [GraphQLarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/query-with-graphql) , [gRPCarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/grpc-overview) , or custom indexers. * * * [hashtag](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world#writing-to-the-world-contracts) Writing to the World Contracts -------------------------------------------------------------------------------------------------------------------------------------------------------- Write operations use the [Sui TypeScript SDKarrow-up-right](https://sdk.mystenlabs.com/typescript) to build and submit transactions. The [world-contracts ts-scriptsarrow-up-right](https://github.com/evefrontier/world-contracts/tree/main/ts-scripts) provide examples on how to interact with the EVE Frontier world. You can also use other SDKs (e.g., [Rustarrow-up-right](https://docs.sui.io/references/rust-sdk) or [community Go SDKarrow-up-right](https://docs.sui.io/references/sui-sdks) ) based on your tech stack. ### [hashtag](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world#example-bring-assembly-online) Example: Bring Assembly Online This script borrows `OwnerCap` from a character, calls the assembly `online` function, then returns the cap: Copy import { Transaction } from "@mysten/sui/transactions"; // 1. Borrow OwnerCap from character const [ownerCap] = tx.moveCall({ target: `${config.packageId}::character::borrow_owner_cap`, typeArguments: [`${config.packageId}::assembly::Assembly`], arguments: [tx.object(characterId), tx.object(ownerCapId)], }); // 2. Bring assembly online tx.moveCall({ target: `${config.packageId}::assembly::online`, arguments: [\ tx.object(assemblyId),\ tx.object(networkNodeId),\ tx.object(config.energyConfig),\ ownerCap,\ ], }); // 3. Return OwnerCap to character tx.moveCall({ target: `${config.packageId}::character::return_owner_cap`, typeArguments: [`${config.packageId}::assembly::Assembly`], arguments: [tx.object(characterId), ownerCap], }); See [ts-scripts/assembly/online.tsarrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/ts-scripts/assembly/online.ts) for the full script. ### [hashtag](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world#example-sponsored-transactions) Example: Sponsored Transactions Many world operations require server-side validation (e.g., proximity checks, sponsor checks). These use **sponsored transactions** — the player signs the intent, and an authorized sponsor (e.g., EVE Frontier) pays gas and submits: Copy tx.setSender(playerAddress); tx.setGasOwner(adminAddress); // Sponsor pays gas // ... moveCall to game_item_to_chain_inventory, etc. const result = await executeSponsoredTransaction( tx, client, playerKeypair, adminKeypair, playerAddress, adminAddress, { showEvents: true } ); See [ts-scripts/storage-unit/deposit-to-ephemeral-inventory.tsarrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/ts-scripts/storage-unit/deposit-to-ephemeral-inventory.ts) for a full example. * * * [hashtag](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world#reading-from-the-world-contracts) Reading from the World Contracts ------------------------------------------------------------------------------------------------------------------------------------------------------------ **SuiClient** is the main entry point for read operations in the [TypeScript SDKarrow-up-right](https://sdk.mystenlabs.com/typescript) . It connects to a Sui full node and exposes methods for querying objects, events, and transactions without submitting any transaction. Use it when you need to read state programmatically — for example, fetching an assembly's current config or checking ownership before building a transaction. ### [hashtag](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world#graphql) GraphQL Use Sui's [GraphQLarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/query-with-graphql) to query objects by type, owner, or filters. **Example: Get objects by type** Copy query GetObjectsByType($type: String!, $first: Int) { objects(filter: { type: $type }, first: $first) { pageInfo { hasNextPage endCursor } nodes { address asMoveObject { contents { json } } } } } Try it: [GraphQL Testnet IDEarrow-up-right](https://graphql.testnet.sui.io/graphql) . Pass variables in the IDE's Variables panel, e.g.: Copy { "type": "0x2ff3e06b96eb830bdcffbc6cae9b8fe43f005c3b94cef05d9ec23057df16f107::network_node::NetworkNode", "first": 10 } ### [hashtag](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world#query-character-by-wallet-address) Query character by wallet address A [PlayerProfilearrow-up-right](https://github.com/evefrontier/world-contracts/blob/8edd7e441daec68afab0558e80574efd6a241ce8/contracts/world/sources/character/character.move#L50) is created at character creation and transferred to the player’s wallet (`character_address`). Query objects owned by the wallet with type `PlayerProfile` to get `character_id`, then fetch the full `Character` if needed. Use your network’s GraphQL endpoint and the world package ID for that network. Set `address` to the wallet (Sui address) and `profileType` to `0x::character::PlayerProfile` (package ID is network-specific; see your deployment or [world-contractsarrow-up-right](https://github.com/evefrontier/world-contracts) ). Copy query GetCharacterDetails($address: SuiAddress!, $profileType: String!) { address(address: $address) { objects(last: 10, filter: { type: $profileType }) { nodes { contents { ... on MoveObject { contents { type { repr } json } } } } } } } Variables: Copy { "address": "0x...", "profileType": "0x::character::PlayerProfile" } Each node’s `json` includes `character_id`. Use that ID to load the full `Character` (e.g. query `objects` by that ID). ### [hashtag](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world#grpc) gRPC For higher throughput and streaming (e.g., checkpoints), use [gRPCarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/grpc-overview) —Sui's preferred read path. Requires a gRPC-enabled Sui full node. Copy # List objects owned by an address grpcurl -d '{ "owner": "" }' :443 sui.rpc.v2.StateService/ListOwnedObjects ### [hashtag](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world#events) Events State changes emit events on transactions. Use [suix\_queryEventsarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/using-events) to filter by module, type, or sender: Copy curl -X POST https://fullnode.mainnet.sui.io:443 \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "suix_queryEvents", "params": [{\ "MoveEventType": "0x...::smartgate::JumpEvent"\ }, null, 10, false] }' World events include `JumpEvent` (gate traversal), inventory updates, and deployment changes. Store and subscribe to events off-chain for dashboards, analytics, or game services. * * * [hashtag](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world#reading-from-the-world) Reading from the World ---------------------------------------------------------------------------------------------------------------------------------------- * **TypeScript** — [SuiClientarrow-up-right](https://sdk.mystenlabs.com/typescript) for objects, events, and transactions. * **GraphQL** — [Query by type, owner, or filtersarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/query-with-graphql) ; [Testnet IDEarrow-up-right](https://graphql.testnet.sui.io/graphql) . * **gRPC** — [Higher throughput and streamingarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/grpc-overview) (requires gRPC-enabled full node). * **Events** — [suix\_queryEventsarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/using-events) for Move events (e.g. gate jumps, inventory updates). [PreviousBrowser Extensionchevron-left](https://docs.evefrontier.com/eve-vault/browser-extension) [Nextefctl (community)chevron-right](https://docs.evefrontier.com/tools/efctl) Last updated 3 days ago --- # efctl (community) | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close [**efctl**arrow-up-right](https://frontier.scetrov.live/links/efctl/) is a community-built CLI that automates the full builder-scaffold setup: bringing up the local EVE Frontier environment, deploying world contracts and smart gates, and tearing it down. Use it when you want a single-command workflow instead of following the manual Docker or Host flow. efctl is built and maintained by a community member; see [efctlarrow-up-right](https://frontier.scetrov.live/links/efctl/) for source and docs. **Docs:** [Unofficial EVE Frontier Development Notesarrow-up-right](https://frontier.scetrov.live/getting-started/) [hashtag](https://docs.evefrontier.com/tools/efctl#for-better-understanding-of-the-building) For better understanding of the building ------------------------------------------------------------------------------------------------------------------------------------------ * [Sui CLI Cookbookarrow-up-right](https://frontier.scetrov.live/devsecops/sui-cli-cookbook/) — Sui CLI basics and common commands * [World contractsarrow-up-right](https://frontier.scetrov.live/develop/world-contracts/) — Design and architecture of EVE Frontier world contracts * [Builder scaffold overviewarrow-up-right](https://frontier.scetrov.live/develop/builder-scaffold/) — How the scaffold works and common gotchas [PreviousInterfacing with the EVE Frontier Worldchevron-left](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world) [NextdApp kitchevron-right](https://docs.evefrontier.com/tools/dapp-kit) Last updated 4 days ago --- # dApp kit | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close > React SDK for building EVE Frontier dApps on the Sui blockchain **Full API documentation (TypeDoc):** [**http://sui-docs.evefrontier.com/**arrow-up-right](http://sui-docs.evefrontier.com/) [hashtag](https://docs.evefrontier.com/tools/dapp-kit#features) Features ----------------------------------------------------------------------------- * 🔌 **Wallet Connection** - Easy integration with EVE Vault and Sui wallets * 📦 **Smart Object Data** - Fetch and transform assembly data via GraphQL * ⚡ **Sponsored Transactions** - Gas-free transactions via EVE Frontier backend * 🔄 **Auto-Polling** - Real-time updates with automatic data refresh * 🎨 **TypeScript First** - Full type safety for all assembly types [hashtag](https://docs.evefrontier.com/tools/dapp-kit#installation) Installation ------------------------------------------------------------------------------------- Copy npm install @evefrontier/dapp-kit # or pnpm add @evefrontier/dapp-kit ### [hashtag](https://docs.evefrontier.com/tools/dapp-kit#peer-dependencies) Peer Dependencies Copy npm install @tanstack/react-query react > Keep your app’s versions of **react**, **@mysten/dapp-kit-react**, and **@mysten/sui** in sync with the versions used by this package to avoid type or runtime mismatches. Check `package.json` for the current ranges. [hashtag](https://docs.evefrontier.com/tools/dapp-kit#quick-start) Quick Start ----------------------------------------------------------------------------------- ### [hashtag](https://docs.evefrontier.com/tools/dapp-kit#id-1.-set-up-the-provider) 1\. Set up the Provider Wrap your app with `EveFrontierProvider`: Copy import { EveFrontierProvider } from "@evefrontier/dapp-kit"; import { QueryClient } from "@tanstack/react-query"; const queryClient = new QueryClient(); function App() { return ( ); } ### [hashtag](https://docs.evefrontier.com/tools/dapp-kit#id-2.-configure-assembly-id) 2\. Configure Assembly ID Set the assembly ID via URL parameter: `https://yourdapp.com/?tenant=utopia&itemId=...` ### [hashtag](https://docs.evefrontier.com/tools/dapp-kit#id-3.-use-the-hooks) 3\. Use the Hooks Copy import { EveFrontierProvider, useConnection, useSmartObject } from "@evefrontier/dapp-kit"; import { QueryClient } from "@tanstack/react-query"; const queryClient = new QueryClient(); function App() { return ( ); } function MyDapp() { const { isConnected, handleConnect } = useConnection(); const { assembly, loading } = useSmartObject(); if (!isConnected) return ; if (loading) return
Loading...
; return
{assembly?.name}
; } [hashtag](https://docs.evefrontier.com/tools/dapp-kit#core-concepts) Core Concepts --------------------------------------------------------------------------------------- ### [hashtag](https://docs.evefrontier.com/tools/dapp-kit#hooks) Hooks Hook Description `useConnection()` Wallet connection state and methods `useSmartObject()` Current assembly data with auto-polling `useNotification()` Display user notifications `dAppKit.signTransaction()` Sign a transaction (from @mysten/dapp-kit-react) `dAppKit.signAndExecuteTransaction()` Sign and execute a transaction ### [hashtag](https://docs.evefrontier.com/tools/dapp-kit#standard-transactions-via-dappkit) Standard Transactions (via dAppKit) For normal transactions, use the `dAppKit` object which wraps Mysten's `@mysten/dapp-kit-react`: Copy import { useDAppKit } from "@mysten/dapp-kit-react"; import { Transaction } from "@mysten/sui/transactions"; function CustomTransactionButton() { const dAppKit = useDAppKit(); const handleCustomTx = async () => { // Build your transaction const tx = new Transaction(); tx.moveCall({ target: "0xpackage::module::function", arguments: [tx.pure.string("hello")], }); // Sign and execute const result = await dAppKit.signAndExecute({ transaction: tx, }); console.log("Transaction digest:", result.digest); }; return ( ); } ### [hashtag](https://docs.evefrontier.com/tools/dapp-kit#assembly-types) Assembly Types The SDK supports all EVE Frontier assembly types: Copy import { Assemblies, AssemblyType } from "@evefrontier/dapp-kit"; // Available types Assemblies.SmartStorageUnit Assemblies.SmartTurret Assemblies.SmartGate Assemblies.NetworkNode Assemblies.Manufacturing Assemblies.Refinery [hashtag](https://docs.evefrontier.com/tools/dapp-kit#graphql-api) GraphQL API ----------------------------------------------------------------------------------- For custom data fetching: Copy import { getAssemblyWithOwner, getObjectWithJson, executeGraphQLQuery } from "@evefrontier/dapp-kit"; // Fetch assembly with owner const { moveObject, character } = await getAssemblyWithOwner("0x123..."); // Fetch any object const result = await getObjectWithJson("0x456..."); // Custom query const data = await executeGraphQLQuery(myQuery, { address: "0x789..." }); [hashtag](https://docs.evefrontier.com/tools/dapp-kit#utilities) Utilities ------------------------------------------------------------------------------- Copy import { abbreviateAddress, isOwner, formatM3, formatDuration, getTxUrl, getDatahubGameInfo, } from "@evefrontier/dapp-kit"; // Shorten address for display abbreviateAddress("0x1234567890abcdef"); // "0x123...cdef" // Fetch item metadata const info = await getDatahubGameInfo(83463); console.log(info.name, info.iconUrl); [hashtag](https://docs.evefrontier.com/tools/dapp-kit#api-reference) API Reference --------------------------------------------------------------------------------------- **Full API documentation (TypeDoc):** [**http://sui-docs.evefrontier.com/**arrow-up-right](http://sui-docs.evefrontier.com/) [Previousefctl (community)chevron-left](https://docs.evefrontier.com/tools/efctl) [NextDebugging Toolschevron-right](https://docs.evefrontier.com/tools/debugging) Last updated 9 days ago --- # Player | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close [PreviousBuilderchevron-left](https://docs.evefrontier.com/troubleshooting/builder) [NextWalletchevron-right](https://docs.evefrontier.com/troubleshooting/wallet) Last updated 4 days ago --- # Sandbox Access | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close circle-info Note that this server is only available during specific events and is not generally accessible. #### [hashtag](https://docs.evefrontier.com/troubleshooting/sandbox-access#download-the-launcher) Download the Launcher * Visit https://evefrontier.com/en/download and select either the Windows or Mac launcher * Download and install #### [hashtag](https://docs.evefrontier.com/troubleshooting/sandbox-access#add-the-utopia-server-to-the-launcher) Add the Utopia Server to the launcher Windows Mac OS **Modify an application shortcut** * Right-click on the desktop shortcut to the EVE Frontier Launcher * Choose Properties * On the "shortcut" tab add the following to the end of the Target field: `--frontier-test-servers=Utopia` * Click "Okay" **Run the launcher from Terminal** * Open Terminal in the folder where the application resides * Run the following command: cd /Applications; open 'EVE Frontier.app/' --args --frontier-test-servers=Utopia #### [hashtag](https://docs.evefrontier.com/troubleshooting/sandbox-access#run-the-launcher-and-select-utopia) Run the Launcher and Select "Utopia" You should then see Utopia on the drop down list of servers in the bottom right of the launcher * Choose Utopia * Click Register * Fill in your details * You will see a prompt to enter a verification code which you will receive by email * You can then download the Utopia Client circle-info After this point you will need to wait for your access to be granted by CCP, until then you will see a "Founder Access Required" Error ### [hashtag](https://docs.evefrontier.com/troubleshooting/sandbox-access#slash-commands) Slash Commands To speed up moving around the universe and gathering materials we have enabled a number of commands you can use on the sandbox To use these commands simply enter them in the chat window * `/moveme` This will display a list of star systems which you can move to instantly * `/giveitem ` This will allow you to spawn the specified item in your current ships' cargo hold * `/giveitem "" ` This works the same way as the above but lets you specify an item by name rather than ItemID circle-info Note it is possible to overload your ships cargo this way which will prevent warping, you would first need to move the excess to a storage unit or jettison it Some common items you may want to spawn include the below, more ItemID's can be found via the WorldAPI (https://world-api-utopia.uat.pub.evefrontier.com/docs/index.html): Name ItemID Carbon Weave 84210 Thermal Composites 88561 Printed Circuits 84180 Reinforced Alloys 84182 Feldspar Crystals 77800 Hydrated Sulfide Matrix 77811 Building Foam 89089 [PreviousWalletchevron-left](https://docs.evefrontier.com/troubleshooting/wallet) [NextA Work In Progresschevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) Last updated 8 minutes ago --- # Builder | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close Below are some of the common gotchas during building [PreviousDebugging Toolschevron-left](https://docs.evefrontier.com/tools/debugging) [NextPlayerchevron-right](https://docs.evefrontier.com/troubleshooting/player) Last updated 4 days ago --- # Debugging Tools | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close [PreviousdApp kitchevron-left](https://docs.evefrontier.com/tools/dapp-kit) [NextBuilderchevron-right](https://docs.evefrontier.com/troubleshooting/builder) Last updated 4 days ago --- # Wallet | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close Below are some of the common gotchas in using the wallet [PreviousPlayerchevron-left](https://docs.evefrontier.com/troubleshooting/player) [NextSandbox Accesschevron-right](https://docs.evefrontier.com/troubleshooting/sandbox-access) Last updated 4 days ago --- # A Work In Progress | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close As we transition EVE Frontier to the Sui Blockchain we are also re-writing all of our documentation to reflect this change and expanding the scope of this site to better serve those new to building in EVE Frontier. This will be a gradual process and you will notice //todo's on a number of pages, these pages are still being actively worked on and will be filled out over the coming days and weeks. That's not the end however; and this new documentation site has been designed for community contribution going forward, so that together, we can build a better experience for builders at all skill levels. ![](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252FbK3yWTpoaJpolr2gGMsB%252Fbanner7.png%3Falt%3Dmedia%26token%3D1ee18ee1-3e7d-42f9-b9fe-b90cbb24c472&width=768&dpr=3&quality=100&sign=9dbc7b73&sv=2) [PreviousSandbox Accesschevron-left](https://docs.evefrontier.com/troubleshooting/sandbox-access) [NextHow to Contributechevron-right](https://docs.evefrontier.com/contributing/contributing) Last updated 29 days ago --- # How to Contribute | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close circle-info This site is synced to GitHub. You can propose changes from any page. Use **Edit on GitHub** to open a pull request. ### [hashtag](https://docs.evefrontier.com/contributing/contributing#what-you-can-contribute) What you can contribute * Fix typos and broken links. * Clarify steps that are confusing or missing. * Add examples, screenshots, or diagrams. * Update docs when behavior changes. * Add troubleshooting notes and known pitfalls. circle-info If you are unsure, submit a small PR first. We can iterate from there. ### [hashtag](https://docs.evefrontier.com/contributing/contributing#quick-workflow-recommended) Quick workflow (recommended) 1 **Open the page you want to change** Navigate to the exact page in the docs. Scroll to the section you want to improve. 2 **Click Edit on GitHub** Open the page menu (top-right dropdown). Select **Edit on GitHub**. Sign in to GitHub if prompted. GitHub will open the source file for that page. 3 **Edit in GitHub** Click the pencil icon to edit the file. If you do not have access, GitHub will fork first. Make your changes in the editor. Use the preview tab to sanity check formatting. 4 **Propose the change** Scroll to the bottom of the editor. Write a clear commit message. Keep it short and specific. Select the option to create a new branch. Use a descriptive branch name. Click **Propose changes**. 5 **Open a pull request** GitHub will suggest creating a PR. Fill in: * **Title**: what changed. * **Description**: why it changed. * **Scope**: which pages or sections. * **Verification**: how you checked accuracy. Then click **Create pull request**. 6 **Respond to review** You may get comments or requested edits. Update the same branch. GitHub will update the PR automatically. 7 **Merge and publish** After approval, a maintainer will merge the PR. This site will sync and publish shortly after. If you do not see updates, wait a few minutes. ### [hashtag](https://docs.evefrontier.com/contributing/contributing#best-practices-for-strong-prs) Best practices for strong PRs #### [hashtag](https://docs.evefrontier.com/contributing/contributing#keep-changes-small) Keep changes small Prefer one topic per PR. Avoid drive-by refactors. Large rewrites are hard to review. #### [hashtag](https://docs.evefrontier.com/contributing/contributing#write-for-the-reader) Write for the reader State prerequisites early. Use concrete values and examples. Prefer copy-pasteable snippets. Call out footguns and failure modes. #### [hashtag](https://docs.evefrontier.com/contributing/contributing#match-existing-style) Match existing style Keep sentences short. Use headings to break up long pages. Use consistent terms across pages. #### [hashtag](https://docs.evefrontier.com/contributing/contributing#be-precise-and-verifiable) Be precise and verifiable Do not guess. If something is unconfirmed, label it clearly. Add a link to a source when possible. #### [hashtag](https://docs.evefrontier.com/contributing/contributing#dont-leak-secrets) Don’t leak secrets Never commit API keys, tokens, or internal URLs. Redact logs that include credentials. ### [hashtag](https://docs.evefrontier.com/contributing/contributing#courtesy-guidelines) Courtesy guidelines * Assume good intent. * Be kind and direct in review comments. * Ask before making broad structural changes. * Don’t “win” arguments by rewriting someone’s work. * Prefer suggestions over mandates. * Be patient with response times. circle-exclamation If your change impacts behavior, call it out. Surprise changes cause real user pain. ### [hashtag](https://docs.evefrontier.com/contributing/contributing#common-reasons-prs-get-delayed) Common reasons PRs get delayed * Mixed, unrelated edits in one PR. * Vague commit message or PR description. * Claims without a way to verify. * Breaking links or inconsistent terminology. * Big rewrites without prior discussion. ### [hashtag](https://docs.evefrontier.com/contributing/contributing#need-help) Need help? If GitHub is blocking your edit, copy the error message. Include it in your PR or message to the maintainers. If you are unsure where to edit, link the page. [PreviousA Work In Progresschevron-left](https://docs.evefrontier.com/contributing/a-work-in-progress) Last updated 21 days ago --- # dApps Quick Start | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close [PreviousBuildchevron-left](https://docs.evefrontier.com/smart-assemblies/gate/build) [NextConnecting from an External Browserchevron-right](https://docs.evefrontier.com/dapps/connecting-from-an-external-browser) Last updated 22 hours ago --- # Why Build on EVE Frontier? | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close ![](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252FCcrQJliZ4OPw3WXFPHV3%252Fbanner_gate.png%3Falt%3Dmedia%26token%3Dd010ecbe-6c44-404f-a266-1c93b9efe17e&width=768&dpr=3&quality=100&sign=9f7a985d&sv=2) In **EVE Frontier**, survival is only the starting point. What truly defines this next generation sandbox is the unprecedented agency it gives to Builders, creators, and developers. Frontier expands on decades of EVE design philosophy, player-driven economies, emergent gameplay, and systemic depth, and pushes it into a new era of openness, modularity, and community-driven evolution. [hashtag](https://docs.evefrontier.com/welcome#a-sandbox-where-builders-shape-the-universe) A Sandbox Where Builders Shape the Universe -------------------------------------------------------------------------------------------------------------------------------------------- At the core of Frontier are **Smart Assemblies**, physical and programmable structures anchored in space. These are not just buildings, they are the foundation of a living infrastructure layer that players can design, modify, automate, and optimize. Turrets, markets, storage facilities, refineries, logistics hubs, and defensive networks become active components of your strategy. Your constructions do not just exist in the world, they act within it. Frontier is designed as a true open environment. The world evolves not only through player actions, but also through server-side, real-time modding by the community. This is a game where builders can directly influence the systems that govern it. [hashtag](https://docs.evefrontier.com/welcome#construct-to-expand-program-to-dominate) Construct to Expand, Program to Dominate ------------------------------------------------------------------------------------------------------------------------------------- Building in Frontier is not cosmetic, it is strategic. ### [hashtag](https://docs.evefrontier.com/welcome#build-infrastructure-to-expand-your-influence) Build Infrastructure to Expand Your Influence Every structure you place expands your agency in the Frontier. Bases become footholds, networks become territory, and entire playstyles emerge from how you design your industrial, logistical, or defensive footprint. ### [hashtag](https://docs.evefrontier.com/welcome#program-functionality-to-master-the-sandbox) Program Functionality to Master the Sandbox Through the programmable layer of Smart Assemblies, you could for example: * automate defenses * create dynamic trade systems * build custom logistics pipelines * design specialized utility structures * script unique gameplay interactions The more you build, and the smarter your assemblies are, the more control you gain over your environment. [hashtag](https://docs.evefrontier.com/welcome#a-fully-open-economic-sandbox) A Fully Open Economic Sandbox ---------------------------------------------------------------------------------------------------------------- Frontier embraces a **community-driven, open in-game economy**. Builders can create: * custom currencies * decentralized markets * trading networks * service economies * reputation-based systems Every tool exists for players to shape the economic landscape, not just participate in it. [hashtag](https://docs.evefrontier.com/welcome#powered-by-eve-frontier-world-smart-contracts) Powered by Eve Frontier World Smart Contracts ------------------------------------------------------------------------------------------------------------------------------------------------ The **World Contracts** extend Frontier's programmability far beyond structures. Any in-game entity can be represented on-chain and edited by player-written code, including: * characters * assemblies * items * killmails * and more This creates a composable and extensible universe where emergent gameplay is not just allowed, it is inevitable. [hashtag](https://docs.evefrontier.com/welcome#building-on-blockchain-a-foundation-for-player-ownership) Building on Blockchain: A Foundation for Player Ownership ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- * **True ownership of your creations** — your assets are verifiably yours, not stored on a centralized server that can be shut down. * **A persistent universe** — your contributions endure on-chain, creating a living history that outlasts any single play session, update, or game cycle. * **An open, composable economy** — player-built systems, markets, and tools can interact with each other, enabling a co-created world rather than a developer-dictated one. [hashtag](https://docs.evefrontier.com/welcome#why-sui-built-for-a-universe-of-this-scale) Why Sui: Built for a Universe of This Scale ------------------------------------------------------------------------------------------------------------------------------------------- Frontier's integration with [**Sui**arrow-up-right](https://www.sui.io/intro-to-sui) is not a cosmetic technical choice — it directly enables the kind of world Frontier is designed to be. * **Objects, not accounts** — Sui treats every asset as an individual object with its own identity, history, and ownership record. * **Safe player modding at scale** — Smart Assemblies let anyone deploy code into a shared universe. Sui's Move language makes entire categories of exploits structurally impossible, so player creativity doesn't come at the cost of world stability. * **Systems that talk to each other** — player-built structures, contracts, and tools can natively compose and extend one another, meaning what you build can plug into what others build. * **No wallet, no gas, no friction** — Sui's zkLogin lets you sign in with your account credentials, and sponsored transactions mean you never need to buy tokens just to play. The blockchain is there, but you don't have to think about it. * **Speed that matches gameplay** — sub-second transaction finality and parallel execution mean on-chain actions feel instant, not like waiting for a confirmation screen. [hashtag](https://docs.evefrontier.com/welcome#build-the-future-of-the-eve-universe) Build the Future of the EVE Universe ------------------------------------------------------------------------------------------------------------------------------ By stepping into the Frontier ecosystem, you join a community empowered to shape the world at every level, from infrastructure to economics to systemic gameplay. Whether you are programming advanced Smart Assemblies, designing tools for other players, or building vast industrial complexes, Frontier gives you both the freedom and the framework to bring your ideas to life. **EVE Frontier is open, collaborative, and powered by the creativity of its builders.** Together, we can define what it truly means to build in the EVE universe. To start building refer [Modding](https://docs.evefrontier.com/smart-assemblies/introduction) [NextSmart Infrastructurechevron-right](https://docs.evefrontier.com/welcome/smart-infrastructure) Last updated 4 days ago --- # Introduction to Smart Contracts | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close [hashtag](https://docs.evefrontier.com/smart-contracts#what-are-smart-contracts) What are Smart Contracts? --------------------------------------------------------------------------------------------------------------- Smart contracts are programs that execute on the blockchain. They enforce persistent rules, manage assets, automate actions, and run shared logic in a secure, deterministic, and verifiable way. In EVE Frontier, smart contracts are the foundation for Smart Assembly functionality and on-chain business logic. Contracts are written in [Movearrow-up-right](https://docs.sui.io/concepts/sui-move-concepts) and deployed to [Suiarrow-up-right](https://sui.io/) . Sui validators compile and verify Move modules, execute transactions on the Move VM, and persist the resulting state on-chain. This ensures that all business logic runs deterministically and that any participant can verify correctness. [hashtag](https://docs.evefrontier.com/smart-contracts#next-steps) Next Steps ---------------------------------------------------------------------------------- * [Move Documentationarrow-up-right](https://move-book.com/concepts/) — Move concepts. * [Move Patterns in Frontier](https://docs.evefrontier.com/smart-contracts/move-patterns-in-frontier) — Key Move patterns used in the world contracts. * [EVE Frontier World Explainer](https://docs.evefrontier.com/smart-contracts/eve-frontier-world-explainer) — Overview of the world architecture. * [World Contractsarrow-up-right](https://github.com/evefrontier/world-contracts) — Source code and examples. [PreviousEnvironment Setupchevron-left](https://docs.evefrontier.com/quickstart/environment-setup) [NextEVE Frontier World Explainerchevron-right](https://docs.evefrontier.com/smart-contracts/eve-frontier-world-explainer) Last updated 4 days ago --- # Environment Setup | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close To start building on EVE Frontier, follow the steps below to set up your local development tools. If you already have the tools, make sure they are the correct version to avoid difficulties building. [hashtag](https://docs.evefrontier.com/quickstart#community-tool-efctl-one-command-setup) Community tool: efctl (one-command setup) ---------------------------------------------------------------------------------------------------------------------------------------- The community CLI [**efctl**arrow-up-right](https://frontier.scetrov.live/links/efctl/) automates the full local setup. * * * [hashtag](https://docs.evefrontier.com/quickstart#recommended-docker-any-os) Recommended: Docker (any OS) -------------------------------------------------------------------------------------------------------------- The fastest way to get a Sui local development environment is with Docker. This works on Windows, Linux, and macOS with a single prerequisite. **Prerequisite:** [Dockerarrow-up-right](https://docs.docker.com/get-docker/) installed and running. Use the EVE Frontier builder-scaffold localnet setup: 1. Clone the builder-scaffold repo and navigate to the Docker setup: Copy mkdir -p workspace && cd workspace git clone https://github.com/evefrontier/builder-scaffold.git cd builder-scaffold/docker 1. Follow the instructions in the [localnet-setup/dockerarrow-up-right](https://github.com/evefrontier/builder-scaffold/blob/main/docker/readme.md) directory. This gives you a pre-configured Sui localnet and development environment without installing Sui CLI, WSL, or platform-specific tools. * * * [hashtag](https://docs.evefrontier.com/quickstart#manual-setup-by-os) Manual setup by OS --------------------------------------------------------------------------------------------- If you prefer to install tools directly on your system, follow the steps for your OS below. Windows Linux macOS This guide is for **Windows** users. [suiuparrow-up-right](https://github.com/MystenLabs/suiup) is a native Windows executable. Run commands in PowerShell, Command Prompt, or **Git Bash** (recommended if you prefer using the bash install script). ### [hashtag](https://docs.evefrontier.com/quickstart#step-1-install-git) Step 1: Install Git Install [Git for Windowsarrow-up-right](https://git-scm.com/download/win) if you haven't already. Git Bash (included with the install) lets you run the suiup bash install script directly without needing to download the binary manually: Copy curl -sSfL https://raw.githubusercontent.com/MystenLabs/suiup/main/install.sh | sh Then continue from Step 3 below. If you prefer the manual binary install, follow Steps 2–3 instead. ### [hashtag](https://docs.evefrontier.com/quickstart#step-2-install-suiup) Step 2: Install suiup suiup is the recommended way to install and manage Sui CLI. It is a cross-compiled native executable for Windows. 1. **Download** the latest Windows release from [suiup releasesarrow-up-right](https://github.com/MystenLabs/suiup/releases) . Choose the archive for Windows x86\_64 (e.g. `suiup-vX.X.X-windows-x86_64.zip`). 2. **Unzip** the archive. You'll get a folder containing the `suiup.exe` executable. 3. **Add suiup to your PATH** — choose one: **Option A — Use a dedicated bin folder (recommended)** * Create `%LOCALAPPDATA%\bin` if it doesn't exist (on most systems this is `C:\Users\\AppData\Local\bin`). * Move `suiup.exe` into that folder. * Add this folder to your user PATH in Environment Variables: **Option B — Use the extracted folder** * Leave `suiup.exe` in the folder where you unzipped it. * Add that folder to your user PATH using the same steps as Option A (Environment Variables → Path → New). 4. **Restart** your terminal (PowerShell or Command Prompt) so the updated PATH is picked up. Test with `suiup --version`. ### [hashtag](https://docs.evefrontier.com/quickstart#step-3-install-sui-cli) Step 3: Install Sui CLI Copy suiup install sui@testnet Verify: Copy sui --version suiup installs binaries to `%LOCALAPPDATA%\bin`. Ensure this folder is on your `PATH`. ### [hashtag](https://docs.evefrontier.com/quickstart#step-4-optional-node.js-and-pnpm) Step 4 (Optional): Node.js and PNPM For interaction using the TypeScript SDK, install [Node.jsarrow-up-right](https://nodejs.org/) (LTS) and then: Copy npm install -g pnpm This guide is for **Linux** users. Supported: Ubuntu 22.04 or newer. ### [hashtag](https://docs.evefrontier.com/quickstart#step-1-install-git-1) Step 1: Install Git Copy sudo apt-get install git curl ### [hashtag](https://docs.evefrontier.com/quickstart#step-2-install-sui-cli-via-suiup) Step 2: Install Sui CLI via suiup [suiuparrow-up-right](https://github.com/MystenLabs/suiup) is the recommended installer for Sui. Copy curl -sSfL https://raw.githubusercontent.com/MystenLabs/suiup/main/install.sh | sh Restart your shell, then install Sui for testnet: Copy suiup install sui@testnet Verify: Copy sui --version ### [hashtag](https://docs.evefrontier.com/quickstart#step-3-optional-node.js-and-pnpm) Step 3 (Optional): Node.js and PNPM For interaction using typescript sdk: Copy curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash && . ~/.bashrc && nvm install 24 npm install -g pnpm This guide is for **macOS** users. Supported: macOS Tahoe or newer. ### [hashtag](https://docs.evefrontier.com/quickstart#step-1-install-homebrew-if-needed) Step 1: Install Homebrew (if needed) Copy /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" Add brew to your path: Copy export PATH="/opt/homebrew/bin:$PATH" ### [hashtag](https://docs.evefrontier.com/quickstart#step-2-install-git) Step 2: Install Git Copy brew install git ### [hashtag](https://docs.evefrontier.com/quickstart#step-3-install-sui-cli-1) Step 3: Install Sui CLI **Option A — suiup (recommended):** Copy curl -sSfL https://raw.githubusercontent.com/MystenLabs/suiup/main/install.sh | sh Restart your shell, then: Copy suiup install sui@testnet **Option B — Homebrew:** Copy brew install sui Verify: Copy sui --version ### [hashtag](https://docs.evefrontier.com/quickstart#step-4-optional-node.js-and-pnpm-1) Step 4 (Optional): Node.js and PNPM For interaction using typescript sdk: Copy brew install node@24 npm install -g pnpm [hashtag](https://docs.evefrontier.com/quickstart#configure-sui-client) Configure Sui Client ------------------------------------------------------------------------------------------------- Installing Sui does not configure the client. To use `sui` commands: 1. [Configure the Sui clientarrow-up-right](https://docs.sui.io/guides/developer/getting-started/configure-sui-client) to create an address and connect to a network. 2. [Get SUI from the faucetarrow-up-right](https://docs.sui.io/guides/developer/getting-started/get-coins) for testnet. [hashtag](https://docs.evefrontier.com/quickstart#next-steps) Next Steps ----------------------------------------------------------------------------- You are ready to build on EVE Frontier. If you learn by doing, head to [Smart Assemblies](https://docs.evefrontier.com/smart-assemblies/storage-unit) . To understand concepts first, see [Introduction to Smart Contracts](https://docs.evefrontier.com/smart-contracts/introduction-to-smart-contracts) . [PreviousSui & Move Fundamentalschevron-left](https://docs.evefrontier.com/welcome/sui-and-move-fundamentals) [NextIntroduction to Smart Contractschevron-right](https://docs.evefrontier.com/smart-contracts/introduction-to-smart-contracts) Last updated 4 days ago --- # Introduction to Modding Smart Assemblies | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close Some EVE Frontier smart assemblies are **programmable** — you can customize their in-game behavior by deploying custom Move contracts. [hashtag](https://docs.evefrontier.com/smart-assemblies#getting-started) Getting Started --------------------------------------------------------------------------------------------- Prerequisites to customize a smart assembly: 1. **Create a Character** — your on-chain identity that owns all your assemblies. See [Smart Character](https://docs.evefrontier.com/smart-assemblies/smart-character) . 2. **Build a Network Node** — anchor a network node at a Lagrange point. This is the power source for your base. See [Network Node](https://docs.evefrontier.com/smart-assemblies/network-node) . 3. **Deposit Fuel & Go Online** — deposit fuel into the network node and bring it online to start generating energy. 4. **Anchor a Smart Assembly** — create a smart assembly (e.g., Storage Unit, Gate) in your base. It automatically connects to the network node for energy. 5. **Bring the Assembly Online** — the assembly reserves energy from the network node and becomes operational. > For local development and testing, refer to [builder-scaffoldarrow-up-right](https://github.com/evefrontier/builder-scaffold) > so you have everything you need to directly write custom logic for your smart assembly. > For a one-command automated setup, see the community tool [efctlarrow-up-right](https://frontier.scetrov.live/links/efctl/) > ([docs](https://docs.evefrontier.com/tools/efctl) > ). [hashtag](https://docs.evefrontier.com/smart-assemblies#programmable-assemblies) Programmable Assemblies ------------------------------------------------------------------------------------------------------------- Each assembly type has its own extension pattern. Each section has a **concept overview** (how the assembly works and its API) and a **build guide** (step-by-step instructions to write, publish, and test a custom extension): * [Smart Gate](https://docs.evefrontier.com/smart-assemblies/gate) — custom rules for space travel (e.g., toll gates, access lists) · [Build](https://docs.evefrontier.com/smart-assemblies/gate/build) * [Smart Storage Unit](https://docs.evefrontier.com/smart-assemblies/storage-unit) — custom rules for item deposits and withdrawals (e.g., vending machines, trade hubs) · [Build](https://docs.evefrontier.com/smart-assemblies/storage-unit/build) * [Smart Turret](https://docs.evefrontier.com/smart-assemblies/turret) — custom targeting logic · [Build](https://docs.evefrontier.com/smart-assemblies/turret/build) To read and write world state from code (SDK, GraphQL, gRPC), see [Interfacing with the EVE Frontier World](https://docs.evefrontier.com/tools/interfacing-with-the-eve-frontier-world) . [PreviousMove Patterns in Frontierchevron-left](https://docs.evefrontier.com/smart-contracts/move-patterns-in-frontier) [NextSmart Characterchevron-right](https://docs.evefrontier.com/smart-assemblies/smart-character) Last updated 4 days ago --- # dApps Quick Start | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close [PreviousBuildchevron-left](https://docs.evefrontier.com/smart-assemblies/gate/build) [NextConnecting from an External Browserchevron-right](https://docs.evefrontier.com/dapps/connecting-from-an-external-browser) Last updated 22 hours ago --- # Wallets & Identity | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close [hashtag](https://docs.evefrontier.com/eve-vault#introduction) Introduction -------------------------------------------------------------------------------- Getting started in EVE Frontier begins with securing your wallet and establishing your in-game identity. With the move to Sui, the foundation for your presence, assets, and interactions—inside the game and across third-party dApps—is built around the EVE Vault wallet and browser extension. * * * [hashtag](https://docs.evefrontier.com/eve-vault#eve-vault-your-wallet-and-identity) EVE Vault: Your Wallet and Identity ----------------------------------------------------------------------------------------------------------------------------- **EVE Vault** is the official wallet and inventory manager for all EVE Frontier experiences on Sui. It's available as a web app and as a Chrome browser extension. EVE Vault does more than hold your tokens and assets—it serves as your digital passport, letting you connect securely to both the main game and the wider EVE Frontier dApp ecosystem. * **Wallet:** Secure storage for your Sui-based assets—including currencies, NFTs, and game items. * **Identity:** The EVE Vault extension functions as your authentication hub for dApps, making it easy (and private) to prove who you are without exposing sensitive keys or details. * **Single Sign-On:** Once the extension is installed and authenticated, connecting to dApps or new services is as simple as approving the prompt—no extra accounts or passwords needed. * * * [hashtag](https://docs.evefrontier.com/eve-vault#seamless-onboarding-with-zklogin) Seamless Onboarding with zkLogin ------------------------------------------------------------------------------------------------------------------------ EVE Vault leverages **zkLogin**—a zero-knowledge login protocol native to Sui—to give you effortless, privacy-preserving authentication: * **No Seed Phrases Needed:** Create your EVE Vault wallet using your EVE Frontier SSO account. * **Zero-Knowledge Proof:** zkLogin lets you prove ownership of your account to dApps and the EVE Vault, without the OAuth provider or anyone else learning your blockchain address or secrets. * **Fast & Private:** You get a secure Sui wallet, instantly ready for game and dApp use, with complete privacy and full control. * * * [hashtag](https://docs.evefrontier.com/eve-vault#your-identity-inside-and-outside-the-client) Your Identity Inside and Outside the Client ---------------------------------------------------------------------------------------------------------------------------------------------- * **In-Game:** Log in with EVE Vault to link your character, assets, and progression on-chain. Tokens, and other on chain property are visible and accessible through the wallet. * **Out-of-Game dApps:** The EVE Vault extension allows you to authenticate and interact with external EVE Frontier dApps, marketplaces, community tools, and integrations. Each connection is permissioned, using your wallet as the anchor of your identity, never re-using or exposing your login elsewhere. * * * [hashtag](https://docs.evefrontier.com/eve-vault#high-level-flow) High-Level Flow -------------------------------------------------------------------------------------- 1. **Install EVE Vault extension** from [evefrontier/evevault/releases/downloadarrow-up-right](https://github.com/evefrontier/evevault/releases/download/v0.0.2/eve-vault-chrome.zip) 2. **Create your wallet** with a single sign on login — no secret phrases or manual backups. 3. **Authorize dApps** and the EVE Frontier game client to interact with your wallet and identity as needed. 4. **Transact, play, and participate** using EVE Vault as your only identity, both in and out of game. * * * [hashtag](https://docs.evefrontier.com/eve-vault#summary) Summary ---------------------------------------------------------------------- * **EVE Vault** is your one wallet and identity for EVE Frontier on Sui. * **zkLogin** provides secure, private onboarding—no seed phrase required. * The **browser extension** acts as your decentralized ID for all dApps and integrations. * Your assets, character, and reputation travel with you, wherever you explore in the EVE Frontier ecosystem. * * * [PreviousConnecting In-Gamechevron-left](https://docs.evefrontier.com/dapps/connecting-in-game) [NextIntroduction to EVE Vaultchevron-right](https://docs.evefrontier.com/eve-vault/introduction-to-eve-vault) Last updated 21 days ago --- # Builder | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close Below are some of the common gotchas during building [PreviousDebugging Toolschevron-left](https://docs.evefrontier.com/tools/debugging) [NextPlayerchevron-right](https://docs.evefrontier.com/troubleshooting/player) Last updated 4 days ago --- # Interfacing with the EVE Frontier World | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close [hashtag](https://docs.evefrontier.com/tools#overview) Overview -------------------------------------------------------------------- You interact with the EVE Frontier world in two ways: * **Write path** — Submit transactions to Move public functions to mutate on-chain state (create assemblies, bring them online, deposit items, etc.). * **Read path** — Query on-chain state and events via [GraphQLarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/query-with-graphql) , [gRPCarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/grpc-overview) , or custom indexers. * * * [hashtag](https://docs.evefrontier.com/tools#writing-to-the-world-contracts) Writing to the World Contracts ---------------------------------------------------------------------------------------------------------------- Write operations use the [Sui TypeScript SDKarrow-up-right](https://sdk.mystenlabs.com/typescript) to build and submit transactions. The [world-contracts ts-scriptsarrow-up-right](https://github.com/evefrontier/world-contracts/tree/main/ts-scripts) provide examples on how to interact with the EVE Frontier world. You can also use other SDKs (e.g., [Rustarrow-up-right](https://docs.sui.io/references/rust-sdk) or [community Go SDKarrow-up-right](https://docs.sui.io/references/sui-sdks) ) based on your tech stack. ### [hashtag](https://docs.evefrontier.com/tools#example-bring-assembly-online) Example: Bring Assembly Online This script borrows `OwnerCap` from a character, calls the assembly `online` function, then returns the cap: Copy import { Transaction } from "@mysten/sui/transactions"; // 1. Borrow OwnerCap from character const [ownerCap] = tx.moveCall({ target: `${config.packageId}::character::borrow_owner_cap`, typeArguments: [`${config.packageId}::assembly::Assembly`], arguments: [tx.object(characterId), tx.object(ownerCapId)], }); // 2. Bring assembly online tx.moveCall({ target: `${config.packageId}::assembly::online`, arguments: [\ tx.object(assemblyId),\ tx.object(networkNodeId),\ tx.object(config.energyConfig),\ ownerCap,\ ], }); // 3. Return OwnerCap to character tx.moveCall({ target: `${config.packageId}::character::return_owner_cap`, typeArguments: [`${config.packageId}::assembly::Assembly`], arguments: [tx.object(characterId), ownerCap], }); See [ts-scripts/assembly/online.tsarrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/ts-scripts/assembly/online.ts) for the full script. ### [hashtag](https://docs.evefrontier.com/tools#example-sponsored-transactions) Example: Sponsored Transactions Many world operations require server-side validation (e.g., proximity checks, sponsor checks). These use **sponsored transactions** — the player signs the intent, and an authorized sponsor (e.g., EVE Frontier) pays gas and submits: Copy tx.setSender(playerAddress); tx.setGasOwner(adminAddress); // Sponsor pays gas // ... moveCall to game_item_to_chain_inventory, etc. const result = await executeSponsoredTransaction( tx, client, playerKeypair, adminKeypair, playerAddress, adminAddress, { showEvents: true } ); See [ts-scripts/storage-unit/deposit-to-ephemeral-inventory.tsarrow-up-right](https://github.com/evefrontier/world-contracts/blob/main/ts-scripts/storage-unit/deposit-to-ephemeral-inventory.ts) for a full example. * * * [hashtag](https://docs.evefrontier.com/tools#reading-from-the-world-contracts) Reading from the World Contracts -------------------------------------------------------------------------------------------------------------------- **SuiClient** is the main entry point for read operations in the [TypeScript SDKarrow-up-right](https://sdk.mystenlabs.com/typescript) . It connects to a Sui full node and exposes methods for querying objects, events, and transactions without submitting any transaction. Use it when you need to read state programmatically — for example, fetching an assembly's current config or checking ownership before building a transaction. ### [hashtag](https://docs.evefrontier.com/tools#graphql) GraphQL Use Sui's [GraphQLarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/query-with-graphql) to query objects by type, owner, or filters. **Example: Get objects by type** Copy query GetObjectsByType($type: String!, $first: Int) { objects(filter: { type: $type }, first: $first) { pageInfo { hasNextPage endCursor } nodes { address asMoveObject { contents { json } } } } } Try it: [GraphQL Testnet IDEarrow-up-right](https://graphql.testnet.sui.io/graphql) . Pass variables in the IDE's Variables panel, e.g.: Copy { "type": "0x2ff3e06b96eb830bdcffbc6cae9b8fe43f005c3b94cef05d9ec23057df16f107::network_node::NetworkNode", "first": 10 } ### [hashtag](https://docs.evefrontier.com/tools#query-character-by-wallet-address) Query character by wallet address A [PlayerProfilearrow-up-right](https://github.com/evefrontier/world-contracts/blob/8edd7e441daec68afab0558e80574efd6a241ce8/contracts/world/sources/character/character.move#L50) is created at character creation and transferred to the player’s wallet (`character_address`). Query objects owned by the wallet with type `PlayerProfile` to get `character_id`, then fetch the full `Character` if needed. Use your network’s GraphQL endpoint and the world package ID for that network. Set `address` to the wallet (Sui address) and `profileType` to `0x::character::PlayerProfile` (package ID is network-specific; see your deployment or [world-contractsarrow-up-right](https://github.com/evefrontier/world-contracts) ). Copy query GetCharacterDetails($address: SuiAddress!, $profileType: String!) { address(address: $address) { objects(last: 10, filter: { type: $profileType }) { nodes { contents { ... on MoveObject { contents { type { repr } json } } } } } } } Variables: Copy { "address": "0x...", "profileType": "0x::character::PlayerProfile" } Each node’s `json` includes `character_id`. Use that ID to load the full `Character` (e.g. query `objects` by that ID). ### [hashtag](https://docs.evefrontier.com/tools#grpc) gRPC For higher throughput and streaming (e.g., checkpoints), use [gRPCarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/grpc-overview) —Sui's preferred read path. Requires a gRPC-enabled Sui full node. Copy # List objects owned by an address grpcurl -d '{ "owner": "" }' :443 sui.rpc.v2.StateService/ListOwnedObjects ### [hashtag](https://docs.evefrontier.com/tools#events) Events State changes emit events on transactions. Use [suix\_queryEventsarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/using-events) to filter by module, type, or sender: Copy curl -X POST https://fullnode.mainnet.sui.io:443 \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "suix_queryEvents", "params": [{\ "MoveEventType": "0x...::smartgate::JumpEvent"\ }, null, 10, false] }' World events include `JumpEvent` (gate traversal), inventory updates, and deployment changes. Store and subscribe to events off-chain for dashboards, analytics, or game services. * * * [hashtag](https://docs.evefrontier.com/tools#reading-from-the-world) Reading from the World ------------------------------------------------------------------------------------------------ * **TypeScript** — [SuiClientarrow-up-right](https://sdk.mystenlabs.com/typescript) for objects, events, and transactions. * **GraphQL** — [Query by type, owner, or filtersarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/query-with-graphql) ; [Testnet IDEarrow-up-right](https://graphql.testnet.sui.io/graphql) . * **gRPC** — [Higher throughput and streamingarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/grpc-overview) (requires gRPC-enabled full node). * **Events** — [suix\_queryEventsarrow-up-right](https://docs.sui.io/guides/developer/accessing-data/using-events) for Move events (e.g. gate jumps, inventory updates). [PreviousBrowser Extensionchevron-left](https://docs.evefrontier.com/eve-vault/browser-extension) [Nextefctl (community)chevron-right](https://docs.evefrontier.com/tools/efctl) Last updated 3 days ago --- # A Work In Progress | Builder Documentation [circle-info\ \ Work in Progress\ \ Important Informationchevron-right](https://docs.evefrontier.com/contributing/a-work-in-progress) close As we transition EVE Frontier to the Sui Blockchain we are also re-writing all of our documentation to reflect this change and expanding the scope of this site to better serve those new to building in EVE Frontier. This will be a gradual process and you will notice //todo's on a number of pages, these pages are still being actively worked on and will be filled out over the coming days and weeks. That's not the end however; and this new documentation site has been designed for community contribution going forward, so that together, we can build a better experience for builders at all skill levels. ![](https://docs.evefrontier.com/~gitbook/image?url=https%3A%2F%2F3422455832-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FjououNqaED1JlIqLVkpm%252Fuploads%252FbK3yWTpoaJpolr2gGMsB%252Fbanner7.png%3Falt%3Dmedia%26token%3D1ee18ee1-3e7d-42f9-b9fe-b90cbb24c472&width=768&dpr=3&quality=100&sign=9dbc7b73&sv=2) [PreviousSandbox Accesschevron-left](https://docs.evefrontier.com/troubleshooting/sandbox-access) [NextHow to Contributechevron-right](https://docs.evefrontier.com/contributing/contributing) Last updated 29 days ago This site uses cookies to deliver its service and to analyze traffic. By browsing this site, you accept the [privacy policy](https://www.ccpgames.com/privacy-policy) . close AcceptReject ---