0.32.0-rc.3

In addition to enabling linking Ethereum addresses to a DID, the upcoming kilt-node release 1.10.0 also changes the challenge mechanism used by the account linking pallet, resulting in a breaking change.

In order to be able to continue to create new links between DIDs and accounts after runtime upgrade, applications should upgrade to version 0.32.0 of the SDK as soon as possible.

What's Changed

• feat: support for new account linking challenge & split `associateAccountToChainArgs by @weichweich in #730
• fix: fromFemtoKilt fails for non-english locales by @rflechtner in #731
• fix: integration test error matching by @rflechtner in fea185f
• chore: enable tests for ethereum linking by @rflechtner in #724
• chore(deps): bump json5 from 1.0.1 to 1.0.2 by @dependabot in #707
• chore(deps): bump some deps by @rflechtner in #721
• chore(deps): update dependency testcontainers to v9 by @renovate in #671

Full Changelog: 0.31.1...0.32.0-rc.3

0.31.1

This patch release fixes decoding of certain light DIDs created with pre-0.29 versions of the SDK and resolves some inconsistencies in documentation.

What's changed

Fixes

• fix: jsdocs for public credential fetch* functions by @ntn-x2 in #723
• fix: light DID decoding logic by @ntn-x2 in #725

Misc

• chore: move DidExporter snippets to docs by @ntn-x2 in #722

Full Changelog: 0.31.0...0.31.1

0.31.1-rc.1

This patch release fixes decoding of certain light DIDs created with pre-0.29 versions of the sdk and resolves some inconsistencies in documentation.

What's changed

Fixes

• fix: jsdocs for public credential fetch* functions by @ntn-x2 in #723
• fix: light DID decoding logic by @ntn-x2 in #725

Misc

• chore: move DidExporter snippets to docs by @ntn-x2 in #722

Full Changelog: 0.31.0...0.31.1-rc.1

0.31.0

This release introduces support for creating, querying and verifying public credentials (#677) as well as for querying CTypes from an archive node (#694).
The DID package is extended with a newly introduced function (compliantResolve) which allows DID resolution that is compliant, out of the box, with specifications detailing data models for the DID resolution process (#665).
This package now also provides a complete json-ld definition of terms commonly used on KILT DID documents. These definitions are now linked to by json-ld representations of DID documents produced by exportToDidDocument (#712).

What's Changed

Breaking changes

• Instead of just returning the CType creator's DID, CType.fromChain now returns an object containing both the creator and the createdAt block (see #694).
• Warnings from polkadot-js upon connecting to a blockchain node (e.g. missing types or non-decorated runtime/rpc calls) will be hidden by default unless the logLevel is set to warn (3) or lower. Use init({logLevel: 3}) to set the global log level for the sdk.

Features

• feat: public credentials and asset DIDs by @ntn-x2 in #677
• feat: add CType block number support by @ntn-x2 in #694
• feat: DID spec compliant implementation of resolve by @rflechtner in #665
• feat: allow passing additional arguments to ApiPromise.create by @rflechtner in #705
• feat: add did contexts by @rflechtner in #712

Fixes

• fix: add peregrine stg chain to type decorations by @wischli in #681
• fix: old session types by @weichweich in #687
• fix: esm imports by @rflechtner in #700
• fix: various minor fixes by @rflechtner in #685
• fix: block parsing logic for public credentials by @ntn-x2 in #697
• fix: backwards-compatible ctype data decoding by @rflechtner in #703
• fix: align dependency versions by @rflechtner in #713

Misc

• chore: update callback docstrings by @rflechtner in #680
• refactor: reduce startup time of tests by using babel to transpile js by @rflechtner in #689
• chore: update and dedupe dependencies by @ntn-x2 in #696
• chore: update 2023 by @weichweich in #698

Full Changelog: 0.30.0...0.31.0

0.31.0-rc.2

This release introduces support for creating, querying and verifying public credentials (#677) as well as for querying CTypes from an archive node (#694).
Additionally, this introduces a function (compliantResolve) which allows DID resolution that is compliant, out of the box, with specifications detailing data models for the DID resolution process (#665).
In this context, the sdk now also provides a complete json-ld definition of terms commonly used on KILT DID documents, which is linked to in json-ld representations of compliant DID documents (#712).

What's Changed

Features

• feat: public credentials and asset DIDs by @ntn-x2 in #677
• feat: add CType block number support by @ntn-x2 in #694
• feat: DID spec compliant implementation of resolve by @rflechtner in #665
• feat: allow passing additional arguments to ApiPromise.create by @rflechtner in #705
• feat: add did contexts by @rflechtner in #712

Fixes

• fix: add peregrine stg chain to type decorations by @wischli in #681
• fix: old session types by @weichweich in #687
• fix: esm imports by @rflechtner in #700
• fix: various minor fixes by @rflechtner in #685
• fix: block parsing logic for public credentials by @ntn-x2 in #697
• fix: backwards-compatible ctype data decoding by @rflechtner in #703
• fix: align dependency versions by @rflechtner in #713

Misc

• chore: update callback docstrings by @rflechtner in #680
• refactor: reduce startup time of tests by using babel to transpile js by @rflechtner in #689
• chore: update and dedupe dependencies by @ntn-x2 in #696
• chore: update 2023 by @weichweich in #698

Full Changelog: 0.30.0...0.31.0-rc.2

0.31.0-rc.1

This release introduces support for creating, querying and verifying public credentials as well as for querying CTypes from an archive node.
Additionally, this introduces a function (compliantResolve) which allows DID resolution that is compliant, out of the box, with specifications detailing data models for the DID resolution process.

What's Changed

Features

• feat: public credentials and asset DIDs by @ntn-x2 in #677
• feat: add CType block number support by @ntn-x2 in #694
• feat: DID spec compliant implementation of resolve by @rflechtner in #665
• feat: allow passing additional arguments to ApiPromise.create by @rflechtner in #705

Fixes

• fix: add peregrine stg chain to type decorations by @wischli in #681
• fix: old session types by @weichweich in #687
• fix: esm imports by @rflechtner in #700
• fix: various minor fixes by @rflechtner in #685
• fix: block parsing logic for public credentials by @ntn-x2 in #697
• fix: backwards-compatible ctype data decoding by @rflechtner in #703

Misc

• chore: update callback docstrings by @rflechtner in #680
• refactor: reduce startup time of tests by using babel to transpile js by @rflechtner in #689
• chore: update and dedupe dependencies by @ntn-x2 in #696
• chore: update 2023 by @weichweich in #698

Full Changelog: 0.30.0...0.31.0-rc.1

0.30.0

What's Changed

Type definitions for runtime version 10800

This release updates type definitions for the runtime upgrade 10800 that has been released as part of KILTprotocol/kilt-node v1.8.0.
These definitions enable the use of new staking runtime api calls that are part of the staking pallet refactor proposed in that upgrade.

Warning
Type definitions released as part of SDK v0.29.0 unfortunately are not compatible with the upcoming runtime upgrade.
If you are using this version you will need to upgrade to 0.30.0 in order to continue to use DID runtime api calls (e.g. for querying DID documents and linked accounts).

Improved Did signature verification logic on credential presentations and quotes

This includes:

• We added two optional flags (expectedSigner and allowUpgraded) to the verifyDidSignature function which allow making assertions about the signer DID.
• Using these flags we now fail presentation verification if the signer is unrelated to the credential owner. A presentation can be signed by a full DID that resulted from upgrading the credential owner DID.
• We expanded the set of signed properties of the IQuoteAgreement. From now on this set includes the credential rootHash and the claimerDid. To enforce this, we provide a new function (verifyQuoteAgreement) to verify signatures over this object.
• Similar to the improvement on presentation verification, verifyQuoteAgreement as well as verifyAttesterSignedQuote fail if claimerSignature and claimerDid or attesterSignature and attesterDid are unrelated. Here, signatures by upgraded DIDs are not permitted.

All changes:

• feat: compare owner and signer of credential on signature verification by @rflechtner in #674
• feat: improve quote verification by @rflechtner in #675
• chore: update develop metadata and migrate to new DID runtime API in integration tests by @ntn-x2 in #678
• fix: type-definitions chain names by @wischli in #673
• chore: update type definitions by @ntn-x2 in #679
• fix: 0.30.0-rc.1 issues by @rflechtner in #690

Full Changelog: 0.29.0...0.30.0

0.30.0-rc.1

What's Changed

We have improved Did signature verification logic on credential presentations and quotes.
This includes:

• Adding two optional flags (expectedSigner and allowUpgraded) to the verifyDidSignature function which allow making assertions about the signer Did.
• Use these to fail presentation verification if the signer is unrelated to the credential owner.
• Add claimerDid and credential rootHash to the set of signed data in quote agreements; add a verifyQuoteAgreement to verify these signatures.
• Make sure quote verification fails if claimerSignature and claimerDid or attesterSignature and attesterDid are unrelated.

We have also updated type definitions to prepare the staking pallet refactor that is to be released with kilt-node version 1.8.0.

All changes:

• feat: compare owner and signer of credential on signature verification by @rflechtner in #674
• feat: improve quote verification by @rflechtner in #675
• chore: migrate to new DID runtime API in integration tests by @ntn-x2 in #678
• fix: type-definitions for staking pallet refactor by @wischli in #673
• chore: update type definitions by @ntn-x2 in #679

Full Changelog: 0.29.0...0.30.0-rc.1

0.29.0

This release bundles a large number of updates and design changes in the SDK to improve usability and reduce the complexity and size of our code base.

Many things have changed; read below for the reasoning behind our updates.

To ease your transition from previous versions, we have assembled instructions and information on upgrade paths and backward compatibility in our docs.

Breaking Changes in the KILT SDK

Direct Usage of the api

The initial SDK architecture was providing wrappers for the api calls, and many of those were one-liners. Over time we realized that knowledge of the polkadot api is common in the wider ecosystem and empowers application developers to interact with the Kilt blockchain and other projects in ways that fit their needs. Thus, we are no longer masking these calls. In fact, we have introduced dedicated runtime api calls for DIDs and account linking that allow querying all information related to a DID with one call and thus replace client-side data aggregation.

In cases where queries and transactions need particularly formatted input, we provide corresponding *ToChain() functions. When the outputs of api calls are not immediately usable we provide *FromChain() functions. As an extra, you will need to know a significantly smaller SDK API surface, as most of get*Tx(), get*Extrinsic(), and query*() functions are removed. For TypeScript developers, this also reduces the amount of checking for a null return value.

TypeScript enums

All the TypeScript enums have been removed in favor of plain strings or numbers. The documentation and the TypeScript completion should provide you with possible values. Arrays of possible values are provided for programmatic comparison in some cases.

Removed completely:

• Message.BodyType
• MessageBodyType
• SigningAlgorithms
• EncryptionAlgorithms
• DidDocumentPublicKeyType
• AttestationStatus

Values available:

• Permission
• KeyRelationship (values as keyRelationships)
• VerificationKeyType (values as verificationKeyTypes)
• EncryptionKeyType (values as encryptionKeyTypes)

SDKErrors

All error classes in the SDKErrors namespace have been renamed from all-uppercase to idiomatic title-case. Some other minor naming changes were done for better alignment. Messages that duplicate the names of the errors were removed.

Our JSDoc documentation for @throws has never been exhaustive, and the language does not provide any means to maintain it properly. To avoid misleading developers, we have removed these lines.

Blockchain and BlockchainUtils

The class Blockchain and its methods are removed. Its most used feature was transaction re-signing, which turned out to not be a solution that would work for all or even most applications.

The namespace BlockchainUtils of the core module is now exported as Blockchain.

BlockchainApiConnection

The class BlockchainApiConnection has been removed. Instead of calling await getConnectionOrConnect() everywhere we recommend to connect via connect() during initialization, and get the api object as const api = ConfigService.get('api') whenever you need it. As a bonus it makes many functions synchronous.

Keystore and Did.DemoKeystore

The class Keystore and its example implementation Did.DemoKeystore are removed in favor of more direct usage of keypairs and callbacks. This has also required changes to the signing callbacks and encryption callbacks expected by our functions.

DidBatchBuilder, FullDidBuilder and descendants

The class DidBatchBuilder has been removed in favor of Did.authorizeBatch. The classes FullDidBuilder, FullDidCreationBuilder, and FullDidUpdateBuilder have been removed in favor of directly creating the lists of transactions to submit.

DidResolver

The namespace DidResolver has been removed, the resolve*() functions are available directly in the did package. The functions accepting the interface IDidResolver were updated to accept the resolve{Key,Service}() method they actually need.

When resolving a light DID that has been upgraded to a full DID, the function resolve() will not return the document, only canonicalId. The functions resolveKey() and resolveService() will not return values in this case.

CType, Claim, Quote, Credential, Attestation, Message

The initial SDK architecture was to use classes for storing data of core types and as namespaces for their processing methods. The same approach was used for the Message.

Now we store data as plain old JavaScript objects. They are passed as parameters to the functions from corresponding namespaces.

The SDK still uses classes in a few exceptional cases.

ICType, ICTypeSchema, ICTypeMetadata

The type ICType was defined but not really used anywhere, except for its schema property. We removed the ICType and renamed ICTypeSchema to ICType. ICTypeMetadata now uses cTypeId in place of ctypeHash.

IDidDetails and DidDetails

For the DID we used the same approach as the core types and replaced classes with plain objects and functions operating on them.

We made other major changes to the package. The data shape IDidDetails has become DidDocument and its shape is very close to the shape of the DID Document in the Decentralized Identifiers Specification. The few differences are justified by better developer ergonomics. You can still use the export*() functions to convert it to a fully interoperable format ConformingDidDocument.

Please only create DidDocuments via the provided SDK functions, for it needs internal consistency. Unless you know what you’re doing, of course!

FullDidDetails and LightDidDetails

The classes FullDidDetails and LightDidDetails have been removed in favor of using the DidDocument. All functions of the did package (except for authorize*() functions) do not care whether the DID document is stored on the blockchain.

Did.Chain, Did.Utils, Did.AccountLinks, Did.Web3Names, Did.DidDocumentExporter

The functions from these sub-namespaces of the did package have been moved to the root namespace of the package.

keySelection and selectKey

Since the KILT blockchain currently only allows one verification key per key relationship in a DID, we removed these callbacks used to select keys.

verify*()

For convenience the verify*() functions now throw errors instead of returning false.

RequestForAttestation

The initial SDK flow was to create a RequestForAttestation object, create or fetch an Attestation for it, and wrap them both in a Credential for passing around. We realized we don’t need to include the Attestation since the receiver side had to fetch the Attestation from the KILT blockchain again in any case. This allowed us to simply rename RequestForAttestation to ICredential and remove the claimer's signature from it. This means that credentials are not signed by the claimer anymore, but they are signed when used by the claimer in presentations (see next section below).

Checking Validity of an Attestation

Because attestation data is no longer attached to an ICredential object, the associated IAttestation has to be queried first from chain and then checked for revocation status.
We have removed the checkValidity function for IAttestations which simply wrapped these checks.

const attestation = await api.query.attestation.attestations(claimHash)

const isAttested = attestation.isSome && attestation.unwrap().revoked.isFalse

Presenting an ICredential

We have removed the optional claimerSignature from the ICredential interface in favor of having it as a required property in the descendant type ICredentialPresentation.

Compression

We have removed the unused feature of compression and decompression of the core data objects.

Breaking commits

8b6e57f refactor!: make verifyDidSignature accept Uint8Array (#666)
3bc648a refactor!: remove queries for did, web3names, and didLookup in favor of the api.call.didApi call (#643)
97c005e refactor!: simplify CType (#656)
3a683e4 feat!: verify* functions take didResolveKey parameter (#651)
f462b5a feat: remove Did.signPayload (#641)
1b210dc feat: align from *Extrinsic to *Tx method names (#602)
3b42a4e feat!: throw instead of return null (#648)
1181c1d chore: rename DidBuilderError (#650)
89b4920 feat!: callback feedback (#647)
ad16670 feat: message.decrypt does not need did document (#645)
b059eec refactor!: single DID namespace (#640)
a52eb1d feat: simplify sign and encrypt callbacks (#624)
94acf9b refactor!: verify* throws (#632)
035f169 refactor!: remove more chain wrappers (#636)
1863827 feat!: remove 40+ basic chain wrappers (#613)
2cc953d feat!: presentations (#618)
b224e0e feat!: replace checkValidity with query + assertions (#623)
b4c8cbb feat: streamline resolution of DIDs, keys, endpoints (#607)
c423069 refactor!: do not auto-manage api connection (#622)
8e04b18 feat!: remove all compression & decompression (#616)
ccb8475 feat!: rename DidDetails to DidDocument (#620)
c396dc3 feat!: better account linking (#605)
14dd33b feat(message)!: separate verify function (#611)
1649262 feat: convert Message to functional style (#597)
fd16f7b feat!: replace function calls with map lookups (#604)
4f4006f feat!: remove identifier from DidDetails (#600)
208986e feat!: replace resolver with resolve (#599)
5035c24 feat!: drop keySelection (#598)
7226fe3 feat!: DID classes -> Document* + functions (#585)
1291aa9 refactor: did enum types (#582)
e3adf83 feat!: remove Did...

0.29.0-rc.4

What's Changed

• fix: DID API types by @wischli in #670

Full Changelog: 0.29.0-rc.3...0.29.0-rc.4