Appzone Factory
Relevant source files
The following files were used as context for generating this wiki page:
The Appzone Factory is a specialized CLI utility within the X3 Star ecosystem designed to facilitate the scaffolding, deployment, and lifecycle management of isolated application zones (App Zones). It provides a standardized pathway for developers to move from initial templates to production-ready network environments by handling boilerplate generation, configuration validation, and deployment orchestration.
As a core supporting product layer in the X3 v0.4 scope, the Appzone Factory implements a CLI-driven registry and deployment path. It integrates with the broader X3 infrastructure, including the X3 Cross-VM Router and the X3 Atomic Kernel, ensuring that App Zones adhere to the project's security and invariant requirements.
Sources: crates/x3-appzone-factory/src/lib.rs:5-10, reports/prompt-runs/latest-full.md:120-121, X3_END_TO_END_GAPS_MASTER_PLAN.md:110-112
Architecture and Components
The Appzone Factory is structured as a Rust-based CLI tool utilizing the clap crate for command parsing. The core logic resides within the AppZoneFactory struct, which manages template directories and interacts with the filesystem and external processes like git and cargo.
Command Structure
The CLI exposes five primary subcommands to handle the lifecycle of an application zone:
| Subcommand | Purpose | Parameters |
|---|---|---|
New | Scaffolds a new zone from a template. | name, template, dir |
Deploy | Builds and pushes a zone to a network. | path, network |
Templates | Lists all available zone templates. | N/A |
Validate | Checks zone configuration for errors. | path |
Update | Upgrades a zone to the latest framework. | path |
Sources: crates/x3-appzone-factory/src/lib.rs:18-53
Workflow Diagram
The following diagram illustrates the standard developer workflow when using the Appzone Factory to create and deploy a new environment.
The workflow ensures that every App Zone starts from a known-good state and passes validation before reaching the network.
Sources: crates/x3-appzone-factory/src/lib.rs:69-122
Core Logic and Implementation
Template Management
Templates are stored in a central templates directory. Each template must contain a template.toml file describing its features and metadata. The factory utilizes AppZoneFactory::copy_template_files to recursively duplicate these structures while injecting the user-provided application name into the Cargo.toml file.
Sources: crates/x3-appzone-factory/src/lib.rs:125-156, crates/x3-appzone-factory/src/lib.rs:214-239
Validation Engine
The validate_app_zone function enforces strict structural requirements. An App Zone is considered invalid if it lacks critical Substrate-compatible configuration files.
Required Files for Validation:
Cargo.toml: Must contain valid package metadata.src/lib.rs: The entry point for the zone logic.app-config.toml: General application settings.pallets.toml: Configuration for integrated pallets.
Sources: crates/x3-appzone-factory/src/lib.rs:159-195
Deployment Orchestration
Deployment involves a multi-step sequence handled by deploy_app_zone. This process transforms source code into an active network presence:
- Validation: Runs the structural check described above.
- Building: Executes
cargo build --releasein the zone directory. - Configuration Generation: Creates a
deploy-config.jsoncontaining RPC endpoints, gas limits (default: 10,000,000), and confirmation requirements (default: 12). - Execution: Connects to the target network (Local, Testnet, or Mainnet) and submits deployment transactions.
Data Structures and Configuration
The factory uses several internal and exported data structures to manage the state of the applications it handles.
Template and App Metadata
#[derive(serde::Deserialize)]
struct TemplateMetadata {
description: String,
features: Vec<String>,
}
#[derive(serde::Serialize, serde::Deserialize)]
struct DeployConfig {
network: String,
app_name: String,
pallets: Vec<String>,
rpc_endpoints: Vec<String>,
gas_limit: u64,
confirmations: u32,
}
Sources: crates/x3-appzone-factory/src/lib.rs:360-394
Network Endpoints
The factory maintains a mapping of standard RPC endpoints for the X3 ecosystem:
- Local:
http://127.0.0.1:9944 - Testnet:
wss://testnet.x3.network:443,wss://testnet.x3.network:9944 - Mainnet:
wss://rpc.x3.network:443,wss://rpc.x3.network:9944
Sources: crates/x3-appzone-factory/src/lib.rs:347-358
Integration with X3 Ecosystem
The Appzone Factory is not a standalone tool but is wired into the project's critical path as defined in the Wiring Audit. It depends on the x3-framework and specific Substrate versions (e.g., 4.0).
Runtime Dependency
As a supporting product layer, the factory's output is intended to interface with the pallet-x3-cross-vm-router to enable interoperability between App Zones and the main X3 chain. The factory specifically targets v0.4 compatibility, ensuring that newly created zones can use the latest x3-packet-standard for replay protection and timeout handling.
Sources: launch-gates/prompts/01-wiring-audit.md:49-50, reports/prompt-runs/latest-full.md:120-121, crates/x3-appzone-factory/src/lib.rs:335-342
Mainnet Readiness
According to the Mainnet Launch Checklist, components like the Appzone Factory must be verified before launch. This includes ensuring that the CLI does not fall back to mock RPCs silently and that all build artifacts are reproducible.
Sources: MAINNET_LAUNCH_CHECKLIST.md:15-20, MAINNET_LAUNCH_CHECKLIST.md:110-115
Summary
The Appzone Factory serves as the primary entry point for developers entering the X3 ecosystem. By automating the scaffolding and deployment of App Zones, it enforces structural consistency across the network while providing a robust CLI for lifecycle management. Its integration with the X3 framework ensure that all generated zones are compliant with the network's security invariants and interoperability protocols.