Ic-py Development and Ongoing Maintenance

Developers
,
1

Background

The original ic-py development team has ceased maintenance of the project. Having maintained a close relationship with the former team—we were jointly supported by the same incubator, now disbanded—I have secured consent from the core developers and the repository owner to continue development. Special thanks to @marc0olo and @eduard-galindo for their ongoing support.

Future maintenance of ic-py will primarily be conducted in my repository. Updates will be submitted to the main repository via pull requests and subsequently released on PyPI.

Current Issues and Approach

Based on feedback gathered from GitHub issues and forum discussions, I have identified and structured existing issues into clear milestones prioritized by urgency and complexity. My immediate focus is addressing known security vulnerabilities and simpler tasks with fewer dependencies or blockers.

Related Discussions:

Roadmap & Milestones

Guiding Principles

  • Resolve all known security vulnerabilities.
  • Modernize and fully support the Candid type system.
  • Maintain alignment with agent-rs’s feature set and release schedule.

Milestone 1 :white_check_mark: Completed

  • Endpoint upgrade

    • Issue: ic-py was pointing at legacy endpoints and needed to switch to v3/v4
    • References:
    • Solution:
      1. Updated ic-py’s default endpoints to the latest BN v3/v4 addresses:
        • Query: /api/v3/canister/<canister_id>/query
        • Call: /api/v4/canister/<canister_id>/call
        • Read State: /api/v3/canister/<canister_id>/read_state
        • Read Subnet State: /api/v3/subnet/<subnet_id>/read_state
      2. Established maintenance tracking for future roadmap changes

  • Timeouts & error classification

    • Issues: Missing timeouts on agent calls; lack of fine-grained error categories for canister responses (e.g. exhausted cycles, missing WASM)
    • References: #117 • #115
    • Solution:
      1. Implemented configurable timeouts on all agent calls
      2. Introduced structured error types for common canister-level failures
      3. Created comprehensive error hierarchy with 11 error classes (ICError, TransportError, SecurityError, ReplicaReject, etc.)

Milestone 2 :white_check_mark: Completed

  • IC certificate verification
    • Issue: request_status_raw and request_status_raw_async did not verify certificates, allowing a malicious node to tamper with update responses
    • References:
    • Solution:
      1. Mirrored agent-rs’s certificate-checking logic (agent-rs implementation)
      2. Resolved Python–BLS compatibility by bridging Rust BLS crate via FFI
      3. Certificate verification enabled by default in update_raw and update_raw_async methods
      4. Certificate verification implemented in poll and poll_async methods
      5. Certificate verification enabled by default in request_status_raw and request_status_raw_async methods
      6. Support for V4 API sharded canister_ranges structure in certificate verification
      7. Enhanced certificate delegation path handling and node key caching

Milestone 3 :white_check_mark: Completed

  • Candid type-system enhancements
    • Issue: Missing support for the latest Candid features (e.g. composite queries, new primitives)
    • References:
    • Solution:
      1. Migrated from Python ANTLR4 implementation to Rust-based candid-parser crate for significant performance improvements (multiple times faster parsing speed)
      2. Implemented comprehensive DIDLoader interface with support for recursive type definitions and service interface parsing
      3. Added comprehensive test suite (test_candid_comprehensive.py, test_did_loader_comprehensive.py, test_parser.py)
      4. Full support for all Candid primitives, composite types (Record, Variant, Vec, Opt), and recursive types
      5. Fixed VarT (type reference) handling in Candid DID parser, supporting service : () -> TypeName pattern and nested type references

Milestone 4 :white_check_mark: Completed

  • Expanded API surface

    • High-level wrappers for ICP Ledger (ledger.py)
    • Complete NNS Governance interface implementation (governance.py - 1510 lines)
    • Cycles Wallet operations (cycles_wallet.py)
    • Canister Management interface (management.py)
    • Comprehensive example code library (ledger, governance, cycles_wallet, management, simple_counter examples)

  • Code optimization

    • Simplified canister.py from 1322 lines to ~112 lines (90%+ reduction)
    • Improved code structure and maintainability
    • Better error handling and dynamic method binding support

  • Additional improvements

    • HTTP/2 support enabled in all async methods (AsyncClient) for improved performance
    • Structured error handling hierarchy with 11 error classes exported from icp_core
    • Enhanced certificate verification with improved error messages and subnet-level read_state operations

Milestone 5 :white_check_mark: Completed

  • Automatically fetch the .did file from the canister

    • Issue: Currently, users must manually provide DID files when creating Canister instances
    • Solution: Implement automatic DID file retrieval from canister’s __get_candid_interface_tmp_hack method or similar mechanisms

  • High-level async API methods

    • Issue: While low-level async methods (update_raw_async, query_raw_async) exist, high-level convenience methods (update_async, query_async) are missing, making async programming less ergonomic
    • Solution:
      • Add Agent.update_async() and Agent.query_async() methods to provide async counterparts to the synchronous update() and query() methods
      • Ensure these methods support the same auto-encoding behavior and certificate verification options as their synchronous counterparts
      • Enable seamless async/await patterns for canister interactions

  • Canister async method support

    • Issue: Canister wrapper class currently generates synchronous methods only, requiring users to manually use update_raw_async or query_raw_async for async operations
    • Solution:
      • Automatically generate async method variants for all canister methods (e.g., canister.method_name_async())
      • Ensure async methods maintain the same type safety and convenience features as synchronous methods
      • Provide consistent async/await support across the entire API surface

  • Replica-signed queries

    • Issue: Query calls currently do not support replica-signed responses for enhanced security
    • Status: Query signature verification is temporarily disabled in v2.2.0 due to certificate delegation issues
    • Solution: Enable replica signature verification once certificate delegation issues are resolved

Future Release

  • Dynamic HTTP provider & routing
    • Issue: Current implementation uses fixed endpoints without adaptive routing
    • Solution:
      • Implement latency-based, adaptive routing between boundary nodes
      • Support more flexible selection of endpoints at runtime
  • High-level wrappers for ICRC-compliant ledgers (ckBTC, ckETH, ckUSDc, etc.)
  • Out-of-the-box helpers for interacting with Bitcoin, Ethereum, and other canisters

Feel free to suggest improvements or features here. Your feedback will help refine the roadmap and guide ongoing development.

Let’s collaborate to enhance icp-py-core and empower more developers to build reliable ICP applications!

2

Progress update:

I am currently working on completing Milestone 1, which involves updating the endpoints and adapting to the new version of the endpoints.

3

nice job,gogogo , can not wait

4

any update new?? good news???

5

There will be an update in about 1–2 weeks, but it won’t be released to PyPI. After that, I’ll post progress updates here once or twice a week.

6

how about a new HTTPS endpoint for making update calls · Issue #118 · rocklabs-io/ic-py · GitHub

7

this is included in Milestone 1:

8

This feature will be fixed in an upcoming update. I am currently working to complete this goal and collaborating with the community for testing.

Thank you for your attention — I will post an update here once the fix is released.

Additionally,

candid-py may be split from ic-py in the future to become a standalone repository and dependency. I am currently discussing this possibility with some friends who are interested in ic-py.

9

The development and testing for upgrading the endpoint to v3 have been completed and are consistent with expectations.

Next, I will optimize the code, and the update is expected to be pushed to the fix branch next week.

This fix will not be released to PyPI individually — instead, the first patched version will be published to PyPI after all issues in milestone 1 have been resolved.

Thank you for your attention.

@charm @icprobot

10

Additionally, I will publish every Monday the latest updates on this week’s icpy maintenance work and the upcoming timeline.

11

Update:

  • Last week I completed development of milestone1 for ic-py.
  • This week I plan to add supplemental test cases for milestone1’s functionality and publish a release. (This release will not be pushed to PyPI; developers can reference the GitHub release once it’s published.)
12

A fully functioning ic-py (or any Python agent) equivalent in functionality to @dfinity/candid will be crucial to bringing Kybra (the Python CDK) to 1.0.

We at Demergent Labs are very grateful to see this work being picked up.

13

Huge thanks for taking on updating Ic-Py. The Fetch.ai agent framework is in Python. So, not having a functioning agent library in Python has been a stopper.

14

Thank you for your interest. candid-py is currently only in the planning stage and hasn’t officially entered development yet.

Right now, I’m focused on finalizing the lagging APIs in ic-py and improving the incomplete interaction logic with canisters.

I expect to begin work on candid-py in August of this year.

15

Thank you for your interest—I’m pleased to see that maintaining ic-py is helping community projects.

I’m currently finalizing Milestone 1; once it’s complete, I’ll update this thread. Please stay tuned!

16

Last week’s work update:

  1. Endpoint v3 compatibility and return‐value handling: Migrated the call endpoint from v2 to v3 and implemented detailed categorization of v3 return values, referencing the agent-rs implementation. This will allow ic-py to interact with canisters more quickly and cover many cases that the old ic-py versions didn’t handle.
  2. Poll function enhancements: In previous ic-py versions, if a call returned no response, ic-py wouldn’t poll the request_id（This explains why some requests didn’t receive return values.）. This has been fixed in my branch.

Remaining tasks before the next release:

  1. Finalize update_raw and query_raw for compatibility with the new version
  2. Conduct more thorough testing of update_raw

I expect these to take 2–3 days. Once complete, I’ll publish a release on my branch and update this thread.

After Milestone 2 is finished, I’ll bundle these changes into a PR against the original ic-py repository and publish to PyPI.

If you have any other ic-py–related questions or feature requests, please let me know here!

17

Nice work!!! :rocket: :rocket: :rocket: :rocket: :rocket:

Seriously rooting for you here at Demergent Labs.

18

Some sad events have occurred in my family over the past few days, so last week’s maintenance work will be postponed to this week.

The schedule for future development plans and milestones will remain unchanged.

Thank you for your understanding.

19

Release v1.0.0 – Milestone 1 Complete

July 14, 2025

I’m happy to announce that Milestone 1 of our ic-py maintenance effort is now complete—and the first release from the fix/issue branch is live! This build addresses every issue raised in Milestone 1 and brings two major improvements:

:rocket: Merge Milestone 1: Endpoint Upgrade & Timeouts/Error Classification

1. Endpoint Upgrade

  • Migration to BN v3 Replaced all legacy RPC endpoints with the new Boundary Node v3 URLs.
  • v3 Response Handling & Classification Adapted to the new BN v3 response formats, with detailed classification and handling of each response case—fixing many of the old-version timeouts, exception bursts, and incomplete logic paths.

2. Timeouts & Error Classification

  • Configurable Timeout Handling You can now set sensible default timeouts—or override them per call—to avoid hanging requests.
  • Structured Error Types Improved our error layer so every canister response is classified and logged consistently, making debugging much clearer.

:package: Release Available

You can find the Milestone 1 release here:

:link: ic-py Milestone1 Release

:soon_arrow: Next Steps: Milestone 2 Kickoff

I’m excited to begin work on Milestone 2 for ic-py! Starting this Monday and every week thereafter, I’ll share progress updates and maintenance notes right here. Thank you all for your continued interest and support.

Note: Once Milestone 2 is complete, we’ll publish the latest ic-py release to PyPI—so you’ll be able to install it directly with pip install ic-py.

Feel free to upgrade and let us know if you encounter any issues! :raising_hands:

20

Hey - you should consider adding a feature to automatically grab the candid from the canister using the candid service (see my provided link for an idea on how I did it). Then if that fails, use the tmp_hack (for legacy canisters). Then if that fails, fail and require the dev to provide the candid.

It is extremely handy to be able to call canisters without having to go find the candid first.