@frequency-chain/ethereum-utils 0.0.0-0eb70a

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@frequency-chain/ethereum-utils",
+  "version": "0.0.0-0eb70a",
+  "bugs": {
+    "url": "https://github.com/frequency-chain/frequency/issues"
+  },
+  "description": "A package which facilitates use of Ethereum addresses, signatures and standards with Frequency chain.",
+  "main": "./cjs/index.js",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/frequency-chain/frequency.git",
+    "directory": "js/ethereum-utils"
+  },
+  "author": "frequency-chain",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@polkadot/api": "^16.4.3",
+    "@polkadot/util": "13.5.4",
+    "ethers": "^6.15.0"
+  },
+  "optionalDependencies": {
+    "@rollup/rollup-linux-x64-gnu": "^4.46.1"
+  },
+  "module": "./esm/index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./cjs/index.js",
+      "import": "./esm/index.js",
+      "default": "./esm/index.js"
+    }
+  }
+}

package/payloads.d.ts

@@ -0,0 +1,104 @@
+export type HexString = `0x${string}`;
+export interface EcdsaSignature {
+    Ecdsa: HexString;
+}
+export interface Address20MultiAddress {
+    Address20: number[];
+}
+export type ChainType = 'Mainnet-Frequency' | 'Paseo-Testnet-Frequency' | 'Dev';
+export interface AddressWrapper {
+    ethereumAddress: HexString;
+    unifiedAddress: HexString;
+    unifiedAddressSS58: string;
+}
+export interface EthereumKeyPair {
+    privateKey: HexString;
+    publicKey: HexString;
+    address: AddressWrapper;
+    mnemonic: string;
+}
+export interface PaginatedUpsertSignaturePayloadV2 {
+    type: 'PaginatedUpsertSignaturePayloadV2';
+    schemaId: number;
+    pageId: number;
+    targetHash: number;
+    expiration: number;
+    payload: HexString;
+}
+export interface PaginatedDeleteSignaturePayloadV2 {
+    type: 'PaginatedDeleteSignaturePayloadV2';
+    schemaId: number;
+    pageId: number;
+    targetHash: number;
+    expiration: number;
+}
+export interface AddItemizedAction {
+    actionType: 'Add';
+    data: HexString;
+    index: 0;
+}
+export interface DeleteItemizedAction {
+    actionType: 'Delete';
+    data: '0x';
+    index: number;
+}
+export type ItemizedAction = AddItemizedAction | DeleteItemizedAction;
+export interface ItemizedSignaturePayloadV2 {
+    type: 'ItemizedSignaturePayloadV2';
+    schemaId: number;
+    targetHash: number;
+    expiration: number;
+    actions: ItemizedAction[];
+}
+export interface PasskeyPublicKey {
+    type: 'PasskeyPublicKey';
+    publicKey: HexString;
+}
+export interface ClaimHandlePayload {
+    type: 'ClaimHandlePayload';
+    handle: string;
+    expiration: number;
+}
+export interface AddKeyData {
+    type: 'AddKeyData';
+    msaId: string;
+    expiration: number;
+    newPublicKey: HexString;
+}
+export interface AuthorizedKeyData {
+    type: 'AuthorizedKeyData';
+    msaId: string;
+    expiration: number;
+    authorizedPublicKey: HexString;
+}
+export interface AddProvider {
+    type: 'AddProvider';
+    authorizedMsaId: string;
+    schemaIds: number[];
+    expiration: number;
+}
+export interface RecoveryCommitmentPayload {
+    type: 'RecoveryCommitmentPayload';
+    recoveryCommitment: HexString;
+    expiration: number;
+}
+export interface SiwfSignedRequestPayload {
+    type: 'SiwfSignedRequestPayload';
+    callback: string;
+    permissions: number[];
+    userIdentifierAdminUrl?: string;
+}
+export interface SiwfLoginRequestPayload {
+    type: 'SiwfLoginRequestPayload';
+    message: string;
+}
+export type SupportedPayload = PaginatedUpsertSignaturePayloadV2 | PaginatedDeleteSignaturePayloadV2 | ItemizedSignaturePayloadV2 | PasskeyPublicKey | ClaimHandlePayload | AddKeyData | AuthorizedKeyData | AddProvider | RecoveryCommitmentPayload | SiwfSignedRequestPayload | SiwfLoginRequestPayload;
+export type NormalizedSupportedPayload = Omit<SupportedPayload, 'type'>;
+export interface EipDomainPayload {
+    name: string;
+    version: string;
+    chainId: HexString;
+    verifyingContract: HexString;
+}
+export type SupportedPayloadTypes = SupportedPayload['type'];
+export type SignatureType = 'EIP-712' | 'EIP-191';

package/signature.d.ts

@@ -0,0 +1,217 @@
+import { AddKeyData, AuthorizedKeyData, AddProvider, ChainType, ClaimHandlePayload, EcdsaSignature, ItemizedSignaturePayloadV2, PaginatedDeleteSignaturePayloadV2, PaginatedUpsertSignaturePayloadV2, PasskeyPublicKey, SupportedPayload, HexString, AddItemizedAction, DeleteItemizedAction, ItemizedAction, EipDomainPayload, RecoveryCommitmentPayload, SiwfSignedRequestPayload, SiwfLoginRequestPayload } from './payloads.js';
+import { KeyringPair } from '@polkadot/keyring/types';
+import { Signer } from '@polkadot/types/types';
+/**
+ * Signing EIP-712 or ERC-191 compatible signature based on payload
+ * @param secretKey
+ * @param payload
+ * @param chain
+ */
+export declare function sign(secretKey: HexString, payload: SupportedPayload, chain: ChainType): Promise<EcdsaSignature>;
+/**
+ * Verify EIP-712 and ERC-191 signatures based on payload
+ * @param ethereumAddress
+ * @param signature
+ * @param payload
+ * @param chain
+ */
+export declare function verifySignature(ethereumAddress: HexString, signature: HexString, payload: SupportedPayload, chain: ChainType): boolean;
+/**
+ * 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 declare function createAddKeyData(msaId: string | bigint, newPublicKey: HexString | Uint8Array, expirationBlock: number): AddKeyData;
+/**
+ * Build an AuthorizedKeyData payload for signature.
+ *
+ * @param msaId                  MSA ID (uint64) to add the key
+ * @param authorizedPublicKey    32 bytes public key to authorize in hex or Uint8Array
+ * @param expirationBlock        Block number after which this payload is invalid
+ */
+export declare function createAuthorizedKeyData(msaId: string | bigint, newPublicKey: HexString | Uint8Array, expirationBlock: number): AuthorizedKeyData;
+/**
+ * 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 declare function createAddProvider(authorizedMsaId: string | bigint, schemaIds: number[], expirationBlock: number): AddProvider;
+/**
+ * Build a RecoveryCommitmentPayload for signature.
+ *
+ * @param recoveryCommitment The recovery commitment data as a HexString
+ * @param expirationBlock Block number after which this payload is invalid
+ */
+export declare function createRecoveryCommitmentPayload(recoveryCommitment: HexString, expirationBlock: number): RecoveryCommitmentPayload;
+/**
+ * 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 declare function createClaimHandlePayload(handle: string, expirationBlock: number): ClaimHandlePayload;
+/**
+ * Build a PasskeyPublicKey payload for signature.
+ *
+ * @param publicKey The passkey’s public key (hex string or raw bytes)
+ */
+export declare function createPasskeyPublicKey(publicKey: HexString | Uint8Array): PasskeyPublicKey;
+/**
+ * Build AddAction payload for Itemized storage.
+ *
+ * @param data The data to be persisted on the Frequency chain
+ */
+export declare function createItemizedAddAction(data: HexString | Uint8Array): AddItemizedAction;
+/**
+ * Build DeleteAction payload for Itemized storage.
+ *
+ * @param index The index of the item that we want to remove from the Frequency chain
+ */
+export declare function createItemizedDeleteAction(index: number): DeleteItemizedAction;
+/**
+ * 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 declare function createItemizedSignaturePayloadV2(schemaId: number, targetHash: number, expiration: number, actions: ItemizedAction[]): ItemizedSignaturePayloadV2;
+/**
+ * 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 declare function createPaginatedDeleteSignaturePayloadV2(schemaId: number, pageId: number, targetHash: number, expiration: number): PaginatedDeleteSignaturePayloadV2;
+/**
+ * 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 declare function createPaginatedUpsertSignaturePayloadV2(schemaId: number, pageId: number, targetHash: number, expiration: number, payload: HexString | Uint8Array): PaginatedUpsertSignaturePayloadV2;
+/**
+ * Build an SiwfSignedRequestPayload payload for signature.
+ *
+ * @param callback        Callback URL for login
+ * @param permissions       One or more schema IDs (uint16) the provider may use
+ * @param userIdentifierAdminUrl Only used for custom integration situations.
+ */
+export declare function createSiwfSignedRequestPayload(callback: string, permissions: number[], userIdentifierAdminUrl?: string): SiwfSignedRequestPayload;
+/**
+ * Build an SiwfLoginRequestPayload payload for signature.
+ *
+ * @param message        login message
+ */
+export declare function createSiwfLoginRequestPayload(message: string): SiwfLoginRequestPayload;
+/**
+ * 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 declare function getEip712BrowserRequestAddKeyData(msaId: string | bigint, newPublicKey: HexString | Uint8Array, expirationBlock: number, domain?: EipDomainPayload): unknown;
+/**
+ * Returns the EIP-712 browser request for a AuthorizedKeyData for signing.
+ *
+ * @param msaId           MSA ID (uint64) to add the key
+ * @param authorizedPublicKey    32 bytes public key to add in hex or Uint8Array
+ * @param expirationBlock Block number after which this payload is invalid
+ * @param domain
+ */
+export declare function getEip712BrowserRequestAuthorizedKeyData(msaId: string | bigint, authorizedPublicKey: HexString | Uint8Array, expirationBlock: number, domain?: EipDomainPayload): unknown;
+/**
+ * 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 declare function getEip712BrowserRequestAddProvider(authorizedMsaId: string | bigint, schemaIds: number[], expirationBlock: number, domain?: EipDomainPayload): unknown;
+/**
+ * Returns the EIP-712 browser request for a RecoveryCommitmentPayload for signing.
+ *
+ * @param recoveryCommitment The recovery commitment data as a Uint8Array
+ * @param expirationBlock Block number after which this payload is invalid
+ * @param domain
+ */
+export declare function getEip712BrowserRequestRecoveryCommitmentPayload(recoveryCommitment: HexString, expirationBlock: number, domain?: EipDomainPayload): unknown;
+/**
+ * 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 declare function getEip712BrowserRequestPaginatedUpsertSignaturePayloadV2(schemaId: number, pageId: number, targetHash: number, expiration: number, payload: HexString | Uint8Array, domain?: EipDomainPayload): unknown;
+/**
+ * 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 declare function getEip712BrowserRequestPaginatedDeleteSignaturePayloadV2(schemaId: number, pageId: number, targetHash: number, expiration: number, domain?: EipDomainPayload): unknown;
+/**
+ * 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 declare function getEip712BrowserRequestItemizedSignaturePayloadV2(schemaId: number, targetHash: number, expiration: number, actions: ItemizedAction[], domain?: EipDomainPayload): unknown;
+/**
+ * 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 declare function getEip712BrowserRequestClaimHandlePayload(handle: string, expirationBlock: number, domain?: EipDomainPayload): unknown;
+/**
+ * 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 declare function getEip712BrowserRequestPasskeyPublicKey(publicKey: HexString | Uint8Array, domain?: EipDomainPayload): unknown;
+/**
+ * Returns the EIP-712 browser request for a SiwfSignedRequestPayload for signing.
+ *
+ * @param callback        Callback URL for login
+ * @param permissions       One or more schema IDs (uint16) the provider may use
+ * @param userIdentifierAdminUrl Only used for custom integration situations.
+ * @param domain
+ */
+export declare function getEip712BrowserRequestSiwfSignedRequestPayload(callback: string, permissions: number[], userIdentifierAdminUrl?: string, domain?: EipDomainPayload): unknown;
+/**
+ * Returns An ethereum compatible signature for the extrinsic
+ * @param ethereumPair
+ */
+export declare function getEthereumRegularSigner(ethereumPair: KeyringPair): Signer;
+/**
+ * This custom signer can get used to mimic EIP-191 message signing. By replacing the `ethereumPair.sign` with
+ * any wallet call we can sign any extrinsic with any wallet
+ * @param ethereumPair
+ */
+export declare function getEthereumMessageSigner(ethereumPair: KeyringPair): Signer;

package/signature.definitions.d.ts

@@ -0,0 +1,130 @@
+import { EipDomainPayload } from './payloads.js';
+export declare const EIP712_DOMAIN_DEFINITION: {
+    EIP712Domain: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare const EIP712_DOMAIN_MAINNET: EipDomainPayload;
+export declare const EIP712_DOMAIN_TESTNET: EipDomainPayload;
+export declare const ADD_PROVIDER_DEFINITION: {
+    AddProvider: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare const ADD_KEY_DATA_DEFINITION: {
+    AddKeyData: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare const AUTHORIZED_KEY_DATA_DEFINITION: {
+    AuthorizedKeyData: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare const RECOVERY_COMMITMENT_PAYLOAD_DEFINITION: {
+    RecoveryCommitmentPayload: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare const CLAIM_HANDLE_PAYLOAD_DEFINITION: {
+    ClaimHandlePayload: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare const PASSKEY_PUBLIC_KEY_DEFINITION: {
+    PasskeyPublicKey: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare const PAGINATED_DELETE_SIGNATURE_PAYLOAD_DEFINITION_V2: {
+    PaginatedDeleteSignaturePayloadV2: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare const PAGINATED_UPSERT_SIGNATURE_PAYLOAD_DEFINITION_V2: {
+    PaginatedUpsertSignaturePayloadV2: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare const ITEMIZED_SIGNATURE_PAYLOAD_DEFINITION_V2: {
+    ItemizedSignaturePayloadV2: {
+        name: string;
+        type: string;
+    }[];
+    ItemAction: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare const SIWF_SIGNED_REQUEST_PAYLOAD_DEFINITION: {
+    SiwfSignedRequestPayload: {
+        name: string;
+        type: string;
+    }[];
+};
+declare const PAYLOAD_DEFINITIONS: ({
+    AddProvider: {
+        name: string;
+        type: string;
+    }[];
+} | {
+    AddKeyData: {
+        name: string;
+        type: string;
+    }[];
+} | {
+    AuthorizedKeyData: {
+        name: string;
+        type: string;
+    }[];
+} | {
+    RecoveryCommitmentPayload: {
+        name: string;
+        type: string;
+    }[];
+} | {
+    ClaimHandlePayload: {
+        name: string;
+        type: string;
+    }[];
+} | {
+    PasskeyPublicKey: {
+        name: string;
+        type: string;
+    }[];
+} | {
+    PaginatedDeleteSignaturePayloadV2: {
+        name: string;
+        type: string;
+    }[];
+} | {
+    PaginatedUpsertSignaturePayloadV2: {
+        name: string;
+        type: string;
+    }[];
+} | {
+    ItemizedSignaturePayloadV2: {
+        name: string;
+        type: string;
+    }[];
+    ItemAction: {
+        name: string;
+        type: string;
+    }[];
+} | {
+    SiwfSignedRequestPayload: {
+        name: string;
+        type: string;
+    }[];
+})[];
+export type SupportedPayloadDefinitions = (typeof PAYLOAD_DEFINITIONS)[number];
+export {};

package/utils.d.ts

@@ -0,0 +1,23 @@
+import { HexString } from './payloads.js';
+/**
+ * Validate that a number is a valid uint16 (0 to 65535)
+ */
+export declare function isValidUint16(value: number): boolean;
+/**
+ * Validate that a number is a valid uint32 (0 to 4294967295)
+ */
+export declare function isValidUint32(value: number): boolean;
+/**
+ * Validate that a number is a valid uint64 (0 to 18446744073709551615n)
+ */
+export declare function isValidUint64String(value: bigint | string): boolean;
+/**
+ * Validate that a string is a valid hex string
+ */
+export declare function isHexString(value: string): value is HexString;
+/**
+ * Universal assert function
+ * @param condition
+ * @param message
+ */
+export declare function assert(condition: boolean, message?: string): asserts condition;