All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
ic-agent: AddedInfoAwareIdentityandIdentity::sender_infofor setting canister-certified sender info.ic-agent: Added PKCS#8 pem parsing toSecp256k1IdentityandPrime256v1Identity.
ic-agent:DynamicRouteProviderBuilder::new()and::from_components()now accept ak_top_nodes: Option<usize>parameter. PassSome(k)to limit routing to theknodes with the highest latency score; passNoneto retain the existing behaviour of routing across all healthy nodes.
Subnet,SubnetNodeIter, andSubnetKeysIternow implementDebug.ic-agent: AddedSubnetTypeenum (System,Application,VerifiedApplication,Unknown(String)) and exposed it via a newsubnet_type()accessor onSubnet. The field isNonewhen the certificate was produced by a replica with certification version older than V25, andSome(SubnetType)otherwise.SubnetTypeis re-exported fromic_agentalongsideSubnet.
- Fix panic in
ic-agenton non-WASM targets caused byasync-watchcrate; replaced withtokio::sync::watch.
- Time out
Unknownstatuses after 5 minutes, regardless of the configuredmax_polling_time. ic-utils: Bumpic-management-canister-typesto 0.7.1.- Added
LogMemoryLimitattribute type andwith_log_memory_limitsetter toCreateCanisterBuilderandUpdateSettingsBuilder. - Added
canister_metadata()query method toManagementCanister. - Re-exported new types:
CanisterLogFilter,CanisterMetadataArgs,CanisterMetadataResult,FetchCanisterLogsArgs,MemoryMetrics,RenameCanisterRecord,RenameToRecord.
- Added
ic-utils:UpdateCanisterBuilderrenamed toUpdateSettingsBuilder.- Migration: Replace all uses of
UpdateCanisterBuilderwithUpdateSettingsBuilder.
- Migration: Replace all uses of
ManagementCanister::fetch_canister_logsnow takes&FetchCanisterLogsArgsinstead of&Principal.- Migration: Replace
fetch_canister_logs(&canister_id)withfetch_canister_logs(&FetchCanisterLogsArgs { canister_id, filter: None }).
- Migration: Replace
- Snapshot methods (
take_canister_snapshot,load_canister_snapshot,delete_canister_snapshot,read_canister_snapshot_metadata,read_canister_snapshot_data,upload_canister_snapshot_metadata,upload_canister_snapshot_data) no longer accept a separatecanister_id: &Principalparameter; the canister ID is now derived from the args struct.- Migration: Remove the leading
&canister_idargument from these calls.
- Migration: Remove the leading
- Removed
with_optional_*builder methods fromCreateCanisterBuilderandUpdateSettingsBuilder(with_optional_controller,with_optional_compute_allocation,with_optional_memory_allocation,with_optional_freezing_threshold,with_optional_reserved_cycles_limit,with_optional_wasm_memory_limit,with_optional_wasm_memory_threshold,with_optional_log_visibility,with_optional_environment_variables).- Migration: Remove calls passing
None(they were no-ops). For calls passingSome(value), use the correspondingwith_*method directly with the value.
- Migration: Remove calls passing
- Removed round-robin routing strategy.
DynamicRouteProvidernow exclusively uses latency-based routing.- Removed
DynamicRoutingStrategyenum andRoundRobinRoutingSnapshottype. DynamicRouteProvideris no longer generic over routing strategy.DynamicRouteProviderBuilder::new(),::from_components(),::run_in_background(), and::run_in_background_with_intervals()no longer acceptsnapshotorstrategyparameters.- Migration: Remove routing strategy arguments from your code - latency-based routing is now the only option.
- Removed
DynamicRouteProviderBuilder::build()is no longer async. Background tasks are no longer started automatically during construction. Callprovider.start().awaitfor explicit initialization, or let it auto-start lazily on firstroute()call.DynamicRouteProvider::run()is now private. Usestart()instead.
- Add
{get,fetch}_subnet_by_{id,canister}functions to enable looking up subnet information. - Fix panic in web worker environments in
ic-agent. - Update
ic-management-canister-typesto 0.5.0
- Fix
Agent::wait_signedto execute the read_state request on every retry iteration.
- Fix
HttpService callretry behavior such that only network errors are retried.
- Added
read_state_subnet_canister_rangeswhich can query the canister id ranges for a given subnet.
- BREAKING: Bump
ic-management-canister-typesto v0.4.0.- The
CanisterSettingstypes contains a new fieldenvironment_variables.
- The
- BREAKING: Change
HttpServicetrait to use normalhttpcrateRequestandResponsetypes withBytesas a body instead ofreqwestones and addsize_limitargument. - BREAKING: Change
AgentError::TransportErrorenum variant to hold a generic string instead ofreqwest::Error. ic-utils: Bumpic-management-canister-typesto v0.3.3 which changes snapshot upload/download types.
-
Use ic-management-canister-types in ic-utils.
- This change introduces some breaking changes in
ic-utilsdue to the type-inconsistency. For example, theStatusCallResultdefined inic-utilsis not consistent to theCanisterStatusResultdefined inic-management-canister-types. - The legacy types defined in
ic-utilsare marked as deprecated with messages. - Some APIs are updated to use the types defined in
ic-management-canister-types, e.g.upload_canister_snapshot_metadata,upload_canister_snapshot_data.
- This change introduces some breaking changes in
-
Bump MSRV from
1.78.0to1.85.0.
- Add canister snapshot download and upload methods to
ManagementCanister.
- Add
read_state_canister_controllersandread_state_canister_module_hashfunctions.
- BREAKING: Added data about the rejected call to CertifiedReject/UncertifiedReject.
- Updated the serialization of
WasmMemoryPersistence. - BREAKING:
AgentBuilder::with_background_dynamic_routingis no longerasync. - Extended
RouteProvidertrait withfn routes_stats(), returning the number of total and healthy routes. - Added
set_k_top_nodesconfiguration option toLatencyRoutingSnapshotthat enables selective routing to onlykAPI boundary nodes with best ranking (based on latencies and availabilities).
-
Added
wasm_memory_thresholdfield toCanisterSettings. -
Added
CanisterInfotoMgmtMethod.
- Bumped
ic-certificationto3.0.0.
- The lower-level update call functions now return the certificate in addition to the parsed response data.
- Make ingress_expiry required and set the default value to 3 min.
- Changed
BasicIdentity's implementation fromringtoed25519-consensus. - Added
AgentBuilder::with_max_polling_timeto config the maximum time to wait for a response from the replica. DelegatedIdentity::newnow checks the delegation chain. The old behavior is available undernew_unchecked.
- Limited the number of HTTP 429 retries. Users receiving this error should configure
with_max_concurrent_requests. - Added
Envelope::encode_bytesandQuery/UpdateBuilder::into_envelopefor external signing workflows. - Added
AgentBuilder::with_arc_http_middlewareforTransport-like functionality at the level of HTTP requests. - Add support for dynamic routing based on boundary node discovery. This is an internal feature for now, with a feature flag
_internal_dynamic-routing.
- Fix
ic-agentmanifest so that documentation can be built for docs.rs.
- Breaking: Removed
Transportand thehyperandreqwestfeatures.ReqwestTransportis now the default andHyperTransporthas been removed. ExistingReqwestTransportfunctions have been moved toAgentBuilder. Urlnow implementsRouteProvider.- Add canister snapshot methods to
ManagementCanister. - Add
AllowedViewerstoLogVisibilityenum. - Remove the cargo feature,
experimental_sync_call, and enable synchronous update calls by default.
- Bug fix: Add
api/v2prefix to read_state requests for hyper transport
- Removed the Bitcoin query methods from
ManagementCanister. Users should useBitcoinCanisterfor that. - Added
BitcoinCanistertoic-utils. - Upgraded MSRV to 1.75.0.
- Changed
ic_utils::interfaces::management_canister::builders::InstallMode::Upgradevariant to beOption<CanisterUpgradeOptions>:CanisterUpgradeOptionsis a new struct which covers the new upgrade option:wasm_memory_persistence: Option<WasmMemoryPersistence>.WasmMemoryPersistenceis a new enum which controls Wasm main memory retention on upgrades which has two variants:KeepandReplace.
- Added an experimental feature,
experimental_sync_call, to enable synchronous update calls. The feature adds a toggle to theReqwestTransportandHyperTransportto enable synchronous update calls.
- Added a default request timeout to
ReqwestTransport. - Introduced transparent http request retry logic for network-related failures.
ReqwestTransport::with_max_tcp_errors_retries(),HyperTransport::with_max_tcp_errors_retries(). - Changed the SyncCall and AsyncCall traits to use an associated type for their output instead of a generic parameter.
- Call builders now generally implement
IntoFuture, allowing.call_and_wait().awaitto be shortened to.await. - Added
log_visibilityto canister creation and canister setting update options.
- Added a limit to the concurrent requests an agent will make at once. This should make server-side ratelimiting much rarer to encounter, even when sending a high volume of requests (for example, a large
ic_utils::ManagementCanister::installcall). - The agent will now automatically retry 429 Too Many Requests responses after a short delay.
- BREAKING: Changed Chunk Store API to conform to the interface specification:
ChunkHashwas changed from[u8; 32]to a struct.- Return types of
ManagementCanister::stored_chunks()andManagementCanister::upload_chunk(). - Argument type of
ManagementCanister::install_chunked_code(). InstallChunkedCodeBuilder.- All occurrences of
storage_canisterwere changed tostore_canister. - The field
chunk_hashes_listwas changed fromvec<vec<u8>>tovec<ChunkHash>.
- All occurrences of
- Changed
WalletCanister::from_canister/create's version check to not rely on the reject code. - Added
QueryBuilder::call_with_verification()andQueryBuilder::call_without_verification()which always/never verify query signatures regardless the Agent level configuration fromAgentBuilder::with_verify_query_signatures. - Function
Agent::fetch_api_boundary_nodes()is split into two functions:fetch_api_boundary_nodes_by_canister_id()andfetch_api_boundary_nodes_by_subnet_id(). ReqwestTransportandHyperTransportstructures storing the trait objectroute_provider: Box<dyn RouteProvider>have been modified to allow for shared ownership viaArc<dyn RouteProvider>.- Added
wasm_memory_limitto canister creation and canister setting update options. - Bumped Reqwest version from
0.11.7to0.12.4
- Changed
AgentError::ReplicaErrortoCertifiedRejectorUncertifiedReject.CertifiedRejects went through consensus, andUncertifiedRejects did not. If your code usesReplicaError:- for queries: use
UncertifiedRejectin all cases (for now) - for updates: use
CertifiedRejectfor errors raised after the message successfully reaches the canister, andUncertifiedRejectotherwise
- for queries: use
- Added
Agent::fetch_api_boundary_nodesfor looking up API boundary nodes in the state tree. - Timestamps are now being checked in
Agent::verifyandAgent::verify_for_subnet. If you were using it with old certificates, increase the expiry timeout to continue to verify them. - Added node metrics, ECDSA, and Bitcoin functions to
MgmtMethod. Most do not have wrappers inManagementCanisterbecause only canisters can call these functions. - Added
FetchCanisterLogsfunction toMgmtMethodand a corresponding wrapper toManagementCanister. - Updated the
ringcrate to 0.17.7.ring0.16 has a bug where it requires incorrect Ed25519 PEM encoding. 0.17.7 fixes that and is backwards compatible. - Removed serde and candid serialization traits from the
Statustype. - Added commas and newlines to the
Statusfmt::Display output. It is valid JSON now (it was close before).
- Changed the return type of
stored_chunksto a struct. - Added a prime256v1-based
Identityimpl to complement the ed25519 and secp256k1Identityimpls. - Changed the type of
InstallMode.skip_pre_upgradefrombooltoOption<bool>to match the interface specification.
- Added the chunked wasm API to ic-utils. Existing code that uses
install_codeshould probably update toinstall, which works the same but silently handles large wasm modules. - Added query stats to
StatusCallResult. - Upgraded
ic-certificationto v2.2.
- Breaking change: Bump candid to 0.10. Downstream libraries need to bump Candid to 0.10 as well.
- Feat: add
idle_cycles_burned_per_dayfield toStatusCallResult.
- Fixed a spurious certificate validation error in the five minutes after a node is added to a subnet
- Fixed
HyperTransportendpoint construction (//in the format/api/v2//canister/5v3p4-iyaaa-aaaaa-qaaaa-cai/query)
- Added node signature certification to query calls, for protection against rogue boundary nodes. This can be disabled with
with_verify_query_signatures. - Added
with_nonce_generationtoQueryBuilderfor precise cache control. - Added the ability to dispatch to multiple URLs to
ReqwestTransportandHyperTransport, with aRouteProvidertrait and a providedRoundRobinRouteProviderimplementation. - Added
read_subnet_state_rawtoAgentandread_subnet_statetoTransportfor looking up raw state by subnet ID instead of canister ID. - Added
read_state_subnet_metricstoAgentto access subnet metrics, such as total spent cycles. - Types passed to the
to_request_idfunction can now contain nested structs, signed integers, and externally tagged enums. Envelopestruct is public also outside of the crate.- Remove non-optional
ic_api_versionfield (whose value is not meaningfully populated by the replica) and optionalimpl_sourceandimpl_revisionfields (that are not populated by the replica) from the expected/api/v2/statusendpoint response. - Drop
sendersfield from user delegations (typeDelegation).
- Added
reserved_cycles_limitto canister creation and canister setting update options. - Added
reserved_cyclesandreserved_cycles_limitto canister status call result.
- Added
DelegatedIdentity, anIdentityimplementation for consuming delegations such as those from Internet Identity. - Replica protocol type definitions have been moved to an
ic-transport-typescrate.ic-agentstill reexports the ones for its API. - The
Unknownlookup of a request_status path in a certificate results in anAgentError(the IC returnsAbsentfor non-existing paths). - For
Canistertype, added methods with no trailing underscore: update(), query(), canister_id(), clone_with()
- Breaking change: Remove argument builder form
ic-utils.CallBuilder::with_argsets a single argument, instead of pushing a new argument to the list. This function can be called at most once. If it's called multiple times, it panics. If you have multiple arguments, useCallBuilder::with_args((arg1, arg2))orCallBuilder::set_raw_arg(candid::Encode!(arg1, arg2)?). - feat: Added
public_key,sign_arbitrary,sign_delegationfunctions toIdentity. - Add
Fromtrait to coercecandid::Errorintoic_agent::AgentError. - Add
Agent::set_arc_identitymethod to switch identity.
Switched from rustls crate to rustls-webpki fork to address https://rustsec.org/advisories/RUSTSEC-2023-0052
Removed the arc_type feature requirement for candid, in order to avoid deprecation warnings. This is a breaking change. The call and call_and_wait are no longer async fn and instead return a Future or BoxFuture.
- Breaking Change: builders are now owning-style rather than borrowing-style; with_arg takes an owned Vec rather than a borrowed Vec
- Breaking Change: Identity::sign takes &EnvelopeContent rather than the request ID.
- Bump Candid crate to 0.9.0
-
fix: Adjust the default polling parameters to provide better UX. Remove the
CouldNotReadRootKeyerror and panic on poisoned mutex. -
chore: remove deprecated code and fix style
-
Breaking Change: removing the PasswordManager
-
Breaking Change: Enum variant
AgentError::ReplicaErroris now a tuple struct containingRejectResponse. -
Handling rejected update calls where status code is 200. See IC-1462
-
Reject code type is changed from
u64to enumRejectCode. -
Support WASM targets in the browser via
wasm-bindgen. Featurewasm-bindgenrequired. -
Do not send
certificate_versionon HTTP Update requests -
Update
certificate_versiontou16instead ofu128, fixes an issue where the asset canister always responds with v1 response verification
- Breaking change: Content and path storage has been changed from a
Cow<[u8]>to a user-providedT: AsRef<u8>, removing the lifetime from various types.
- Fixed issue where a missing request header caused the canister to not respond with an
ic-certificateheader.
- Expose the root key to clients through
read_root_key
- Add
lookup_subtreemethod to HashTree & HashTreeNode to allow for subtree lookups. - Derive
CloneonCertificateandDelegationstructs. - Add certificate version to http_request canister interface.
- (ic-utils) Add specified_id in provisional_create_canister_with_cycles.
- Remove
garconfrom API. Callers can remove the dependency and any usages of it; all waiting functions no longer take a waiter parameter. - Create
ic-certificationcrate and move HashTree and Certificate types.
- Drop
disable_range_checkflag from certificate delegation checking.
- Update
candidto v0.8.0. - Move
hash_treefromic-typesand no more re-export ic-types.
- Set
default-features = falseforic-agentinterdependencies to reduce unused nested dependencies. - Bump
candidto0.7.18.
- Fixed custom configured HTTP headers - no longer is the header's value wrapped with double quotes.
- Switched to
ic-verify-bls-signaturecrate for verify BLS signatures - Added new
hypertransportHyperReplicaV2Transport - Added Agent::set_identity method (#379)
- Updated lookup_request_status method to handle proofs of absent paths in certificates.
- Make it possible to specify effective canister id in CreateCanisterBuilder
- Remove
PrincipalInnerPrincipaldirectly holdslenandbytesfields
PrincipalErrorenum has different set of variants reflecting changes infrom_textlogic.from_textaccepts input containing uppercase letters which results in Err before.from_textverifies CRC32 check sequence
Added support configurable inclusion and exclusion of files and directories (including dotfiles and dot directories), done via .ic-assets.json config file:
- example of
.ic-assets.jsonfile format:[ { "match": ".*", "cache": { "max_age": 20 }, "headers": { "X-Content-Type-Options": "nosniff" }, "ignore": false } ] - see PR and tests for more examples
Added support for configuring HTTP headers for assets in asset canister (via .ic-assets.json config file):
- example of
.ic-assets.jsonfile format:[ { "match": "*", "cache": { "max_age": 20 }, "headers": { "X-Content-Type-Options": "nosniff" } }, { "match": "**/*", "headers": null }, ] headersfrom multiple applicable rules are being stacked/concatenated, unlessnullis specified, which resets/empties the headers. Both"headers": {}and absence ofheadersdon't have any effect on end result.
Added support for asset canister config files in ic-assets.
- reads configuration from
.ic-assets.jsonconfig files if placed inside assets directory, multiple config files can be used (nested in subdirectories) - runs successfully only if the config file is right format (valid JSON, valid glob pattern, JSON fields in correct format)
- example of
.ic-assets.jsonfile format:[ { "match": "*", "cache": { "max_age": 20 } } ] - works only during asset creation
- the config file is being taken into account only when calling
ic_asset::sync(i.e.dfx deployoricx-asset sync)
Breaking change: ic-asset::sync() now synchronizes from multiple source directories.
This is to allow for configuration files located alongside assets in asset source directories.
Also, ic-asset::sync:
- skips files and directories that begin with a ".", as dfx does when copying assets to an output directory.
- reports an error if more than one asset file would resolve to the same asset key
agent-rs/349 feat: add with_max_response_body_size to ReqwestHttpReplicaV2Transport
Updated dependencies. Some had breaking changes: k256 0.11, pkcs 0.9, and sec1 0.3.
Fixed a potential panic in secp256k1 signature generation.
Added ReqwestHttpReplicaV2Transport::create_with_client.
Remove openssl in favor of pure rust libraries.
Updated minimum version of reqwest to 0.11.7. This is to avoid the following error, seen with reqwest 0.11.6:
Unknown TLS backend passed to use_preconfigured_tls
Updated wallet interface for 128-bit API.
Remove parameterized canister pattern. Use WalletCanister::create rather than Wallet::create.
wallet_send takes Principal instead of &Canister.
Updated ic_utils::interfaces::http_request structures to use &str to reduce copying.
Removed Deserialize from HttpRequest.
Changed HttpResponse to be generic over entire callback instead of just ArgToken.
Added HttpRequestStreamingCallbackAny to deserialize any callback, regardless of signature.
Added conversion helpers for HttpResponse, StreamingStrategy and CallbackStrategy across generics.
Changes to Canister<HttpRequestCanister> interface.
- Made
http_request,http_request_update, andhttp_request_stream_callbackmore generic and require fewer string copies. - Added
_customvariants to enable customtokendeserialization.
Introduced HttpRequestStreamingCallback to work around dfinity/candid#273.
Response certificate verification will check that the canister id falls within the range of valid canister ids for the subnet.
Secp256k1 identity now checks if a curve actually uses the secp256k1 parameters. It cannot be used to load non-secp256k1 identities anymore.
Data type of cycles changed to u128 (was u64).
fetch_root_key() only fetches on the first call.
Re-genericized Token to allow use of an arbitrary Token type with StreamingStrategy.
Renamed BatchOperationKind._Clear to Clear for compatibility with the certified assets canister. This avoids decode errors, even though the type isn't referenced here.
Changed the 'HttpRequest.upgrade' field to 'Option' from 'bool'.
The lookup_value function now takes generics which can be iterated over (IntoIterator<Item = &'p Label>) and transformed into a Vec<Label>, rather than just a Vec<Label>.
The lookup_path method now takes an Iterator<Label> rather than an AsRef<[Label]>
Added support for upgrading HTTP requests (http_request_update method)
Updated crate dependencies, most notably updating rustls, removing the direct dependency on webpki-roots, and allowing consumers of ic-agent to update to reqwest 0.11.7.
Implements https://github.com/dfinity-lab/ic-ref/pull/371
Fixed a defect in asset synchronization where no retries would be attempted after the first 30 seconds overall.
Unified all version numbers and removed the zzz-release tool.
It's now possible to specify which encodings will be accepted. The default (and previous) behavior is to accept only the identity encoding. Specifying encodings that browsers more commonly accept demonstrates the difference in the returned data and certificate.
For example, here is the data and certificate returned when only accepting the identity encoding.
$ cargo run -p icx-cert -- print 'http://localhost:8000/index.js?canisterId=ryjl3-tyaaa-aaaaa-aaaba-cai'
DATA HASH: 1495cd574831c23b4db97bc3860666ea495386f0ef0dab73c23ef31db5aa2765
Label("/index.js", Leaf(0x1495cd574831c23b4db97bc3860666ea495386f0ef0dab73c23ef31db5aa2765)),
Here is an example accepting the gzip encoding (as most browsers do), showing that the canister responded with different data having a different data hash.
$ cargo run -p icx-cert -- print --accept-encoding gzip 'http://localhost:8000/index.js?canisterId=ryjl3-tyaaa-aaaaa-aaaba-cai'
DATA HASH: 1770e76af0816ba951320c03eab1263c43de7ac4b0558dd9049cc532b7d6cd01
Label("/index.js", Leaf(0x1495cd574831c23b4db97bc3860666ea495386f0ef0dab73c23ef31db5aa2765)),
This project moved to https://github.com/dfinity/icx-proxy.
- Added field
replica_health_statustoStatus.- typical values
healthywaiting_for_certified_state
- typical values