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

package/es/channel/Contract.d.ts

@@ -0,0 +1,247 @@
+import BigNumber from 'bignumber.js';
+import { SignTx, ChannelState, ChannelOptions } from './internal';
+import { Encoded } from '../utils/encoder';
+import { ContractCallReturnType } from '../apis/node';
+import { ContractCallObject } from '../contract/Contract';
+import ChannelSpend from './Spend';
+interface CallContractOptions {
+    amount?: number | BigNumber;
+    callData?: Encoded.ContractBytearray;
+    abiVersion?: number;
+    contract?: Encoded.ContractAddress;
+    returnValue?: any;
+    gasUsed?: number | BigNumber;
+    gasPrice?: number | BigNumber;
+    height?: number;
+    callerNonce?: number;
+    log?: any;
+    returnType?: ContractCallReturnType;
+}
+interface Contract {
+    abiVersion: number;
+    active: boolean;
+    deposit: number | BigNumber;
+    id: string;
+    ownerId: string;
+    referrerIds: string[];
+    vmVersion: number;
+}
+export default class ChannelContract extends ChannelSpend {
+    static initialize(options: ChannelOptions): Promise<ChannelContract>;
+    /**
+     * Trigger create contract update
+     *
+     * The create contract update is creating a contract inside the channel's internal state tree.
+     * The update is a change to be applied on top of the latest state.
+     *
+     * That would create a contract with the poster being the owner of it. Poster commits initially
+     * a deposit amount of coins to the new contract.
+     *
+     * @param options - Options
+     * @param options.code - Api encoded compiled AEVM byte code
+     * @param options.callData - Api encoded compiled AEVM call data for the code
+     * @param options.deposit - Initial amount the owner of the contract commits to it
+     * @param options.vmVersion - Version of the Virtual Machine
+     * @param options.abiVersion - Version of the Application Binary Interface
+     * @param sign - Function which verifies and signs create contract transaction
+     * @example
+     * ```js
+     * channel.createContract({
+     *   code: 'cb_HKtpipK4aCgYb17wZ...',
+     *   callData: 'cb_1111111111111111...',
+     *   deposit: 10,
+     *   vmVersion: 3,
+     *   abiVersion: 1
+     * }).then(({ accepted, signedTx, address }) => {
+     *   if (accepted) {
+     *     console.log('New contract has been created')
+     *     console.log('Contract address:', address)
+     *   } else {
+     *     console.log('New contract has been rejected')
+     *   }
+     * })
+     * ```
+     */
+    createContract({ code, callData, deposit, vmVersion, abiVersion, }: {
+        code: Encoded.ContractBytearray;
+        callData: Encoded.ContractBytearray;
+        deposit: number | BigNumber;
+        vmVersion: number;
+        abiVersion: number;
+    }, sign: SignTx): Promise<{
+        accepted: boolean;
+        signedTx: Encoded.Transaction;
+        address: Encoded.ContractAddress;
+    }>;
+    /**
+     * Trigger call a contract update
+     *
+     * The call contract update is calling a preexisting contract inside the channel's
+     * internal state tree. The update is a change to be applied on top of the latest state.
+     *
+     * That would call a contract with the poster being the caller of it. Poster commits
+     * an amount of coins to the contract.
+     *
+     * The call would also create a call object inside the channel state tree. It contains
+     * the result of the contract call.
+     *
+     * It is worth mentioning that the gas is not consumed, because this is an off-chain
+     * contract call. It would be consumed if it were an on-chain one. This could happen
+     * if a call with a similar computation amount is to be forced on-chain.
+     *
+     * @param options - Options
+     * @param options.amount - Amount the caller of the contract commits to it
+     * @param options.callData - ABI encoded compiled AEVM call data for the code
+     * @param options.contract - Address of the contract to call
+     * @param options.abiVersion - Version of the ABI
+     * @param sign - Function which verifies and signs contract call transaction
+     * @example
+     * ```js
+     * channel.callContract({
+     *   contract: 'ct_9sRA9AVE4BYTAkh5RNfJYmwQe1NZ4MErasQLXZkFWG43TPBqa',
+     *   callData: 'cb_1111111111111111...',
+     *   amount: 0,
+     *   abiVersion: 1
+     * }).then(({ accepted, signedTx }) => {
+     *   if (accepted) {
+     *     console.log('Contract called succesfully')
+     *   } else {
+     *     console.log('Contract call has been rejected')
+     *   }
+     * })
+     * ```
+     */
+    callContract({ amount, callData, contract, abiVersion, }: CallContractOptions, sign: SignTx): Promise<{
+        accepted: boolean;
+        signedTx: Encoded.Transaction;
+    }>;
+    /**
+     * Trigger a force progress contract call
+     * This call is going on-chain
+     * @param options - Options
+     * @param options.amount - Amount the caller of the contract commits to it
+     * @param options.callData - ABI encoded compiled AEVM call data for the code
+     * @param options.contract - Address of the contract to call
+     * @param options.abiVersion - Version of the ABI
+     * @param options.gasPrice=1000000000]
+     * @param options.gasLimit=1000000]
+     * @param sign - Function which verifies and signs contract force progress transaction
+     * @param callbacks - Callbacks
+     * @example
+     * ```js
+     * channel.forceProgress({
+     *   contract: 'ct_9sRA9AVE4BYTAkh5RNfJYmwQe1NZ4MErasQLXZkFWG43TPBqa',
+     *   callData: 'cb_1111111111111111...',
+     *   amount: 0,
+     *   abiVersion: 1,
+     *   gasPrice: 1000005554
+     * }).then(({ accepted, signedTx }) => {
+     *   if (accepted) {
+     *     console.log('Contract force progress call successful')
+     *   } else {
+     *     console.log('Contract force progress call has been rejected')
+     *   }
+     * })
+     * ```
+     */
+    forceProgress({ amount, callData, contract, abiVersion, gasLimit, gasPrice, }: {
+        amount: number;
+        callData: Encoded.ContractBytearray;
+        contract: Encoded.ContractAddress;
+        abiVersion: number;
+        gasLimit?: number;
+        gasPrice?: number;
+    }, sign: SignTx, { onOnChainTx }?: Pick<ChannelState, 'onOnChainTx'>): Promise<{
+        accepted: boolean;
+        signedTx: Encoded.Transaction;
+        tx: Encoded.Transaction | Uint8Array;
+    }>;
+    /**
+     * Call contract using dry-run
+     *
+     * In order to get the result of a potential contract call, one might need to
+     * dry-run a contract call. It takes the exact same arguments as a call would
+     * and returns the call object.
+     *
+     * The call is executed in the channel's state, but it does not impact the state
+     * whatsoever. It uses as an environment the latest channel's state and the current
+     * top of the blockchain as seen by the node.
+     *
+     * @param options - Options
+     * @param options.amount - Amount the caller of the contract commits to it
+     * @param options.callData - ABI encoded compiled AEVM call data for the code
+     * @param options.contract - Address of the contract to call
+     * @param options.abiVersion - Version of the ABI
+     * @example
+     * ```js
+     * channel.callContractStatic({
+     *   contract: 'ct_9sRA9AVE4BYTAkh5RNfJYmwQe1NZ4MErasQLXZkFWG43TPBqa',
+     *   callData: 'cb_1111111111111111...',
+     *   amount: 0,
+     *   abiVersion: 1
+     * }).then(({ returnValue, gasUsed }) => {
+     *   console.log('Returned value:', returnValue)
+     *   console.log('Gas used:', gasUsed)
+     * })
+     * ```
+     */
+    callContractStatic({ amount, callData, contract, abiVersion, }: {
+        amount: number;
+        callData: Encoded.ContractBytearray;
+        contract: Encoded.ContractAddress;
+        abiVersion: number;
+    }): Promise<CallContractOptions>;
+    /**
+     * Get contract call result
+     *
+     * The combination of a caller, contract and a round of execution determines the
+     * contract call. Providing an incorrect set of those results in an error response.
+     *
+     * @param options - Options
+     * @param options.caller - Address of contract caller
+     * @param options.contract - Address of the contract
+     * @param options.round - Round when contract was called
+     * @example
+     * ```js
+     * channel.getContractCall({
+     *   caller: 'ak_Y1NRjHuoc3CGMYMvCmdHSBpJsMDR6Ra2t5zjhRcbtMeXXLpLH',
+     *   contract: 'ct_9sRA9AVE4BYTAkh5RNfJYmwQe1NZ4MErasQLXZkFWG43TPBqa',
+     *   round: 3
+     * }).then(({ returnType, returnValue }) => {
+     *   if (returnType === 'ok') console.log(returnValue)
+     * })
+     * ```
+     */
+    getContractCall({ caller, contract, round }: {
+        caller: Encoded.AccountAddress;
+        contract: Encoded.ContractAddress;
+        round: number;
+    }): Promise<ContractCallObject>;
+    /**
+     * Get the latest contract state
+     *
+     * @param contract - Address of the contract
+     * @example
+     * ```js
+     * channel.getContractState(
+     *   'ct_9sRA9AVE4BYTAkh5RNfJYmwQe1NZ4MErasQLXZkFWG43TPBqa'
+     * ).then(({ contract }) => {
+     *   console.log('deposit:', contract.deposit)
+     * })
+     * ```
+     */
+    getContractState(contract: Encoded.ContractAddress): Promise<{
+        contract: Contract;
+        contractState: object;
+    }>;
+    /**
+     * Clean up all locally stored contract calls
+     *
+     * Contract calls are kept locally in order for the participant to be able to look them up.
+     * They consume memory and in order for the participant to free it - one can prune all messages.
+     * This cleans up all locally stored contract calls and those will no longer be available for
+     * fetching and inspection.
+     */
+    cleanContractCalls(): Promise<void>;
+}
+export {};

package/es/channel/Contract.mjs

@@ -0,0 +1,420 @@
+/*
+ * ISC License (ISC)
+ * Copyright (c) 2022 aeternity developers
+ *
+ *  Permission to use, copy, modify, and/or distribute this software for any
+ *  purpose with or without fee is hereby granted, provided that the above
+ *  copyright notice and this permission notice appear in all copies.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+ *  REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+ *  AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+ *  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+ *  LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+ *  OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+ *  PERFORMANCE OF THIS SOFTWARE.
+ */
+import { snakeToPascal } from "../utils/string.mjs";
+import { MIN_GAS_PRICE, Tag } from "../tx/builder/constants.mjs";
+import { signAndNotify, awaitingCompletion, channelClosed, channelOpen, handleUnexpectedMessage } from "./handlers.mjs";
+import { notify, call, changeState, emit } from "./internal.mjs";
+import Channel from "./Base.mjs";
+import ChannelSpend from "./Spend.mjs";
+import { UnexpectedChannelMessageError } from "../utils/errors.mjs";
+import { unpackTx } from "../tx/builder/index.mjs";
+import { encodeContractAddress } from "../utils/crypto.mjs";
+function snakeToPascalObjKeys(obj) {
+  return Object.entries(obj).reduce((result, _ref) => {
+    let [key, val] = _ref;
+    return {
+      ...result,
+      [snakeToPascal(key)]: val
+    };
+  }, {});
+}
+export default class ChannelContract extends ChannelSpend {
+  static async initialize(options) {
+    return Channel._initialize(new ChannelContract(), options);
+  }
+
+  /**
+   * Trigger create contract update
+   *
+   * The create contract update is creating a contract inside the channel's internal state tree.
+   * The update is a change to be applied on top of the latest state.
+   *
+   * That would create a contract with the poster being the owner of it. Poster commits initially
+   * a deposit amount of coins to the new contract.
+   *
+   * @param options - Options
+   * @param options.code - Api encoded compiled AEVM byte code
+   * @param options.callData - Api encoded compiled AEVM call data for the code
+   * @param options.deposit - Initial amount the owner of the contract commits to it
+   * @param options.vmVersion - Version of the Virtual Machine
+   * @param options.abiVersion - Version of the Application Binary Interface
+   * @param sign - Function which verifies and signs create contract transaction
+   * @example
+   * ```js
+   * channel.createContract({
+   *   code: 'cb_HKtpipK4aCgYb17wZ...',
+   *   callData: 'cb_1111111111111111...',
+   *   deposit: 10,
+   *   vmVersion: 3,
+   *   abiVersion: 1
+   * }).then(({ accepted, signedTx, address }) => {
+   *   if (accepted) {
+   *     console.log('New contract has been created')
+   *     console.log('Contract address:', address)
+   *   } else {
+   *     console.log('New contract has been rejected')
+   *   }
+   * })
+   * ```
+   */
+  async createContract(_ref2, sign) {
+    let {
+      code,
+      callData,
+      deposit,
+      vmVersion,
+      abiVersion
+    } = _ref2;
+    return this.enqueueAction(() => {
+      notify(this, 'channels.update.new_contract', {
+        code,
+        call_data: callData,
+        deposit,
+        vm_version: vmVersion,
+        abi_version: abiVersion
+      });
+      return {
+        handler: async (_, message, state) => {
+          if (message.method !== 'channels.sign.update') {
+            return handleUnexpectedMessage(this, message, state);
+          }
+          await signAndNotify(this, 'channels.update', message.params.data, async tx => state.sign(tx));
+          return {
+            handler: (_2, message2, state2) => awaitingCompletion(this, message2, state2, () => {
+              const {
+                round
+              } = unpackTx(message2.params.data.state, Tag.SignedTx).tx.encodedTx.tx;
+              const addressKey = this._options.role === 'initiator' ? 'initiatorId' : 'responderId';
+              const owner = this._options[addressKey];
+              changeState(this, message2.params.data.state);
+              state2.resolve({
+                accepted: true,
+                address: encodeContractAddress(owner, round),
+                signedTx: message2.params.data.state
+              });
+              return {
+                handler: channelOpen
+              };
+            }),
+            state
+          };
+        },
+        state: {
+          sign
+        }
+      };
+    });
+  }
+
+  /**
+   * Trigger call a contract update
+   *
+   * The call contract update is calling a preexisting contract inside the channel's
+   * internal state tree. The update is a change to be applied on top of the latest state.
+   *
+   * That would call a contract with the poster being the caller of it. Poster commits
+   * an amount of coins to the contract.
+   *
+   * The call would also create a call object inside the channel state tree. It contains
+   * the result of the contract call.
+   *
+   * It is worth mentioning that the gas is not consumed, because this is an off-chain
+   * contract call. It would be consumed if it were an on-chain one. This could happen
+   * if a call with a similar computation amount is to be forced on-chain.
+   *
+   * @param options - Options
+   * @param options.amount - Amount the caller of the contract commits to it
+   * @param options.callData - ABI encoded compiled AEVM call data for the code
+   * @param options.contract - Address of the contract to call
+   * @param options.abiVersion - Version of the ABI
+   * @param sign - Function which verifies and signs contract call transaction
+   * @example
+   * ```js
+   * channel.callContract({
+   *   contract: 'ct_9sRA9AVE4BYTAkh5RNfJYmwQe1NZ4MErasQLXZkFWG43TPBqa',
+   *   callData: 'cb_1111111111111111...',
+   *   amount: 0,
+   *   abiVersion: 1
+   * }).then(({ accepted, signedTx }) => {
+   *   if (accepted) {
+   *     console.log('Contract called succesfully')
+   *   } else {
+   *     console.log('Contract call has been rejected')
+   *   }
+   * })
+   * ```
+   */
+  async callContract(_ref3, sign) {
+    let {
+      amount,
+      callData,
+      contract,
+      abiVersion
+    } = _ref3;
+    return this.enqueueAction(() => {
+      notify(this, 'channels.update.call_contract', {
+        amount,
+        call_data: callData,
+        contract_id: contract,
+        abi_version: abiVersion
+      });
+      return {
+        handler: async (_, message, state) => {
+          if (message.method !== 'channels.sign.update') {
+            return handleUnexpectedMessage(this, message, state);
+          }
+          await signAndNotify(this, 'channels.update', message.params.data, async tx => state.sign(tx, {
+            updates: message.params.data.updates
+          }));
+          return {
+            handler: (_2, message2, state2) => awaitingCompletion(this, message2, state2, () => {
+              changeState(this, message2.params.data.state);
+              state2.resolve({
+                accepted: true,
+                signedTx: message2.params.data.state
+              });
+              return {
+                handler: channelOpen
+              };
+            }),
+            state
+          };
+        },
+        state: {
+          sign
+        }
+      };
+    });
+  }
+
+  /**
+   * Trigger a force progress contract call
+   * This call is going on-chain
+   * @param options - Options
+   * @param options.amount - Amount the caller of the contract commits to it
+   * @param options.callData - ABI encoded compiled AEVM call data for the code
+   * @param options.contract - Address of the contract to call
+   * @param options.abiVersion - Version of the ABI
+   * @param options.gasPrice=1000000000]
+   * @param options.gasLimit=1000000]
+   * @param sign - Function which verifies and signs contract force progress transaction
+   * @param callbacks - Callbacks
+   * @example
+   * ```js
+   * channel.forceProgress({
+   *   contract: 'ct_9sRA9AVE4BYTAkh5RNfJYmwQe1NZ4MErasQLXZkFWG43TPBqa',
+   *   callData: 'cb_1111111111111111...',
+   *   amount: 0,
+   *   abiVersion: 1,
+   *   gasPrice: 1000005554
+   * }).then(({ accepted, signedTx }) => {
+   *   if (accepted) {
+   *     console.log('Contract force progress call successful')
+   *   } else {
+   *     console.log('Contract force progress call has been rejected')
+   *   }
+   * })
+   * ```
+   */
+  async forceProgress(_ref4, sign) {
+    let {
+      amount,
+      callData,
+      contract,
+      abiVersion,
+      gasLimit = 1000000,
+      gasPrice = MIN_GAS_PRICE
+    } = _ref4;
+    let {
+      onOnChainTx
+    } = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    return this.enqueueAction(() => {
+      notify(this, 'channels.force_progress', {
+        amount,
+        call_data: callData,
+        contract_id: contract,
+        abi_version: abiVersion,
+        gas_price: gasPrice,
+        gas: gasLimit
+      });
+      return {
+        handler: async (_, message, state) => {
+          if (message.method !== 'channels.sign.force_progress_tx') {
+            return handleUnexpectedMessage(this, message, state);
+          }
+          await signAndNotify(this, 'channels.force_progress_sign', message.params.data, async tx => state.sign(tx, {
+            updates: message.params.data.updates
+          }));
+          return {
+            handler: (_2, message2, state2) => {
+              if (message2.method === 'channels.on_chain_tx') {
+                var _state2$onOnChainTx;
+                (_state2$onOnChainTx = state2.onOnChainTx) === null || _state2$onOnChainTx === void 0 ? void 0 : _state2$onOnChainTx.call(state2, message2.params.data.tx);
+                emit(this, 'onChainTx', message2.params.data.tx, {
+                  info: message2.params.data.info,
+                  type: message2.params.data.type
+                });
+                state2.resolve({
+                  accepted: true,
+                  tx: message2.params.data.tx
+                });
+                // TODO: shouldn't be unexpected message in this case
+              }
+
+              return handleUnexpectedMessage(this, message2, state2);
+            },
+            state
+          };
+        },
+        state: {
+          sign,
+          onOnChainTx
+        }
+      };
+    });
+  }
+
+  /**
+   * Call contract using dry-run
+   *
+   * In order to get the result of a potential contract call, one might need to
+   * dry-run a contract call. It takes the exact same arguments as a call would
+   * and returns the call object.
+   *
+   * The call is executed in the channel's state, but it does not impact the state
+   * whatsoever. It uses as an environment the latest channel's state and the current
+   * top of the blockchain as seen by the node.
+   *
+   * @param options - Options
+   * @param options.amount - Amount the caller of the contract commits to it
+   * @param options.callData - ABI encoded compiled AEVM call data for the code
+   * @param options.contract - Address of the contract to call
+   * @param options.abiVersion - Version of the ABI
+   * @example
+   * ```js
+   * channel.callContractStatic({
+   *   contract: 'ct_9sRA9AVE4BYTAkh5RNfJYmwQe1NZ4MErasQLXZkFWG43TPBqa',
+   *   callData: 'cb_1111111111111111...',
+   *   amount: 0,
+   *   abiVersion: 1
+   * }).then(({ returnValue, gasUsed }) => {
+   *   console.log('Returned value:', returnValue)
+   *   console.log('Gas used:', gasUsed)
+   * })
+   * ```
+   */
+  async callContractStatic(_ref5) {
+    let {
+      amount,
+      callData,
+      contract,
+      abiVersion
+    } = _ref5;
+    return snakeToPascalObjKeys(await call(this, 'channels.dry_run.call_contract', {
+      amount,
+      call_data: callData,
+      contract_id: contract,
+      abi_version: abiVersion
+    }));
+  }
+
+  /**
+   * Get contract call result
+   *
+   * The combination of a caller, contract and a round of execution determines the
+   * contract call. Providing an incorrect set of those results in an error response.
+   *
+   * @param options - Options
+   * @param options.caller - Address of contract caller
+   * @param options.contract - Address of the contract
+   * @param options.round - Round when contract was called
+   * @example
+   * ```js
+   * channel.getContractCall({
+   *   caller: 'ak_Y1NRjHuoc3CGMYMvCmdHSBpJsMDR6Ra2t5zjhRcbtMeXXLpLH',
+   *   contract: 'ct_9sRA9AVE4BYTAkh5RNfJYmwQe1NZ4MErasQLXZkFWG43TPBqa',
+   *   round: 3
+   * }).then(({ returnType, returnValue }) => {
+   *   if (returnType === 'ok') console.log(returnValue)
+   * })
+   * ```
+   */
+  async getContractCall(_ref6) {
+    let {
+      caller,
+      contract,
+      round
+    } = _ref6;
+    return snakeToPascalObjKeys(await call(this, 'channels.get.contract_call', {
+      caller_id: caller,
+      contract_id: contract,
+      round
+    }));
+  }
+
+  /**
+   * Get the latest contract state
+   *
+   * @param contract - Address of the contract
+   * @example
+   * ```js
+   * channel.getContractState(
+   *   'ct_9sRA9AVE4BYTAkh5RNfJYmwQe1NZ4MErasQLXZkFWG43TPBqa'
+   * ).then(({ contract }) => {
+   *   console.log('deposit:', contract.deposit)
+   * })
+   * ```
+   */
+  async getContractState(contract) {
+    const result = await call(this, 'channels.get.contract', {
+      pubkey: contract
+    });
+    return snakeToPascalObjKeys({
+      ...result,
+      contract: snakeToPascalObjKeys(result.contract)
+    });
+  }
+
+  /**
+   * Clean up all locally stored contract calls
+   *
+   * Contract calls are kept locally in order for the participant to be able to look them up.
+   * They consume memory and in order for the participant to free it - one can prune all messages.
+   * This cleans up all locally stored contract calls and those will no longer be available for
+   * fetching and inspection.
+   */
+  async cleanContractCalls() {
+    return this.enqueueAction(() => {
+      notify(this, 'channels.clean_contract_calls');
+      return {
+        handler(_, message, state) {
+          if (message.method === 'channels.calls_pruned.reply') {
+            state.resolve();
+            return {
+              handler: channelOpen
+            };
+          }
+          state.reject(new UnexpectedChannelMessageError('Unexpected message received'));
+          return {
+            handler: channelClosed
+          };
+        }
+      };
+    });
+  }
+}
+//# sourceMappingURL=Contract.mjs.map