Skip to main content

Dapp developer

DIP feature support
  • 1.13.0 Peregrine
  • 1.12.1 Peregrine

    • The Decentralized Identity Provider (DIP) SDK helps Dapp developers build DIP functionality into their apps.

    Installation​

    Add the SDK as a dependency:

    npm install @kiltprotocol/dip-sdk

    Import the SDK into your code:

    import { * } from '@kiltprotocol/dip-sdk'

    Example application​

    This example application walks through the code you can find in the tests for the DIP SDK.

    1. Generate a base proof​

    Start by generating the base proof for the DIP using the [generateDipSiblingBaseProof](https://kiltprotocol.github.io/dip-sdk/functions/generateDipSiblingBaseProof.html) method and passing the desired configuration:

    const baseDipProof = await DipSdk.generateDipSiblingBaseProof(config)
    What's a base proof?

    A base proof is a cross-chain state proof, revealing the parts of a DID Document stored on the KILT blockchain.

    The configuration for the base proof takes the following parameters:

    • didUri: (Required) The DID URI of the DIP subject performing the cross-chain operation. For example, did:kilt:4q4QzFTs9hKh4QizLB3B7zuGYCG3QPamiBFEgwM6gTM7gK3g
    • keyIds: (Required) An array of verification method IDs of the DID revealed in the cross-chain operation.
    • proofVersion: (Required) The version of the DIP proof to generate. Currently only supports version 1.
    • blockNumber: The block number of the relay chain to use for the generation of the DIP proof. If not provided, uses the last finalized block.
    • linkedAccounts: An array of account addresses linked to the DID to reveal in the generated proof.
    • web3Name: Whether to reveal the web3name of the DID subject in the generated proof.

    In the example code, the configuration also has extra parameters for the time-bound DID signature extension mentioned below.

    The configuration also has details of the provider, which in this case uses a value populated from an environment variable:

    const providerAddress = `ws://127.0.0.1:${process.env['PROVIDER_ALICE_RPC']}`

    2. Generate a submittable extrinsic​

    The method returns the DID base proof. You have to call a second method, the [generateDipSubmittableExtrinsic](https://kiltprotocol.github.io/dip-sdk/functions/generateDipSubmittableExtrinsic.html) method to generate a submittable extrinsic that includes the generated proof.

    You need to pass the following parameters:

    • The API of the consumer chain.
    • The base proof.
    • The call to the consumer chain.
    • The DID URI.
    Submittable extrinsics

    A transaction that originates from an external account and affects the state of the blockchain. An extrinisc executes actions on the network, such as transferring funds, making governance decisions, using functionality of the parachain, or interacting with smart contracts.

    const dipSubmittable = DipSdk.generateDipSubmittableExtrinsic({
        api: consumerApi,
        baseDipProof,
        call,
        didUri: did.uri,
    })

    The method returns the different components of the proof, which you can see in the example code:

    • The provider head proof, which is proof of the provider parachain header on the relay chain.
    • The commitment proof, which proves the DIP commitment for the subject of the action, which is the DID URI.
    • The DID proof, which reveals parts of the DID document as specified by key IDs, proof version, and whether to include the web3name and any of its linked accounts.

    Behind the scenes, the method uses the dispatchAs method (and corresponding chain method) to pass the extrinsic following the consumer's type registry. You can now sign and submit to the consumer chain.

    await signAndSubmitTx(consumerApi, dipSubmittable, submitterKeypair)

    3. Linking accounts (optional)​

    Linked accounts let you specify which accounts you want to prove that you control when you make the cross-chain proof. As part of the proof provided, you can also include other values, such as the web3name.

    For all the accounts you want to link, use the associateAccountToChainArgs method, as detailed in this guide.

    You can then batch all the linked account transactions and authorize them using the authorizeTx method.

    const signedLinkedAccounts = await Kilt.Did.authorizeTx(
        newFullDidUri,
        providerApi.tx.utility.batchAll(linkAccountTxs),
        signCallback,
        newSubmitterKeypair.address as KiltAddress,
        { txCounter: new BN(4) }
    )

    Creating extensions for specific proofs​

    If you need a specific proof type for a consumer chain, then a chain developer needs to submit a PR to the SDK repository in the src > dipProof > extensions folder. The extension included with the SDK adds support for a time-bound DID signature, i.e., a signature which is valid only until a certain block number on the consumer chain.

    The extension can take any form, but must return a SCALE encoded object. There's an example of how the extension does this on GitHub.

    To add the extension, use the generateDipSubmittableExtrinsic method and pass the additional proof elements along with consumer chain specific components.

    const dipSubmittable = DipSdk.generateDipSubmittableExtrinsic({
        additionalProofElements:
            DipSdk.dipProof.extensions.timeBoundDidSignature.toChain(
                crossChainDidSignature
            ),
        api: consumerApi,
        baseDipProof,
        call,
        didUri: did.uri,
    })
    info

    Read the auto-generated API documentation for more details on the methods the SDK provides.