This version of the web SDK focuses on forward compatibility, i.e. making it easier to keep applications and services running through updates to the integration point (Concordium nodes).
Up until this release, certain extensions to the Concordium Node API have resulted in the SDK failing to parse query responses, resulting in the entire query failing. This is the case even for the larger queries where the unknown/missing information is only a small part of the response preventing the application to access the entire response. Usually the fix was to update the SDK to a newer version which know how to parse the new information, but this imposes work for the ecosystem for every change in the API (usually part of protocol version updates).
This major release introduces Upward<A> a type wrapper representing information which might be extended in future version
of the API, providing a variant representing unknown information such that queries can provide partial information.
It makes potentially extended information explicit in the types and allows each application to decide how to handle the
case of new unknown data on a case by case basis.
UpwardHandling upward depends on what you want to achieve. If you're running a service that integrates with a Concordium node, you might want to fail safely by handling unknown variants gracefully. If you're writing a script it's probably easier to fail fast.
import { isKnown, type TransactionHash } from '@concordium/web-sdk';
...
const transactionSummary: Upward<BlockItemSummary> = ...
// branch on unknown
if (isKnown(transactionSummary)) {
// transactionSummary is statically known at this point
} else {
// handle the unknown case
console.warn('Encountered unknown transaction type.');
}
// Handle as optional
// `Unknown` variant is simply represented as `null` underneath.
const transactionHash: TransactionHash.Type | undefined = transactionSummary?.hash;
import { assertError, type TransactionHash } from '@concordium/web-sdk';
...
const transactionSummary: Upward<BlockItemSummary> = ...
// fail with an error message in case of the unexpected happening.
assertKnown(transctionSummary, 'Expected transaction type to be known');
// transactionSummary is known at this point on.
// or handle by simple null assertion, e.g. in the case where you just sent
// the transaction to a node.
handleKnownTransaction(transactionSummary!);
In the SDK, undefined is used to represent when an optional value is not present and null is used to represent
unknown values. If you want to branch on these different cases, it can be handled by targeting thesee specific types:
const optionalUnknown: Upward<Value> | undefined = ...
switch (optionalUnknown) {
case undefined: ... // handle optionality
case null: ... // handle unknown variant
default: ... // at this point, we know the type is `Value`
}
Several types have been replaced with a module containing the type itself together with functions for constructing and converting the type:
AccountAddress is now a module with functions related to account addresses:AccountAddress as a type use AccountAddress.Type.new AccountAddress("<address>") is now AccountAddress.fromBase58("<address>").isAlias and getAlias are now accessable from AccountAddress.isAlias and AccountAddress.getAlias.ContractAddresss is now a module with functions related to contract addresses:ContractAddress as a type use ContractAddress.Type.ContractAddress.create(index, subindex).CredentialRegistrationId is now a module with functions related to credential registration IDs:CredentialRegistrationId as a type use CredentialRegistrationId.Type.new CredentialRegistrationId("<hex-string>") is now
CredentialRegistrationId.fromHexString("<hex-string>").Duration is now a module with functions related to durations of time.Duration as a type use Duration.Type.Timestamp is now a module with functions related to timestamps.Timestamp as a type use Timestamp.Type.The API now uses dedicated types instead of language primitives:
AccountAddress instead of a string with base58 encoding.
Can be constructed using AccountAddress.fromBase58('<base58>').BlockHash instead of a string with hex encoding.
Can be constructed using BlockHash.fromHexString('<hex>').TranactionHash instead of a string with hex encoding.
Can be constructed using TransactionHash.fromHexString('<hex>').Energy instead of a bigint.
Can be constructed using Energy.create(<integer>).ReceiveName instead of a string.
Can be constructed using ReceiveName.fromString('<contract>.<function>').InitName instead of a string.
Can be constructed using Init.fromString('init_<contract>').ContractName instead of a string.
Can be constructed using ContractName.fromString('<contract>').EntrypointName instead of a string.
Can be constructed using EntrypointName.fromString('<function>').Parameter instead of a string with hex encoding.
Can be constructed using Parameter.fromHexString('<hex>').SequenceNumber (formerly called nonce) instead of a bigint.
Can be constructed using SequenceNumber.create(<integer>).Timestamp instead of a bigint.
Can be constructed using Timestamp.fromMillis(<integer>).Duration instead of a bigint.
Can be constructed using Duration.fromMillis(<integer>).The @concordium/web-sdk now requires bundlers to respect exports field of
package.json of a module. This is due to relying on entrypoints declared in
the exports field of @concordium/rust-bindings to make it possible to select
only parts of the SDK to include in your application.
Furthermore, the SDK is now published as an ES module, making it possible to
eliminate dead code.
For TypeScript users, at least typescript version 5 is required along with
the setting compilerOptions.moduleResolution to "bundler" to match the
resolution strategy of modern bundlers.
The following entrypoints are made available for consumers of
@concordium/web-sdk:
@concordium/web-sdk exposes the full API of the SDK.
This can safely be used by projects built with ES modules.@concordium/web-sdk/cis0 entrypoint exposes functionality for working with
contracts adhering to the
CIS-0 standard.@concordium/web-sdk/cis2 entrypoint exposes functionality for working with
contracts adhering to the
CIS-2 standard.@concordium/web-sdk/cis4 entrypoint exposes functionality for working with
contracts adhering to the
CIS-4 standard.@concordium/web-sdk/grpc entrypoint exposes the grpc client for interacting
with a nodes GRPCv2 interface.@concordium/web-sdk/id entrypoint exposes functionality for working with
ID proofs.@concordium/web-sdk/json-rpc entrypoint exposes the (deprecated)
json-rpc client for interacting with a nodes GPRCv1 interface.@concordium/web-sdk/schema entrypoint exposes functionality for working
with smart contract schemas, i.e.(de)serializing types using a smart
contract schema.@concordium/rust-bindings/dapp.@concordium/web-sdk/types entrypoint exposes functionality for working
with concordium domain types.@concordium/web-sdk/wasm entrypoint exposes a variety of functionality for
working with concordium domain types, which requires WASM.@concorodium/rust-bindings/wallet.@concordium/web-sdk/web3-id entrypoint exposes functionality for working
with web3-id proofs.The @concordium/node-sdk has been removed in favor of unifying both web and
nodejs SDK's in a single platform agnostic SDK. This means users of
@concordium/node-sdk looking to upgrade, will need to install
@concordium/web-sdk instead.
The @concordium/web-sdk module is not compatible with
node versions <16 and is published only as an ES module.
This, in turn, requires users to also run applications as ES modules.
The easiest way to run your node application as an ES module, is by setting
the type field of package.json to be set to "module":
{
...
"type": "module",
...
}
Alternatively, files names with the extension mjs (or mts for TypeScript)
are always handled as ES modules.
For TypeScript users, at least typescript version 4.7 is required along
with the setting compilerOptions.moduleResolution to "node16" or
"nodenext" to match the resolution strategy of node version 16 and later.
Some classes and types have been renamed or changed, and should be update if used.
Some types in the AccountTransactionType enum have been changed to align with other languages.
The GtuAmount class has been renamed to CcdAmount to reflect the current
name of token. If an object was used in place of a class instance, the field
microGtuAmount should be renamed to microCcdAmount.
The field content has been renamed to source to align with other languages.
Field names have been renamed to align with other languages. contractAddress
field has been renamed to address. parameter field has been renamed to
message.
Field names have been renamed to align with other languages. contractName
field has been renamed to initName. parameter field has been renamed to
params.
Generated using TypeDoc