@aeternity/aepp-sdk 12.0.0 → 12.1.0

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

@@ -1,253 +1,248 @@
-import BigNumber from 'bignumber.js'
-import { hash, salt } from '../../utils/crypto'
-import { encode, decode, EncodedData, EncodingType } from '../../utils/encoder'
-import { toBytes } from '../../utils/bytes'
-import { concatBuffers } from '../../utils/other'
+import BigNumber from 'bignumber.js';
+import { genSalt, hash } from '../../utils/crypto';
 import {
-  ID_TAG_PREFIX,
-  PREFIX_ID_TAG,
+  decode, encode, Encoded, Encoding,
+} from '../../utils/encoder';
+import { toBytes } from '../../utils/bytes';
+import { concatBuffers } from '../../utils/other';
+import {
+  AensName,
   NAME_BID_RANGES,
-  NAME_FEE_BID_INCREMENT,
   NAME_BID_TIMEOUT_BLOCKS,
+  NAME_FEE_BID_INCREMENT,
   NAME_MAX_LENGTH_FEE,
-  POINTER_KEY_BY_PREFIX,
-  AensName
-} from './constants'
-import { ceil } from '../../utils/bignumber'
-import {
-  TagNotFoundError,
-  PrefixNotFoundError,
-  IllegalBidFeeError,
-  ArgumentError
-} from '../../utils/errors'
+} 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
  */
 
-export const createSalt = salt
-
-export { encode, decode }
-
-export interface Pointer {
-  key: string
-  id: string
-}
-
 /**
  * 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: EncodedData<'ak'>, nonce: number | BigNumber): EncodedData<'ct'> {
-  const ownerIdAndNonce = Buffer.from([...decode(ownerId), ...toBytes(nonce)])
-  const b2bHash = hash(ownerIdAndNonce)
-  return encode(b2bHash, 'ct')
+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: EncodedData<'ak'>,
+export function oracleQueryId(
+  senderId: Encoded.AccountAddress,
   nonce: number | BigNumber | string,
-  oracleId: EncodedData<'ok'>
-): EncodedData<'oq'> {
-  function _int32 (val: number | string | BigNumber): Buffer {
-    const nonceBE = toBytes(val, true)
-    return concatBuffers([Buffer.alloc(32 - nonceBE.length), nonceBE])
+  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, 'oq')
+    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')
+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): EncodedData<'nm'> {
-  return encode(hash(name.toLowerCase()), 'nm')
+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 = createSalt()): EncodedData<'cm'> {
-  return encode(hash(concatBuffers([Buffer.from(name.toLowerCase()), formatSalt(salt)])), 'cm')
-}
-
-/**
- * Utility function to create and _id type
- * @param hashId - Encoded hash
- * @returns Buffer Buffer with ID tag and decoded HASh
- */
-export function writeId (hashId: string): Buffer {
-  if (typeof hashId !== 'string') throw new ArgumentError('hashId', 'a string', hashId)
-  const prefix = hashId.slice(0, 2) as keyof typeof PREFIX_ID_TAG
-  const idTag = PREFIX_ID_TAG[prefix]
-  if (idTag == null) throw new TagNotFoundError(prefix)
-  return Buffer.from([...toBytes(idTag), ...decode(hashId as EncodedData<EncodingType>)])
-}
-
-/**
- * Utility function to read and _id type
- * @param buf - Data
- * @returns Encoided hash string with prefix
- */
-export function readId (buf: Buffer): string {
-  const tag = Buffer.from(buf).readUIntBE(0, 1)
-  const prefix = ID_TAG_PREFIX[tag]
-  if (prefix == null) throw new PrefixNotFoundError(tag)
-  return encode(buf.slice(1, buf.length), prefix)
+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)
+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)
+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: Pointer[]): Buffer[][] {
+export function buildPointers(pointers: NamePointer[]): Buffer[][] {
   return pointers.map(
-    p => [
+    (p) => [
       toBytes(p.key),
-      writeId(p.id)
-    ]
-  )
+      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]>): Pointer[] {
+export function readPointers(pointers: Array<[key: string, id: Buffer]>): NamePointer[] {
   return pointers.map(
-    ([key, id]) => Object.assign({
+    ([key, id]) => ({
       key: key.toString(),
-      id: readId(id)
-    })
-  )
+      id: readId(id),
+    }),
+  );
 }
 
-const AENS_SUFFIX = '.chain'
+const AENS_SUFFIX = '.chain';
 
 /**
  * Is AENS name valid
+ * @category AENS
  * @param name - AENS name
  */
-export function isNameValid (name: string): name is AensName {
+export function isNameValid(name: string): name is AensName {
   // TODO: probably there are stronger requirements
-  return name.endsWith(AENS_SUFFIX)
+  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: EncodedData<keyof typeof POINTER_KEY_BY_PREFIX>
-): POINTER_KEY_BY_PREFIX {
-  decode(identifier)
-  const prefix = identifier.substring(0, 2) as keyof typeof POINTER_KEY_BY_PREFIX
-  return POINTER_KEY_BY_PREFIX[prefix]
+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)]
+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 (
+export function computeBidFee(
   name: AensName,
   { startFee, increment = NAME_FEE_BID_INCREMENT }:
-  { startFee?: number | string | BigNumber, increment?: number } = {}
+  { 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}`)
+  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))
-  )
+      .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
+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
+export function isAuctionName(name: AensName): boolean {
+  return name.length < 13 + AENS_SUFFIX.length;
 }