How ton-org/blueprint works
Project Type & Purpose
• This project is a developer tool designed to streamline the process of creating, compiling, testing, and deploying TON blockchain smart contracts written in FunC, Tact, and Tolk.
• Its core functionality includes project scaffolding, compilation of contracts, running tests (using Sandbox), deploying via various wallet/deeplink integrations (e.g., TON Connect), and supporting a plugins ecosystem.
• The README emphasizes its usage as a CLI tool (invoked via commands like “npx blueprint build”) that manages workflows for contract development.
File Structure
• Top-Level Folders:
– The “src” directory contains the core codebase including CLI commands (src/cli), compiler configuration and processing (src/compile), configuration handling (src/config), and network integration (src/network).
– The “example” folder mirrors a typical project structure for a user-created project, with directories for contracts, compilables, tests, wrappers, and scripts.
– The “src/templates” directory holds a variety of contract templates (for different languages: func, tact, tolk) which defines how new projects or contracts are scaffolded.
– Other configuration and support files (.github, package.json, tsconfig.json, etc.) are present for CI/CD and overall project configuration.
• Key Architectural Patterns:
– Separation of concerns: There is a clear modular division between CLI logic, compilation, network operations, configuration management, and templating.
– Plugin architecture: As indicated in the README and supported by its config submodules, a dynamic plugin system is in place to allow extension without modifying core code.
– Multi-language support: The project supports different smart contract languages (each with its own template and compilation path), which is clearly represented by the well-organized “src/templates” structure.
Main Components
A. CLI Interface & Command Runner:
• Location: src/cli (files like cli.ts, Runner.ts, various command modules such as build, test, run, set, etc.)
• Role: Serves as the entry point for user commands; parses inputs and orchestrates the invocation of the appropriate subsystems.
B. Compiler Subsystem:
• Location: src/compile and related virtual file system support (OverwritableVirtualFileSystem.ts).
• Role: Handles compilation of smart contracts using external compilers for FunC, Tact, and Tolk. Outputs artifacts to the build directory.
C. Configuration & Plugin Manager:
• Location: src/config (Config.ts, Plugin.ts, etc.)
• Role: Reads and applies the user’s configurations and loaded plugins (which may alter or extend features of the main application).
D. Network Provider & Deployment:
• Location: src/network including directories “send” (with providers like TonConnectProvider.ts, MnemonicProvider.ts) and “storage” (FSStorage.ts).
• Role: Manages blockchain connectivity, sending transactions, and deployment/verification processes.
E. Templating & Project Scaffolding:
• Location: src/templates, where separate directories for “func”, “tact”, “tolk”, and variants (counter, empty, legacy, etc.) are maintained.
• Role: Provides blueprints for project or contract creation, encapsulating best practices in separate, re-usable templates.
F. User Interface Layer:
• Location: src/ui (InquirerUIProvider.ts, UIProvider.ts).
• Role: Provides interactive prompts and UI support for the CLI, enhancing the developer experience.
G. Utility Modules:
• Location: src/utils.
• Role: Provide helper functions for object manipulation, selection handling, timing, and TON-specific utilities.
Relationships & Data Flow
• The CLI acts as the central orchestrator, accepting user commands and input, then calling into the Configuration Manager to load settings and plugins.
• In project scaffolding or contract creation commands, the Template Engine fetches the appropriate blueprints from the “src/templates” directory.
• Data flows from the CLI to the relevant subsystems (compiler, network, etc.), with feedback and logs returned, possibly also using the UI module for interactive commands.
Architectural Patterns & Technologies
• Command Pattern: Different CLI commands are modularized (build, run, test, etc.), each with a dedicated module.
• Plugin Architecture: The configuration system is prepared for plugins (as also shown in the README examples), allowing external community additions.
• Multi-language Compilation: By supporting FunC, Tact, and Tolk through distinct template and compiler modules, the architecture decouples language-specific concerns.
• External Dependencies: Usage of external libraries for compilation (func-js, tolk-js, tact), testing (Sandbox), and deployment (TON Connect library).