Skip to main content

DID

create(name, address, seed, customDocumentFields)

Parameters:

  • name REQUIRED <string>: DID name.

  • address <string>: DID address that is used to call the extrinsic.

  • seed <string>: seed phrase where keyring is derived.

  • customDocumentFields <Object>: used to set verification methods, signatures, and services.

NOTE

If the user has already passed the seed at the time of creating the SDK instance, then it is not necessary to pass it again at the time of creating the DID. The Keypair which is used to sign transactions is derived from this phrase. The address parameter is obtained through this same Keyring, so it can be omitted. If the case arises where you'd like to use a different seed or address when creating the DID, this function offers the option to set it manually.

NOTE

Must add tokens to your wallet address in order to execute write functions. See Get $AGUNG tokens for more details.

This function creates a DID (i.e. DIDs, MachineIds, peaqIDs) based on provided parameters. Function returns the block hash the extrinsic was executed at.

Code example

// Use previously stated imports as referenced in SDK Quickstart

const createDID = async (sdk, nameDID) => {
const block_hash = await sdk.did.create({name: nameDID});
return block_hash;
};

// Example usage
const main = async () => {
const nameDID = 'myDID';
// see SDK Quickstart for createSdkInstance() function
const sdk = await createSdkInstance();
await sdk.connect();

try {
const hash = await createDID(sdk, nameDID);
console.log(hash);
}
catch(error) {
console.error(`Failed to create SDK instance: ${error}`);
throw error;
}
finally {
await sdk.disconnect();
}
};

main();

Response object

{
"block_hash": "0xc3951eb57b075de3d97dca930bec1c836fc07700469a05402d5ae3e1ab124b1c",
"unsubscribe": [Function (anonymous)]
}

INFORMATION
  • block_hash The hash of the block the transaction was executed on. For more information about that particular block you can go on our Subscan Explorer (for the proper chain) and search for the block hash.

  • unsubscribe Object is a function that you can call to stop listening to further status updates for the transaction. This is useful when you want to manage resources and avoid receiving updates once you've obtained the necessary information or if the operation is completed.

read(name, address)

Parameters:

  • name REQUIRED <string>: name of DID.

  • address : user wallet address of the entity that created the DID.

This function retrieves information linked to a registered DID on the blockchain. Returns json object with DID information.

NOTE

If the user has already passed the seed at the time of creating the SDK instance, then it is not necessary to pass address when reading DID. Unless the user would like to read a known DID at a known Address for verification flow.

Code example

// Use previously stated imports as referenced in SDK Quickstart

const readDID = async (sdk, nameDID) => {
const did = await sdk.did.read({name: nameDID});
return did;
};

// Example usage
const main = async () => {
// see SDK Quickstart for createSdkInstance() function
const nameDID = 'myDID';
const sdk = await createSdkInstance();
await sdk.connect();

try {
const did = await readDID(sdk, nameDID);
console.log(did);
}
catch (error) {
console.error(`Failed to read DID with error: ${error}`);
throw error;
}
finally {
await sdk.disconnect();
}
};

main();

Response object

{
"name": "myDID",
"value": "0x0a39646.....1325067",
"validity": "4,294,967,295",
"created": "1,724,745,822,024",
"document": {
"id": "did:peaq:5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg",
"controller": "did:peaq:5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg",
"verificationMethods": [],
"signature": undefined,
"services": [],
"authentications": []
}
}

INFORMATION
  • name The name of the DID given when creating the DID. This is a human-readable name that can be used to identify the DID on-chain.

  • value The value of a peaq DID is a hash of the peaq DID document. The peaq DID document contains the DID name and the user's public address, among other information.

  • created Provides a timestamp for when the DID was added to the blockchain.

  • document

    • id peaq DID followed by user public address.

    • controller The controller of the DID. This is the DID of the entity that has control over the DID, and can make updates or revoke the DID if necessary.

    • verificationMethods Set of parameters used to verify a proof.

    • signature Holds the signature that is used in the verification process.

    • services Customizable parameter that can be used to contain off-chain storage endpoints, link machines, etc.

    • authentications Pointer to identify which verification method held in the DID Document has been used for validation.

In order to use the DID Document to cater to your needs customDocumentFields must be set.

customDocumentFields(prefix, controller, verifications, signature, services)

The customDocumentFields parameter, referenced earlier in the create() example, is an optional argument that links additional information to your DID document. The DID we created in the previous example contains no initial values, so it's crucial to understand how the customDocumentFields object works to make your DID functional.

Parameters:

  • prefix <string>: Used to create a customizable URI for your DID Document's id and controller. The resulting format will be did:[custom_prefix]:[machineAddress].

  • controller <string>: Allows the creator of the DID to set a new controller with the authority to update the existing DID Document. The controller must be either an SS58 or Ethereum Address.

  • verifications <Verification[]>: Specifies the signature scheme used for creating a signature. The available options are Ed25519VerificationKey2020 or Sr25519VerificationKey2020, methods derived from the Polkadot Keyring object. You can also custom set the publicKeyMultibase in the verification object (e.g. verification: [{type: Ed25519VerificationKey2020, publicKeyMultibase: 'z12345'}]), if there is a certain base you would like to resolve to. Otherwise by default the public address will be encoded using base64 encoding.

  • signature <Signature>: Defines the type of signature used, the issuer of the signature, and the hash employed for verification.

  • services <Service[]>: User-defined services that establish connections utilized by your DID.

Code example

// Use previously stated imports as referenced in SDK Quickstart

const createDID = async (sdk, nameDID) => {
const mongoID = '123';
const customFields = {
prefix: 'custom_prefix',
controller: '5FEw7aWmqcnWDaMcwjKyGtJMjQfqYGxXmDWKVfcpnEPmUM7q',
verifications: [
{
type: 'Ed25519VerificationKey2020'
}
],
signature: {
type: 'Ed25519VerificationKey2020',
issuer: '5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg',
hash: '0x12345'
},
services: [
{
id: '#mongoDBConnection',
type: 'yourDataBaseName',
serviceEndpoint: 'mongodb://localhost:27017',
data: 'yourCollectionName'
},
{
id: '#mongoDBIdentifier',
type: 'mongoID',
serviceEndpoint: 'mongodb://localhost:27017',
data: mongoID
},
]
}

const block_hash = await sdk.did.create({name: nameDID, customDocumentFields: customFields});
return block_hash;
};

const readDID = async (sdk, nameDID) => {
const did = await sdk.did.read({name: nameDID});
return did;
};

// Example usage
const main = async () => {
const nameDID = 'myDID';
// see SDK Quickstart for createSdkInstance() function
const sdk = await createSdkInstance();
await sdk.connect();

try {
const hash = await createDID(sdk, nameDID);
const did = await readDID(sdk, nameDID);
console.log(did.document);
}
catch(error) {
console.error(`Failed to create SDK instance: ${error}`);
throw error;
}
finally {
await sdk.disconnect();
}
};

main();

INFORMATION

The example above demonstrates how to configure the customDocumentFields parameter when creating a DID Document.

  • Prefix A custom prefix is set to alter the URI format of the DID Document's id and controller. This customization enables the creation of a DID that fits specific organizational or application needs, ensuring a unique namespace within the DID ecosystem.

  • Controller The controller field is manually set to a specific wallet address. This address now has the authority to make updates to the DID Document. This capability is essential in scenarios where control over the DID needs to be delegated or transferred.

  • Verifications The verification method is specified as Ed25519VerificationKey2020, indicating that the DID Document utilizes the Ed25519 cryptographic algorithm to generate a signature. This method is widely recognized and supported within the DID community, ensuring strong cryptographic security. The corresponding signature is then defined in the signature field, where the method type (Ed25519VerificationKey2020), the issuer’s address, and the signature hash are all provided. It is crucial that the verification method type matches the signature type to ensure consistency and proper validation of the DID Document.

  • Services The services field is used to define connections to external, off-chain services. In this example, the DID Document includes two services:

    1. A MongoDB connection #mongoDBConnection with a specified service endpoint (mongodb://localhost:27017). This service could be used to store or retrieve data related to the DID, such as metadata or associated records.

    2. A MongoDB identifier #mongoDBIdentifier linked to a specific MongoDB document (mongoID), allowing for seamless interaction between the DID and the MongoDB database. These services enable the DID to interact with off-chain resources, facilitating the secure exchange of data between decentralized identifiers and centralized databases. By utilizing cryptographic methods, the DID ensures that the data stored or accessed via these services is verifiable and trustworthy.


DID Document Response object from read()

{
"id": "did:custom_prefix:5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg",
"controller": "did:custom_prefix:5FEw7aWmqcnWDaMcwjKyGtJMjQfqYGxXmDWKVfcpnEPmUM7q",
"verificationMethods": [
{
"id": "did:custom_prefix:5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg#keys-1",
"type": "Ed25519VerificationKey2020",
"controller": "did:custom_prefix:5FEw7aWmqcnWDaMcwjKyGtJMjQfqYGxXmDWKVfcpnEPmUM7q",
"publicKeyMultibase": "466e7d57daf5d7176c3afce9ddf8e26b3670c932476f270cec0f625274788e23"
}
],
"signature": {
"type": "Ed25519VerificationKey2020",
"issuer": "5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg",
"hash": "0x12345"
},
"services": [
{
"id": "#mongoDBConnection",
"type": "yourDataBaseName",
"serviceEndpoint": "mongodb://localhost:27017",
"data": "yourCollectionName"
},
{
"id": "#mongoDBIdentifier",
"type": "mongoID",
"serviceEndpoint": "mongodb://localhost:27017",
"data": "123"
}
],
"authentications": [
"did:custom_prefix:5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg#keys-1"
]
}

update(name, address, seed, customDocumentFields)

Parameters:

  • name REQUIRED <string>: DID name.

  • address <string>: DID address that is used to call the extrinsic.

  • seed <string>: seed phrase where keyring is derived.

  • customDocumentFields <Object>: used to set verification methods, signatures, and services.

The update() function allows users to modify an existing DID Document by setting new fields or updating existing ones. This is particularly useful when you need to change the controller, add new verification methods, or link additional services.

CAUTION

When using the update() function, the previous DID Document will be completely overwritten by the new configuration specified in customDocumentFields. It is essential to ensure that all necessary fields are included in the update to maintain the integrity and usability of the DID Document.

Code Example

The following code demonstrates how to create an initial DID with no fields set, update the DID with custom fields as described in the earlier example, and then perform a read operation to confirm that the DID Document was successfully updated.

// Use previously stated imports as referenced in SDK Quickstart

const createDID = async (sdk, nameDID) => {
const block_hash = await sdk.did.create({name: nameDID});
return block_hash;
};

const updateDID = async (sdk, nameDID) => {
const mongoID = '123';
const customFields = {
prefix: 'custom_prefix',
controller: '5FEw7aWmqcnWDaMcwjKyGtJMjQfqYGxXmDWKVfcpnEPmUM7q',
verifications: [
{
type: 'Ed25519VerificationKey2020'
}
],
signature: {
type: 'Ed25519VerificationKey2020',
issuer: '5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg',
hash: '0x12345'
},
services: [
{
id: '#mongoDBConnection',
type: 'yourDataBaseName',
serviceEndpoint: 'mongodb://localhost:27017',
data: 'yourCollectionName'
},
{
id: '#mongoDBIdentifier',
type: 'mongoID',
serviceEndpoint: 'mongodb://localhost:27017',
data: mongoID
},
]
}

const block_hash = await sdk.did.update({name: nameDID, customDocumentFields: customFields});
return block_hash;
};

const readDID = async (sdk, nameDID) => {
const did = await sdk.did.read({name: nameDID});
return did;
};

// Example usage
const main = async () => {
const nameDID = 'myDID';
// see SDK Quickstart for createSdkInstance() function
const sdk = await createSdkInstance();
await sdk.connect();

try {
const hash = await createDID(sdk, nameDID);
const update_hash = await updateDID(sdk, nameDID);
const did = await readDID(sdk, nameDID);
console.log(did.document);
}
catch(error) {
console.error(`Failed to create SDK instance: ${error}`);
throw error;
}
finally {
await sdk.disconnect();
}
};

main();

Response object: The update() method returns the same object as the create() method, along with a log message confirming the update.

{
"log": "Successfully updated the DID Document of name myDID at address 5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg",
"block_hash": "0x195383694776f46fc466afd535155fa3baf400b4c1da0dfdb2ddc7da431bb30f",
"unsubscribe": [Function (anonymous)]
}

DID Document after update() from read() Response Object

{
"id": "did:custom_prefix:5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg",
"controller": "did:custom_prefix:5FEw7aWmqcnWDaMcwjKyGtJMjQfqYGxXmDWKVfcpnEPmUM7q",
"verificationMethods": [
{
"id": "did:custom_prefix:5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg#keys-1",
"type": "Ed25519VerificationKey2020",
"controller": "did:custom_prefix:5FEw7aWmqcnWDaMcwjKyGtJMjQfqYGxXmDWKVfcpnEPmUM7q",
"publicKeyMultibase": "466e7d57daf5d7176c3afce9ddf8e26b3670c932476f270cec0f625274788e23"
}
],
"signature": {
"type": "Ed25519VerificationKey2020",
"issuer": "5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg",
"hash": "0x12345"
},
"services": [
{
"id": "#mongoDBConnection",
"type": "yourDataBaseName",
"serviceEndpoint": "mongodb://localhost:27017",
"data": "yourCollectionName"
},
{
"id": "#mongoDBIdentifier",
"type": "mongoID",
"serviceEndpoint": "mongodb://localhost:27017",
"data": "123"
}
],
"authentications": [
"did:custom_prefix:5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg#keys-1"
]
}

remove(name, address, seed)

Parameters:

  • name REQUIRED <string>: DID name.

  • address <string>: DID address that is used to call the extrinsic.

  • seed <string>: seed phrase where keyring is derived.

The remove() function is used to delete an existing DID Document from the blockchain. This method is essential for scenarios where a DID is no longer needed, such as when the associated entity is deprecated, replaced, or when the data is no longer relevant.

CAUTION

Important Considerations:

  • Irreversibility: Once a DID is removed using this method, the associated DID Document is permanently deleted and cannot be recovered. Ensure that the removal is intentional and that there is no future need for the DID.

  • Impact on Services: Deleting a DID Document will also impact any services, verifications, or relationships associated with it. Any off-chain services or applications relying on this DID will no longer be able to validate or interact with it.

Code Example

The following code demonstrates how to create a DID, remove it, and then log the result of the removal operation.

// Use previously stated imports as referenced in SDK Quickstart

const createDID = async (sdk, nameDID) => {
const block_hash = await sdk.did.create({name: nameDID});
return block_hash;
};

const removeDID = async (sdk, nameDID) => {
const block_hash = await sdk.did.remove({name: nameDID});
return block_hash;
};

// Example usage
const main = async () => {
const nameDID = 'myDID';
// see SDK Quickstart for createSdkInstance() function
const sdk = await createSdkInstance();
await sdk.connect();

try {
const hash = await createDID(sdk, nameDID);
const delete_hash = await removeDID(sdk, nameDID);
console.log(delete_hash);
}
catch(error) {
console.error(`Failed to create SDK instance: ${error}`);
throw error;
}
finally {
await sdk.disconnect();
}
};

main();

Response object

{
"log": "Successfully removed the DID of name myDID from address 5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg",
"block_hash": "0x78d98b64d1349b325470e0845ee79a6e2c0a32b28c4a29b683ac20222aa7273d",
"unsubscribe": [Function (anonymous)]
}

generateDidDocument(address, customDocumentFields)

Parameters:

  • address REQUIRED <string>: DID address that is used in the DID Document hash generation.

  • customDocumentFields <Object>: used to set verification methods, signatures, and services.

The generateDidDocument() function generates a cryptographic hash of a DID Document, including all the fields specified in customDocumentFields. This process does not require interaction with a blockchain and can be done entirely offline, making it ideal for pre-generating and validating DID Documents before on-chain submission.

The function can be used to ensure that all necessary fields, such as verification methods and services, are correctly formatted and included in the document. Once the hash is generated, users can utilize the EVM DID precompiled smart contract to send the hashed DID Document to the blockchain if needed.

NOTE
  • Hash Calculation: The function returns a hash representing the entire DID Document, including all custom fields. This hash can be used for integrity verification or off-chain processing.

  • No On-Chain Action: Unlike other functions that involve blockchain transactions, generateDidDocument() does not invoke any extrinsics or update the blockchain. The generated hash is purely for local use or for passing between off-chain systems.

  • Use Cases: Ideal for developers who need to pre-compute the DID Document hash before submitting it via the EVM DID precompiled smart contract. It can also be used to test DID configurations, create mock documents for development, or verify document integrity before interacting with a blockchain.

Code Example

import { Sdk } from "@peaq-network/sdk";

const generateDidHash = async () => {
// create custom fields that will be encoded in the DID Document hash
const mongoID = '123';
const customFields = {
prefix: 'custom_prefix',
controller: '5FEw7aWmqcnWDaMcwjKyGtJMjQfqYGxXmDWKVfcpnEPmUM7q',
verifications: [
{
type: 'Ed25519VerificationKey2020'
}
],
signature: {
type: 'Ed25519VerificationKey2020',
issuer: '5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg',
hash: '0x12345'
},
services: [
{
id: '#mongoDBConnection',
type: 'yourDataBaseName',
serviceEndpoint: 'mongodb://localhost:27017',
data: 'yourCollectionName'
},
{
id: '#mongoDBIdentifier',
type: 'mongoID',
serviceEndpoint: 'mongodb://localhost:27017',
data: mongoID
},
]
}

// create new offline SDK connection to generate DID Document hash
const did_hash = await Sdk.generateDidDocument({address: "5Df42mkztLtkksgQuLy4YV6hmhzdjYvDknoxHv1QBkaY12Pg", customDocumentFields: customFields})
return did_hash;
};

// Example usage
const main = async () => {
try {
const did_hash = await generateDidHash();
console.log(did_hash);
}
catch(error) {
console.error(`Failed to create SDK instance: ${error}`);
throw error;
}
};

main();

Response Object

{
"value": "0x0a426469643a637573.....615931325067236b6579732d31"
}