Merge pull request #1553 from aeternity/feature/docs

Docs improvements

Author: davidyuk

.eslintrc.js

@@ -46,7 +46,7 @@ module.exports = {
   plugins: [
     '@typescript-eslint'
   ],
-  ignorePatterns: ['dist', 'es', 'src/apis'],
+  ignorePatterns: ['dist', 'es', 'src/apis', 'docs/api'],
   rules: {
     'max-len': ['error', 100, 2, {
       ignoreUrls: true,

src/chain.ts

@@ -22,7 +22,7 @@
  * @example import { Chain } from '@aeternity/aepp-sdk'
  */
 
-import { AE_AMOUNT_FORMATS, AeAmountFormats, formatAmount } from './utils/amount-formatter'
+import { AE_AMOUNT_FORMATS, formatAmount } from './utils/amount-formatter'
 import verifyTransaction from './tx/validator'
 import { pause } from './utils/other'
 import { isNameValid, produceNameId, decode } from './tx/builder/helpers'
@@ -181,7 +181,7 @@ export async function getAccount (
 export async function getBalance (
   address: EncodedData<'ak'>,
   { format = AE_AMOUNT_FORMATS.AETTOS, ...options }:
-  { format: AeAmountFormats } & Parameters<typeof getAccount>[1]
+  { format: AE_AMOUNT_FORMATS } & Parameters<typeof getAccount>[1]
 ): Promise<string> {
   const { balance } = await getAccount(address, options).catch(() => ({ balance: 0n }))
 

src/contract/ga.ts

@@ -138,7 +138,7 @@ export async function createMetaTx (
 
   const opt = { ...onAccount.Ae.defaults, ...options }
   const { abiVersion } = await onAccount.getVmVersion(TX_TYPE.contractCall)
-  const wrappedTx = wrapInEmptySignedTx(unpackTx(rawTransaction, { txType: TX_TYPE.signed }))
+  const wrappedTx = wrapInEmptySignedTx(unpackTx<TX_TYPE.signed>(rawTransaction))
   const params = {
     ...opt,
     tx: {

src/tx/builder/constants.ts

@@ -19,12 +19,12 @@ 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 const POINTER_KEY_BY_PREFIX = {
-  ak: 'account_pubkey',
-  ok: 'oracle_pubkey',
-  ct: 'contract_pubkey',
-  ch: 'channel'
-} as const
+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:
@@ -62,15 +62,6 @@ export const NAME_BID_RANGES = mapObject({
   1: 5702887
 }, ([key, value]) => [key, new BigNumber(value).times(NAME_FEE_MULTIPLIER)])
 
-// # ref: https://github.com/aeternity/aeternity/blob/72e440b8731422e335f879a31ecbbee7ac23a1cf/apps/aecore/src/aec_governance.erl#L273
-// # name bid timeouts
-export const NAME_BID_TIMEOUTS = {
-  13: new BigNumber(0),
-  12: new BigNumber(NAME_BID_TIMEOUT_BLOCKS), // # 480 blocks
-  8: new BigNumber(31).times(NAME_BID_TIMEOUT_BLOCKS), // # 14880 blocks
-  4: new BigNumber(62).times(NAME_BID_TIMEOUT_BLOCKS) // # 29760 blocks
-}
-
 // # 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>>

src/tx/builder/helpers.ts

@@ -8,7 +8,7 @@ import {
   PREFIX_ID_TAG,
   NAME_BID_RANGES,
   NAME_FEE_BID_INCREMENT,
-  NAME_BID_TIMEOUTS,
+  NAME_BID_TIMEOUT_BLOCKS,
   NAME_MAX_LENGTH_FEE,
   POINTER_KEY_BY_PREFIX
 } from './constants'
@@ -203,8 +203,8 @@ export function isNameValid (name: string): boolean {
  */
 export function getDefaultPointerKey (
   identifier: EncodedData<keyof typeof POINTER_KEY_BY_PREFIX>
-): typeof POINTER_KEY_BY_PREFIX[keyof typeof POINTER_KEY_BY_PREFIX] {
-  decode(identifier as any)
+): 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]
 }
@@ -249,15 +249,16 @@ export function computeBidFee (
  * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
  * @param name
  * @param claimHeight Auction starting height
+ * @link https://github.com/aeternity/aeternity/blob/72e440b8731422e335f879a31ecbbee7ac23a1cf/apps/aecore/src/aec_governance.erl#L273
  * @return Auction end height
  */
-export function computeAuctionEndBlock (name: AensName, claimHeight: number | string): string {
+export function computeAuctionEndBlock (name: AensName, claimHeight: number): number {
   const length = name.length - AENS_SUFFIX.length
-  const h = (length <= 4 && NAME_BID_TIMEOUTS[4]) ||
-    (length <= 8 && NAME_BID_TIMEOUTS[8]) ||
-    (length <= 12 && NAME_BID_TIMEOUTS[12]) ||
-    NAME_BID_TIMEOUTS[13]
-  return h.plus(claimHeight).toString(10)
+  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
 }
 
 /**

src/tx/builder/index.ts

@@ -1,4 +1,3 @@
-import { AeAmountFormats } from './../../utils/amount-formatter'
 import { EncodedData, EncodingType } from './../../utils/encoder'
 import BigNumber from 'bignumber.js'
 import { decode as rlpDecode, encode as rlpEncode, NestedUint8Array } from 'rlp'
@@ -10,16 +9,13 @@ import {
   DEFAULT_FEE,
   FIELD_TYPES,
   MIN_GAS_PRICE,
-  OBJECT_ID_TX_TYPE,
   RawTxObject,
   TxField,
   TxTypeSchemas,
   TxParamsCommon,
-  TxType,
-  TX_DESERIALIZATION_SCHEMA,
   TX_FEE_BASE_GAS,
   TX_FEE_OTHER_GAS,
-  TX_SERIALIZATION_SCHEMA,
+  TX_SCHEMA,
   TX_TYPE,
   TxSchema
 } from './schema'
@@ -37,7 +33,7 @@ import {
 } from './helpers'
 import { toBytes } from '../../utils/bytes'
 import MPTree, { MPTreeBinary } from '../../utils/mptree'
-import { ArgumentError, InvalidTxParamsError, SchemaNotFoundError, UnexpectedTsError } from '../../utils/errors'
+import { ArgumentError, InvalidTxParamsError, SchemaNotFoundError, DecodeError } from '../../utils/errors'
 import { isKeyOfObject } from '../../utils/other'
 
 /**
@@ -223,7 +219,7 @@ function validateField (
 function transformParams (
   params: TxParamsCommon,
   schema: TxField[],
-  { denomination }: {denomination?: AeAmountFormats} = {}
+  { denomination }: {denomination?: AE_AMOUNT_FORMATS} = {}
 ): any {
   params = schema
     .filter(([, t]) => t === FIELD_TYPES.amount)
@@ -255,7 +251,7 @@ function transformParams (
     )
 }
 
-function getOracleRelativeTtl (params: any, txType: TxType): number {
+function getOracleRelativeTtl (params: any, txType: TX_TYPE): number {
   const ttlKeys = {
     [TX_TYPE.oracleRegister]: 'oracleTtl',
     [TX_TYPE.oracleExtend]: 'oracleTtl',
@@ -281,7 +277,7 @@ function getOracleRelativeTtl (params: any, txType: TxType): number {
  * @example calculateMinFee('spendTx', { gasLimit, params })
  */
 export function calculateMinFee (
-  txType: TxType,
+  txType: TX_TYPE,
   { params, vsn }: { params?: Object, vsn?: number }
 ): string {
   const multiplier = new BigNumber(1e9) // 10^9 GAS_PRICE
@@ -309,7 +305,7 @@ export function calculateMinFee (
  * @param options.vsn
  */
 function buildFee (
-  txType: TxType,
+  txType: TX_TYPE,
   { params, multiplier, vsn }: { params: TxParamsCommon, multiplier: BigNumber, vsn?: number }
 ): BigNumber {
   const { rlpEncoded: txWithOutFee } = buildTx({ ...params }, txType, { vsn })
@@ -339,7 +335,7 @@ function buildFee (
  */
 export function calculateFee (
   fee: number | BigNumber | string = 0,
-  txType: TxType,
+  txType: TX_TYPE,
   { params, showWarning = true, vsn }: {
     gasLimit?: number | string | BigNumber
     params?: TxSchema
@@ -376,7 +372,7 @@ export function validateParams (
 
 interface TxOptionsRaw {
   excludeKeys?: string[]
-  denomination?: AeAmountFormats
+  denomination?: AE_AMOUNT_FORMATS
 }
 /**
  * Build binary transaction
@@ -442,7 +438,7 @@ export interface BuiltTx<Tx extends TxSchema, Prefix extends EncodingType> {
 }
 
 export type TxParamsBuild = TxParamsCommon & {
-  denomination?: AeAmountFormats
+  denomination?: AE_AMOUNT_FORMATS
 }
 /**
  * Build transaction hash
@@ -461,29 +457,25 @@ export type TxParamsBuild = TxParamsCommon & {
  */
 export function buildTx<Prefix> (
   params: TxParamsBuild,
-  type: TxType,
+  type: TX_TYPE,
   { excludeKeys = [], prefix = 'tx', vsn, denomination = AE_AMOUNT_FORMATS.AETTOS }: {
     excludeKeys?: string[]
     prefix?: EncodingType
     vsn?: number
-    denomination?: AeAmountFormats
+    denomination?: AE_AMOUNT_FORMATS
   } = {}
 ): Prefix extends EncodingType
     ? BuiltTx<TxSchema, Prefix>
     : BuiltTx<TxSchema, 'tx'> {
-  const schemas = TX_SERIALIZATION_SCHEMA[type]
-  if (schemas == null) throw new UnexpectedTsError()
+  const schemas = TX_SCHEMA[type]
 
   vsn ??= Math.max(...Object.keys(schemas).map(a => +a))
-  if (!isKeyOfObject(vsn, schemas)) throw new SchemaNotFoundError('serialization', type.toString(), vsn)
+  if (!isKeyOfObject(vsn, schemas)) throw new SchemaNotFoundError('serialization', TX_TYPE[type], vsn)
 
   const schema = schemas[vsn]
 
-  const tags = Object.entries(OBJECT_ID_TX_TYPE).find(([, t]) => t === type)
-  if (tags == null) { throw new UnexpectedTsError() }
-  const tag = tags[0]
   const binary = buildRawTx(
-    { ...params, VSN: vsn, tag },
+    { ...params, VSN: vsn, tag: type },
     schema,
     { excludeKeys, denomination: params.denomination ?? denomination }
   ).filter(e => e !== undefined)
@@ -494,12 +486,12 @@ export function buildTx<Prefix> (
     tx,
     rlpEncoded,
     binary,
-    txObject: unpackRawTx<TxTypeSchemas[TxType]>(binary, schema)
+    txObject: unpackRawTx<TxTypeSchemas[TX_TYPE]>(binary, schema)
   } as any
 }
 
 export interface TxUnpacked<Tx extends TxSchema> {
-  txType: TxType
+  txType: TX_TYPE
   tx: RawTxObject<Tx>
   rlpEncoded: Uint8Array
   binary: Uint8Array | NestedUint8Array
@@ -516,7 +508,7 @@ export interface TxUnpacked<Tx extends TxSchema> {
  * @returns object.rlpEncoded rlp encoded transaction
  * @returns object.binary binary transaction
  */
-export function unpackTx<TxType extends keyof TxTypeSchemas> (
+export function unpackTx<TxType extends TX_TYPE> (
   encodedTx: EncodedData<'tx'> | Uint8Array,
   { txType, fromRlpBinary = false }:
   { txType?: TxType, fromRlpBinary?: boolean } = {
@@ -525,16 +517,15 @@ export function unpackTx<TxType extends keyof TxTypeSchemas> (
 ): TxUnpacked<TxTypeSchemas[TxType]> {
   const rlpEncoded = fromRlpBinary ? encodedTx as Uint8Array : decode(encodedTx as EncodedData<'tx'>)
   const binary = rlpDecode(rlpEncoded)
-  const objId = readInt(binary[0] as Buffer) as unknown as keyof typeof TX_DESERIALIZATION_SCHEMA
-  txType ??= OBJECT_ID_TX_TYPE[objId] as TxType
-  const vsn = readInt(binary[1] as Buffer) as keyof typeof TX_DESERIALIZATION_SCHEMA[typeof objId]
-  const schema = TX_DESERIALIZATION_SCHEMA[objId][vsn]
-  if (schema == null) {
-    throw new SchemaNotFoundError('deserialization', `tag ${objId}`, vsn)
-  }
+  const objId = +readInt(binary[0] as Buffer)
+  if (!isKeyOfObject(objId, TX_SCHEMA)) throw new DecodeError(`Unknown transaction tag: ${objId}`)
+  if (txType != null && txType !== objId) throw new DecodeError(`Expected transaction to have ${TX_TYPE[txType]} tag, got ${TX_TYPE[objId]} instead`)
+  const vsn = +readInt(binary[1] as Buffer)
+  if (!isKeyOfObject(vsn, TX_SCHEMA[objId])) throw new SchemaNotFoundError('deserialization', `tag ${objId}`, vsn)
+  const schema = TX_SCHEMA[objId][vsn]
   return {
-    txType,
-    tx: unpackRawTx<TxTypeSchemas[typeof txType]>(binary, schema),
+    txType: objId,
+    tx: unpackRawTx<TxTypeSchemas[TxType]>(binary, schema),
     rlpEncoded,
     binary
   }
@@ -560,8 +551,8 @@ export function buildTxHash (rawTx: EncodedData<'tx'> | Uint8Array): string {
  * @return Contract public key
  */
 export function buildContractIdByContractTx (contractTx: EncodedData<'tx'>): EncodedData<'ct'> {
-  const { txType, tx } = unpackTx(contractTx, { txType: TX_TYPE.contractCreate })
-  if (![TX_TYPE.contractCreate, TX_TYPE.gaAttach].includes(txType as any)) {
+  const { txType, tx } = unpackTx<TX_TYPE.contractCreate | TX_TYPE.gaAttach>(contractTx)
+  if (![TX_TYPE.contractCreate, TX_TYPE.gaAttach].includes(txType)) {
     throw new ArgumentError('contractCreateTx', 'a contractCreateTx or gaAttach', txType)
   }
   return buildContractId(tx.ownerId, +tx.nonce)