Ic-py Development and Ongoing Maintenance

[C-B-Elite]

Release Announcement: icp-py-core v1.0.0 — First Stable Version

Release Date: 2025-10-20
Author: Elie Zhao

icp-py-core is a modernized and actively maintained fork of ic-py, fully compatible with Internet Computer Boundary Node v3 endpoints and offering a more developer-friendly Python Agent API.

---

Overview

This is the first stable release (v1.0.0) of icp-py-core.
It introduces a modular architecture, improved reliability, optional BLS certificate verification, and full API parity with the Rust/TypeScript IC Agents.

Highlights:

• Modular architecture (src/ with separate subpackages: agent / identity / candid / principal / certificate)
• Unified import entrypoint icp_core
• Updated BN v3 endpoint /api/v3/canister/.../call
• New Agent.update() and Agent.query() with auto Candid encoding
• Optional certificate verification via blst (recommended for production)

---

Installation

pip install icp-py-core

Requires Python 3.9+.
To enable certificate verification, follow the blst installation guide in the README.

---

Quick Start Example

from icp_core import Agent, Client, Identity, Types

iden = Identity()  # or from private key: Identity(privkey="hex...")
client = Client("https://ic0.app")
agent = Agent(iden, client)

# Update: auto Candid encoding for non-bytes arguments
agent.update("wcrzb-2qaaa-aaaap-qhpgq-cai", "set", [{'type': Types.Nat, 'value': 2}],
             verify_certificate=True)

# Query: auto-encodes empty args when None or []
res = agent.query("wcrzb-2qaaa-aaaap-qhpgq-cai", "get", None, return_type=[Types.Nat])
print(res)

Setting verify_certificate=True performs BLS verification on the response — recommended for production.

---

Key Improvements

1) Modular Architecture

src/
├── icp_agent/         # Agent & HTTP client
├── icp_identity/      # Identity (ed25519, secp256k1)
├── icp_candid/        # Candid encoder/decoder & parser
├── icp_principal/     # Principal utilities (strict DER mode)
├── icp_certificate/   # Certificate verification (BLS12-381)
├── icp_core/          # Unified import facade

2) Unified Facade: icp_core

from icp_core import Agent, Client, Identity, Principal, Certificate, encode, decode, Types

3) Agent API Modernization

• New Agent.update() and Agent.query() methods (aligned with Rust/TS IC Agents)
• Automatic Candid encoding (non-bytes args auto-encoded, bytes passed through directly)

4) Enhanced Identity Management

• Unified support for Ed25519 and Secp256k1
• Added SLIP-10 deterministic derivation (replacing legacy derivation)
• Improved PEM/DER handling and added comprehensive tests

5) Strict Principal Validation

• Principal.self_authenticating() now accepts only DER format for stronger compliance and security

6) Improved Polling and Error Handling

• Added exponential backoff with configurable delay, max interval, and timeout
• poll() and poll_and_wait() now mirror Rust Agent semantics
• Enhanced error messages and handling for malformed or partial responses

7) Candid Parser Fixes

• Pinned antlr4-python3-runtime==4.9.3 to resolve ATN version mismatch
• Updated parser imports for compatibility

8) Packaging Modernization

• Adopted PEP 621-compliant pyproject.toml (replacing setup.py)
• Clean MANIFEST.in (excludes .venv-test, tests, .git)
• Runtime deps: httpx, cbor2, leb128, ecdsa, PyNaCl
• Optional dependency: blst (for certificate verification)

---

Migration from ic-py

• Unified entrypoint:
  from icp_core import Agent, Client, Identity, encode, decode, Types, Principal, Certificate
• Subpackage imports also supported: icp_agent, icp_identity, icp_candid, icp_principal, icp_certificate
• update() and query() now automatically Candid-encode arguments (no manual encode() required)

See MIGRATION.md in the repository for detailed mapping.

---

Stability and Security

• Certificate verification is optional but strongly recommended for production use (verify_certificate=True)
• Verification uses the BLS12-381 cryptographic scheme via blst bindings

---

Roadmap

Completed:

• Milestone 1 — v3 Endpoint Migration & Polling Stability
• Milestone 2 — BLS Certificate Verification

Next Steps:

• Candid type-system enhancements
• Dynamic routing between boundary nodes
• ICRC helpers and token canister wrappers

Full roadmap available in ROADMAP.md.

---

Links

• PyPI: https://pypi.org/project/icp-py-core/
• Release (v1.0.0): https://github.com/eliezhao/icp-py-core/releases/tag/v1.0.0
• GitHub: https://github.com/eliezhao/icp-py-core

---

Acknowledgments

Thanks to the DFINITY community, original ic-py contributors, and everyone supporting this ongoing project.
icp-py-core aims to provide a modern, secure, and Pythonic SDK for the Internet Computer.

Feedback, issues, and PRs are warmly welcome!