@aeternity/aepp-sdk 11.0.1 → 12.1.1

package/src/contract/ga.ts

@@ -0,0 +1,199 @@
+/*
+ * 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.
+ */
+
+/**
+ * Generalized Account module - routines to use generalized account
+ */
+
+import { MAX_AUTH_FUN_GAS, TxSchema } from '../tx/builder/schema';
+import { Tag } from '../tx/builder/constants';
+import {
+  buildContractIdByContractTx, buildTx, BuiltTx, TxUnpacked, unpackTx,
+} from '../tx/builder';
+import {
+  _buildTx, BuildTxOptions, getVmVersion, prepareTxParams,
+} from '../tx';
+import { hash } from '../utils/crypto';
+import { decode, Encoded, Encoding } from '../utils/encoder';
+import { IllegalArgumentError, MissingParamError, InvalidAuthDataError } from '../utils/errors';
+import { concatBuffers } from '../utils/other';
+import AccountBase from '../account/Base';
+import { getContractInstance } from './methods';
+import { send, SendOptions } from '../spend';
+import Node from '../Node';
+import { getAccount } from '../chain';
+import Compiler from './Compiler';
+
+/**
+ * Check if account is GA
+ * @category contract
+ * @param address - Account address
+ * @param options - Options
+ * @returns if account is GA
+ */
+export async function isGA(
+  address: Encoded.AccountAddress,
+  options: Parameters<typeof getAccount>[1],
+): Promise<boolean> {
+  const { contractId } = await getAccount(address, options);
+  return contractId != null;
+}
+
+/**
+ * Convert current account to GA
+ * @category contract
+ * @param authFnName - Authorization function name
+ * @param source - Auth contract source code
+ * @param args - init arguments
+ * @param options - Options
+ * @returns General Account Object
+ */
+export async function createGeneralizedAccount(
+  authFnName: string,
+  source: string,
+  args: any[],
+  {
+    onAccount, onCompiler, onNode, ...options
+  }: CreateGeneralizedAccountOptions,
+): Promise<Readonly<{
+    owner: Encoded.AccountAddress;
+    transaction: Encoded.TxHash;
+    rawTx: Encoded.Transaction;
+    gaContractId: Encoded.ContractAddress;
+  }>> {
+  const ownerId = await onAccount.address(options);
+  if (await isGA(ownerId, { onNode })) throw new IllegalArgumentError(`Account ${ownerId} is already GA`);
+
+  const contract = await getContractInstance({
+    onAccount, onCompiler, onNode, source,
+  });
+
+  const tx = await _buildTx(Tag.GaAttachTx, {
+    ...options,
+    onNode,
+    code: await contract.compile(),
+    gasLimit: options.gasLimit ?? await contract._estimateGas('init', args, options),
+    ownerId,
+    callData: contract.calldata.encode(contract._name, 'init', args),
+    authFun: hash(authFnName),
+  });
+  const contractId = buildContractIdByContractTx(tx);
+  const { hash: transaction, rawTx } = await send(tx, {
+    onNode, onAccount, onCompiler, ...options,
+  });
+
+  return Object.freeze({
+    owner: ownerId,
+    transaction,
+    rawTx,
+    gaContractId: contractId,
+  });
+}
+
+interface CreateGeneralizedAccountOptions extends
+  BuildTxOptions<Tag.GaAttachTx, 'authFun' | 'callData' | 'code' | 'ownerId' | 'gasLimit'>,
+  SendOptions {
+  onAccount: AccountBase;
+  onCompiler: Compiler;
+  onNode: Node;
+  gasLimit?: number;
+}
+
+/**
+ * Create a metaTx transaction
+ * @category contract
+ * @param rawTransaction - Inner transaction
+ * @param authData - Object with gaMeta params
+ * @param authFnName - Authorization function name
+ * @param options - Options
+ * @param options.onAccount - Account to use
+ * @returns Transaction string
+ */
+export async function createMetaTx(
+  rawTransaction: Encoded.Transaction,
+  authData: {
+    gasLimit?: number;
+    callData?: Encoded.ContractBytearray;
+    source?: string;
+    args?: any[];
+  },
+  authFnName: string,
+  {
+    onAccount, onCompiler, onNode, ...options
+  }:
+  { onAccount: AccountBase; onCompiler: Compiler; onNode: Node }
+  & Parameters<AccountBase['address']>[0],
+): Promise<Encoded.Transaction> {
+  const wrapInEmptySignedTx = (
+    tx: Encoded.Transaction | Uint8Array | TxUnpacked<TxSchema>,
+  ): BuiltTx<TxSchema, Encoding.Transaction> => (
+    buildTx({ encodedTx: tx, signatures: [] }, Tag.SignedTx)
+  );
+
+  if (Object.keys(authData).length <= 0) throw new MissingParamError('authData is required');
+
+  const gasLimit = authData.gasLimit ?? MAX_AUTH_FUN_GAS;
+  if (gasLimit > MAX_AUTH_FUN_GAS) {
+    throw new InvalidAuthDataError(`the maximum gasLimit value for ga authFun is ${MAX_AUTH_FUN_GAS}, got ${gasLimit}`);
+  }
+
+  const authCallData = authData.callData ?? await (async () => {
+    if (authData.source == null || authData.args == null) throw new InvalidAuthDataError('Auth data must contain source code and arguments.');
+    const contract = await getContractInstance({
+      onCompiler, onNode, source: authData.source,
+    });
+    return contract.calldata.encode(contract._name, authFnName, authData.args);
+  })();
+
+  const { abiVersion } = await getVmVersion(Tag.ContractCallTx, { onNode });
+  const wrappedTx = wrapInEmptySignedTx(unpackTx<Tag.SignedTx>(rawTransaction));
+  const params = {
+    ...options,
+    tx: {
+      ...wrappedTx,
+      tx: wrappedTx.txObject,
+    },
+    // TODO: accept an address instead
+    gaId: await onAccount.address(options),
+    abiVersion,
+    authData: authCallData,
+    gasLimit,
+    vsn: 2,
+  };
+  // @ts-expect-error createMetaTx needs to be integrated into tx builder
+  const { fee } = await prepareTxParams(Tag.GaMetaTx, { ...params, onNode });
+  const { rlpEncoded: metaTxRlp } = buildTx({ ...params, fee }, Tag.GaMetaTx);
+  return wrapInEmptySignedTx(metaTxRlp).tx;
+}
+
+/**
+ * Build a transaction hash the same as `Auth.tx_hash`
+ * @category contract
+ * @param transaction - tx-encoded transaction
+ * @param options - Options
+ * @param options.onNode - Node to use
+ * @returns Transaction hash
+ */
+export async function buildAuthTxHash(
+  transaction: Encoded.Transaction,
+  { onNode }: { onNode: Node },
+): Promise<Uint8Array> {
+  const { networkId } = await onNode.getStatus();
+  return new Uint8Array(hash(
+    concatBuffers([Buffer.from(networkId), decode(transaction)]),
+  ));
+}

package/src/contract/methods.ts

@@ -0,0 +1,123 @@
+/*
+ * 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.
+ */
+
+/**
+ * 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 { AensName } from '../tx/builder/constants';
+import { produceNameId } from '../tx/builder/helpers';
+import { concatBuffers } from '../utils/other';
+import { decode, Encoded } from '../utils/encoder';
+import AccountBase from '../account/Base';
+import Node from '../Node';
+
+export { default as getContractInstance } from './aci';
+
+/**
+ * Utility method to create a delegate signature for a contract
+ * @category contract
+ * @param ids - The list of id's to prepend
+ * @param opt - Options
+ * @param opt.onNode - Node to use
+ * @param opt.onAccount - Account to use
+ * @returns Signature in hex representation
+ */
+async function delegateSignatureCommon(
+  ids: Encoded.Any[],
+  { onAccount, onNode, ...opt }:
+  { onAccount: AccountBase; onNode: Node } & Parameters<AccountBase['sign']>[1],
+): Promise<string> {
+  const signature = await onAccount.sign(
+    concatBuffers([
+      Buffer.from((await onNode.getStatus()).networkId),
+      ...ids.map((e) => decode(e)),
+    ]),
+    opt,
+  );
+  return Buffer.from(signature).toString('hex');
+}
+
+/**
+ * Helper to generate a signature to delegate pre-claim/claim/transfer/revoke of a name to
+ * a contract.
+ * @category contract
+ * @param contractId - Contract Id
+ * @param opt - Options
+ * @param opt.name - The name
+ * @returns Signature for delegation
+ * @example
+ * ```js
+ * const aeSdk = new AeSdk({ ... })
+ * const contractId = 'ct_asd2ks...' // contract address
+ * const name = 'example.chain' // AENS name
+ * const onAccount = await aeSdk.address() // Sign with a specific account
+ * // Preclaim signature
+ * const preclaimSig = await aeSdk.createAensDelegationSignature(contractId, { onAccount: current })
+ * // Claim, transfer and revoke signature
+ * const aensDelegationSig = await contract.createAensDelegationSignature(
+ *   contractId, { name, onAccount: current }
+ * )
+ * ```
+ */
+export async function createAensDelegationSignature(
+  contractId: Encoded.ContractAddress,
+  opt: Parameters<AccountBase['address']>[0] & Parameters<typeof delegateSignatureCommon>[1] &
+  { name?: AensName },
+): Promise<string> {
+  return delegateSignatureCommon(
+    [
+      await opt.onAccount.address(opt),
+      ...opt.name != null ? [produceNameId(opt.name)] : [],
+      contractId,
+    ],
+    opt,
+  );
+}
+
+/**
+ * Helper to generate a signature to delegate register/extend/respond of a Oracle to a contract.
+ * @category contract
+ * @param contractId - Contract Id
+ * @param opt - Options
+ * @param opt.queryId - Oracle Query Id
+ * @returns Signature for delegation
+ * @example
+ * ```js
+ * const aeSdk = new AeSdk({ ... })
+ * const contractId = 'ct_asd2ks...' // contract address
+ * const queryId = 'oq_...' // Oracle Query Id
+ * const onAccount = await aeSdk.address() // Sign with a specific account
+ * // Oracle register and extend signature
+ * const oracleDelegationSig = await aeSdk.createOracleDelegationSignature(contractId)
+ * // Oracle respond signature
+ * const respondSig = await aeSdk.createOracleDelegationSignature(contractId, { queryId })
+ * ```
+ */
+export async function createOracleDelegationSignature(
+  contractId: Encoded.ContractAddress,
+  opt: Parameters<AccountBase['address']>[0] & Parameters<typeof delegateSignatureCommon>[1] &
+  { queryId?: Encoded.OracleQueryId },
+): Promise<string> {
+  return delegateSignatureCommon(
+    [opt.queryId ?? await opt.onAccount.address(opt), contractId],
+    opt,
+  );
+}

package/src/deprecated/index.ts

@@ -0,0 +1,172 @@
+import BigNumber from 'bignumber.js';
+import { buildTx } from '../tx/builder';
+import { Tag } from '../tx/builder/constants';
+import { calculateMinFee as calculateMinFeeInternal } from '../tx/builder/field-types/fee';
+import { TxParamsCommon } from '../tx/builder/schema';
+import { AE_AMOUNT_FORMATS } from '../utils/amount-formatter';
+import { mapObject } from '../utils/other';
+import { Encoding } from '../utils/encoder';
+
+export * from './methods';
+
+/**
+ * @deprecated use NamePointer from apis/node instead
+ * @hidden
+ */
+export interface Pointer {
+  key: string;
+  id: string;
+}
+
+/**
+ * @deprecated use genSalt instead
+ * @hidden
+ */
+export function salt(): number {
+  return Math.floor(Math.random() * Math.floor(Number.MAX_SAFE_INTEGER));
+}
+
+/**
+ * @deprecated use genSalt instead
+ * @hidden
+ */
+export const createSalt = salt;
+
+/**
+ * Calculate min fee
+ * @category transaction builder
+ * @param txType - Transaction type
+ * @param options - Options object
+ * @param options.params - Tx params
+ * @deprecated use buildTx to generate transaction, unpack it and refer to `fee` field
+ * @hidden
+ * @example
+ * ```js
+ * calculateMinFee('spendTx', { gasLimit, params })
+ * ```
+ */
+export function calculateMinFee(
+  txType: Tag,
+  { params, vsn, denomination }: CalculateMinFeeOptions,
+): BigNumber {
+  return calculateMinFeeInternal(
+    txType,
+    (fee: BigNumber) => (
+      // @ts-expect-error anyway this planned to be removed
+      buildTx({ ...params, _computingMinFee: fee }, txType, { vsn, denomination })
+    ),
+  );
+}
+
+interface CalculateMinFeeOptions {
+  params: TxParamsCommon;
+  vsn?: number;
+  denomination?: AE_AMOUNT_FORMATS;
+}
+
+/**
+ * @deprecated Maximum gas limit depends on transaction size, this value is outdated,
+ * sdk check/provides gasLimit by itself while building a transaction
+ * @hidden
+ */
+export const GAS_MAX = 1600000 - 21000;
+
+/**
+ * @deprecated use `Tag`
+ * @hidden
+ */
+export enum TX_TYPE {
+  account = 10,
+  signed = 11,
+  spend = 12,
+  oracleRegister = 22,
+  oracleQuery = 23,
+  oracleResponse = 24,
+  oracleExtend = 25,
+  nameClaim = 32,
+  namePreClaim = 33,
+  nameUpdate = 34,
+  nameRevoke = 35,
+  nameTransfer = 36,
+  contract = 40,
+  contractCallResult = 41,
+  contractCreate = 42,
+  contractCall = 43,
+  channelCreate = 50,
+  channelDeposit = 51,
+  channelWithdraw = 52,
+  channelCloseMutual = 53,
+  channelCloseSolo = 54,
+  channelSlash = 55,
+  channelSettle = 56,
+  channelOffChain = 57,
+  channel = 58,
+  channelSnapshotSolo = 59,
+  proofOfInclusion = 60,
+  stateTrees = 62,
+  merklePatriciaTree = 63,
+  merklePatriciaTreeValue = 64,
+  sophiaByteCode = 70,
+  gaAttach = 80,
+  gaMeta = 81,
+  payingFor = 82,
+  channelForceProgress = 521,
+  channelOffChainUpdateTransfer = 570,
+  channelOffChainUpdateDeposit = 571,
+  channelOffChainUpdateWithdrawal = 572,
+  channelOffChainCreateContract = 573,
+  channelOffChainCallContract = 574,
+  channelReconnect = 575,
+  contractsTree = 621,
+  contractCallsTree = 622,
+  channelsTree = 623,
+  nameserviceTree = 624,
+  oraclesTree = 625,
+  accountsTree = 626,
+}
+
+/**
+ * @deprecated use `readId`, `writeId`
+ * @hidden
+ */
+export const ID_TAG = {
+  account: 1,
+  name: 2,
+  commitment: 3,
+  oracle: 4,
+  contract: 5,
+  channel: 6,
+} as const;
+
+/**
+ * @deprecated use `readId`, `writeId`
+ * @hidden
+ */
+export const PREFIX_ID_TAG = {
+  ak: ID_TAG.account,
+  nm: ID_TAG.name,
+  cm: ID_TAG.commitment,
+  ok: ID_TAG.oracle,
+  ct: ID_TAG.contract,
+  ch: ID_TAG.channel,
+} as const;
+
+/**
+ * @deprecated use `readId`, `writeId`
+ * @hidden
+ */
+export const ID_TAG_PREFIX = mapObject(
+  PREFIX_ID_TAG,
+  ([key, value]: [Encoding, number]) => [value, key],
+);
+
+/**
+ * @deprecated use `getDefaultPointerKey`
+ * @hidden
+ */
+export enum POINTER_KEY_BY_PREFIX {
+  ak = 'account_pubkey',
+  ok = 'oracle_pubkey',
+  ct = 'contract_pubkey',
+  ch = 'channel',
+}

package/src/deprecated/methods.ts

@@ -0,0 +1,25 @@
+import { Encoded } from '../utils/encoder';
+import { createMetaTx } from '../contract/ga';
+import Node from '../Node';
+
+/**
+ * @deprecated Use createMetaTx instead
+ * @hidden
+ */
+export async function signUsingGA(
+  tx: Encoded.Transaction,
+  { authData, authFun, ...options }: {
+    authData: Parameters<typeof createMetaTx>[1];
+    authFun: Parameters<typeof createMetaTx>[2];
+  } & Parameters<typeof createMetaTx>[3],
+): Promise<Encoded.Transaction> {
+  return createMetaTx(tx, authData, authFun, options);
+}
+
+/**
+ * @deprecated Use getHeight instead
+ * @hidden
+ */
+export async function height({ onNode }: { onNode: Node }): Promise<number> {
+  return (await onNode.getCurrentKeyBlockHeight()).height;
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+/*
+ * 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.
+ */
+
+export * from './chain';
+export * from './utils/crypto';
+export * from './utils/keystore';
+export * from './utils/bytes';
+export * from './tx';
+export * from './tx/builder';
+export * from './tx/builder/helpers';
+export * from './tx/builder/constants';
+export * from './tx/builder/schema';
+export * from './tx/builder/address';
+export * from './utils/amount-formatter';
+export * from './utils/hd-wallet';
+export {
+  sha256hash, encode, decode, Encoding,
+} from './utils/encoder';
+export * from './aens';
+export * from './contract/methods';
+export * from './oracle';
+export * from './spend';
+export * from './contract/ga';
+export * from './deprecated';
+
+export { default as AeSdkBase } from './AeSdkBase';
+export { default as AeSdk } from './AeSdk';
+export { default as AeSdkAepp } from './AeSdkAepp';
+export { default as AeSdkWallet } from './AeSdkWallet';
+export { default as Node } from './Node';
+export { default as verifyTransaction } from './tx/validator';
+export { default as AccountBase } from './account/Base';
+export { default as MemoryAccount } from './account/Memory';
+export { default as Compiler } from './contract/Compiler';
+export { default as Channel } from './channel';
+
+export { default as connectionProxy } from './aepp-wallet-communication/connection-proxy';
+export * from './aepp-wallet-communication/schema';
+export { default as walletDetector } from './aepp-wallet-communication/wallet-detector';
+export { default as BrowserRuntimeConnection } from './aepp-wallet-communication/connection/BrowserRuntime';
+export { default as BrowserWindowMessageConnection } from './aepp-wallet-communication/connection/BrowserWindowMessage';
+export * from './utils/errors';