WASM Repository + Deployer Canister

[deucalioncodes]

Summary

Build a basilisk canister that stores versioned cpython_canister_template.wasm files on-chain and can deploy new basilisk canisters from them. This serves as a proof-of-concept for decentralized deployment before extending the pattern to Realms.

Motivation

Currently, basilisk template WASMs are distributed via GitHub releases and downloaded by build_wasm_binary_or_exit.py. Deployment requires off-chain tooling (dfx deploy). Moving the WASM storage and deployment on-chain enables:

• Decentralized deployment: Users can deploy new basilisk canisters directly from the repository canister, without needing local tooling
• Version catalog: All released versions available on-chain with metadata
• Upgrade path: Existing canisters can be upgraded to newer versions via the deployer
• Proof-of-concept: Validates the pattern before applying it to the more complex multi-canister Realms deployment (see realms#166)

Prior Art

• SNS-W (qaa6y-5yaaa-aaaaa-aaafa-cai): DFINITY's NNS canister that stores versioned SNS WASM modules and deploys new SNS DAOs. Source: dfinity/ic/rs/nns/sns-wasm
• Juno CDN: A satellite canister storing pre-built versioned WASMs for Satellites, Mission Controls, and Orbiters. The Console canister orchestrates deployment from the CDN.
• CosmWasm (Cosmos): Protocol-level store/instantiate pattern where WASM bytecode is stored once with a code_id, then instantiated many times with different configs.

Architecture

Location: basilisk/deployer/ in this repo

Language: Basilisk (Python) — dogfooding

Canister API:

Admin endpoints (controller-only)

• upload_chunk(version: str, chunk_index: int, data: bytes) — upload WASM in ≤2MB chunks (IC message limit)
• finalize_version(version: str, description: str) — mark version complete, verify integrity
• remove_version(version: str) — remove a version from the catalog

Public endpoints

• list_versions() — return version catalog with metadata (size, hash, upload date)
• get_version_info(version: str) — detailed info for a specific version
• deploy(version: str) — create a new canister + install selected WASM, return canister ID
• get_deployment_status(deployment_id: str) — check async deployment progress

Technical Details

Storage

• WASM blobs stored in stable memory via ic_python_db entities or stable structures
• Each version: metadata (version string, SHA256 hash, size, upload timestamp, description) + chunked WASM data
• Template WASM is ~5MB, well within stable memory limits

Deployment flow

1. Caller invokes deploy(version)
2. Deployer calls management_canister.create_canister() (needs cycles)
3. Deployer calls management_canister.upload_chunk() in 2MB chunks to target canister
4. Deployer calls management_canister.install_chunked_code() to install from chunks
5. Returns new canister ID to caller

Cycles management

• Deployer canister holds a cycles pool
• Each deployment deducts from pool (or caller attaches cycles)

Version upload (CI/CD)

• GHA workflow step after basilisk release: upload new template WASM to deployer canister via dfx canister call

Implementation Steps

1. Scaffold canister (dfx.json, main.py, directory structure)
2. Implement chunked WASM upload + storage entities
3. Implement version catalog (list, metadata, finalize)
4. Implement deploy — create_canister + upload_chunk + install_chunked_code
5. Add deployment status tracking
6. Add CI/CD step to upload template WASMs on release
7. Test locally + staging
8. Document usage

Future extensions

• DAO-gated version approval (replace admin-only upload)
• Extend to Realms multi-canister deployment
• User-initiated upgrades for existing canisters
• Cycles payment / credit system