@aeternity/aepp-sdk 11.0.0 → 12.1.0

package/es/tx/builder/helpers.d.ts

@@ -0,0 +1,125 @@
+/// <reference types="node" />
+import BigNumber from 'bignumber.js';
+import { Encoded } from '../../utils/encoder';
+import { AensName } from './constants';
+import { NamePointer } from '../../apis/node';
+/**
+ * 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 declare function buildContractId(ownerId: Encoded.AccountAddress, nonce: number | BigNumber): Encoded.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 declare function oracleQueryId(senderId: Encoded.AccountAddress, nonce: number | BigNumber | string, oracleId: Encoded.OracleAddress): Encoded.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 declare function formatSalt(salt: number): Buffer;
+/**
+ * Encode an AENS name
+ * @category AENS
+ * @param name - Name to encode
+ * @returns `nm_` prefixed encoded AENS name
+ */
+export declare function produceNameId(name: AensName): Encoded.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 declare function commitmentHash(name: AensName, salt?: number): Encoded.Commitment;
+/**
+ * Utility function to convert int to bytes
+ * @category transaction builder
+ * @param val - Value
+ * @returns Buffer Buffer from number(BigEndian)
+ */
+export declare function writeInt(val: number | string | BigNumber): Buffer;
+/**
+ * Utility function to convert bytes to int
+ * @category transaction builder
+ * @param buf - Value
+ * @returns Buffer Buffer from number(BigEndian)
+ */
+export declare function readInt(buf?: Buffer): string;
+/**
+ * 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 declare function buildPointers(pointers: NamePointer[]): Buffer[][];
+/**
+ * Helper function to read pointers from name update TX
+ * @category transaction builder
+ * @param pointers - Array of pointers
+ * @returns Deserialize pointer array
+ */
+export declare function readPointers(pointers: Array<[key: string, id: Buffer]>): NamePointer[];
+/**
+ * Is AENS name valid
+ * @category AENS
+ * @param name - AENS name
+ */
+export declare function isNameValid(name: string): name is AensName;
+declare const encodingToPointerKey: readonly [readonly [Encoded.Encoding.AccountAddress, "account_pubkey"], readonly [Encoded.Encoding.OracleAddress, "oracle_pubkey"], readonly [Encoded.Encoding.ContractAddress, "contract_pubkey"], readonly [Encoded.Encoding.Channel, "channel"]];
+/**
+ * @category AENS
+ * @param identifier - account/oracle/contract address, or channel
+ * @returns default AENS pointer key
+ */
+export declare function getDefaultPointerKey(identifier: Encoded.Generic<typeof encodingToPointerKey[number][0]>): typeof encodingToPointerKey[number][1];
+/**
+ * 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 declare function getMinimumNameFee(name: AensName): BigNumber;
+/**
+ * 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 declare function computeBidFee(name: AensName, { startFee, increment }?: {
+    startFee?: number | string | BigNumber;
+    increment?: number;
+}): BigNumber;
+/**
+ * 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 declare function computeAuctionEndBlock(name: AensName, claimHeight: number): number;
+/**
+ * Is name accept going to auction
+ * @category AENS
+ */
+export declare function isAuctionName(name: AensName): boolean;
+export {};

package/es/tx/builder/helpers.mjs

@@ -3,60 +3,55 @@ const {
   Buffer: _Buffer
 } = _buffer;
 import BigNumber from 'bignumber.js';
-import bs58 from 'bs58';
-import { hash, salt, sha256hash } from "../../utils/crypto.mjs";
+import { genSalt, hash } from "../../utils/crypto.mjs";
+import { decode, encode, Encoding } from "../../utils/encoder.mjs";
 import { toBytes } from "../../utils/bytes.mjs";
-import { ID_TAG_PREFIX, PREFIX_ID_TAG, NAME_BID_RANGES, NAME_FEE_BID_INCREMENT, NAME_BID_TIMEOUTS, NAME_MAX_LENGTH_FEE, POINTER_KEY_BY_PREFIX } from "./schema.mjs";
+import { concatBuffers } from "../../utils/other.mjs";
+import { NAME_BID_RANGES, NAME_BID_TIMEOUT_BLOCKS, NAME_FEE_BID_INCREMENT, NAME_MAX_LENGTH_FEE } from "./constants.mjs";
 import { ceil } from "../../utils/bignumber.mjs";
-import { PrefixMismatchError, DecodeError, EncodeError, PayloadLengthError, TagNotFoundError, PrefixNotFoundError, InvalidNameError, IllegalBidFeeError, NoDefaultAensPointerError, ArgumentError, InvalidChecksumError } from "../../utils/errors.mjs";
+import { ArgumentError, IllegalBidFeeError } from "../../utils/errors.mjs";
+import { readId, writeId } from "./address.mjs";
 /**
  * JavaScript-based Transaction builder helper function's
- * @module @aeternity/aepp-sdk/es/tx/builder/helpers
- * @export TxBuilderHelper
- * @example import { TxBuilderHelper } from '@aeternity/aepp-sdk'
  */
 
-export const createSalt = salt;
 /**
  * Build a contract public key
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {string} ownerId The public key of the owner account
- * @param {number} nonce the nonce of the transaction
- * @return {string} 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, nonce) {
-  const ownerIdAndNonce = _Buffer.from([...decode(ownerId, 'ak'), ...toBytes(nonce)]);
+  const ownerIdAndNonce = _Buffer.from([...decode(ownerId), ...toBytes(nonce)]);
 
   const b2bHash = hash(ownerIdAndNonce);
-  return encode(b2bHash, 'ct');
+  return encode(b2bHash, Encoding.ContractAddress);
 }
 /**
  * Build a oracle query id
- * @function
- * @function* @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {String} senderId The public key of the sender account
- * @param {Number} nonce the nonce of the transaction
- * @param {Number} oracleId The oracle public key
- * @return {string} Contract public key
+ * @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, nonce, oracleId) {
   function _int32(val) {
     const nonceBE = toBytes(val, true);
-    return _Buffer.concat([_Buffer.alloc(32 - nonceBE.length), nonceBE]);
+    return concatBuffers([_Buffer.alloc(32 - nonceBE.length), nonceBE]);
   }
 
-  const b2bHash = hash(_Buffer.from([...decode(senderId, 'ak'), ..._int32(nonce), ...decode(oracleId, 'ok')]));
-  return encode(b2bHash, 'oq');
+  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
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {number} salt
- * @return {string} Zero-padded hex string of salt
+ * @category transaction builder
+ * @param salt - Random number
+ * @returns Zero-padded hex string of salt
  */
 
 export function formatSalt(salt) {
@@ -64,156 +59,32 @@ export function formatSalt(salt) {
 }
 /**
  * Encode an AENS name
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {String} name Name to encode
- * @return {String} `nm_` prefixed encoded AENS name
+ * @category AENS
+ * @param name - Name to encode
+ * @returns `nm_` prefixed encoded AENS name
  */
 
 export function produceNameId(name) {
-  ensureNameValid(name);
-  return encode(hash(name.toLowerCase()), 'nm');
+  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_'
- *
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @function commitmentHash
- * @category async
- * @rtype (name: String, salt?: String) => hash: Promise[String]
- * @param {String} name - Name to be registered
- * @param {Number} salt Random salt
- * @return {String} Commitment hash
+ * @category transaction builder
+ * @param name - Name to be registered
+ * @param salt - Random salt
+ * @returns Commitment hash
  */
 
 export function commitmentHash(name) {
-  let salt = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : createSalt();
-  ensureNameValid(name);
-  return encode(hash(_Buffer.concat([_Buffer.from(name.toLowerCase()), formatSalt(salt)])), 'cm');
-} // based on https://github.com/aeternity/protocol/blob/master/node/api/api_encoding.md
-
-const base64Types = ['ba', 'cb', 'or', 'ov', 'pi', 'ss', 'cs', 'ck', 'cv', 'st', 'tx'];
-const base58Types = ['ak', 'bf', 'bs', 'bx', 'ch', 'cm', 'ct', 'kh', 'mh', 'nm', 'ok', 'oq', 'pp', 'sg', 'th']; // TODO: add all types with a fixed length
-
-const typesLength = {
-  ak: 32,
-  ct: 32,
-  ok: 32
-};
-
-function ensureValidLength(data, type) {
-  if (!typesLength[type]) return;
-  if (data.length === typesLength[type]) return;
-  throw new PayloadLengthError(`Payload should be ${typesLength[type]} bytes, got ${data.length} instead`);
-}
-
-const getChecksum = payload => sha256hash(sha256hash(payload)).slice(0, 4);
-
-const addChecksum = input => {
-  const payload = _Buffer.from(input);
-
-  return _Buffer.concat([payload, getChecksum(payload)]);
-};
-
-function getPayload(buffer) {
-  const payload = buffer.slice(0, -4);
-  if (!getChecksum(payload).equals(buffer.slice(-4))) throw new InvalidChecksumError();
-  return payload;
-}
-
-const base64 = {
-  encode: buffer => addChecksum(buffer).toString('base64'),
-  decode: string => getPayload(_Buffer.from(string, 'base64'))
-};
-const base58 = {
-  encode: buffer => bs58.encode(addChecksum(buffer)),
-  decode: string => getPayload(bs58.decode(string))
-};
-/**
- * Decode data using the default encoding/decoding algorithm
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {string} data An Base58/64check encoded and prefixed string (ex tx_..., sg_..., ak_....)
- * @param {string} [requiredPrefix] Ensure that data have this prefix
- * @return {Buffer} Decoded data
- */
-
-export function decode(data, requiredPrefix) {
-  if (typeof data !== 'string') throw new DecodeError(`Encoded should be a string, got ${data} instead`);
-  const [prefix, encodedPayload, extra] = data.split('_');
-  if (!encodedPayload) throw new DecodeError(`Encoded string missing payload: ${data}`);
-  if (extra) throw new DecodeError(`Encoded string have extra parts: ${data}`);
-
-  if (requiredPrefix && requiredPrefix !== prefix) {
-    throw new PrefixMismatchError(prefix, requiredPrefix);
-  }
-
-  const decoder = base64Types.includes(prefix) && base64.decode || base58Types.includes(prefix) && base58.decode;
-
-  if (!decoder) {
-    throw new DecodeError(`Encoded string have unknown type: ${prefix}`);
-  }
-
-  const payload = decoder(encodedPayload);
-  ensureValidLength(payload, prefix);
-  return payload;
-}
-/**
- * Encode data using the default encoding/decoding algorithm
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {Buffer|String} data  An decoded data
- * @param {string} type Prefix of Transaction
- * @return {String} Encoded string Base58check or Base64check data
- */
-
-export function encode(data, type) {
-  const encoder = base64Types.includes(type) && base64.encode || base58Types.includes(type) && base58.encode;
-
-  if (!encoder) {
-    throw new EncodeError(`Unknown type: ${type}`);
-  }
-
-  ensureValidLength(data, type);
-  return `${type}_${encoder(data)}`;
-}
-/**
- * Utility function to create and _id type
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {string} hashId Encoded hash
- * @return {Buffer} Buffer Buffer with ID tag and decoded HASh
- */
-
-export function writeId(hashId) {
-  if (typeof hashId !== 'string') throw new ArgumentError('hashId', 'a string', hashId);
-  const prefix = hashId.slice(0, 2);
-  const idTag = PREFIX_ID_TAG[prefix];
-  if (!idTag) throw new TagNotFoundError(prefix);
-  return _Buffer.from([...toBytes(idTag), ...decode(hashId, prefix)]);
-}
-/**
- * Utility function to read and _id type
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {Buffer} buf Data
- * @return {String} Encoided hash string with prefix
- */
-
-export function readId(buf) {
-  const tag = _Buffer.from(buf).readUIntBE(0, 1);
-
-  const prefix = ID_TAG_PREFIX[tag];
-  if (!prefix) throw new PrefixNotFoundError(tag);
-  return encode(buf.slice(1, buf.length), prefix);
+  let salt = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : genSalt();
+  return encode(hash(concatBuffers([_Buffer.from(name.toLowerCase()), formatSalt(salt)])), Encoding.Commitment);
 }
 /**
  * Utility function to convert int to bytes
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {Number|String|BigNumber} val Value
- * @return {Buffer} Buffer Buffer from number(BigEndian)
+ * @category transaction builder
+ * @param val - Value
+ * @returns Buffer Buffer from number(BigEndian)
  */
 
 export function writeInt(val) {
@@ -221,10 +92,9 @@ export function writeInt(val) {
 }
 /**
  * Utility function to convert bytes to int
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {Buffer} buf Value
- * @return {String} Buffer Buffer from number(BigEndian)
+ * @category transaction builder
+ * @param buf - Value
+ * @returns Buffer Buffer from number(BigEndian)
  */
 
 export function readInt() {
@@ -233,11 +103,10 @@ export function readInt() {
 }
 /**
  * Helper function to build pointers for name update TX
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {Array} pointers - Array of pointers
- * ([ { key: 'account_pubkey', id: 'ak_32klj5j23k23j5423l434l2j3423'} ])
- * @return {Array} Serialized pointers array
+ * @category transaction builder
+ * @param pointers - Array of pointers
+ * `([ { key: 'account_pubkey', id: 'ak_32klj5j23k23j5423l434l2j3423'} ])`
+ * @returns Serialized pointers array
  */
 
 export function buildPointers(pointers) {
@@ -245,119 +114,104 @@ export function buildPointers(pointers) {
 }
 /**
  * Helper function to read pointers from name update TX
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {Array} pointers - Array of pointers
- * ([ { key: 'account_pubkey', id: 'ak_32klj5j23k23j5423l434l2j3423'} ])
- * @return {Array} Deserialize pointer array
+ * @category transaction builder
+ * @param pointers - Array of pointers
+ * @returns Deserialize pointer array
  */
 
 export function readPointers(pointers) {
   return pointers.map(_ref => {
     let [key, id] = _ref;
-    return Object.assign({
+    return {
       key: key.toString(),
       id: readId(id)
-    });
+    };
   });
 }
 const AENS_SUFFIX = '.chain';
-/**
- * Ensure that AENS name is valid
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {string} name
- * @return void
- * @throws Error
- */
-
-export function ensureNameValid(name) {
-  if (!name || typeof name !== 'string') throw new InvalidNameError('Name must be a string');
-  if (!name.endsWith(AENS_SUFFIX)) throw new InvalidNameError(`Name should end with ${AENS_SUFFIX}: ${name}`);
-}
 /**
  * Is AENS name valid
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {string} name
- * @return Boolean
+ * @category AENS
+ * @param name - AENS name
  */
 
 export function isNameValid(name) {
-  try {
-    ensureNameValid(name);
-    return true;
-  } catch (error) {
-    return false;
-  }
+  // 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']];
 /**
+ * @category AENS
  * @param identifier - account/oracle/contract address, or channel
- * @returns {String} default AENS pointer key
- * @throws exception when default key not defined
+ * @returns default AENS pointer key
  */
 
 export function getDefaultPointerKey(identifier) {
+  var _encodingToPointerKey;
+
   decode(identifier);
-  const prefix = identifier.substr(0, 2);
-  return POINTER_KEY_BY_PREFIX[prefix] || (() => {
-    throw new NoDefaultAensPointerError(prefix);
-  })();
+  const encoding = identifier.substring(0, 2);
+  const result = (_encodingToPointerKey = encodingToPointerKey.find(_ref2 => {
+    let [e] = _ref2;
+    return e === encoding;
+  })) === null || _encodingToPointerKey === void 0 ? void 0 : _encodingToPointerKey[1];
+  if (result != null) return result;
+  throw new ArgumentError('identifier', `prefixed with one of ${encodingToPointerKey.map(_ref3 => {
+    let [e] = _ref3;
+    return `${e}_`;
+  }).join(', ')}`, identifier);
 }
 /**
  * Get the minimum AENS name fee
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {String} name the AENS name to get the fee for
- * @return {String} the minimum fee for the AENS name auction
+ * @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) {
-  ensureNameValid(name);
   const nameLength = name.length - AENS_SUFFIX.length;
   return NAME_BID_RANGES[Math.min(nameLength, NAME_MAX_LENGTH_FEE)];
 }
 /**
  * Compute bid fee for AENS auction
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {String} name the AENS name to get the fee for
- * @param {Number|String} startFee Auction start fee
- * @param {Number} [increment=0.5] Bid multiplier(In percentage, must be between 0 and 1)
- * @return {String} Bid fee
- */
-
-export function computeBidFee(name, startFee) {
-  let increment = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : NAME_FEE_BID_INCREMENT;
+ * @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) {
+  let {
+    startFee,
+    increment = NAME_FEE_BID_INCREMENT
+  } = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
   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}`);
-  return ceil(BigNumber(startFee !== null && startFee !== void 0 ? startFee : getMinimumNameFee(name)).times(BigNumber(NAME_FEE_BID_INCREMENT).plus(1)));
+  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 !== null && startFee !== void 0 ? startFee : getMinimumNameFee(name)).times(new BigNumber(NAME_FEE_BID_INCREMENT).plus(1)));
 }
 /**
  * Compute auction end height
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {String} name
- * @param {Number|String} claimHeight Auction starting height
- * @return {String} 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, claimHeight) {
-  ensureNameValid(name);
   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;
 }
 /**
  * Is name accept going to auction
- * @function
- * @alias module:@aeternity/aepp-sdk/es/tx/builder/helpers
- * @param {String} name
- * @return {Boolean}
+ * @category AENS
  */
 
 export function isAuctionName(name) {
-  ensureNameValid(name);
   return name.length < 13 + AENS_SUFFIX.length;
 }
 //# sourceMappingURL=helpers.mjs.map