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

  • 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

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. :white_check_mark: Certificate verification enabled by default in update_raw and update_raw_async methods
      4. :white_check_mark: Certificate verification implemented in poll and poll_async methods

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. :white_check_mark: Migrated from Python ANTLR4 implementation to Rust-based candid-parser crate for significant performance improvements (multiple times faster parsing speed)
      2. :white_check_mark: Implemented comprehensive DIDLoader interface with support for recursive type definitions and service interface parsing
      3. :white_check_mark: Added comprehensive test suite (test_candid_comprehensive.py, test_did_loader_comprehensive.py, test_parser.py)
      4. :white_check_mark: Full support for all Candid primitives, composite types (Record, Variant, Vec, Opt), and recursive types

Milestone 4 :white_check_mark: Completed

  • Expanded API surface

    • :white_check_mark: High-level wrappers for ICP Ledger (ledger.py)
    • :white_check_mark: Complete NNS Governance interface implementation (governance.py - 1510 lines)
    • :white_check_mark: Cycles Wallet operations (cycles_wallet.py)
    • :white_check_mark: Canister Management interface (management.py)
    • :white_check_mark: Comprehensive example code library (ledger, governance, cycles_wallet, management, simple_counter examples)
    • :hourglass_not_done: High-level wrappers for ICRC-compliant ledgers (ckBTC, ckETH, ckUSDc, etc.)
    • :hourglass_not_done: Out-of-the-box helpers for interacting with Bitcoin, Ethereum, and other canisters

  • Code optimization

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

Milestone 5 (Next Release)

  • Automatically fetch the .did file from the canister (if available)

  • Replica-signed queries

    • Issue: Query calls currently do not support replica-signed responses for enhanced security

  • Certificate Verification Security Enhancement in Low-level Functions

    • Issue: The request_status_raw and request_status_raw_async methods currently return certificates but do not verify them, posing a security risk

  • HTTP Endpoint Update to Latest API

    • Issue: Query and read_state operations are still using v2 endpoints and need to be updated to the latest API version
    • References:

Other long-standing bugs

  • Dynamic HTTP provider & routing

    • Implement latency-based, adaptive routing between boundary nodes
    • Support more flexible selection of endpoints at runtime

  • Ongoing alignment & optimization

    • Keep pace with agent-rs’s feature roadmap
    • Targeted performance tuning, stricter type checks
    • Define additional milestones once Milestones 1–3 are complete

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

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

11 Likes
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.

6 Likes
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.

3 Likes
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:

3 Likes
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.

4 Likes
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

2 Likes
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.)
5 Likes
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.

2 Likes
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!

1 Like
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!

4 Likes
17

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

Seriously rooting for you here at Demergent Labs.

1 Like
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.

1 Like
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:

7 Likes
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.

4 Likes