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 DidBatcher (#581)
99e7086 feat!: request for attestation -> credential (#563)
ad7736b fix!: rename service endpoint URLs to URIs (#569)
3c97bba feat!: idiomatic consistent errors (#577)
9b993ed feat: remove enums (#574)
903f1b7 feat: remove Keystore (#555)
471ee37 feat: remove Blockchain class and re-signing (#549)
0d9adf1 feat: no classes for core types (#471)

Full Changelog: 0.28.3...0.29.0