feat: custom runtime functions to generate deterministic Eth address from an MSA ID (#2358)

# Goal
This PR adds some internal pallet functions and custom runtime to
deterministically generate an Ethereum address from an MSA ID, and vice
versa.

The general approach is:
- Use a domain separator prefix to eliminate any possible conflict with
addresses generated by `CREATE2`
- Use a salt that is the hash of the string "MSA Generated"
- Take the last 20 bytes of the hash of `(prefix + MSA ID + salt)`
- If returning a string for the runtime query, pass through an [ERC-55
checksum
algorithm](https://github.com/ethereum/ercs/blob/master/ERCS/erc-55.md)
to alter the returned hex string

Note, although addresses generated in this manner cannot be reversed to
recover the related MSA ID, they can be verified (ie, given an address
and an MSA ID, we can determine whether or not the address is the result
of applying the above algorithm to the MSA ID). It is not envisioned
that there would ever be an _on-chain_ requirement to recover the MSA ID
from the address; if such a use case was desired for off-chain purposes,
it would be relatively trivial to populate a static lookup table mapping
all known or possible MSAs to their corresponding address, or
vice-versa.

Closes #2353 
Closes #2352 

# Discussion

- Q0: Currently returning ASCII bytes; or do we want to return the
binary address bytes?
- A: Now returning a struct containing both the binary address &
checksummed string

# Checklist
- [x] Updated Pallet Readme?
- [ ] Updated js/api-augment for Custom RPC APIs?
- [ ] Design doc(s) updated?
- [x] Unit Tests added?
- [x] e2e Tests added?
- [ ] Benchmarks added?
- [x] Spec version incremented?

Author: JoeCap08055

Cargo.lock

@@ -22,6 +22,7 @@ thiserror = "2.0.12"
 apache-avro = { version = "0.17.0", default-features = false }
 rand = "0.9.0"
 parking_lot = "0.12.1"
+lazy_static = { version = "1.5", features = ["spin_no_std"] }
 
 # substrate wasm
 parity-scale-codec = { version = "3.6.12", default-features = false }

Cargo.toml

@@ -15,6 +15,19 @@ pub use crate::schema::SchemaId;
 /// Message Source Id or msaId is the unique identifier for Message Source Accounts
 pub type MessageSourceId = u64;
 
+/// Ethereum address type alias
+pub use sp_core::H160;
+
+/// Response type for getting Ethereum address as a 20-byte array and checksummed hex string
+#[derive(TypeInfo, Encode, Decode)]
+pub struct AccountId20Response {
+	/// Ethereum address as a 20-byte array
+	pub account_id: H160,
+
+	/// Ethereum address as a checksummed 42-byte hex string (including 0x prefix)
+	pub account_id_checksummed: alloc::string::String,
+}
+
 /// A DelegatorId an MSA Id serving the role of a Delegator.
 /// Delegators delegate to Providers.
 /// Encodes and Decodes as just a `u64`

common/primitives/src/msa.rs

@@ -78,7 +78,9 @@ ignore = [
   { id = "RUSTSEC-2025-0010", reason = "Unmaintained sub-dependency: ring, pending updates to those dependencies."},
   { id = "RUSTSEC-2025-0009", reason = "Unmaintained sub-dependency: ring, pending updates to dependencies."},
   { id = "RUSTSEC-2024-0436", reason = "Unmaintained sub-dependency: paste, pending updates to dependencies."},
-  { id = "RUSTSEC-2025-0017", reason = "Renamed sub-dependency: trust-dns-proto -> hickory-proto, pending updates to dependencies."}
+  { id = "RUSTSEC-2025-0017", reason = "Renamed sub-dependency: trust-dns-proto -> hickory-proto, pending updates to dependencies."},
+  { id = "RUSTSEC-2023-0091", reason = "'Users prior to 10.0.0 are unaffected', according to the advisory; we are on 8.0.1"},
+  { id = "RUSTSEC-2024-0438", reason = "Windows only"}
 ]
 # If this is true, then cargo deny will use the git executable to fetch advisory database.
 # If this is false, then it uses a built-in git library.
@@ -107,6 +109,7 @@ allow = [
   "OpenSSL",
   "Zlib",
   "Unicode-3.0",
+  "CDLA-Permissive-2.0"
 ]
 # The confidence threshold for detecting a license from license text.
 # The higher the value, the more closely the license text must be to the

deny.toml

@@ -19,9 +19,9 @@ describe('Balance transfer ethereum', function () {
     before(async function () {
       senderSr25519Keys = await createAndFundKeypair(fundingSource, 30n * DOLLARS);
       senderEthereumKeys = await createAndFundKeypair(fundingSource, 30n * DOLLARS, undefined, undefined, 'ethereum');
-      ethereumKeys = await createKeys('another-key-1', 'ethereum');
-      ethereumKeys2 = await createKeys('another-key-2', 'ethereum');
-      sr25519Keys = await createKeys('another-sr25519', 'sr25519');
+      ethereumKeys = createKeys('another-key-1', 'ethereum');
+      ethereumKeys2 = createKeys('another-key-2', 'ethereum');
+      sr25519Keys = createKeys('another-sr25519', 'sr25519');
     });
 
     it('should transfer from sr25519 to ethereum style key', async function () {

e2e/miscellaneous/balance.ethereum.test.ts

@@ -0,0 +1,106 @@
+/* eslint-disable mocha/no-skipped-tests */
+import '@frequency-chain/api-augment';
+import assert from 'assert';
+import { ExtrinsicHelper } from '../scaffolding/extrinsicHelpers';
+import { ethereumAddressToKeyringPair } from '../scaffolding/ethereum';
+import { getFundingSource } from '../scaffolding/funding';
+import { H160 } from '@polkadot/types/interfaces';
+import { bnToU8a, hexToU8a, stringToU8a } from '@polkadot/util';
+import { KeyringPair } from '@polkadot/keyring/types';
+import { keccak256AsU8a } from '@polkadot/util-crypto';
+import { getExistentialDeposit } from '../scaffolding/helpers';
+
+const fundingSource = getFundingSource(import.meta.url);
+
+/**
+ *
+ * @param msaId
+ * @returns Ethereum address generated from the MSA ID
+ *
+ * This function generates an Ethereum address based on the provided MSA ID,
+ * using a specific hashing algorithm and a salt value, as follows:
+ *
+ * Domain prefix: 0xD9
+ * MSA ID: Big-endian bytes representation of the 64-bit MSA ID
+ * Salt: Keccak256 hash of the string "MSA Generated"
+ *
+ * Hash = keccak256(0xD9 || MSA ID bytes || Salt)
+ *
+ * Address = Hash[-20:]
+ */
+function generateMsaAddress(msaId: string | number | bigint): H160 {
+  const msa64 = ExtrinsicHelper.api.registry.createType('u64', msaId);
+  const msaBytes = bnToU8a(msa64.toBn(), { isLe: false, bitLength: 64 });
+  const salt = keccak256AsU8a(stringToU8a('MSA Generated'));
+  const combined = new Uint8Array([0xd9, ...msaBytes, ...salt]);
+  const hash = keccak256AsU8a(combined);
+
+  return ExtrinsicHelper.api.registry.createType('H160', hash.slice(-20));
+}
+
+describe('MSAs Holding Tokens', function () {
+  const MSA_ID_1234 = 1234; // MSA ID for testing
+  const CHECKSUMMED_ETH_ADDR_1234 = '0x65928b9a88Db189Eea76F72d86128Af834d64c32'; // Checksummed Ethereum address for MSA ID 1234
+  let ethKeys: KeyringPair;
+  let ethAddress20: H160;
+
+  before(async function () {
+    ethAddress20 = ExtrinsicHelper.apiPromise.createType('H160', hexToU8a(CHECKSUMMED_ETH_ADDR_1234));
+    ethKeys = ethereumAddressToKeyringPair(ethAddress20);
+  });
+
+  describe('getEthereumAddressForMsaId', function () {
+    it('should return the correct address for a given MSA ID', async function () {
+      const expectedAddress = CHECKSUMMED_ETH_ADDR_1234.toLowerCase();
+      const { accountId, accountIdChecksummed } =
+        await ExtrinsicHelper.apiPromise.call.msaRuntimeApi.getEthereumAddressForMsaId(MSA_ID_1234);
+      assert.equal(accountId.toHex(), expectedAddress, `Expected address ${expectedAddress}, but got ${accountId}`);
+      assert.equal(
+        accountIdChecksummed.toString(),
+        CHECKSUMMED_ETH_ADDR_1234,
+        `Expected checksummed address ${CHECKSUMMED_ETH_ADDR_1234}, but got ${accountIdChecksummed.toString()}`
+      );
+    });
+
+    it('should validate the Ethereum address for an MSA ID', async function () {
+      const isValid = await ExtrinsicHelper.apiPromise.call.msaRuntimeApi.validateEthAddressForMsa(
+        generateMsaAddress(MSA_ID_1234),
+        MSA_ID_1234
+      );
+      assert.equal(isValid, true, 'Expected the Ethereum address to be valid for the given MSA ID');
+    });
+
+    it('should fail to validate the Ethereum address for an incorrect MSA ID', async function () {
+      const isValid = await ExtrinsicHelper.apiPromise.call.msaRuntimeApi.validateEthAddressForMsa(
+        CHECKSUMMED_ETH_ADDR_1234,
+        4321
+      );
+      assert.equal(isValid, false, 'Expected the Ethereum address to be invalid for a different MSA ID');
+    });
+  });
+
+  describe('Send tokens to MSA', function () {
+    it('should send tokens to the MSA', async function () {
+      const ed = await getExistentialDeposit();
+      const transferAmount = 1n + ed;
+      let accountData = await ExtrinsicHelper.getAccountInfo(ethKeys);
+      const initialBalance = accountData.data.free.toBigInt();
+      const op = ExtrinsicHelper.transferFunds(
+        fundingSource,
+        ethereumAddressToKeyringPair(ethAddress20),
+        transferAmount
+      );
+
+      const { target: transferEvent } = await op.fundAndSend(fundingSource);
+      assert.notEqual(transferEvent, undefined, 'should have transferred tokens');
+
+      accountData = await ExtrinsicHelper.getAccountInfo(ethKeys);
+      const finalBalance = accountData.data.free.toBigInt();
+      assert.equal(
+        finalBalance,
+        initialBalance + transferAmount,
+        'Final balance should be increased by transfer amount'
+      );
+    });
+  });
+});

e2e/msa/msaTokens.test.ts

@@ -8,14 +8,26 @@ import { secp256k1 } from '@noble/curves/secp256k1';
 import { Keyring } from '@polkadot/api';
 import { Keypair } from '@polkadot/util-crypto/types';
 import { Address20MultiAddress } from './helpers';
+import { H160 } from '@polkadot/types/interfaces';
+
+/**
+ * Create a partial KeyringPair from an Ethereum address
+ */
+export function ethereumAddressToKeyringPair(ethereumAddress: H160): KeyringPair {
+  return {
+    type: 'ethereum',
+    address: ethereumAddress.toHex(),
+    addressRaw: ethereumAddress,
+  } as unknown as KeyringPair;
+}
 
 /**
  * Returns unified 32 bytes SS58 accountId
  * @param pair
  */
 export function getUnifiedAddress(pair: KeyringPair): string {
   if ('ethereum' === pair.type) {
-    const etheAddressHex = ethereumEncode(pair.publicKey);
+    const etheAddressHex = ethereumEncode(pair.publicKey || pair.address);
     return getSS58AccountFromEthereumAccount(etheAddressHex);
   }
   if (pair.type === 'ecdsa') {
@@ -71,7 +83,7 @@ export function getAccountId20MultiAddress(pair: KeyringPair): Address20MultiAdd
   if (pair.type !== 'ethereum') {
     throw new Error(`Only ethereum keys are supported!`);
   }
-  const etheAddress = ethereumEncode(pair.publicKey);
+  const etheAddress = ethereumEncode(pair.publicKey || pair.address);
   const ethAddress20 = Array.from(hexToU8a(etheAddress));
   return { Address20: ethAddress20 };
 }
@@ -86,15 +98,14 @@ export function getKeyringPairFromSecp256k1PrivateKey(secretKey: Uint8Array): Ke
     secretKey,
     publicKey,
   };
-  const keyring = new Keyring({ type: 'ethereum' });
-  return keyring.addFromPair(keypair, undefined, 'ethereum');
+  return new Keyring({ type: 'ethereum' }).createFromPair(keypair, undefined, 'ethereum');
 }
 
 /**
  * converts an ethereum account to SS58 format
  * @param accountId20Hex
  */
-function getSS58AccountFromEthereumAccount(accountId20Hex: string): string {
+export function getSS58AccountFromEthereumAccount(accountId20Hex: string): string {
   const addressBytes = hexToU8a(accountId20Hex);
   const suffix = new Uint8Array(12).fill(0xee);
   const result = new Uint8Array(32);

e2e/scaffolding/ethereum.ts

@@ -18,6 +18,7 @@ parity-scale-codec = { workspace = true, features = ["derive"] }
 frame-benchmarking = { workspace = true, optional = true }
 frame-support = { workspace = true }
 frame-system = { workspace = true }
+lazy_static = { workspace = true }
 
 scale-info = { workspace = true, features = ["derive"] }
 sp-core = { workspace = true }
@@ -42,6 +43,8 @@ parking_lot = { workspace = true }
 
 [features]
 default = ["std"]
+frequency = []
+frequency-testnet = []
 runtime-benchmarks = [
   "frame-benchmarking/runtime-benchmarks",
   "pallet-schemas/runtime-benchmarks",

pallets/msa/Cargo.toml

@@ -17,6 +17,13 @@ All users on Frequency must have an MSA in order to:
 Once a user creates an MSA, they are assigned an MSA Id, a unique number the time of creation with one or more keys attached for control.
 (A control key may only be attached to ONE MSA at any single point in time.)
 
+#### MSA Id and Addresses
+
+Each MSA Id has a unique 20-byte address associated with it. This address can be queried using an MSA pallet runtime call, or computed using the following algorithm:
+```ignore
+Address = keccak256(0xD9 + <MSA Id as 8-byte big-endian bytes> + keccak256(b"MSA Generated"))[12..]
+```
+
 ### Actions
 
 The MSA pallet provides for:
@@ -70,3 +77,13 @@ Note: May be restricted based on node settings and configuration.
 \* Must be enabled with off-chain indexing
 
 See [Rust Docs](https://frequency-chain.github.io/frequency/pallet_msa_rpc/trait.MsaApiServer.html) for more details.
+
+### Runtime API
+
+| Name | Description | Call | Runtime Added | MSA Runtime API Version Added |
+| ------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------- |
+| Has Delegation                        | Check to see if a delegation existed between the given delegator and provider at a given block | ['hasDelegation'](https://frequency-chain.github.io/frequency/pallet_msa_runtime_api/trait.MsaRuntimeApi.html#method.has_delegation) | 1 | 1 |
+| Get Granted Schemas by MSA ID         | Get the list of schema permission grants (if any) that exist in any delegation between the delegator and provider. | ['getGrantedSchemasByMsaId'](https://frequency-chain.github.io/frequency/pallet_msa_runtime_api/trait.MsaRuntimeApi.html#method.get_granted_schemas_by_msa_id) | 1 | 1 |
+| Get All Granted Delegations by MSA ID | Get the list of all delegated providers with schema permission grants (if any) that exist in any delegation between the delegator and provider. | ['getAllGrantedDelegationsByMsaId'](https://frequency-chain.github.io/frequency/pallet_msa_runtime_api/trait.MsaRuntimeApi.html#method.get_all_granted_delegations_by_msa_id) | 83 | 2 |
+| Get Ethereum Address for MSA ID       | Get the Ethereum address of the given MSA. | ['getEthereumAddressForMsaId'](https://frequency-chain.github.io/frequency/pallet_msa_runtime_api/trait.MsaRuntimeApi.html#method.get_ethereum_address_for_msa_id) | 156 | 3 |
+| Validate Ethereum Address for MSA ID  | Validate if the given Ethereum address is associated with the given MSA. | ['validateEthAddressForMsa'](https://frequency-chain.github.io/frequency/pallet_msa_runtime_api/trait.MsaRuntimeApi.html#method.validate_eth_address_for_msa) | 156 | 3 |

pallets/msa/README.md

@@ -36,6 +36,7 @@ use frame_support::{
 	pallet_prelude::*,
 	traits::IsSubType,
 };
+use lazy_static::lazy_static;
 use parity_scale_codec::{Decode, Encode};
 
 use common_runtime::signature::check_signature;
@@ -48,14 +49,15 @@ use common_primitives::{
 	msa::{
 		Delegation, DelegationValidator, DelegatorId, MsaLookup, MsaValidator, ProviderId,
 		ProviderLookup, ProviderRegistryEntry, SchemaGrant, SchemaGrantValidator,
-		SignatureRegistryPointer,
+		SignatureRegistryPointer, H160,
 	},
 	node::ProposalProvider,
 	schema::{SchemaId, SchemaValidator},
 };
 use frame_system::pallet_prelude::*;
 use scale_info::TypeInfo;
 use sp_core::crypto::AccountId32;
+use sp_io::hashing::keccak_256;
 #[allow(deprecated)]
 #[allow(unused)]
 use sp_runtime::{
@@ -89,6 +91,7 @@ mod tests;
 pub mod types;
 
 pub mod weights;
+
 #[frame_support::pallet]
 pub mod pallet {
 	use super::*;
@@ -1357,6 +1360,67 @@ impl<T: Config> Pallet<T> {
 		Ok(result)
 	}
 
+	/// Converts an MSA ID into a synthetic Ethereum address (raw 20-byte format) by
+	/// taking the last 20 bytes of the keccak256 hash of the following:
+	/// [0..1]: 0xD9 (first byte of the keccak256 hash of the domain prefix "Frequency")
+	/// [1..9]:   u64 (big endian)
+	/// [9..41]:  keccack256("MSA Generated")
+	pub fn msa_id_to_eth_address(id: MessageSourceId) -> H160 {
+		/// First byte of the keccak256 hash of the domain prefix "Frequency"
+		/// This "domain separator" ensures that the generated address will not collide with Ethereum addresses
+		/// generated by the standard 'CREATE2' opcode.
+		const DOMAIN_PREFIX: u8 = 0xD9;
+
+		lazy_static! {
+			/// Salt used to generate MSA addresses
+			static ref MSA_ADDRESS_SALT: [u8; 32] = keccak_256(b"MSA Generated");
+		}
+		let input_value = id.to_be_bytes();
+
+		let mut hash_input = [0u8; 41];
+		hash_input[0] = DOMAIN_PREFIX;
+		hash_input[1..9].copy_from_slice(&input_value);
+		hash_input[9..].copy_from_slice(&(*MSA_ADDRESS_SALT));
+
+		let hash = keccak_256(&hash_input);
+		H160::from_slice(&hash[12..])
+	}
+
+	/// Returns a boolean indicating whether the given Ethereum address was generated from the given MSA ID.
+	pub fn validate_eth_address_for_msa(address: &H160, msa_id: MessageSourceId) -> bool {
+		let generated_address = Self::msa_id_to_eth_address(msa_id);
+		*address == generated_address
+	}
+
+	/// Converts a 20-byte synthetic Ethereum address into a checksummed string format,
+	/// using ERC-55 checksum rules.
+	/// Formats a 20-byte address into an EIP-55 checksummed `0x...` string.
+	pub fn eth_address_to_checksummed_string(address: &H160) -> alloc::string::String {
+		let addr_bytes = address.0;
+		let addr_hex = hex::encode(addr_bytes);
+		let hash = keccak_256(addr_hex.as_bytes());
+
+		let mut result = alloc::string::String::with_capacity(42);
+		result.push_str("0x");
+
+		for (i, c) in addr_hex.chars().enumerate() {
+			let hash_byte = hash[i / 2];
+			let bit = if i % 2 == 0 { (hash_byte >> 4) & 0xf } else { hash_byte & 0xf };
+
+			result.push(if c.is_ascii_hexdigit() && c.is_ascii_alphabetic() {
+				if bit >= 8 {
+					c.to_ascii_uppercase()
+				} else {
+					c
+				}
+			} else {
+				c
+			});
+		}
+
+		result
+	}
+
 	/// Adds a signature to the `PayloadSignatureRegistryList`
 	/// Check that mortality_block is within bounds. If so, proceed and add the new entry.
 	/// Raises `SignatureAlreadySubmitted` if the signature exists in the registry.

pallets/msa/src/lib.rs

@@ -29,7 +29,7 @@ sp_api::decl_runtime_apis! {
 	/// Runtime Version for MSAs
 	/// - MUST be incremented if anything changes
 	/// - See: https://paritytech.github.io/polkadot/doc/polkadot_primitives/runtime_api/index.html
-	#[api_version(2)]
+	#[api_version(3)]
 
 	/// Runtime API definition for [MSA](../pallet_msa/index.html)
 	pub trait MsaRuntimeApi<AccountId> where
@@ -45,5 +45,12 @@ sp_api::decl_runtime_apis! {
 		/// Get the list of all delegated providers with schema permission grants (if any) that exist in any delegation between the delegator and provider
 		/// The returned list contains both schema id and the block number at which permission was revoked (0 if currently not revoked)
 		fn get_all_granted_delegations_by_msa_id(delegator: DelegatorId) -> Vec<DelegationResponse<SchemaId, BlockNumber>>;
+
+		/// Get the Ethereum address of the given MSA.
+		/// The address is returned as both a 20-byte binary address and a hex-encoded checksummed string (ERC-55).
+		fn get_ethereum_address_for_msa_id(msa_id: MessageSourceId) -> AccountId20Response;
+
+		/// Validate if the given Ethereum address is associated with the given MSA
+		fn validate_eth_address_for_msa(eth_address: &H160, msa_id: MessageSourceId) -> bool;
 	}
 }