Releases: KILTprotocol/sdk-js
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
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
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 thecreator
and thecreatedAt
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. Useinit({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
andallowUpgraded
) to theverifyDidSignature
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 credentialrootHash
and theclaimerDid
. 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 asverifyAttesterSignedQuote
fail ifclaimerSignature
andclaimerDid
orattesterSignature
andattesterDid
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
andallowUpgraded
) to theverifyDidSignature
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 credentialrootHash
to the set of signed data in quote agreements; add averifyQuoteAgreement
to verify these signatures. - Make sure quote verification fails if
claimerSignature
andclaimerDid
orattesterSignature
andattesterDid
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 askeyRelationships
)VerificationKeyType
(values asverificationKeyTypes
)EncryptionKeyType
(values asencryptionKeyTypes
)
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 DidDocument
s 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 IAttestation
s 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...