doc: w3n query

code_examples/sdk_examples/src/core_features/web3names/02_query_did_name.ts

@@ -1,21 +1,16 @@
-import { assert } from 'console'
-
 import * as Kilt from '@kiltprotocol/sdk-js'
 
-export async function verifyNameAndDidEquality(
-  web3Name: Kilt.Did.Web3Name,
-  did: Kilt.DidUri
-): Promise<void> {
+export async function queryDidDocument(
+  web3Name: Kilt.Did.Web3Name
+): Promise<Kilt.DidDocument> {
   const api = Kilt.ConfigService.get('api')
 
-  console.log(
-    `Querying the blockchain for the web3name "${web3Name}" and the DID "${did}"...`
-  )
+  console.log(`Querying the blockchain for the web3name "${web3Name}"`)
   // Query the owner of the provided web3name.
   const encodedWeb3NameOwner = await api.call.did.queryByWeb3Name(web3Name)
-  const {
-    document: { uri }
-  } = Kilt.Did.linkedInfoFromChain(encodedWeb3NameOwner)
-  // Assert that it is the right owner.
-  assert(uri === did)
+
+  // Extract the DidDocument and other linked information from the encodedWeb3NameOwner.
+  const { document } = Kilt.Did.linkedInfoFromChain(encodedWeb3NameOwner)
+
+  return document
 }

code_examples/sdk_examples/src/core_features/web3names/index.ts

@@ -5,10 +5,10 @@ import * as Kilt from '@kiltprotocol/sdk-js'
 
 import { claimWeb3Name } from './01_claim'
 import { createSimpleFullDid } from '../did/04_full_did_simple'
+import { queryDidDocument } from './02_query_did_name'
 import { queryPublishedCredentials } from './03_query_name_credentials'
 import { reclaimWeb3NameDeposit } from './05_reclaim_deposit'
 import { releaseWeb3Name } from './04_release'
-import { verifyNameAndDidEquality } from './02_query_did_name'
 
 import { generateKeypairs } from '../utils/generateKeypairs'
 
@@ -40,7 +40,11 @@ export async function runAll(
     })
   )
   console.log('2 w3n) Verify web3name owner and DID web3name')
-  await verifyNameAndDidEquality(randomWeb3Name, fullDid.uri)
+  const doc = await queryDidDocument(randomWeb3Name)
+  if (doc.uri !== fullDid.uri) {
+    throw new Error('web3name is registered for a wrong DID')
+  }
+
   console.log('3 w3n) Query credentials for "john_doe" web3name')
   try {
     await queryPublishedCredentials('john_doe')

docs/develop/01_sdk/02_cookbook/02_web3names/03_release.md

@@ -10,14 +10,39 @@ import ReclaimDeposit from '!!raw-loader!@site/code_examples/sdk_examples/src/co
 
 If a web3name is no longer needed, either the DID owner or the deposit payer can release it, with deposit being released and returned to the original payer.
 
+## Releasing a Web3name by the DID Owner
+
 In the case of the DID owner willing to release the web3name, the following snippet provides a reference implementation on how to achieve that.
 
 <TsJsBlock>
   {Release}
 </TsJsBlock>
 
+In the code above, the `releaseWeb3Name` function takes the following parameters:
+
+* **did**: The DID URI of the owner.
+* **submitterAccount**: The keyring pair of the submitter.
+* **signCallback**: The sign extrinsic callback function. This function is used to sign the extrinsic, read more that in [the SignCallback section](../07_signCallback.md).
+
+The function `releaseWeb3Name` uses the KILT SDK to create a *web3name release transaction* using `api.tx.web3Names.releaseByOwner`.
+It then authorizes the transaction using the `Kilt.Did.authorizeTx` method and submits the authorized transaction to the blockchain using `Kilt.Blockchain.signAndSubmitTx`.
+This process ensures that the release transaction is signed by the DID owner.
+
+
+## Reclaiming a Web3name Deposit by the Deposit Payer
+
 If the web3name is being released by the deposit payer, the signature of the DID owner is not required; a regular signed extrinsic can be submitted to the KILT blockchain, as shown below.
 
 <TsJsBlock>
   {ReclaimDeposit}
-</TsJsBlock>
+</TsJsBlock>
+
+In the code above, the `reclaimWeb3NameDeposit` function takes the following parameters:
+
+* **submitterAddress**: The keyring pair of the submitter.
+* **web3Name**: The web3name for which the deposit is to be reclaimed.
+
+The function creates a web3name deposit reclaim transaction using `api.tx.web3Names.reclaimDeposit` and submits the signed transaction to the blockchain using `Kilt.Blockchain.signAndSubmitTx`.
+Since the web3name is being released by the deposit payer, the signature of the DID owner is not required.
+
+By using these code examples, you can easily release or reclaim the deposit of a web3name, depending on the scenario and the role of the entity initiating the release.

docs/develop/01_sdk/02_cookbook/02_web3names/04_query.md

@@ -0,0 +1,24 @@
+---
+id: web3name-query
+title: Resolve a web3name
+---
+
+import TsJsBlock from '@site/src/components/TsJsBlock';
+
+import QueryDid from '!!raw-loader!@site/code_examples/sdk_examples/src/core_features/web3names/02_query_did_name.ts';
+
+
+A web3name can be resolved in a similar manner to [how a DID is resolved](../01_dids/04_did_query.md).
+Resolving the web3name will provide the same information as resolving a DID does.
+
+To query and retrieve the DID document associated with a web3name, you can use the following code example:
+
+
+<TsJsBlock>
+  {QueryDid}
+</TsJsBlock>
+
+In the code example above, the `queryDidDocument` function takes a web3Name parameter, which represents the web3name to be resolved.
+It internally uses the `api.call.did.queryByWeb3Name` method to query the information of the provided web3name from the blockchain.
+
+The function then decodes the result using `Kilt.Did.linkedInfoFromChain` to extract the associated DID document and any other linked blockchain accounts. Finally, it returns the resolved DID document.