✨ Components & Systems Bundle

[notdanilo]

Status	Type	⚠️ Core Change	Issue
Hold	Feature	Yes	#65

Problem

Deployment cost of projects with several components and systems programs might get too high. We want to allow developers to bundle systems and components in a single program to reduce deployment costs.

Solution

Introduce the #[bundle] to allow to ship several #[component]s and #[system]s in a single program.

To implement this, we need to add discriminators for components and systems in the program.

The biggest API change is in the delegation instruction, because now we need to send the seeds as a parameter.

Greptile Overview

Updated On: 2025-10-06 07:08:22 UTC

Summary

This PR introduces a major architectural feature called "bundling" that allows developers to combine multiple `#[component]`s and `#[system]`s into a single Solana program, addressing the high deployment costs of approximately 1.7 SOL per component/system. The solution adds a new `#[bundle]` procedural macro that generates unified programs with discriminator-based routing to distinguish between different components and systems within the same program.

The implementation involves significant changes across the entire codebase:

Core Architecture Changes:

• Removes standalone bolt-component and bolt-system programs, replacing them with bundle functionality
• Introduces discriminator-based operation routing using SHA-256 hashes of method names (e.g., "global:initialize", "global:update")
• Refactors the world program to use manual CPI calls instead of high-level Anchor calls to support discriminator parameters
• Centralizes attribute processing logic into a shared bolt-attribute crate to enable code reuse between standalone and bundled deployments

Bundle Implementation:

• The #[bundle] macro processes modules containing mixed component structs and system modules
• Components within bundles use component names as PDA seed prefixes to ensure unique addressing
• Systems within bundles get renamed with suffixes to avoid naming collisions
• Generated programs include wrapper functions that handle discriminator routing to the correct component/system logic

Client Integration:

• All client libraries (TypeScript, C#) updated to support discriminator parameters in API calls
• New Component and System classes provide abstractions for working with both standalone and bundled entities
• GetDiscriminator functions implement Anchor's standard SHA-256-based discriminator generation

Development Workflow:

• New CLI command bolt bundle <name> creates bundle templates in programs-ecs/bundles/
• Bundle templates demonstrate combining Position/Velocity components with movement/stop systems
• Updated workspace configuration to include bundle directories and dependencies

The bundling feature maintains backward compatibility with existing standalone components and systems while providing a cost-effective deployment option for projects with multiple ECS entities. The architecture enables the same component and system logic to work in both contexts through shared instruction modules and unified API interfaces.

Sequence Diagram

sequenceDiagram
    participant User
    participant BoltCLI
    participant BundleTemplate
    participant BundleAttribute
    participant ComponentGen
    participant SystemGen
    participant AnchorProgram
    
    User->>BoltCLI: "bolt bundle example-bundle"
    BoltCLI->>BundleTemplate: "create_bundle_template()"
    BundleTemplate->>BundleTemplate: "generate bundle lib.rs with #[bundle]"
    BundleTemplate-->>BoltCLI: "bundle files created"
    
    User->>AnchorProgram: "anchor build"
    AnchorProgram->>BundleAttribute: "process(#[bundle] mod)"
    BundleAttribute->>BundleAttribute: "parse bundle module content"
    
    loop "for each item in bundle"
        alt "item is #[component] struct"
            BundleAttribute->>ComponentGen: "generate_implementation()"
            ComponentGen->>ComponentGen: "generate initialize/update/destroy functions"
            ComponentGen->>ComponentGen: "add component name as PDA seed suffix"
            ComponentGen-->>BundleAttribute: "component instructions generated"
        else "item is #[system] mod"
            BundleAttribute->>SystemGen: "transform_module_for_bundle()"
            SystemGen->>SystemGen: "rename Components to {name}Components"
            SystemGen->>SystemGen: "generate {name}_bolt_execute wrapper"
            SystemGen-->>BundleAttribute: "system instructions generated"
        end
    end
    
    BundleAttribute->>BundleAttribute: "wrap everything in #[program] module"
    BundleAttribute-->>AnchorProgram: "unified program module"
    
    User->>User: "deploy bundle as single program"
    
    Note over User,AnchorProgram: Bundle allows multiple components/systems<br/>in one program to reduce deployment costs

Loading

Summary by CodeRabbit

• New Features

  • Bundle support to combine components and systems into unified programs
  • New ECS domain objects and APIs: Component and System (C# & TypeScript)
  • CLI command, project template, and example bundle to scaffold bundles

• Improvements

  • Modernized ApplySystem/transaction flows with discriminator and session variants
  • Client tests updated to exercise bundled components and use standard commitment flow
  • CI/workflows publish keys updated to include example bundle deployment keypair