@aeternity/aepp-sdk 10.0.0 → 12.0.0

package/src/tx/builder/constants.ts

@@ -0,0 +1,96 @@
+import { EncodingType } from './../../utils/encoder'
+import BigNumber from 'bignumber.js'
+import { mapObject } from '../../utils/other'
+
+// # AENS
+export type AensName = `${string}.chain`
+export const NAME_TTL = 180000
+// # max number of block into the future that the name is going to be available
+// # https://github.com/aeternity/protocol/blob/epoch-v0.22.0/AENS.md#update
+// # https://github.com/aeternity/protocol/blob/44a93d3aab957ca820183c3520b9daf6b0fedff4/AENS.md#aens-entry
+export const NAME_MAX_TTL = 36000
+export const NAME_MAX_CLIENT_TTL = 84600
+export const CLIENT_TTL = NAME_MAX_CLIENT_TTL
+export const MIN_GAS_PRICE = 1e9
+// # see https://github.com/aeternity/aeternity/blob/72e440b8731422e335f879a31ecbbee7ac23a1cf/apps/aecore/src/aec_governance.erl#L67
+export const NAME_FEE_MULTIPLIER = 1e14 // 100000000000000
+export const NAME_FEE_BID_INCREMENT = 0.05 // # the increment is in percentage
+// # see https://github.com/aeternity/aeternity/blob/72e440b8731422e335f879a31ecbbee7ac23a1cf/apps/aecore/src/aec_governance.erl#L272
+export const NAME_BID_TIMEOUT_BLOCKS = 480 // # ~1 day
+// # this is the max length for a domain that requires a base fee to be paid
+export const NAME_MAX_LENGTH_FEE = 31
+export const NAME_BID_MAX_LENGTH = 12 // # this is the max length for a domain to be part of a bid
+export enum POINTER_KEY_BY_PREFIX {
+  ak = 'account_pubkey',
+  ok = 'oracle_pubkey',
+  ct = 'contract_pubkey',
+  ch = 'channel'
+}
+// # https://github.com/aeternity/aeternity/blob/72e440b8731422e335f879a31ecbbee7ac23a1cf/apps/aecore/src/aec_governance.erl#L290
+// # https://github.com/aeternity/protocol/blob/master/AENS.md#protocol-fees-and-protection-times
+// # bid ranges:
+export const NAME_BID_RANGES = mapObject({
+  31: 3,
+  30: 5,
+  29: 8,
+  28: 13,
+  27: 21,
+  26: 34,
+  25: 55,
+  24: 89,
+  23: 144,
+  22: 233,
+  21: 377,
+  20: 610,
+  19: 987,
+  18: 1597,
+  17: 2584,
+  16: 4181,
+  15: 6765,
+  14: 10946,
+  13: 17711,
+  12: 28657,
+  11: 46368,
+  10: 75025,
+  9: 121393,
+  8: 196418,
+  7: 317811,
+  6: 514229,
+  5: 832040,
+  4: 1346269,
+  3: 2178309,
+  2: 3524578,
+  1: 5702887
+}, ([key, value]) => [key, new BigNumber(value).times(NAME_FEE_MULTIPLIER)])
+
+// # Tag constant for ids (type uint8)
+// # see https://github.com/aeternity/protocol/blob/master/serializations.md#the-id-type
+// # <<Tag:1/unsigned-integer-unit:8, Hash:32/binary-unit:8>>
+const ID_TAG_ACCOUNT = 1
+const ID_TAG_NAME = 2
+const ID_TAG_COMMITMENT = 3
+const ID_TAG_ORACLE = 4
+const ID_TAG_CONTRACT = 5
+const ID_TAG_CHANNEL = 6
+
+export const ID_TAG = {
+  account: ID_TAG_ACCOUNT,
+  name: ID_TAG_NAME,
+  commitment: ID_TAG_COMMITMENT,
+  oracle: ID_TAG_ORACLE,
+  contract: ID_TAG_CONTRACT,
+  channel: ID_TAG_CHANNEL
+}
+
+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
+
+export const ID_TAG_PREFIX = mapObject(
+  PREFIX_ID_TAG, ([key, value]: [EncodingType, number]) => [value, key]
+)

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

@@ -0,0 +1,111 @@
+import {
+  writeId, readId, produceNameId, getMinimumNameFee, readInt, writeInt, isNameValid
+} from './helpers'
+import { InsufficientNameFeeError, IllegalArgumentError } from '../../utils/errors'
+import BigNumber from 'bignumber.js'
+import { MIN_GAS_PRICE, AensName } from './constants'
+import { EncodedData } from '../../utils/encoder'
+
+type Int = number | string | BigNumber
+
+// todo: update me
+// ? This is a TS workaround because this has to be a class with only static methods
+export class Field {
+  public prototype: any
+
+  static serialize (value: any, _txFields: object = {}): Buffer {
+    return Buffer.from(value)
+  }
+
+  static deserialize (value: Buffer): any {
+    return value.toString()
+  }
+}
+
+export class Name extends Field {
+  /**
+   * @param value - AENS name
+   */
+  static serialize (value: AensName): Buffer {
+    return Buffer.from(value)
+  }
+
+  /**
+   * @param value - AENS name
+   */
+  static deserialize (value: Buffer): string {
+    return value.toString()
+  }
+}
+
+export class NameId extends Field {
+  /**
+   * @param value - AENS name ID
+   */
+  static serialize (value: AensName | EncodedData<'nm'>): Buffer {
+    return writeId(isNameValid(value) ? produceNameId(value) : value)
+  }
+
+  /**
+   * @param value - AENS name ID Buffer
+   */
+  static deserialize (value: Buffer): string {
+    return readId(value)
+  }
+}
+
+export class NameFee extends Field {
+  /**
+   * @param value - AENS name fee Buffer
+   * @param txFields - Transaction fields
+   * @param txFields.name - AENS Name in transaction
+   */
+  static serialize (value: Int | undefined, { name }: { name: AensName }): Buffer {
+    const minNameFee = getMinimumNameFee(name)
+    value ??= minNameFee
+    if (minNameFee.gt(value)) {
+      throw new InsufficientNameFeeError(new BigNumber(value), minNameFee)
+    }
+    return writeInt(value)
+  }
+
+  /**
+   * @param value - AENS name fee Buffer
+   * @returns AENS name fee
+   */
+  static deserialize (value: Buffer): string {
+    return readInt(value)
+  }
+}
+
+export class Deposit extends Field {
+  /**
+   * @param value - Deposit value in string format. Should be equal to  '0'.
+   * @returns Deposit value Buffer.
+   */
+  static serialize (value: string = '0'): Buffer {
+    if (parseInt(value) !== 0) throw new IllegalArgumentError(`Contract deposit is not refundable, so it should be equal 0, got ${value.toString()} instead`)
+    return writeInt(0)
+  }
+
+  /**
+   * @param value - Deposit value Buffer.
+   * @returns Deposit value.
+   */
+  static deserialize (value: Buffer): string {
+    return readInt(value)
+  }
+}
+
+export class GasPrice extends Field {
+  static serialize (value: Int = MIN_GAS_PRICE): Buffer {
+    if (+value < MIN_GAS_PRICE) {
+      throw new IllegalArgumentError(`Gas price ${value.toString()} must be bigger then ${MIN_GAS_PRICE}`)
+    }
+    return writeInt(value)
+  }
+
+  static deserialize (value: Buffer): string {
+    return readInt(value)
+  }
+}

package/src/tx/builder/helpers.ts

@@ -0,0 +1,253 @@
+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 {
+  ID_TAG_PREFIX,
+  PREFIX_ID_TAG,
+  NAME_BID_RANGES,
+  NAME_FEE_BID_INCREMENT,
+  NAME_BID_TIMEOUT_BLOCKS,
+  NAME_MAX_LENGTH_FEE,
+  POINTER_KEY_BY_PREFIX,
+  AensName
+} from './constants'
+import { ceil } from '../../utils/bignumber'
+import {
+  TagNotFoundError,
+  PrefixNotFoundError,
+  IllegalBidFeeError,
+  ArgumentError
+} from '../../utils/errors'
+
+/**
+ * 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
+ * @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')
+}
+
+/**
+ * Build a oracle query id
+ * @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'>,
+  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])
+  }
+
+  const b2bHash = hash(
+    Buffer.from([...decode(senderId), ..._int32(nonce), ...decode(oracleId)]))
+  return encode(b2bHash, 'oq')
+}
+
+/**
+ * Format the salt into a 64-byte hex string
+ * @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
+ *
+ * @param name - Name to encode
+ * @returns `nm_` prefixed encoded AENS name
+ */
+export function produceNameId (name: AensName): EncodedData<'nm'> {
+  return encode(hash(name.toLowerCase()), 'nm')
+}
+
+/**
+ * Generate the commitment hash by hashing the formatted salt and
+ * name, base 58 encoding the result and prepending 'cm_'
+ *
+ * @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)
+}
+
+/**
+ * Utility function to convert int to bytes
+ * @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
+ * @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
+ * @param pointers - Array of pointers
+ * `([ { key: 'account_pubkey', id: 'ak_32klj5j23k23j5423l434l2j3423'} ])`
+ * @returns Serialized pointers array
+ */
+export function buildPointers (pointers: Pointer[]): Buffer[][] {
+  return pointers.map(
+    p => [
+      toBytes(p.key),
+      writeId(p.id)
+    ]
+  )
+}
+
+/**
+ * Helper function to read pointers from name update TX
+ * @param pointers - Array of pointers
+ * @returns Deserialize pointer array
+ */
+export function readPointers (pointers: Array<[key: string, id: Buffer]>): Pointer[] {
+  return pointers.map(
+    ([key, id]) => Object.assign({
+      key: key.toString(),
+      id: readId(id)
+    })
+  )
+}
+
+const AENS_SUFFIX = '.chain'
+
+/**
+ * Is AENS name valid
+ * @param name - AENS name
+ */
+export function isNameValid (name: string): name is AensName {
+  // TODO: probably there are stronger requirements
+  return name.endsWith(AENS_SUFFIX)
+}
+
+/**
+ * @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]
+}
+
+/**
+ * Get the minimum AENS name fee
+ *
+ * @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
+ *
+ * @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
+ *
+ * @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
+ */
+export function isAuctionName (name: AensName): boolean {
+  return name.length < 13 + AENS_SUFFIX.length
+}