@aeternity/aepp-sdk 11.0.0 → 12.1.0

package/src/tx/builder/field-types/coin-amount.ts

@@ -0,0 +1,27 @@
+import uInt, { Int } from './u-int';
+import { AE_AMOUNT_FORMATS, formatAmount } from '../../../utils/amount-formatter';
+import { ArgumentError } from '../../../utils/errors';
+
+export interface Options { denomination?: AE_AMOUNT_FORMATS }
+
+export default {
+  ...uInt,
+
+  serializeAettos(value: string | undefined): string {
+    if (value == null) throw new ArgumentError('value', 'provided', value);
+    return value;
+  },
+
+  serializeOptional(value: Int | undefined, { denomination, ...options }: Options): Buffer {
+    return uInt.serialize(
+      this.serializeAettos(
+        value != null ? formatAmount(value, { denomination }) : value,
+        options,
+      ),
+    );
+  },
+
+  serialize(value: Int, options: Options): Buffer {
+    return this.serializeOptional(value, options);
+  },
+};

package/src/tx/builder/field-types/deposit.ts

@@ -0,0 +1,21 @@
+import coinAmount from './coin-amount';
+import { Int } from './u-int';
+import { IllegalArgumentError } from '../../../utils/errors';
+
+export default {
+  ...coinAmount,
+
+  /**
+   * @param value - Deposit value in string format. Should be equal to '0'.
+   * @param options - Options
+   * @returns Deposit value Buffer.
+   */
+  serialize(
+    value: Int | undefined,
+    options: Parameters<typeof coinAmount['serialize']>[1],
+  ): Buffer {
+    value ??= 0;
+    if (+value !== 0) throw new IllegalArgumentError(`Contract deposit is not refundable, so it should be equal 0, got ${value.toString()} instead`);
+    return coinAmount.serialize(value, options);
+  },
+};

package/src/tx/builder/field-types/fee.ts

@@ -0,0 +1,143 @@
+import BigNumber from 'bignumber.js';
+import { IllegalArgumentError } from '../../../utils/errors';
+import { MIN_GAS_PRICE, Tag } from '../constants';
+import coinAmount from './coin-amount';
+import { isKeyOfObject } from '../../../utils/other';
+
+const BASE_GAS = 15000;
+const GAS_PER_BYTE = 20;
+const KEY_BLOCK_INTERVAL = 3;
+
+/**
+ * Calculate the Base fee gas
+ * @see {@link https://github.com/aeternity/protocol/blob/master/consensus/README.md#gas}
+ * @param txType - The transaction type
+ * @returns The base fee
+ * @example
+ * ```js
+ * TX_FEE_BASE('channelForceProgress') => new BigNumber(30 * 15000)
+ * ```
+ */
+const TX_FEE_BASE_GAS = (txType: Tag): BigNumber => {
+  const feeFactors = {
+    [Tag.ChannelForceProgressTx]: 30,
+    [Tag.ChannelOffChainTx]: 0,
+    [Tag.ChannelOffChainUpdateCallContract]: 0,
+    [Tag.ChannelOffChainUpdateCreateContract]: 0,
+    [Tag.ChannelOffChainUpdateDeposit]: 0,
+    [Tag.ChannelOffChainUpdateWithdraw]: 0,
+    [Tag.ChannelOffChainUpdateTransfer]: 0,
+    [Tag.ContractCreateTx]: 5,
+    [Tag.ContractCallTx]: 12,
+    [Tag.GaAttachTx]: 5,
+    [Tag.GaMetaTx]: 5,
+    [Tag.PayingForTx]: 1 / 5,
+  } as const;
+  const factor = feeFactors[txType as keyof typeof feeFactors] ?? 1;
+  return new BigNumber(factor * BASE_GAS);
+};
+
+/**
+ * Calculate fee for Other types of transactions
+ * @see {@link https://github.com/aeternity/protocol/blob/master/consensus/README.md#gas}
+ * @param txType - The transaction type
+ * @param txSize - The transaction size
+ * @returns parameters - The transaction parameters
+ * @returns parameters.relativeTtl - The relative ttl
+ * @returns parameters.innerTxSize - The size of the inner transaction
+ * @returns The Other fee
+ * @example
+ * ```js
+ * TX_FEE_OTHER_GAS('oracleResponse',10, { relativeTtl: 10, innerTxSize: 10 })
+ *  => new BigNumber(10).times(20).plus(Math.ceil(32000 * 10 / Math.floor(60 * 24 * 365 / 2)))
+ * ```
+ */
+const TX_FEE_OTHER_GAS = (
+  txType: Tag,
+  txSize: number,
+  { relativeTtl, innerTxSize }: { relativeTtl: number; innerTxSize: number },
+): BigNumber => {
+  switch (txType) {
+    case Tag.OracleRegisterTx:
+    case Tag.OracleExtendTx:
+    case Tag.OracleQueryTx:
+    case Tag.OracleResponseTx:
+      return new BigNumber(txSize)
+        .times(GAS_PER_BYTE)
+        .plus(
+          Math.ceil((32000 * relativeTtl) / Math.floor((60 * 24 * 365) / KEY_BLOCK_INTERVAL)),
+        );
+    case Tag.GaMetaTx:
+    case Tag.PayingForTx:
+      return new BigNumber(txSize).minus(innerTxSize).times(GAS_PER_BYTE);
+    default:
+      return new BigNumber(txSize).times(GAS_PER_BYTE);
+  }
+};
+
+function getOracleRelativeTtl(params: any, txType: Tag): number {
+  const ttlKeys = {
+    [Tag.OracleRegisterTx]: 'oracleTtlValue',
+    [Tag.OracleExtendTx]: 'oracleTtlValue',
+    [Tag.OracleQueryTx]: 'queryTtlValue',
+    [Tag.OracleResponseTx]: 'responseTtlValue',
+  } as const;
+
+  if (!isKeyOfObject(txType, ttlKeys)) return 1;
+  return params[ttlKeys[txType]];
+}
+
+/**
+ * Calculate fee based on tx type and params
+ */
+export function buildFee(txType: Tag, buildTx: any): BigNumber {
+  const { rlpEncoded: { length }, txObject } = buildTx;
+
+  return TX_FEE_BASE_GAS(txType)
+    .plus(TX_FEE_OTHER_GAS(txType, length, {
+      relativeTtl: getOracleRelativeTtl(txObject, txType),
+      innerTxSize: [Tag.GaMetaTx, Tag.PayingForTx].includes(txType)
+        ? txObject.tx.tx.encodedTx.rlpEncoded.length
+        : 0,
+    }))
+    .times(MIN_GAS_PRICE);
+}
+
+/**
+ * Calculate min fee
+ * @category transaction builder
+ * @param txType - Transaction type
+ * @param rebuildTx - Callback to get built transaction with specific fee
+ */
+export function calculateMinFee(
+  txType: Tag,
+  rebuildTx: (value: BigNumber) => any,
+): BigNumber {
+  let fee = new BigNumber(0);
+  let previousFee;
+  do {
+    previousFee = fee;
+    fee = buildFee(txType, rebuildTx(fee));
+  } while (!fee.eq(previousFee));
+  return fee;
+}
+
+export default {
+  ...coinAmount,
+
+  serializeAettos(
+    _value: string | undefined,
+    { txType, rebuildTx, _computingMinFee }:
+    { txType: Tag; rebuildTx: (params: any) => any; _computingMinFee?: string },
+  ): string {
+    if (_computingMinFee != null) return _computingMinFee;
+    const minFee = calculateMinFee(txType, (fee) => rebuildTx({ _computingMinFee: fee }));
+    const value = new BigNumber(_value ?? minFee);
+    if (minFee.gt(value)) {
+      throw new IllegalArgumentError(`Fee ${value.toString()} must be bigger then ${minFee}`);
+    }
+    return value.toFixed();
+  },
+
+  serialize: coinAmount.serializeOptional,
+};

package/src/tx/builder/field-types/field.ts

@@ -0,0 +1,9 @@
+export default {
+  serialize(value: string): Buffer {
+    return Buffer.from(value);
+  },
+
+  deserialize(value: Buffer): string {
+    return value.toString();
+  },
+};

package/src/tx/builder/field-types/gas-limit.ts

@@ -0,0 +1,41 @@
+import { IllegalArgumentError } from '../../../utils/errors';
+import { MIN_GAS_PRICE, Tag } from '../constants';
+import shortUInt from './short-u-int';
+import { buildFee } from './fee';
+
+function calculateGasLimitMax(
+  txType: Tag,
+  gasMax: number,
+  rebuildTx: (value: number) => any,
+): number {
+  return gasMax - +buildFee(txType, rebuildTx(gasMax)).dividedBy(MIN_GAS_PRICE);
+}
+
+export default {
+  ...shortUInt,
+
+  serialize(
+    _value: number | undefined,
+    {
+      txType, rebuildTx, gasMax = 6e6, _computingGasLimit,
+    }: {
+      txType: Tag;
+      rebuildTx: (params: any) => any;
+      gasMax: number;
+      _computingGasLimit?: number;
+    },
+  ): Buffer {
+    if (_computingGasLimit != null) return shortUInt.serialize(_computingGasLimit);
+
+    const gasLimitMax = calculateGasLimitMax(
+      txType,
+      gasMax,
+      (gasLimit) => rebuildTx({ _computingGasLimit: gasLimit }),
+    );
+    const value = _value ?? gasLimitMax;
+    if (value > gasLimitMax) {
+      throw new IllegalArgumentError(`Gas limit ${value} must be less or equal to ${gasLimitMax}`);
+    }
+    return shortUInt.serialize(value);
+  },
+};

package/src/tx/builder/field-types/gas-price.ts

@@ -0,0 +1,16 @@
+import coinAmount from './coin-amount';
+import { IllegalArgumentError } from '../../../utils/errors';
+import { MIN_GAS_PRICE } from '../constants';
+
+export default {
+  ...coinAmount,
+
+  serializeAettos(value: string | undefined = MIN_GAS_PRICE.toString()): string {
+    if (+value < MIN_GAS_PRICE) {
+      throw new IllegalArgumentError(`Gas price ${value.toString()} must be bigger then ${MIN_GAS_PRICE}`);
+    }
+    return value;
+  },
+
+  serialize: coinAmount.serializeOptional,
+};

package/src/tx/builder/field-types/index.ts

@@ -0,0 +1,45 @@
+import _field from './field';
+import _uInt from './u-int';
+import _shortUInt from './short-u-int';
+import _coinAmount from './coin-amount';
+
+import _deposit from './deposit';
+import _fee from './fee';
+import _gasLimit from './gas-limit';
+import _gasPrice from './gas-price';
+import _name from './name';
+import _nameFee from './name-fee';
+import _nameId from './name-id';
+
+// TODO: remove after fixing https://github.com/Gerrit0/typedoc-plugin-missing-exports/issues/15
+const field = _field;
+const uInt = _uInt;
+const shortUInt = _shortUInt;
+const coinAmount = _coinAmount;
+
+const deposit = _deposit;
+const fee = _fee;
+const gasLimit = _gasLimit;
+const gasPrice = _gasPrice;
+const name = _name;
+const nameFee = _nameFee;
+const nameId = _nameId;
+
+export type Field = typeof field | typeof uInt | typeof shortUInt | typeof coinAmount
+  | typeof deposit | typeof fee | typeof gasLimit | typeof gasPrice | typeof name | typeof nameFee
+  | typeof nameId;
+
+export {
+  field,
+  uInt,
+  shortUInt,
+  coinAmount,
+
+  deposit,
+  fee,
+  gasLimit,
+  gasPrice,
+  name,
+  nameFee,
+  nameId,
+};

package/src/tx/builder/field-types/name-fee.ts

@@ -0,0 +1,32 @@
+import BigNumber from 'bignumber.js';
+import { getMinimumNameFee } from '../helpers';
+import { InsufficientNameFeeError } from '../../../utils/errors';
+import { Int } from './u-int';
+import coinAmount from './coin-amount';
+import { AensName } from '../constants';
+
+export default {
+  ...coinAmount,
+
+  serializeAettos(
+    _value: string | undefined,
+    txFields: { name: AensName },
+  ): string {
+    const minNameFee = getMinimumNameFee(txFields.name);
+    const value = new BigNumber(_value ?? minNameFee);
+    if (minNameFee.gt(value)) throw new InsufficientNameFeeError(value, minNameFee);
+    return value.toFixed();
+  },
+
+  /**
+   * @param value - AENS name fee Buffer
+   * @param txFields - Transaction fields
+   * @param txFields.name - AENS Name in transaction
+   */
+  serialize(
+    value: Int | undefined,
+    txFields: { name: AensName } & Parameters<typeof coinAmount['serialize']>[1],
+  ): Buffer {
+    return coinAmount.serializeOptional.call(this, value, txFields);
+  },
+};

package/src/tx/builder/field-types/name-id.ts

@@ -0,0 +1,20 @@
+import { AensName } from '../constants';
+import { produceNameId, isNameValid } from '../helpers';
+import { writeId, readId } from '../address';
+import { Encoded } from '../../../utils/encoder';
+
+export default {
+  /**
+   * @param value - AENS name ID
+   */
+  serialize(value: AensName | Encoded.Name): Buffer {
+    return writeId(isNameValid(value) ? produceNameId(value) : value);
+  },
+
+  /**
+   * @param value - AENS name ID Buffer
+   */
+  deserialize(value: Buffer): Encoded.Name {
+    return readId(value) as Encoded.Name;
+  },
+};

package/src/tx/builder/field-types/name.ts

@@ -0,0 +1,18 @@
+import field from './field';
+import { AensName } from '../constants';
+
+export default {
+  /**
+   * @param value - AENS name
+   */
+  serialize(value: AensName): Buffer {
+    return field.serialize(value);
+  },
+
+  /**
+   * @param value - AENS name
+   */
+  deserialize(value: Buffer): AensName {
+    return field.deserialize(value) as AensName;
+  },
+};

package/src/tx/builder/field-types/short-u-int.ts

@@ -0,0 +1,11 @@
+import uInt from './u-int';
+
+export default {
+  serialize(value: number): Buffer {
+    return uInt.serialize(value);
+  },
+
+  deserialize(value: Buffer): number {
+    return +uInt.deserialize(value);
+  },
+};

package/src/tx/builder/field-types/u-int.ts

@@ -0,0 +1,16 @@
+import BigNumber from 'bignumber.js';
+import { readInt, writeInt } from '../helpers';
+import { ArgumentError } from '../../../utils/errors';
+
+export type Int = number | string | BigNumber;
+
+export default {
+  serialize(value: Int): Buffer {
+    if (value < 0) throw new ArgumentError('value', 'greater or equal to 0', value);
+    return writeInt(value);
+  },
+
+  deserialize(value: Buffer): string {
+    return readInt(value);
+  },
+};

package/src/tx/builder/helpers.ts

@@ -0,0 +1,248 @@
+import BigNumber from 'bignumber.js';
+import { genSalt, hash } from '../../utils/crypto';
+import {
+  decode, encode, Encoded, Encoding,
+} from '../../utils/encoder';
+import { toBytes } from '../../utils/bytes';
+import { concatBuffers } from '../../utils/other';
+import {
+  AensName,
+  NAME_BID_RANGES,
+  NAME_BID_TIMEOUT_BLOCKS,
+  NAME_FEE_BID_INCREMENT,
+  NAME_MAX_LENGTH_FEE,
+} from './constants';
+import { ceil } from '../../utils/bignumber';
+import { ArgumentError, IllegalBidFeeError } from '../../utils/errors';
+import { NamePointer } from '../../apis/node';
+import { readId, writeId } from './address';
+
+/**
+ * JavaScript-based Transaction builder helper function's
+ */
+
+/**
+ * Build a contract public key
+ * @category contract
+ * @param ownerId - The public key of the owner account
+ * @param nonce - the nonce of the transaction
+ * @returns Contract public key
+ */
+export function buildContractId(
+  ownerId: Encoded.AccountAddress,
+  nonce: number | BigNumber,
+): Encoded.ContractAddress {
+  const ownerIdAndNonce = Buffer.from([...decode(ownerId), ...toBytes(nonce)]);
+  const b2bHash = hash(ownerIdAndNonce);
+  return encode(b2bHash, Encoding.ContractAddress);
+}
+
+/**
+ * Build a oracle query id
+ * @category oracle
+ * @param senderId - The public key of the sender account
+ * @param nonce - the nonce of the transaction
+ * @param oracleId - The oracle public key
+ * @returns Contract public key
+ */
+export function oracleQueryId(
+  senderId: Encoded.AccountAddress,
+  nonce: number | BigNumber | string,
+  oracleId: Encoded.OracleAddress,
+): Encoded.OracleQueryId {
+  function _int32(val: number | string | BigNumber): Buffer {
+    const nonceBE = toBytes(val, true);
+    return concatBuffers([Buffer.alloc(32 - nonceBE.length), nonceBE]);
+  }
+
+  const b2bHash = hash(
+    Buffer.from([...decode(senderId), ..._int32(nonce), ...decode(oracleId)]),
+  );
+  return encode(b2bHash, Encoding.OracleQueryId);
+}
+
+/**
+ * Format the salt into a 64-byte hex string
+ * @category transaction builder
+ * @param salt - Random number
+ * @returns Zero-padded hex string of salt
+ */
+export function formatSalt(salt: number): Buffer {
+  return Buffer.from(salt.toString(16).padStart(64, '0'), 'hex');
+}
+
+/**
+ * Encode an AENS name
+ * @category AENS
+ * @param name - Name to encode
+ * @returns `nm_` prefixed encoded AENS name
+ */
+export function produceNameId(name: AensName): Encoded.Name {
+  return encode(hash(name.toLowerCase()), Encoding.Name);
+}
+
+/**
+ * Generate the commitment hash by hashing the formatted salt and
+ * name, base 58 encoding the result and prepending 'cm_'
+ * @category transaction builder
+ * @param name - Name to be registered
+ * @param salt - Random salt
+ * @returns Commitment hash
+ */
+export function commitmentHash(
+  name: AensName,
+  salt: number = genSalt(),
+): Encoded.Commitment {
+  return encode(
+    hash(concatBuffers([Buffer.from(name.toLowerCase()), formatSalt(salt)])),
+    Encoding.Commitment,
+  );
+}
+
+/**
+ * Utility function to convert int to bytes
+ * @category transaction builder
+ * @param val - Value
+ * @returns Buffer Buffer from number(BigEndian)
+ */
+export function writeInt(val: number | string | BigNumber): Buffer {
+  return toBytes(val, true);
+}
+
+/**
+ * Utility function to convert bytes to int
+ * @category transaction builder
+ * @param buf - Value
+ * @returns Buffer Buffer from number(BigEndian)
+ */
+export function readInt(buf: Buffer = Buffer.from([])): string {
+  return new BigNumber(Buffer.from(buf).toString('hex'), 16).toString(10);
+}
+
+/**
+ * Helper function to build pointers for name update TX
+ * @category transaction builder
+ * @param pointers - Array of pointers
+ * `([ { key: 'account_pubkey', id: 'ak_32klj5j23k23j5423l434l2j3423'} ])`
+ * @returns Serialized pointers array
+ */
+export function buildPointers(pointers: NamePointer[]): Buffer[][] {
+  return pointers.map(
+    (p) => [
+      toBytes(p.key),
+      writeId(p.id as Parameters<typeof writeId>[0]),
+    ],
+  );
+}
+
+/**
+ * Helper function to read pointers from name update TX
+ * @category transaction builder
+ * @param pointers - Array of pointers
+ * @returns Deserialize pointer array
+ */
+export function readPointers(pointers: Array<[key: string, id: Buffer]>): NamePointer[] {
+  return pointers.map(
+    ([key, id]) => ({
+      key: key.toString(),
+      id: readId(id),
+    }),
+  );
+}
+
+const AENS_SUFFIX = '.chain';
+
+/**
+ * Is AENS name valid
+ * @category AENS
+ * @param name - AENS name
+ */
+export function isNameValid(name: string): name is AensName {
+  // TODO: probably there are stronger requirements
+  return name.endsWith(AENS_SUFFIX);
+}
+
+const encodingToPointerKey = [
+  [Encoding.AccountAddress, 'account_pubkey'],
+  [Encoding.OracleAddress, 'oracle_pubkey'],
+  [Encoding.ContractAddress, 'contract_pubkey'],
+  [Encoding.Channel, 'channel'],
+] as const;
+
+/**
+ * @category AENS
+ * @param identifier - account/oracle/contract address, or channel
+ * @returns default AENS pointer key
+ */
+export function getDefaultPointerKey(
+  identifier: Encoded.Generic<typeof encodingToPointerKey[number][0]>,
+): typeof encodingToPointerKey[number][1] {
+  decode(identifier);
+  const encoding = identifier.substring(0, 2);
+  const result = encodingToPointerKey.find(([e]) => e === encoding)?.[1];
+  if (result != null) return result;
+  throw new ArgumentError(
+    'identifier',
+    `prefixed with one of ${encodingToPointerKey.map(([e]) => `${e}_`).join(', ')}`,
+    identifier,
+  );
+}
+
+/**
+ * Get the minimum AENS name fee
+ * @category AENS
+ * @param name - the AENS name to get the fee for
+ * @returns the minimum fee for the AENS name auction
+ */
+export function getMinimumNameFee(name: AensName): BigNumber {
+  const nameLength = name.length - AENS_SUFFIX.length;
+  return NAME_BID_RANGES[Math.min(nameLength, NAME_MAX_LENGTH_FEE)];
+}
+
+/**
+ * Compute bid fee for AENS auction
+ * @category AENS
+ * @param name - the AENS name to get the fee for
+ * @param options - Options
+ * @param options.startFee - Auction start fee
+ * @param options.increment - Bid multiplier(In percentage, must be between 0 and 1)
+ * @returns Bid fee
+ */
+export function computeBidFee(
+  name: AensName,
+  { startFee, increment = NAME_FEE_BID_INCREMENT }:
+  { startFee?: number | string | BigNumber; increment?: number } = {},
+): BigNumber {
+  if (!(Number(increment) === increment && increment % 1 !== 0)) throw new IllegalBidFeeError(`Increment must be float. Current increment ${increment}`);
+  if (increment < NAME_FEE_BID_INCREMENT) throw new IllegalBidFeeError(`minimum increment percentage is ${NAME_FEE_BID_INCREMENT}`);
+  // FIXME: increment should be used somehow here
+  return ceil(
+    new BigNumber(startFee ?? getMinimumNameFee(name))
+      .times(new BigNumber(NAME_FEE_BID_INCREMENT).plus(1)),
+  );
+}
+
+/**
+ * Compute auction end height
+ * @category AENS
+ * @param name - Name to compute auction end for
+ * @param claimHeight - Auction starting height
+ * @see {@link https://github.com/aeternity/aeternity/blob/72e440b8731422e335f879a31ecbbee7ac23a1cf/apps/aecore/src/aec_governance.erl#L273}
+ * @returns Auction end height
+ */
+export function computeAuctionEndBlock(name: AensName, claimHeight: number): number {
+  const length = name.length - AENS_SUFFIX.length;
+  const h = (length <= 4 && 62 * NAME_BID_TIMEOUT_BLOCKS)
+    || (length <= 8 && 31 * NAME_BID_TIMEOUT_BLOCKS)
+    || (length <= 12 && NAME_BID_TIMEOUT_BLOCKS)
+    || 0;
+  return h + claimHeight;
+}
+
+/**
+ * Is name accept going to auction
+ * @category AENS
+ */
+export function isAuctionName(name: AensName): boolean {
+  return name.length < 13 + AENS_SUFFIX.length;
+}