How r-near/nearc works
Main Components Identification
• Compiler CLI Interface – represented by the cli.py module. This is the primary entrypoint for users running NEARC from the command line.
• Code Analyzer – modules such as analyzer.py and utils.py manage the detection of exported functions (via decorators like @near.export), dependency detection, and the analysis of Python code.
• Manifest and Metadata Management – the manifest.py, metadata.py, and exports.py files handle the generation of a MicroPython manifest (containing module and dependency details) and inject NEP-330 compliant metadata.
• Code Builder and WebAssembly Compiler – the builder.py module (which leverages a customized version of MicroPython located in src/nearc/micropython) coordinates the creation of C wrappers, integration with Emscripten, and optimization to produce a final WebAssembly (WASM) file.
• Reproducible Build Support – reproducible.py (and the related reproducible-builds.md document) along with Dockerfile and Git actions ensure that builds can be recreated exactly for contract verification.
• External Integrations – include integration with uv (Python package management), Docker (for reproducible builds), and Emscripten (the WASM compiler driver).
Architectural Relationships and Data Flow
• User invokes the CLI (cli.py) which parses command-line options and identifies the contract entrypoint (using auto-detection rules such as looking for __init__.py or main.py).
• The CLI module then calls the Analyzer component to scan code for decorators and dependencies.
• The Manifest Generator (manifest.py) collects module information, while the Metadata Generator (metadata.py) prepares and injects NEP-330 compliant metadata based on project configurations (including potentially reading pyproject.toml).
• The Builder (builder.py) receives the processed abstract representation and, working with the integrated MicroPython runtime, generates C wrappers and triggers Emscripten to compile to WASM.
• If reproducible builds are requested, the process enters a Docker-centered build environment (as configured in Dockerfile, reproducible.py, and via Docker-based GitHub workflows) to ensure deterministic builds and subsequent verification.
• Finally, outputs such as the final WASM file and metadata information are generated and returned.
Important Architectural Patterns and Principles
• Modular Design – each stage of compilation (analysis, manifest creation, metadata injection, building) is separated into its own module.
• Decorator-Driven Functionality – the use of decorators (ex: @near.export) is central to exporting functions, which is a distinctive pattern in this design.
• Reproducible and Deterministic Builds – architectural emphasis on build reproducibility is supported via Docker configurations and Git integration.
• Integration with External Tools – such as Emscripten for WebAssembly compilation and uv for dependency management reflects a hybrid on-premise/CI workflow approach.
Technologies, Frameworks, and Tools
• Python (with MicroPython subset) is the language of choice.
• Emscripten serves as the WebAssembly compilation tool.
• Docker is used to guarantee reproducible builds.
• Git and uv are used for source control and package management respectively.
• GitHub Actions and associated workflow configurations (.github/workflows) streamline CI/CD and testing.
Detailing the Essential Architectural Elements
• Sequential processing: from code analysis (detecting functions and dependencies) to generating manifests and metadata, and then moving to the build/output stage.
• Incorporate annotations or notes that mention the NEP-330 metadata injection and the fact that all stateful changes (via decorators and the manifest) lead to the final WASM bytecode.
• Configuration dependencies (reproducible build settings and Docker image verification in the metadata).