ic-basilisk-toolkit 0.4.0

Basilisk Toolkit — Services, shell, and SFTP for IC Python canisters

ic-basilisk-toolkit

Basilisk Toolkit — A set of ready-made tools on top of Basilisk CDK for IC Python canisters.

Live demo: https://ic-basilisk.tech/.

Overview

Task Management	Create, schedule, and run background tasks
%task create heartbeat every 60s --code "print('alive')" %task start 1 %task info 1 %task list t = Task(name="sync") TaskStep(task=t, code="print('syncing...')") TaskSchedule(task=t, interval=60) TaskManager().run()
Wallet	ICRC-1 token registry, transfers, balance tracking
%wallet balance %wallet transfer ckBTC <principal> 1000 w = Wallet() w.register_token("ckBTC", ledger="mxzaz-...", indexer="n5wcd-...") yield from w.balance_of("ckBTC") yield from w.transfer("ckBTC", to_principal, amount=1000) yield from w.refresh("ckBTC", max_results=50) w.list_transfers("ckBTC", limit=20)
Encryption	vetKeys + per-principal envelopes + groups
%crypto encrypt "secret" %group create team1 %group add team1 <principal> cs = CryptoService(vetkey_service) yield from cs.init_scope("my-scope") cs.grant_access("my-scope", target_principal) cs.create_group("team") cs.add_member("team", principal) cs.grant_group_access("my-scope", "team") cs.revoke_access("my-scope", principal)
FX	Exchange rate queries via the IC XRC canister
%fx ICP/USD fx = FXService() fx.register_pair("ICP", "USD") yield from fx.refresh() # fetch latest rates from XRC canister fx.get_rate("ICP", "USD") # cached float fx.get_rate_info("ICP", "USD") # full info with staleness metadata
Entities	Persistent ORM via ic-python-db
%db types %db list User 10 %db show User 1 %db search User name=alice %db export User backup.json %db import backup.json u = User(name="alice") # auto-persisted on creation u.name = "bob" # changes save automatically bob = User['bob'] bob.friends
Schema Upgrades	Pre-deploy schema diff, migration safety, read-only data browsing
basilisk check-upgrade --canister my_app --network ic See documentation.
Logging	Structured logging via ic-python-logging
from ic_python_logging import get_logger logger = get_logger("my_module") logger.info("processing") logger.error("failed", exc_info=True)
HTTP Fetch	Download a URL into the canister filesystem
%wget https://example.com/data.json /data.json yield from wget("https://example.com/data.json", "/data.json") run("/data.json") # execute a downloaded Python script
File Transfer	Move files between local machine and canister
%put local_script.py /app/script.py %get /app/output.json result.json
Interactive Shell	REPL for live canister interaction
basilisk-toolkit shell --canister my_app --network ic basilisk-toolkit exec --canister my_app 'print(ic.time())'
SFTP	Browse and edit canister filesystem over SSH
basilisk-toolkit sshd --canister my_app --network ic sftp -P 2222 localhost ssh -p 2222 localhost

Type :help inside the shell for full command reference, or see the tip_jar template for a working example project.

Templates

Full-stack example canisters, each deployable as-is:

• Tip Jar — crypto donations in ckBTC / ckETH / ckUSDC / ICP with live exchange rates, encrypted messages, donor leaderboard. Live.
• File Registry — general-purpose on-chain file storage with HTTP serving, CORS, chunked upload for large WASMs, and per-namespace ACLs. Live.

Website

website/ is the static landing page at ic-basilisk.tech — it introduces basilisk and this toolkit and links out to the live template demos. Pure assets canister, no backend.

Installation

pip install ic-basilisk-toolkit

For shell/SFTP support (requires asyncssh):

pip install ic-basilisk-toolkit[shell]

CLI Usage

basilisk-toolkit exec 'print("hello")'                    # Execute code on canister
basilisk-toolkit shell --canister my_app --network ic      # Interactive shell
basilisk-toolkit sshd --canister my_app --network ic       # SSH/SFTP server

Schema Upgrade Checking & Data Browsing

See docs/SCHEMA_UPGRADE_CHECKING.md for the full guide on pre-deploy schema diffing, step-by-step migration examples, verbose mode, on-chain enforcement, and the read-only __browse__ query API.

Security note: The sshd command starts a local development proxy that accepts any password. It is intended for local use only — do not expose it on a public network without adding proper authentication.

Dependencies

• ic-basilisk — CDK (types, decorators, ic.* API)
• ic-python-db — Persistent entity ORM
• ic-python-logging — Structured logging

Disclaimer

This software is in alpha and may have unknown security vulnerabilities. It has not undergone an independent security audit. Use at your own risk — see the Basilisk disclaimer for details.

License

MIT — see LICENSE.