feat: new runtime API for unique linking (#787)

Part of KILTprotocol/ticket#3650, based on top
of #784. Last bit of
required functionality.

## Features

* Since it's not possible to batch multiple runtime API calls, I
introduced a `batch_` version for our old `did` runtime API, which
allows to do batching instead of firing one request per lookup
* Similarly to that, I introduced a new runtime API (since it's not
possible to implement the same API twice for the same runtime), which
resolves an account given a name, or a name given an account. This new
API also provides a batched version to resolve multiple names or
addresses at once. This was one of the requirements we got from Parity
to make the solution easier to integrate in the mobile app

## How to test

Polkadot Apps support new runtime APIs out of the box. So just compile
Peregrine or Spiritnet runtime and spin up a network with Chopsticks.
Then:

1. Create a new account-controlled DID. For the Sudo key, use this call
`0x401003921cbc0ffe09a865dbf4ae1d0410aa17c656881fe86666da0f97939e3701b674`
2. Claim a new dotname. For the Sudo key, use this call
`0x400f921cbc0ffe09a865dbf4ae1d0410aa17c656881fe86666da0f97939e3701b674490020746573742e646f74`
3. Link the Sudo account to the DID. Use this call
`0x400f921cbc0ffe09a865dbf4ae1d0410aa17c656881fe86666da0f97939e3701b6744a01`
4. Call the runtime API `uniqueLinking.addressForName("test.dot")` which
should return
```
{
  Ok: {
    address: {
      AccountId32: 4rDeMGr3Hi4NfxRUp8qVyhvgW3BSUBLneQisGa9ASkhh2sXB
    }
    extra: 4rDeMGr3Hi4NfxRUp8qVyhvgW3BSUBLneQisGa9ASkhh2sXB
  }
}
```
5. Call the runtime API `uniqueLinking.nameForAddress({AccountId32:
"4rDeMGr3Hi4NfxRUp8qVyhvgW3BSUBLneQisGa9ASkhh2sXB"})` which should
return
```
{
  Ok: {
    name: test.dot
    extra: 4rDeMGr3Hi4NfxRUp8qVyhvgW3BSUBLneQisGa9ASkhh2sXB
  }
}
```

Author: ntn-x2

Cargo.lock

@@ -87,6 +87,7 @@ kilt-runtime-api-dip-provider       = { path = "runtime-api/dip-provider", defau
 kilt-runtime-api-public-credentials = { path = "runtime-api/public-credentials", default-features = false }
 kilt-runtime-api-staking            = { path = "runtime-api/staking", default-features = false }
 pallet-asset-switch-runtime-api     = { path = "runtime-api/asset-switch", default-features = false }
+unique-linking-runtime-api          = { path = "runtime-api/unique-linking", default-features = false }
 
 # Internal KILT runtimes (with default disabled)
 kestrel-runtime   = { path = "runtimes/kestrel", default-features = false }

Cargo.toml

@@ -660,6 +660,18 @@ impl_runtime_apis! {
 			})
 		}
 
+		fn batch_query_by_web3_name(names: Vec<Vec<u8>>) -> Vec<Option<kilt_runtime_api_did::RawDidLinkedInfo<
+				DidIdentifier,
+				AccountId,
+				LinkableAccountId,
+				Balance,
+				Hash,
+				BlockNumber
+			>
+		>> {
+			names.into_iter().map(Self::query_by_web3_name).collect()
+		}
+
 		fn query_by_account(account: LinkableAccountId) -> Option<
 			kilt_runtime_api_did::RawDidLinkedInfo<
 				DidIdentifier,
@@ -689,6 +701,19 @@ impl_runtime_apis! {
 				})
 		}
 
+		fn batch_query_by_account(accounts: Vec<LinkableAccountId>) -> Vec<Option<
+			kilt_runtime_api_did::RawDidLinkedInfo<
+				DidIdentifier,
+				AccountId,
+				LinkableAccountId,
+				Balance,
+				Hash,
+				BlockNumber
+			>
+		>> {
+			accounts.into_iter().map(Self::query_by_account).collect()
+		}
+
 		fn query(did: DidIdentifier) -> Option<
 			kilt_runtime_api_did::RawDidLinkedInfo<
 				DidIdentifier,
@@ -712,6 +737,19 @@ impl_runtime_apis! {
 				details: details.into(),
 			})
 		}
+
+		fn batch_query(dids: Vec<DidIdentifier>) -> Vec<Option<
+			kilt_runtime_api_did::RawDidLinkedInfo<
+				DidIdentifier,
+				AccountId,
+				LinkableAccountId,
+				Balance,
+				Hash,
+				BlockNumber
+			>
+		>> {
+			dids.into_iter().map(Self::query).collect()
+		}
 	}
 
 	impl kilt_runtime_api_dip_provider::DipProvider<Block, runtime_api::DipProofRequest, CompleteMerkleProof<Hash, DidMerkleProofOf<Runtime>>, runtime_api::DipProofError> for Runtime {

dip-template/runtimes/dip-provider/src/lib.rs

@@ -66,7 +66,7 @@ pub type RawDidLinkedInfo<DidIdentifier, AccountId, LinkableAccountId, Balance,
 >;
 
 sp_api::decl_runtime_apis! {
-	#[api_version(2)]
+	#[api_version(3)]
 	pub trait Did<DidIdentifier, AccountId, LinkableAccountId, Balance, Key: Ord, BlockNumber: MaxEncodedLen> where
 		DidIdentifier: Codec,
 		AccountId: Codec,
@@ -84,6 +84,9 @@ sp_api::decl_runtime_apis! {
 		#[changed_in(2)]
 		fn query_by_web3_name(name: Vec<u8>) -> Option<RawDidLinkedInfo<DidIdentifier, AccountId, AccountId, Balance, Key, BlockNumber>>;
 		fn query_by_web3_name(name: Vec<u8>) -> Option<RawDidLinkedInfo<DidIdentifier, AccountId, LinkableAccountId, Balance, Key, BlockNumber>>;
+		/// Allows for batching multiple `query_by_web3_name` requests into one. For each requested name, the corresponding vector entry contains either `Some` or `None` depending on the result of each query.
+		#[allow(clippy::type_complexity)]
+		fn batch_query_by_web3_name(names: Vec<Vec<u8>>) -> Vec<Option<RawDidLinkedInfo<DidIdentifier, AccountId, LinkableAccountId, Balance, Key, BlockNumber>>>;
 		/// Given an account address this returns:
 		/// * the DID
 		/// * public keys stored for the did
@@ -93,6 +96,9 @@ sp_api::decl_runtime_apis! {
 		#[changed_in(2)]
 		fn query_by_account(account: AccountId) -> Option<RawDidLinkedInfo<DidIdentifier, AccountId, AccountId, Balance, Key, BlockNumber>>;
 		fn query_by_account(account: LinkableAccountId) -> Option<RawDidLinkedInfo<DidIdentifier, AccountId, LinkableAccountId, Balance, Key, BlockNumber>>;
+		/// Allows for batching multiple `query_by_account` requests into one. For each requested name, the corresponding vector entry contains either `Some` or `None` depending on the result of each query.
+		#[allow(clippy::type_complexity)]
+		fn batch_query_by_account(accounts: Vec<LinkableAccountId>) -> Vec<Option<RawDidLinkedInfo<DidIdentifier, AccountId, LinkableAccountId, Balance, Key, BlockNumber>>>;
 		/// Given a did this returns:
 		/// * the DID
 		/// * public keys stored for the did
@@ -102,5 +108,8 @@ sp_api::decl_runtime_apis! {
 		#[changed_in(2)]
 		fn query(did: DidIdentifier) -> Option<RawDidLinkedInfo<DidIdentifier, AccountId, AccountId, Balance, Key, BlockNumber>>;
 		fn query(did: DidIdentifier) -> Option<RawDidLinkedInfo<DidIdentifier, AccountId, LinkableAccountId, Balance, Key, BlockNumber>>;
+		/// Allows for batching multiple `query` requests into one. For each requested name, the corresponding vector entry contains either `Some` or `None` depending on the result of each query.
+		#[allow(clippy::type_complexity)]
+		fn batch_query(dids: Vec<DidIdentifier>) -> Vec<Option<RawDidLinkedInfo<DidIdentifier, AccountId, LinkableAccountId, Balance, Key, BlockNumber>>>;
 	}
 }

runtime-api/did/src/lib.rs

@@ -0,0 +1,24 @@
+[package]
+authors       = { workspace = true }
+description   = "Runtime APIs for integrating the unique-lookup capabilities."
+documentation = { workspace = true }
+edition       = { workspace = true }
+homepage      = { workspace = true }
+license-file  = { workspace = true }
+name          = "unique-linking-runtime-api"
+readme        = { workspace = true }
+repository    = { workspace = true }
+version       = { workspace = true }
+
+[dependencies]
+# External dependencies
+parity-scale-codec = { workspace = true }
+scale-info         = { workspace = true }
+
+# Substrate dependencies
+sp-api = { workspace = true }
+sp-std = { workspace = true }
+
+[features]
+default = ["std"]
+std     = ["parity-scale-codec/std", "scale-info/std", "sp-api/std", "sp-std/std"]

runtime-api/unique-linking/Cargo.toml

@@ -0,0 +1,60 @@
+// KILT Blockchain – https://botlabs.org
+// Copyright (C) 2019-2024 BOTLabs GmbH
+
+// The KILT Blockchain is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// The KILT Blockchain is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+// If you feel like getting in touch with us, you can do so at [email protected]
+
+#![cfg_attr(not(feature = "std"), no_std)]
+
+use parity_scale_codec::{Codec, Decode, Encode};
+use scale_info::TypeInfo;
+use sp_std::vec::Vec;
+
+#[derive(Encode, Decode, TypeInfo)]
+pub struct AddressResult<Address, Extra> {
+	address: Address,
+	extra: Option<Extra>,
+}
+
+impl<Address, Extra> AddressResult<Address, Extra> {
+	pub const fn new(address: Address, extra: Option<Extra>) -> Self {
+		Self { address, extra }
+	}
+}
+
+#[derive(Encode, Decode, TypeInfo)]
+pub struct NameResult<Name, Extra> {
+	name: Name,
+	extra: Option<Extra>,
+}
+
+impl<Name, Extra> NameResult<Name, Extra> {
+	pub const fn new(name: Name, extra: Option<Extra>) -> Self {
+		Self { name, extra }
+	}
+}
+
+sp_api::decl_runtime_apis! {
+	pub trait UniqueLinking<Address, Name, Extra> where
+		Address: Codec,
+		Name: Codec,
+		Extra: Codec,
+		{
+			fn address_for_name(name: Name) -> Option<AddressResult<Address, Extra>>;
+			fn batch_address_for_name(names: Vec<Name>) -> Vec<Option<AddressResult<Address, Extra>>>;
+			fn name_for_address(address: Address) -> Option<NameResult<Name, Extra>>;
+			fn batch_name_for_address(addresses: Vec<Address>) -> Vec<Option<NameResult<Name, Extra>>>;
+		}
+}

runtime-api/unique-linking/src/lib.rs

@@ -1034,6 +1034,18 @@ impl_runtime_apis! {
 			})
 		}
 
+		fn batch_query_by_web3_name(names: Vec<Vec<u8>>) -> Vec<Option<kilt_runtime_api_did::RawDidLinkedInfo<
+				DidIdentifier,
+				AccountId,
+				LinkableAccountId,
+				Balance,
+				Hash,
+				BlockNumber
+			>
+		>> {
+			names.into_iter().map(Self::query_by_web3_name).collect()
+		}
+
 		fn query_by_account(account: LinkableAccountId) -> Option<
 			kilt_runtime_api_did::RawDidLinkedInfo<
 				DidIdentifier,
@@ -1063,6 +1075,19 @@ impl_runtime_apis! {
 				})
 		}
 
+		fn batch_query_by_account(accounts: Vec<LinkableAccountId>) -> Vec<Option<
+			kilt_runtime_api_did::RawDidLinkedInfo<
+				DidIdentifier,
+				AccountId,
+				LinkableAccountId,
+				Balance,
+				Hash,
+				BlockNumber
+			>
+		>> {
+			accounts.into_iter().map(Self::query_by_account).collect()
+		}
+
 		fn query(did: DidIdentifier) -> Option<
 			kilt_runtime_api_did::RawDidLinkedInfo<
 				DidIdentifier,
@@ -1086,6 +1111,19 @@ impl_runtime_apis! {
 				details: details.into(),
 			})
 		}
+
+		fn batch_query(dids: Vec<DidIdentifier>) -> Vec<Option<
+			kilt_runtime_api_did::RawDidLinkedInfo<
+				DidIdentifier,
+				AccountId,
+				LinkableAccountId,
+				Balance,
+				Hash,
+				BlockNumber
+			>
+		>> {
+			dids.into_iter().map(Self::query).collect()
+		}
 	}
 
 	impl kilt_runtime_api_public_credentials::PublicCredentials<Block, Vec<u8>, Hash, public_credentials::CredentialEntry<Hash, DidIdentifier, BlockNumber, AccountId, Balance, AuthorizationId<<Runtime as delegation::Config>::DelegationNodeId>>, PublicCredentialsFilter<Hash, AccountId>, PublicCredentialsApiError> for Runtime {

runtimes/kestrel/src/lib.rs

@@ -33,6 +33,7 @@ kilt-runtime-api-public-credentials        = { workspace = true }
 kilt-runtime-api-staking                   = { workspace = true }
 pallet-asset-switch-runtime-api            = { workspace = true }
 pallet-transaction-payment-rpc-runtime-api = { workspace = true }
+unique-linking-runtime-api                 = { workspace = true }
 
 # KILT pallets & primitives
 attestation                   = { workspace = true }
@@ -247,6 +248,7 @@ std = [
   "sp-transaction-pool/std",
   "sp-version/std",
   "sp-weights/std",
+  "unique-linking-runtime-api/std",
   "xcm-builder/std",
   "xcm-executor/std",
   "xcm/std",