@dfinity/oisy-wallet-signer/services/signer.service.d.ts

A library designed to facilitate communication between a dApp and the OISY Wallet on the Internet Computer.

import type { IcrcCallCanisterRequestParams } from '../types/icrc-requests';
import type { Notify } from '../types/signer-handlers';
import type { SignerOptions } from '../types/signer-options';
import { CallCanisterPrompt, ConsentMessagePrompt } from '../types/signer-prompts';
export declare class SignerService {
    #private;
    assertAndPromptConsentMessage({ params: { sender, ...params }, prompt, notify, options: { owner, host } }: {
        params: IcrcCallCanisterRequestParams;
        prompt: ConsentMessagePrompt | undefined;
        notify: Notify;
        options: SignerOptions;
    }): Promise<{
        result: 'approved' | 'rejected' | 'error';
    }>;
    callCanister({ params, prompt, notify, options }: {
        params: IcrcCallCanisterRequestParams;
        prompt: CallCanisterPrompt | undefined;
        notify: Notify;
        options: SignerOptions;
    }): Promise<{
        result: 'success' | 'error';
    }>;
    private assertSender;
    private callConsentMessage;
    private notifyError;
    private promptConsentMessage;
    /**
     * If the ICRC-21 call to fetch the consent message fails, it might be due to the fact
     * that the targeted canister does not implement the ICRC-21 specification.
     *
     * To address the potential lack of support for the most common types of calls for ledgers,
     * namely transfer and approve, we use custom builders. Those builders construct
     * messages similar to those that would be implemented by the canisters.
     *
     * @param {Object} params - The parameters for loading the consent message.
     * @param {Omit<IcrcCallCanisterRequestParams, 'sender'>} params.params - The ICRC call canister parameters minus the sender.
     * @param {SignerOptions} params.options - The signer options - host and owner.
     * @returns {Promise<icrc21_consent_message_response | ConsentInfoWarn>} - A consent message response. Returns "Ok" if the message was decoded by the targeted canister, or "Warn" if the fallback builder was used.
     * @throws The potential original error from the ICRC-21 call. The errors related to
     *         the custom builder is ignored.
     **/
    private loadConsentMessage;
    /**
     * Attempts to build a consent message when the signer cannot decode the arguments
     * with the targeted canister. When decoding is attempted locally, user must be warned
     * as specified by the ICRC-49 standards.
     *
     * Instead of returning "Ok" upon success, this function returns "Warn" to indicate
     * that the signer performed the decoding rather than the canister.
     *
     * @see {@link https://github.com/dfinity/wg-identity-authentication/blob/main/topics/icrc_49_call_canister.md#message-processing ICRC-49 Message Processing}
     *
     * @param {Object} params - The parameters for building the consent message.
     * @param {Object} params.params - The ICRC call canister parameters excluding the sender.
     * @param {string} params.params.method - The method being called on the canister.
     * @param {string} params.params.arg - The encoded arguments for the canister call.
     * @param {string} params.params.canisterId - The ID of the targeted canister.
     * @param {Object} params.options - The signer options including host and owner.
     * @param {string} params.options.owner - The principal ID of the signer (caller).
     * @param {string} params.options.host - The host URL for the signer environment.
     *
     * @returns {Promise<{NoFallback: null} | ConsentInfoWarn | {Err: unknown}>} -
     *          - `{NoFallback: null}` if no fallback method is available.
     *          - `ConsentInfoWarn` if a warning response is built successfully.
     *          - `{Err: unknown}` if an error occurs during processing.
     *
     * @throws {Error} - Throws an error if building the consent message fails completely.
     */
    private tryBuildConsentMessageOnError;
}