@aeternity/aepp-sdk 12.1.3 → 13.0.0-alpha.1

package/es/contract/Contract.d.ts

@@ -0,0 +1,210 @@
+/// <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 { BuildTxOptions } from '../tx';
+import { send, SendOptions } from '../spend';
+import { Encoded } from '../utils/encoder';
+import { ContractCallObject as NodeContractCallObject, ContractCallReturnType, Event as NodeEvent } from '../apis/node';
+import CompilerBase, { Aci } from './compiler/Base';
+import Node, { TransformNodeType } from '../Node';
+import { txDryRun } from '../chain';
+import AccountBase from '../account/Base';
+type FunctionAci = Aci['encodedAci']['contract']['functions'][0];
+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: SendOptions): 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] & Partial<BuildTxOptions<Tag.ContractCreateTx, 'ownerId' | 'code' | 'callData'>>): Promise<Omit<SendAndProcessReturnType, 'hash'> & {
+        transaction?: Encoded.TxHash;
+        owner?: Encoded.AccountAddress;
+        address?: Encoded.ContractAddress;
+        decodedEvents?: ReturnType<Contract<M>['$decodeEvents']>;
+    }>;
+    /**
+     * 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?: Partial<BuildTxOptions<Tag.ContractCallTx, 'callerId' | 'contractId' | 'callData'>> & Parameters<Contract<M>['$decodeEvents']>[1] & Omit<Parameters<Contract<M>['_sendAndProcess']>[1], 'onAccount' | 'onNode'> & Omit<Parameters<typeof txDryRun>[2], 'onNode'> & {
+        onAccount?: AccountBase;
+        onNode?: Node;
+        callStatic?: boolean;
+    }): 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, bytecode, aci, address, sourceCodePath, sourceCode, 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: Omit<ConstructorParameters<typeof Contract>[0], 'aci'>;
+    constructor({ aci, ...otherOptions }: {
+        onCompiler?: CompilerBase;
+        onNode: Node;
+        bytecode?: Encoded.ContractBytearray;
+        aci: Aci;
+        address?: Encoded.ContractAddress;
+        sourceCodePath?: Parameters<CompilerBase['compile']>[0];
+        sourceCode?: Parameters<CompilerBase['compileBySourceCode']>[0];
+        fileSystem?: Parameters<CompilerBase['compileBySourceCode']>[1];
+    } & Parameters<Contract<M>['$deploy']>[1]);
+}
+interface ContractWithMethodsClass {
+    new <M extends ContractMethodsBase>(options: ConstructorParameters<typeof Contract>[0]): ContractWithMethods<M>;
+    initialize: typeof Contract['initialize'];
+}
+declare const ContractWithMethods: ContractWithMethodsClass;
+export default ContractWithMethods;