diff --git a/docs/api/classes/modules_signer.SignerService.md b/docs/api/classes/modules_signer.SignerService.md index b7c851bc..11abd3e5 100644 --- a/docs/api/classes/modules_signer.SignerService.md +++ b/docs/api/classes/modules_signer.SignerService.md @@ -2,6 +2,13 @@ [modules/signer](../modules/modules_signer.md).SignerService +Service responsible for sending transactions to the blockchain + +```typescript +const { signerService } = await initWithPrivateKeySigner(privateKey, rpcUrl); +signerService.signMessage(...); +``` + ## Table of contents ### Constructors @@ -47,7 +54,7 @@ #### Parameters | Name | Type | -| :------ | :------ | +| :-- | :-- | | `_signer` | `Required`<[`SignerT`](../modules/modules_signer.md#signert)\> | | `_providerType` | [`ProviderType`](../enums/modules_signer.ProviderType.md) | @@ -57,142 +64,244 @@ • `get` **accountInfo**(): [`AccountInfo`](../modules/modules_signer.md#accountinfo) +Get account info, including chain id, chain name and user address. + +```typescript +signerService.accountInfo; +``` + #### Returns [`AccountInfo`](../modules/modules_signer.md#accountinfo) -___ +account info + +--- ### address • `get` **address**(): `string` +Get user address. + +```typescript +signerService.address; +``` + #### Returns `string` -___ +user address + +--- ### chainId • `get` **chainId**(): `number` +Get current connection chain id. + +```typescript +signerService.chainId; +``` + #### Returns `number` -___ +chain id + +--- ### did • `get` **did**(): `string` +Get current user DID address. + +```typescript +signerService.did; +``` + #### Returns `string` -___ +DID address + +--- ### didHex • `get` **didHex**(): `string` +Get current user DID address with hex representation of the chain id. + +```typescript +signerService.didHex; +``` + #### Returns `string` -___ +DID address + +--- ### isEthSigner • `get` **isEthSigner**(): `boolean` +Get if the signer is an Ethereum signer. + +```typescript +signerService.isEthSigner; +``` + #### Returns `boolean` -___ +true if the signer is an Ethereum signer + +--- ### provider • `get` **provider**(): `Provider` +Get connection provider. + +```typescript +signerService.provider; +``` + #### Returns `Provider` -___ +connection provider + +--- ### providerType • `get` **providerType**(): [`ProviderType`](../enums/modules_signer.ProviderType.md) +Get provider type of current signer connection. + +```typescript +signerService.providerType; +``` + #### Returns [`ProviderType`](../enums/modules_signer.ProviderType.md) -___ +provider type + +--- ### signer • `get` **signer**(): `Required`<[`SignerT`](../modules/modules_signer.md#signert)\> +Custom signer instance. + +```typescript +signerService.signer; +``` + #### Returns `Required`<[`SignerT`](../modules/modules_signer.md#signert)\> +signer + ## Methods ### balance ▸ **balance**(): `Promise`<`BigNumber`\> +Get current user balance. + +```typescript +signerService.getBalance(); +``` + #### Returns `Promise`<`BigNumber`\> -___ +user balance + +--- ### call -▸ **call**(`__namedParameters`): `Promise`<`string`\> +▸ **call**(`options`): `Promise`<`string`\> -Makes a (readonly) call to a smart contract -https://docs.ethers.io/v5/single-page/#/v5/api/providers/provider/-%23-Provider-call +Makes a (readonly) call to a smart contract. https://docs.ethers.io/v5/single-page/#/v5/api/providers/provider/-%23-Provider-call + +```typescript +signerService.call({ + to: ':0x00...0', + data: contract.interface.encodeFunctionData(...) +}); +``` #### Parameters -| Name | Type | -| :------ | :------ | -| `__namedParameters` | `TransactionRequest` | +| Name | Type | Description | +| :-------- | :------------------- | :------------------ | +| `options` | `TransactionRequest` | object with options | #### Returns `Promise`<`string`\> -The result of the call +the result of the call -___ +--- ### chainName ▸ **chainName**(): `string` +Get current chain name. + +```typescript +signerService.chainName(); +``` + #### Returns `string` -___ +chain name + +--- ### closeConnection ▸ **closeConnection**(): `Promise`<`boolean`\> +Close connection with the signer wallet. + +```typescript +signerService.closeConnection(); +``` + #### Returns `Promise`<`boolean`\> -___ +true if connection was closed + +--- ### connect @@ -201,7 +310,7 @@ ___ #### Parameters | Name | Type | -| :------ | :------ | +| :-- | :-- | | `signer` | `Required`<[`SignerT`](../modules/modules_signer.md#signert)\> | | `providerType` | [`ProviderType`](../enums/modules_signer.ProviderType.md) | @@ -209,7 +318,7 @@ ___ `Promise`<`void`\> -___ +--- ### emit @@ -217,15 +326,15 @@ ___ #### Parameters -| Name | Type | -| :------ | :------ | -| `e` | [`ProviderEvent`](../enums/modules_signer.ProviderEvent.md) | +| Name | Type | +| :--- | :---------------------------------------------------------- | +| `e` | [`ProviderEvent`](../enums/modules_signer.ProviderEvent.md) | #### Returns `Promise`<`void`\> -___ +--- ### init @@ -235,7 +344,7 @@ ___ `Promise`<`void`\> -___ +--- ### initEventHandlers @@ -249,7 +358,7 @@ Add event handler for certain events `void` -___ +--- ### on @@ -257,16 +366,16 @@ ___ #### Parameters -| Name | Type | -| :------ | :------ | +| Name | Type | +| :------ | :---------------------------------------------------------- | | `event` | [`ProviderEvent`](../enums/modules_signer.ProviderEvent.md) | -| `cb` | `any` | +| `cb` | `any` | #### Returns `void` -___ +--- ### onInit @@ -277,85 +386,131 @@ Registers reinitialization of dependent service on signer reconnection #### Parameters | Name | Type | -| :------ | :------ | +| :-- | :-- | | `initializer` | [`ServiceInitializer`](../modules/modules_signer.md#serviceinitializer) | #### Returns `void` -___ +--- ### publicKey ▸ **publicKey**(): `Promise`<`string`\> +Get current user public key. + +```typescript +signerService.publicKey(); +``` + #### Returns `Promise`<`string`\> -___ +public key + +--- ### publicKeyAndIdentityToken ▸ **publicKeyAndIdentityToken**(): `Promise`<[`IPubKeyAndIdentityToken`](../interfaces/modules_signer.IPubKeyAndIdentityToken.md)\> +Generate public key and identity token for authentication purposes. + +```typescript +signerService.publicKeyAndIdentityToken(); +``` + #### Returns `Promise`<[`IPubKeyAndIdentityToken`](../interfaces/modules_signer.IPubKeyAndIdentityToken.md)\> -___ +object with public key and identity token + +--- ### send -▸ **send**(`__namedParameters`): `Promise`<`TransactionReceipt`\> +▸ **send**(`options`): `Promise`<`TransactionReceipt`\> + +Send transaction to the blockchain. + +```typescript +signerService.send({ + to: ':0x00...0', + data: contract.interface.encodeFunctionData(...) +}); +``` #### Parameters -| Name | Type | -| :------ | :------ | -| `__namedParameters` | `TransactionRequest` | +| Name | Type | Description | +| :-------- | :------------------- | :------------------ | +| `options` | `TransactionRequest` | object with options | #### Returns `Promise`<`TransactionReceipt`\> -___ +transaction receipt + +--- ### signMessage ▸ **signMessage**(`message`): `Promise`<`string`\> -**`description`** Tries to create `eth_sign` conformant signature (https://eth.wiki/json-rpc/API#eth_sign) -Whether or not to hash the message prior to signature is determined by signature performed during login. -When running in browser `isEthSigner` variable should be stored in local storage +Tries to create `eth_sign` conformant signature (https://eth.wiki/json-rpc/API#eth_sign). Whether or not to hash the message prior to signature is determined by signature performed during login. When running in browser `isEthSigner` variable should be stored in local storage. + +```typescript +signerService.signMessage(arrayify('Hello World')); +``` #### Parameters | Name | Type | Description | -| :------ | :------ | :------ | +| :-- | :-- | :-- | | `message` | `Uint8Array` | The message to be signed. The message should have binary representation to avoid confusion of text with hexadecimal binary data | #### Returns `Promise`<`string`\> -___ +the signature + +--- ### signTypedData ▸ **signTypedData**(`domain`, `types`, `message`): `Promise`<`string`\> -**`description`** Tries to create conformant signature (https://eips.ethereum.org/EIPS/eip-712) +Tries to create conformant EIP-712 signature (https://eips.ethereum.org/EIPS/eip-712). + +```typescript +signerService.signTypedData( + { name: 'MyToken', version: '1.0' }, + { + Model: [ + { name: 'name', type: 'string' }, + { name: 'type', type: 'string' }, + ], + }, + { name: 'MyToken', type: 'erc721' } +); +``` #### Parameters -| Name | Type | -| :------ | :------ | -| `domain` | `TypedDataDomain` | -| `types` | `Record`<`string`, `TypedDataField`[]\> | -| `message` | `Record`<`string`, `unknown`\> | +| Name | Type | Description | +| :-------- | :-------------------------------------- | :--------------------- | +| `domain` | `TypedDataDomain` | EIP-712 domain object | +| `types` | `Record`<`string`, `TypedDataField`[]\> | EIP-712 types object | +| `message` | `Record`<`string`, `unknown`\> | EIP-712 message object | #### Returns `Promise`<`string`\> + +the signature diff --git a/src/modules/signer/signer.service.ts b/src/modules/signer/signer.service.ts index 66466e60..bfb8ea41 100644 --- a/src/modules/signer/signer.service.ts +++ b/src/modules/signer/signer.service.ts @@ -34,6 +34,15 @@ const { verifyMessage, } = utils; export type ServiceInitializer = () => Promise; + +/** + * Service responsible for signing messages and sending transactions to the blockchain + * + * ```typescript + * const { signerService } = await initWithPrivateKeySigner(privateKey, rpcUrl); + * signerService.signMessage(...); + * ``` + */ export class SignerService { private _publicKey: string; private _isEthSigner: boolean; @@ -126,18 +135,60 @@ export class SignerService { } } + async connect(signer: Required, providerType: ProviderType) { + this._signer = signer; + this._providerType = providerType; + await this.init(); + } + + /** + * The instance of the `ether` library signer in use by the service + * + * ```typescript + * signerService.signer; + * ``` + * + * @return signer + */ get signer() { return this._signer; } + /** + * If signer is EIP-191 compliant https://eips.ethereum.org/EIPS/eip-191. + * + * ```typescript + * signerService.isEthSigner; + * ``` + * + * @return true if the signer is EIP-191 compliant. + */ get isEthSigner() { return this._isEthSigner; } + /** + * Get user address. + * + * ```typescript + * signerService.address; + * ``` + * + * @return user address + */ get address() { return this._address; } + /** + * Get account info, including chain id, chain name and user address. + * + * ```typescript + * signerService.accountInfo; + * ``` + * + * @return account info + */ get accountInfo(): AccountInfo { return { account: this._account, @@ -146,26 +197,67 @@ export class SignerService { }; } + /** + * Get connection provider. + * + * ```typescript + * signerService.provider; + * ``` + * + * @return connection provider + */ get provider() { return this._signer.provider; } + /** + * Get current connection chain id. + * + * ```typescript + * signerService.chainId; + * ``` + * + * @return chain id + */ get chainId() { return this._chainId; } - async balance() { - return this.signer.getBalance(); - } - + /** + * Get provider type of current signer connection. + * + * ```typescript + * signerService.providerType; + * ``` + * + * @return provider type + */ get providerType() { return this._providerType; } + /** + * Get current user DID + * + * ```typescript + * signerService.did; + * ``` + * + * @return DID + */ get did() { return `did:${Methods.Erc1056}:${this.chainName()}:${this._address}`; } + /** + * Get current user DID address with hex representation of the chain id. + * + * ```typescript + * signerService.didHex; + * ``` + * + * @return DID address + */ get didHex() { const chainBn = BigNumber.from(this.chainId); return `did:${ @@ -173,6 +265,32 @@ export class SignerService { }:${chainBn.toHexString()}:${this._address.toLowerCase()}`; } + /** + * Get current user balance. + * + * ```typescript + * signerService.getBalance(); + * ``` + * + * @return user balance + */ + async balance() { + return this.signer.getBalance(); + } + + /** + * Send transaction to the blockchain. + * + * ```typescript + * signerService.send({ + * to: ':0x00...0', + * data: contract.interface.encodeFunctionData(...) + * }); + * ``` + * + * @param {TransactionRequest} options object with options + * @return transaction receipt + */ async send({ to, data, @@ -189,11 +307,18 @@ export class SignerService { } /** - * Makes a (readonly) call to a smart contract + * Makes a (readonly) call to a smart contract. * https://docs.ethers.io/v5/single-page/#/v5/api/providers/provider/-%23-Provider-call - * @param params.to adddress of contract - * @param params.data call data - * @returns The result of the call + * + * ```typescript + * signerService.call({ + * to: ':0x00...0', + * data: contract.interface.encodeFunctionData(...) + * }); + * ``` + * + * @param {TransactionRequest} options object with options + * @return the result of the call */ async call({ to, data }: providers.TransactionRequest): Promise { const tx = { to, from: this.address, data }; @@ -202,13 +327,18 @@ export class SignerService { } /** - * @description Tries to create `eth_sign` conformant signature (https://eth.wiki/json-rpc/API#eth_sign) - * Whether or not to hash the message prior to signature is determined by signature performed during login. - * When running in browser `isEthSigner` variable should be stored in local storage + * Tries to create `eth_sign` conformant signature (https://eth.wiki/json-rpc/API#eth_sign). + * Whether or not to hash the message prior to signature is depends on whether is signer EIP-191 compliant. + * When running in browser `isEthSigner` variable should be stored in local storage. * - * @param message The message to be signed. The message should have binary representation to avoid confusion of text with hexadecimal binary data + * ```typescript + * signerService.signMessage(arrayify('Hello World')); + * ``` + * + * @param {Uint8Array} message The message to be signed. The message should have binary representation to avoid confusion of text with hexadecimal binary data + * @return the signature */ - async signMessage(message: Uint8Array) { + async signMessage(message: Uint8Array): Promise { if (this._isEthSigner === undefined) { throw new Error(ERROR_MESSAGES.IS_ETH_SIGNER_NOT_SET); } @@ -223,18 +353,26 @@ export class SignerService { } /** - * @description Tries to create conformant signature (https://eips.ethereum.org/EIPS/eip-712) + * Tries to create conformant EIP-712 signature (https://eips.ethereum.org/EIPS/eip-712). * - * @param domain - * @param types - * @param message + * ```typescript + * signerService.signTypedData( + * { name: 'MyToken', version: '1.0' }, + * { Model: [{ name: 'name', type: 'string' }, { name: 'type', type: 'string' }] }, + * { name: 'MyToken', type: 'erc721' }, + * ); + * ``` * + * @param {TypedDataDomain} domain EIP-712 domain object + * @param {Record>} types EIP-712 types object + * @param {Record} message EIP-712 message object + * @return the signature */ async signTypedData( domain: TypedDataDomain, types: Record>, message: Record - ) { + ): Promise { if (!this.signer?._signTypedData) { throw new Error(ERROR_MESSAGES.SIGN_TYPED_DATA_NOT_SUPPORTED); } @@ -243,13 +381,16 @@ export class SignerService { return await this.signer._signTypedData(domain, types, message); } - async connect(signer: Required, providerType: ProviderType) { - this._signer = signer; - this._providerType = providerType; - await this.init(); - } - - async closeConnection() { + /** + * Close connection with the signer wallet. + * + * ```typescript + * signerService.closeConnection(); + * ``` + * + * @return true if connection was closed + */ + async closeConnection(): Promise { if (this._signer instanceof WalletConnectProvider) { await this._signer.disconnect(); } else if (this._signer instanceof EkcSigner) { @@ -263,7 +404,16 @@ export class SignerService { return true; } - async publicKey() { + /** + * Get current user public key. + * + * ```typescript + * signerService.publicKey(); + * ``` + * + * @return public key + */ + async publicKey(): Promise { if (this._publicKey) return this._publicKey; else if (this._signer instanceof Wallet) { this._publicKey = this._signer.publicKey; @@ -273,10 +423,28 @@ export class SignerService { return this._publicKey; } - chainName() { + /** + * Get current chain name. + * + * ```typescript + * signerService.chainName(); + * ``` + * + * @return chain name + */ + chainName(): string { return this._chainName; } + /** + * Generate public key and identity token for authentication purposes. + * + * ```typescript + * signerService.publicKeyAndIdentityToken(); + * ``` + * + * @return object with public key and identity token + */ async publicKeyAndIdentityToken(): Promise { if (!this._publicKey || !this._identityToken) { await this._calculatePubKeyAndIdentityToken(); @@ -287,6 +455,11 @@ export class SignerService { }; } + /** + * Generate public key and identity token for authentication purposes. + * + * @return object with public key and identity token + */ private async _calculatePubKeyAndIdentityToken() { const header = { alg: 'ES256',