@aeternity/aepp-sdk 12.1.2 → 13.0.0-alpha.0

package/es/contract/Contract.d.ts

@@ -0,0 +1,235 @@
+/// <reference types="@aeternity__aepp-calldata" />
+/**
+ * Contract module - routines to interact with the æternity contract
+ *
+ * High level documentation of the contracts are available at
+ * https://github.com/aeternity/protocol/tree/master/contracts and
+ */
+import { Encoder as Calldata } from '@aeternity/aepp-calldata';
+import { Tag, AensName } from '../tx/builder/constants';
+import { unpackTx } from '../tx/builder';
+import { send } from '../spend';
+import { Encoded } from '../utils/encoder';
+import { Aci as BaseAci } from '../apis/compiler';
+import { ContractCallObject as NodeContractCallObject, ContractCallReturnType, Event as NodeEvent } from '../apis/node';
+import CompilerHttp from './CompilerHttp';
+import Node, { TransformNodeType } from '../Node';
+import AccountBase from '../account/Base';
+interface FunctionACI {
+    arguments: any[];
+    name: string;
+    payable: boolean;
+    returns: string;
+    stateful: boolean;
+}
+interface Aci extends BaseAci {
+    encodedAci: {
+        contract: {
+            name: string;
+            event: any;
+            kind: string;
+            state: any;
+            type_defs: any[];
+            functions: FunctionACI[];
+        };
+    };
+    externalEncodedAci: any[];
+}
+interface Event extends NodeEvent {
+    address: Encoded.ContractAddress;
+    data: Encoded.ContractBytearray;
+}
+export interface ContractCallObject extends NodeContractCallObject {
+    returnValue: Encoded.ContractBytearray;
+    log: Event[];
+}
+interface DecodedEvent {
+    name: string;
+    args: unknown[];
+    contract: {
+        name: string;
+        address: Encoded.ContractAddress;
+    };
+}
+type TxData = Awaited<ReturnType<typeof send>>;
+interface SendAndProcessReturnType {
+    result?: TransformNodeType<ContractCallObject>;
+    hash: TxData['hash'];
+    tx: Awaited<ReturnType<typeof unpackTx<Tag.ContractCallTx | Tag.ContractCreateTx>>>;
+    txData: TxData;
+    rawTx: Encoded.Transaction;
+}
+export interface ContractMethodsBase {
+    [key: string]: (...args: any[]) => any;
+}
+type MethodsToContractApi<M extends ContractMethodsBase> = {
+    [Name in keyof M]: M[Name] extends (...args: infer Args) => infer Ret ? (...args: [
+        ...Args,
+        ...[] | [
+            Name extends 'init' ? Parameters<Contract<M>['$deploy']>[1] : Parameters<Contract<M>['$call']>[2]
+        ]
+    ]) => Promise<Awaited<ReturnType<Contract<M>['$call']>> & {
+        decodedResult?: Ret;
+    }> : never;
+};
+type ContractWithMethods<M extends ContractMethodsBase> = Contract<M> & MethodsToContractApi<M>;
+type MethodNames<M extends ContractMethodsBase> = keyof M & string | 'init';
+type MethodParameters<M extends ContractMethodsBase, Fn extends MethodNames<M>> = Fn extends 'init' ? M extends {
+    init: any;
+} ? Parameters<M['init']> : [] : Parameters<M[Fn]>;
+/**
+ * Generate contract ACI object with predefined js methods for contract usage - can be used for
+ * creating a reference to already deployed contracts
+ * @category contract
+ * @param options - Options object
+ * @returns JS Contract API
+ * @example
+ * ```js
+ * const contractIns = await aeSdk.initializeContract({ sourceCode })
+ * await contractIns.$deploy([321]) or await contractIns.init(321)
+ * const callResult = await contractIns.$call('setState', [123])
+ * const staticCallResult = await contractIns.$call('setState', [123], { callStatic: true })
+ * ```
+ * Also you can call contract like: `await contractIns.setState(123, options)`
+ * Then sdk decide to make on-chain or static call(dry-run API) transaction based on function is
+ * stateful or not
+ */
+declare class Contract<M extends ContractMethodsBase> {
+    /**
+     * Helper to generate a signature to delegate
+     *  - pre-claim/claim/transfer/revoke of a name to a contract.
+     *  - register/extend/respond of an Oracle to a contract.
+     * @category contract
+     * @param ids - The list of id's to prepend
+     * @param _options - Options
+     * @param _options.omitAddress - Prepend delegation signature with an account address
+     * @param _options.onAccount - Account to use
+     * @returns Signature
+     * @example
+     * ```js
+     * const aeSdk = new AeSdk({ ... })
+     * const contract = await aeSdk.initializeContract({ address: 'ct_asd2ks...' })
+     * const aensName = 'example.chain'
+     * const onAccount = new MemoryAccount(...) // Sign with a specific account
+     * // Preclaim signature
+     * const preclaimSig = await contract.$createDelegationSignature([], { onAccount })
+     * // Claim, transfer and revoke signature
+     * const aensDelegationSig = await contract
+     *   .$createDelegationSignature([aensName], { onAccount })
+     * ```
+     * @example
+     * ```js
+     * const aeSdk = new AeSdk({ ... })
+     * const contract = await aeSdk.initializeContract({ address: 'ct_asd2ks...' })
+     * const oracleQueryId = 'oq_...'
+     * const onAccount = new MemoryAccount(...) // Sign with a specific account
+     * // Oracle register and extend signature
+     * const oracleDelegationSig = await contract.$createDelegationSignature([], { onAccount })
+     * // Oracle respond signature
+     * const respondSig = await contract
+     *   .$createDelegationSignature([oracleQueryId], { onAccount, omitAddress: true })
+     * ```
+     */
+    $createDelegationSignature(ids?: Array<Encoded.Any | AensName>, _options?: {
+        omitAddress?: boolean;
+        onAccount?: AccountBase;
+    }): Promise<Uint8Array>;
+    /**
+     * Compile contract
+     * @returns bytecode
+     */
+    $compile(): Promise<Encoded.ContractBytearray>;
+    protected _handleCallError({ returnType, returnValue }: {
+        returnType: ContractCallReturnType;
+        returnValue: Encoded.ContractBytearray;
+    }, transaction: string): void;
+    protected _sendAndProcess(tx: Encoded.Transaction, options: any): Promise<SendAndProcessReturnType>;
+    _estimateGas<Fn extends MethodNames<M>>(name: Fn, params: MethodParameters<M, Fn>, options?: object): Promise<number>;
+    /**
+     * Deploy contract
+     * @param params - Contract init function arguments array
+     * @param options - Options
+     * @returns deploy info
+     */
+    $deploy(params: MethodParameters<M, 'init'>, options?: Parameters<Contract<M>['$call']>[2] & Parameters<Contract<M>['_sendAndProcess']>[1]): Promise<Omit<SendAndProcessReturnType, 'hash'> & {
+        transaction?: Encoded.TxHash;
+        owner?: Encoded.AccountAddress;
+        address?: Encoded.ContractAddress;
+    }>;
+    /**
+     * Get function schema from contract ACI object
+     * @param name - Function name
+     * @returns function ACI
+     */
+    protected _getFunctionACI(name: string): Partial<FunctionACI>;
+    /**
+     * Call contract function
+     * @param fn - Function name
+     * @param params - Array of function arguments
+     * @param options - Array of function arguments
+     * @returns CallResult
+     */
+    $call<Fn extends MethodNames<M>>(fn: Fn, params: MethodParameters<M, Fn>, options?: object): Promise<{
+        decodedResult?: any;
+        decodedEvents?: ReturnType<Contract<M>['$decodeEvents']>;
+    } & SendAndProcessReturnType>;
+    /**
+     * @param ctAddress - Contract address that emitted event
+     * @param nameHash - Hash of emitted event name
+     * @param options - Options
+     * @returns Contract name
+     * @throws {@link MissingEventDefinitionError}
+     * @throws {@link AmbiguousEventDefinitionError}
+     */
+    protected _getContractNameByEvent(ctAddress: Encoded.ContractAddress, nameHash: BigInt, { contractAddressToName }: {
+        contractAddressToName?: {
+            [key: Encoded.ContractAddress]: string;
+        };
+    }): string;
+    /**
+     * Decode Events
+     * @param events - Array of encoded events (callRes.result.log)
+     * @param options - Options
+     * @returns DecodedEvents
+     */
+    $decodeEvents(events: Event[], { omitUnknown, ...opt }?: {
+        omitUnknown?: boolean;
+    } & Parameters<Contract<M>['_getContractNameByEvent']>[2]): DecodedEvent[];
+    static initialize<M extends ContractMethodsBase>({ onCompiler, onNode, sourceCode, bytecode, aci, address, fileSystem, validateBytecode, ...otherOptions }: Omit<ConstructorParameters<typeof Contract>[0], 'aci' | 'address'> & {
+        validateBytecode?: boolean;
+        aci?: Aci;
+        address?: Encoded.ContractAddress | AensName;
+    }): Promise<ContractWithMethods<M>>;
+    _aci: Aci;
+    _name: string;
+    _calldata: Calldata;
+    $options: {
+        sourceCode?: string;
+        bytecode?: Encoded.ContractBytearray;
+        address?: Encoded.ContractAddress;
+        onCompiler: CompilerHttp;
+        onNode: Node;
+        omitUnknown?: boolean;
+        contractAddressToName?: {
+            [key: Encoded.ContractAddress]: string;
+        };
+        [key: string]: any;
+    };
+    constructor({ aci, ...otherOptions }: {
+        onAccount?: AccountBase;
+        onCompiler: CompilerHttp;
+        onNode: Node;
+        sourceCode?: string;
+        bytecode?: Encoded.ContractBytearray;
+        aci: Aci;
+        address?: Encoded.ContractAddress;
+        fileSystem?: Record<string, string>;
+        [key: string]: any;
+    });
+}
+interface ContractWithMethodsClass {
+    new <M extends ContractMethodsBase>(options: ConstructorParameters<typeof Contract>[0]): ContractWithMethods<M>;
+    initialize: typeof Contract['initialize'];
+}
+declare const ContractWithMethods: ContractWithMethodsClass;
+export default ContractWithMethods;