@frequency-chain/ethereum-utils 1.17.0-rc4

package/esm/address.js

@@ -0,0 +1,83 @@
+import { encodeAddress, ethereumEncode } from '@polkadot/util-crypto';
+import { hexToU8a, u8aToHex } from '@polkadot/util';
+import { ethers } from 'ethers';
+/**
+ * Creates a Random Ethereum key
+ */
+export function createRandomKey() {
+    const k = ethers.Wallet.createRandom();
+    return {
+        publicKey: k.publicKey,
+        privateKey: k.privateKey,
+        address: {
+            ethereumAddress: k.address,
+            unifiedAddress: getUnified32BytesAddress(k.address),
+            unifiedAddressSS58: getSS58AccountFromEthereumAccount(k.address),
+        },
+        mnemonic: k.mnemonic?.phrase ?? '',
+    };
+}
+/**
+ * Create a partial KeyringPair from an Ethereum address
+ */
+export function ethereumAddressToKeyringPair(ethereumAddress) {
+    return {
+        type: 'ethereum',
+        address: ethereumAddress.toHex(),
+        addressRaw: ethereumAddress,
+    };
+}
+/**
+ * Returns unified 32 bytes SS58 accountId
+ * @param pair
+ */
+export function getUnifiedAddress(pair) {
+    if ('ethereum' === pair.type) {
+        const etheAddressHex = ethereumEncode(pair.publicKey || pair.address);
+        return getSS58AccountFromEthereumAccount(etheAddressHex);
+    }
+    if (pair.type === 'ecdsa') {
+        throw new Error('Ecdsa key type is not supported and it should be replaced with ethereum ones!');
+    }
+    return pair.address;
+}
+/**
+ * Returns ethereum style public key with suffixed 0xee example: 0x19a701d23f0ee1748b5d5f883cb833943096c6c4eeeeeeeeeeeeeeeeeeeeeeee
+ * @param pair
+ */
+export function getUnifiedPublicKey(pair) {
+    if ('ethereum' === pair.type) {
+        const unifiedHex = getUnified32BytesAddress(u8aToHex(pair.publicKey));
+        return hexToU8a(unifiedHex);
+    }
+    if (pair.type === 'ecdsa') {
+        throw new Error('Ecdsa key type is not supported and it should be replaced with ethereum ones!');
+    }
+    return pair.publicKey;
+}
+export function reverseUnifiedAddressToEthereumAddress(unifiedAddress) {
+    if (!unifiedAddress.toLowerCase().endsWith('ee'.repeat(12))) {
+        throw new Error(`Address ${unifiedAddress} is not reversible!`);
+    }
+    return `${unifiedAddress.substring(0, 42)}`;
+}
+/**
+ * converts an ethereum account to SS58 format
+ * @param accountId20Hex
+ */
+export function getSS58AccountFromEthereumAccount(accountId20Hex) {
+    const addressBytes = hexToU8a(accountId20Hex);
+    const suffix = new Uint8Array(12).fill(0xee);
+    const result = new Uint8Array(32);
+    result.set(addressBytes, 0);
+    result.set(suffix, 20);
+    return encodeAddress(result);
+}
+function getUnified32BytesAddress(ethAddressOrPublicKey) {
+    const ethAddressBytes = hexToU8a(ethereumEncode(ethAddressOrPublicKey));
+    const suffix = new Uint8Array(12).fill(0xee);
+    const result = new Uint8Array(32);
+    result.set(ethAddressBytes, 0);
+    result.set(suffix, 20);
+    return u8aToHex(result);
+}

package/esm/index.js

@@ -0,0 +1,9 @@
+import * as address from './address';
+import * as payloads from './payloads';
+import * as signature from './signature';
+import * as signatureDefinitions from './signature.definitions';
+export * from './payloads';
+export * from './signature';
+export * from './signature.definitions';
+export * from './address';
+export default { ...payloads, ...address, ...signatureDefinitions, ...signature };

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/payloads.js

@@ -0,0 +1 @@
+export {};

package/esm/signature.definitions.js

@@ -0,0 +1,148 @@
+export const EIP712_DOMAIN_DEFINITION = {
+    EIP712Domain: [
+        {
+            name: 'name',
+            type: 'string',
+        },
+        {
+            name: 'version',
+            type: 'string',
+        },
+        {
+            name: 'chainId',
+            type: 'uint256',
+        },
+        {
+            name: 'verifyingContract',
+            type: 'address',
+        },
+    ],
+};
+// using pallet_revive test chain ID for now.
+export const EIP712_DOMAIN_DEFAULT = {
+    name: 'Frequency',
+    version: '1',
+    chainId: '0x190f1b44',
+    verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC',
+};
+export const ADD_PROVIDER_DEFINITION = {
+    AddProvider: [
+        {
+            name: 'authorizedMsaId',
+            type: 'uint64',
+        },
+        {
+            name: 'schemaIds',
+            type: 'uint16[]',
+        },
+        {
+            name: 'expiration',
+            type: 'uint32',
+        },
+    ],
+};
+export const ADD_KEY_DATA_DEFINITION = {
+    AddKeyData: [
+        {
+            name: 'msaId',
+            type: 'uint64',
+        },
+        {
+            name: 'expiration',
+            type: 'uint32',
+        },
+        {
+            name: 'newPublicKey',
+            type: 'address',
+        },
+    ],
+};
+export const CLAIM_HANDLE_PAYLOAD_DEFINITION = {
+    ClaimHandlePayload: [
+        {
+            name: 'handle',
+            type: 'string',
+        },
+        {
+            name: 'expiration',
+            type: 'uint32',
+        },
+    ],
+};
+export const PASSKEY_PUBLIC_KEY_DEFINITION = {
+    PasskeyPublicKey: [
+        {
+            name: 'publicKey',
+            type: 'bytes',
+        },
+    ],
+};
+export const PAGINATED_DELETE_SIGNATURE_PAYLOAD_DEFINITION_V2 = {
+    PaginatedDeleteSignaturePayloadV2: [
+        {
+            name: 'schemaId',
+            type: 'uint16',
+        },
+        {
+            name: 'pageId',
+            type: 'uint16',
+        },
+        {
+            name: 'targetHash',
+            type: 'uint32',
+        },
+        {
+            name: 'expiration',
+            type: 'uint32',
+        },
+    ],
+};
+export const PAGINATED_UPSERT_SIGNATURE_PAYLOAD_DEFINITION_V2 = {
+    PaginatedUpsertSignaturePayloadV2: [
+        {
+            name: 'schemaId',
+            type: 'uint16',
+        },
+        {
+            name: 'pageId',
+            type: 'uint16',
+        },
+        {
+            name: 'targetHash',
+            type: 'uint32',
+        },
+        {
+            name: 'expiration',
+            type: 'uint32',
+        },
+        {
+            name: 'payload',
+            type: 'bytes',
+        },
+    ],
+};
+export const ITEMIZED_SIGNATURE_PAYLOAD_DEFINITION_V2 = {
+    ItemizedSignaturePayloadV2: [
+        {
+            name: 'schemaId',
+            type: 'uint16',
+        },
+        {
+            name: 'targetHash',
+            type: 'uint32',
+        },
+        {
+            name: 'expiration',
+            type: 'uint32',
+        },
+        {
+            name: 'actions',
+            type: 'ItemAction[]',
+        },
+    ],
+    ItemAction: [
+        { name: 'actionType', type: 'string' },
+        { name: 'data', type: 'bytes' },
+        { name: 'index', type: 'uint16' },
+    ],
+};

package/esm/signature.js

@@ -0,0 +1,322 @@
+import { assert, isHexString, isValidUint16, isValidUint32, isValidUint64String } from './utils';
+import { reverseUnifiedAddressToEthereumAddress } from './address';
+import { ethers } from 'ethers';
+import { u8aToHex } from '@polkadot/util';
+import { ADD_KEY_DATA_DEFINITION, ADD_PROVIDER_DEFINITION, CLAIM_HANDLE_PAYLOAD_DEFINITION, EIP712_DOMAIN_DEFAULT, EIP712_DOMAIN_DEFINITION, ITEMIZED_SIGNATURE_PAYLOAD_DEFINITION_V2, PAGINATED_DELETE_SIGNATURE_PAYLOAD_DEFINITION_V2, PAGINATED_UPSERT_SIGNATURE_PAYLOAD_DEFINITION_V2, PASSKEY_PUBLIC_KEY_DEFINITION, } from './signature.definitions';
+/**
+ * Signing EIP-712 compatible signature for payload
+ * @param secretKey
+ * @param payload
+ * @param chain
+ */
+export async function signEip712(secretKey, payload, chain = 'Mainnet-Frequency') {
+    const types = getTypesFor(payload.type);
+    const normalizedPayload = normalizePayload(payload);
+    const wallet = new ethers.Wallet(secretKey);
+    // TODO: use correct chainID for different networks
+    // TODO: use correct contract address for different payloads
+    const signature = await wallet.signTypedData(EIP712_DOMAIN_DEFAULT, types, normalizedPayload);
+    return { Ecdsa: signature };
+}
+/**
+ * Verify EIP-712 signatures
+ * @param ethereumAddress
+ * @param signature
+ * @param payload
+ * @param chain
+ */
+export function verifyEip712Signature(ethereumAddress, signature, payload, chain = 'Mainnet-Frequency') {
+    const types = getTypesFor(payload.type);
+    const normalizedPayload = normalizePayload(payload);
+    // TODO: use correct chainID for different networks
+    // TODO: use correct contract address for different payloads
+    const recoveredAddress = ethers.verifyTypedData(EIP712_DOMAIN_DEFAULT, types, normalizedPayload, signature);
+    return recoveredAddress.toLowerCase() === ethereumAddress.toLowerCase();
+}
+function normalizePayload(payload) {
+    const clonedPayload = Object.assign({}, payload);
+    switch (clonedPayload.type) {
+        case 'PaginatedUpsertSignaturePayloadV2':
+        case 'PaginatedDeleteSignaturePayloadV2':
+        case 'ItemizedSignaturePayloadV2':
+        case 'PasskeyPublicKey':
+        case 'ClaimHandlePayload':
+        case 'AddProvider':
+            break;
+        case 'AddKeyData':
+            // convert to 20 bytes ethereum address for signature
+            if (clonedPayload.newPublicKey.length !== 42) {
+                clonedPayload.newPublicKey = reverseUnifiedAddressToEthereumAddress(payload.newPublicKey);
+            }
+            clonedPayload.newPublicKey = clonedPayload.newPublicKey.toLowerCase();
+            break;
+        default:
+            throw new Error(`Unsupported payload type: ${JSON.stringify(payload)}`);
+    }
+    // Remove the type field
+    const { type, ...payloadWithoutType } = clonedPayload;
+    return payloadWithoutType;
+}
+function getTypesFor(payloadType) {
+    const PAYLOAD_TYPE_DEFINITIONS = {
+        PaginatedUpsertSignaturePayloadV2: PAGINATED_UPSERT_SIGNATURE_PAYLOAD_DEFINITION_V2,
+        PaginatedDeleteSignaturePayloadV2: PAGINATED_DELETE_SIGNATURE_PAYLOAD_DEFINITION_V2,
+        ItemizedSignaturePayloadV2: ITEMIZED_SIGNATURE_PAYLOAD_DEFINITION_V2,
+        PasskeyPublicKey: PASSKEY_PUBLIC_KEY_DEFINITION,
+        ClaimHandlePayload: CLAIM_HANDLE_PAYLOAD_DEFINITION,
+        AddKeyData: ADD_KEY_DATA_DEFINITION,
+        AddProvider: ADD_PROVIDER_DEFINITION,
+    };
+    const definition = PAYLOAD_TYPE_DEFINITIONS[payloadType];
+    if (!definition) {
+        throw new Error(`Unsupported payload type: ${payloadType}`);
+    }
+    return definition;
+}
+/**
+ * Build an AddKeyData payload for signature.
+ *
+ * @param msaId           MSA ID (uint64) to add the key
+ * @param newPublicKey    32 bytes public key to add in hex or Uint8Array
+ * @param expirationBlock Block number after which this payload is invalid
+ */
+export function createAddKeyData(msaId, newPublicKey, expirationBlock) {
+    const parsedMsaId = typeof msaId === 'string' ? msaId : `${msaId}`;
+    const parsedNewPublicKey = typeof newPublicKey === 'object' ? u8aToHex(newPublicKey) : newPublicKey;
+    assert(isValidUint64String(parsedMsaId), 'msaId should be a valid uint64');
+    assert(isValidUint32(expirationBlock), 'expiration should be a valid uint32');
+    assert(isHexString(parsedNewPublicKey), 'newPublicKey should be valid hex');
+    return {
+        type: 'AddKeyData',
+        msaId: parsedMsaId,
+        expiration: expirationBlock,
+        newPublicKey: parsedNewPublicKey,
+    };
+}
+/**
+ * Build an AddProvider payload for signature.
+ *
+ * @param authorizedMsaId MSA ID (uint64) that will be granted provider rights
+ * @param schemaIds       One or more schema IDs (uint16) the provider may use
+ * @param expirationBlock Block number after which this payload is invalid
+ */
+export function createAddProvider(authorizedMsaId, schemaIds, expirationBlock) {
+    assert(isValidUint64String(authorizedMsaId), 'authorizedMsaId should be a valid uint64');
+    assert(isValidUint32(expirationBlock), 'expiration should be a valid uint32');
+    schemaIds.forEach((schemaId) => {
+        assert(isValidUint16(schemaId), 'schemaId should be a valid uint16');
+    });
+    return {
+        type: 'AddProvider',
+        authorizedMsaId: authorizedMsaId.toString(),
+        schemaIds,
+        expiration: expirationBlock,
+    };
+}
+/**
+ * Build a ClaimHandlePayload for signature.
+ *
+ * @param handle          The handle the user wishes to claim
+ * @param expirationBlock Block number after which this payload is invalid
+ */
+export function createClaimHandlePayload(handle, expirationBlock) {
+    assert(handle.length > 0, 'handle should be a valid string');
+    assert(isValidUint32(expirationBlock), 'expiration should be a valid uint32');
+    return {
+        type: 'ClaimHandlePayload',
+        handle,
+        expiration: expirationBlock,
+    };
+}
+/**
+ * Build a PasskeyPublicKey payload for signature.
+ *
+ * @param publicKey The passkey’s public key (hex string or raw bytes)
+ */
+export function createPasskeyPublicKey(publicKey) {
+    const parsedNewPublicKey = typeof publicKey === 'object' ? u8aToHex(publicKey) : publicKey;
+    assert(isHexString(parsedNewPublicKey), 'publicKey should be valid hex');
+    return {
+        type: 'PasskeyPublicKey',
+        publicKey: parsedNewPublicKey,
+    };
+}
+export function createItemizedAddAction(data) {
+    const parsedData = typeof data === 'object' ? u8aToHex(data) : data;
+    assert(isHexString(parsedData), 'itemized data should be valid hex');
+    return { actionType: 'Add', data, index: 0 };
+}
+export function createItemizedDeleteAction(index) {
+    assert(isValidUint16(index), 'itemized index should be a valid uint16');
+    return { actionType: 'Delete', data: '0x', index };
+}
+/**
+ * Build an ItemizedSignaturePayloadV2 for signing.
+ *
+ * @param schemaId   uint16 schema identifier
+ * @param targetHash uint32 page hash
+ * @param expiration uint32 expiration block
+ * @param actions    Array of Add/Delete itemized actions
+ */
+export function createItemizedSignaturePayloadV2(schemaId, targetHash, expiration, actions) {
+    assert(isValidUint16(schemaId), 'schemaId should be a valid uint16');
+    assert(isValidUint32(targetHash), 'targetHash should be a valid uint32');
+    assert(isValidUint32(expiration), 'expiration should be a valid uint32');
+    assert(actions.length > 0, 'At least one action is required for ItemizedSignaturePayloadV2');
+    return {
+        type: 'ItemizedSignaturePayloadV2',
+        schemaId,
+        targetHash,
+        expiration,
+        actions,
+    };
+}
+/**
+ * Build a PaginatedDeleteSignaturePayloadV2 for signing.
+ *
+ * @param schemaId   uint16 schema identifier
+ * @param pageId     uint16 page identifier
+ * @param targetHash uint32 page hash
+ * @param expiration uint32 expiration block
+ */
+export function createPaginatedDeleteSignaturePayloadV2(schemaId, pageId, targetHash, expiration) {
+    assert(isValidUint16(schemaId), 'schemaId should be a valid uint16');
+    assert(isValidUint16(pageId), 'pageId should be a valid uint16');
+    assert(isValidUint32(targetHash), 'targetHash should be a valid uint32');
+    assert(isValidUint32(expiration), 'expiration should be a valid uint32');
+    return {
+        type: 'PaginatedDeleteSignaturePayloadV2',
+        schemaId,
+        pageId,
+        targetHash,
+        expiration,
+    };
+}
+/**
+ * Build a PaginatedUpsertSignaturePayloadV2 for signing.
+ *
+ * @param schemaId   uint16 schema identifier
+ * @param pageId     uint16 page identifier
+ * @param targetHash uint32 page hash
+ * @param expiration uint32 expiration block
+ * @param payload    HexString or Uint8Array data to upsert
+ */
+export function createPaginatedUpsertSignaturePayloadV2(schemaId, pageId, targetHash, expiration, payload) {
+    const parsedPayload = typeof payload === 'object' ? u8aToHex(payload) : payload;
+    assert(isValidUint16(schemaId), 'schemaId should be a valid uint16');
+    assert(isValidUint16(pageId), 'pageId should be a valid uint16');
+    assert(isValidUint32(targetHash), 'targetHash should be a valid uint32');
+    assert(isValidUint32(expiration), 'expiration should be a valid uint32');
+    assert(isHexString(parsedPayload), 'payload should be valid hex');
+    return {
+        type: 'PaginatedUpsertSignaturePayloadV2',
+        schemaId,
+        pageId,
+        targetHash,
+        expiration,
+        payload: parsedPayload,
+    };
+}
+/**
+ * Returns the EIP-712 browser request for a AddKeyData for signing.
+ *
+ * @param msaId           MSA ID (uint64) to add the key
+ * @param newPublicKey    32 bytes public key to add in hex or Uint8Array
+ * @param expirationBlock Block number after which this payload is invalid
+ * @param domain
+ */
+export function getEip712BrowserRequestAddKeyData(msaId, newPublicKey, expirationBlock, domain = EIP712_DOMAIN_DEFAULT) {
+    const message = createAddKeyData(msaId, newPublicKey, expirationBlock);
+    const normalized = normalizePayload(message);
+    return createEip712Payload(ADD_KEY_DATA_DEFINITION, message.type, domain, normalized);
+}
+/**
+ * Returns the EIP-712 browser request for a AddProvider for signing.
+ *
+ * @param authorizedMsaId MSA ID (uint64) that will be granted provider rights
+ * @param schemaIds       One or more schema IDs (uint16) the provider may use
+ * @param expirationBlock Block number after which this payload is invalid
+ * @param domain
+ */
+export function getEip712BrowserRequestAddProvider(authorizedMsaId, schemaIds, expirationBlock, domain = EIP712_DOMAIN_DEFAULT) {
+    const message = createAddProvider(authorizedMsaId, schemaIds, expirationBlock);
+    const normalized = normalizePayload(message);
+    return createEip712Payload(ADD_PROVIDER_DEFINITION, message.type, domain, normalized);
+}
+/**
+ * Returns the EIP-712 browser request for a PaginatedUpsertSignaturePayloadV2 for signing.
+ *
+ * @param schemaId   uint16 schema identifier
+ * @param pageId     uint16 page identifier
+ * @param targetHash uint32 page hash
+ * @param expiration uint32 expiration block
+ * @param payload    HexString or Uint8Array data to upsert
+ * @param domain
+ */
+export function getEip712BrowserRequestPaginatedUpsertSignaturePayloadV2(schemaId, pageId, targetHash, expiration, payload, domain = EIP712_DOMAIN_DEFAULT) {
+    const message = createPaginatedUpsertSignaturePayloadV2(schemaId, pageId, targetHash, expiration, payload);
+    const normalized = normalizePayload(message);
+    return createEip712Payload(PAGINATED_UPSERT_SIGNATURE_PAYLOAD_DEFINITION_V2, message.type, domain, normalized);
+}
+/**
+ * Returns the EIP-712 browser request for a PaginatedDeleteSignaturePayloadV2 for signing.
+ *
+ * @param schemaId   uint16 schema identifier
+ * @param pageId     uint16 page identifier
+ * @param targetHash uint32 page hash
+ * @param expiration uint32 expiration block
+ * @param domain
+ */
+export function getEip712BrowserRequestPaginatedDeleteSignaturePayloadV2(schemaId, pageId, targetHash, expiration, domain = EIP712_DOMAIN_DEFAULT) {
+    const message = createPaginatedDeleteSignaturePayloadV2(schemaId, pageId, targetHash, expiration);
+    const normalized = normalizePayload(message);
+    return createEip712Payload(PAGINATED_DELETE_SIGNATURE_PAYLOAD_DEFINITION_V2, message.type, domain, normalized);
+}
+/**
+ * Returns the EIP-712 browser request for a ItemizedSignaturePayloadV2 for signing.
+ *
+ * @param schemaId   uint16 schema identifier
+ * @param targetHash uint32 page hash
+ * @param expiration uint32 expiration block
+ * @param actions    Array of Add/Delete itemized actions
+ * @param domain
+ */
+export function getEip712BrowserRequestItemizedSignaturePayloadV2(schemaId, targetHash, expiration, actions, domain = EIP712_DOMAIN_DEFAULT) {
+    const message = createItemizedSignaturePayloadV2(schemaId, targetHash, expiration, actions);
+    const normalized = normalizePayload(message);
+    return createEip712Payload(ITEMIZED_SIGNATURE_PAYLOAD_DEFINITION_V2, message.type, domain, normalized);
+}
+/**
+ * Returns the EIP-712 browser request for a ClaimHandlePayload for signing.
+ *
+ * @param handle          The handle the user wishes to claim
+ * @param expirationBlock Block number after which this payload is invalid
+ * @param domain
+ */
+export function getEip712BrowserRequestClaimHandlePayload(handle, expirationBlock, domain = EIP712_DOMAIN_DEFAULT) {
+    const message = createClaimHandlePayload(handle, expirationBlock);
+    const normalized = normalizePayload(message);
+    return createEip712Payload(CLAIM_HANDLE_PAYLOAD_DEFINITION, message.type, domain, normalized);
+}
+/**
+ * Returns the EIP-712 browser request for a PasskeyPublicKey for signing.
+ *
+ * @param publicKey The passkey’s public key (hex string or raw bytes)
+ * @param domain
+ */
+export function getEip712BrowserRequestPasskeyPublicKey(publicKey, domain = EIP712_DOMAIN_DEFAULT) {
+    const message = createPasskeyPublicKey(publicKey);
+    const normalized = normalizePayload(message);
+    return createEip712Payload(PASSKEY_PUBLIC_KEY_DEFINITION, message.type, domain, normalized);
+}
+function createEip712Payload(typeDefinition, primaryType, domain, message) {
+    return {
+        types: {
+            ...EIP712_DOMAIN_DEFINITION,
+            ...typeDefinition,
+        },
+        primaryType,
+        domain,
+        message,
+    };
+}

package/esm/utils.js

@@ -0,0 +1,38 @@
+/**
+ * Validate that a number is a valid uint16 (0 to 65535)
+ */
+export function isValidUint16(value) {
+    return Number.isInteger(value) && value >= 0 && value <= 65535;
+}
+/**
+ * Validate that a number is a valid uint32 (0 to 4294967295)
+ */
+export function isValidUint32(value) {
+    return Number.isInteger(value) && value >= 0 && value <= 4294967295;
+}
+/**
+ * Validate that a number is a valid uint64 (0 to 18446744073709551615n)
+ */
+export function isValidUint64String(value) {
+    const bigIntValue = typeof value === 'string' ? BigInt(value) : value;
+    return bigIntValue >= 0 && bigIntValue <= 18446744073709551615n;
+}
+/**
+ * Validate that a string is a valid hex string
+ */
+export function isHexString(value) {
+    // Check if string starts with '0x' and contains only hex characters
+    const hexRegex = /^0[xX][0-9a-fA-F]*$/;
+    const isHex = hexRegex.test(value);
+    return isHex && value.length % 2 === 0;
+}
+/**
+ * Universal assert function
+ * @param condition
+ * @param message
+ */
+export function assert(condition, message) {
+    if (!condition) {
+        throw new Error(message || ' Assertion failed');
+    }
+}