@aeternity/aepp-sdk 14.1.0 → 15.0.0

package/es/tx/builder/field-types/with-formatting.d.ts

@@ -1,4 +1,4 @@
-export default function withFormatting<Input, Output, Binary, Params, Options>(format: (v: Input | undefined) => Input, field: {
+export default function withFormatting<Input, Output, Binary, Params, Options>(format: (v: Input | undefined, params: Params) => Input, field: {
     serialize: (value: Input, params: Params, options: Options) => Binary;
     deserialize: (value: Binary) => Output;
 }): {

package/es/tx/builder/field-types/with-formatting.js

@@ -2,7 +2,7 @@ export default function withFormatting(format, field) {
   return {
     ...field,
     serialize(value, params, options) {
-      return field.serialize(format(value), params, options);
+      return field.serialize(format(value, params), params, options);
     }
   };
 }

package/es/tx/builder/field-types/with-formatting.js.map

@@ -1 +1 @@
-{"version":3,"file":"with-formatting.js","names":["withFormatting","format","field","serialize","value","params","options"],"sources":["../../../../src/tx/builder/field-types/with-formatting.ts"],"sourcesContent":["export default function withFormatting<Input, Output, Binary, Params, Options>(\n  format: (v: Input | undefined) => Input,\n  field: {\n    serialize: (value: Input, params: Params, options: Options) => Binary;\n    deserialize: (value: Binary) => Output;\n  },\n): {\n  serialize: (value: Input | undefined, params: Params, options: Options) => Binary;\n  deserialize: (value: Binary) => Output;\n} {\n  return {\n    ...field,\n\n    serialize(value, params, options) {\n      return field.serialize(format(value), params, options);\n    },\n  };\n}\n"],"mappings":"AAAA,eAAe,SAASA,cAAcA,CACpCC,MAAuC,EACvCC,KAGC,EAID;EACA,OAAO;IACL,GAAGA,KAAK;IAERC,SAASA,CAACC,KAAK,EAAEC,MAAM,EAAEC,OAAO,EAAE;MAChC,OAAOJ,KAAK,CAACC,SAAS,CAACF,MAAM,CAACG,KAAK,CAAC,EAAEC,MAAM,EAAEC,OAAO,CAAC;IACxD;EACF,CAAC;AACH","ignoreList":[]}
+{"version":3,"file":"with-formatting.js","names":["withFormatting","format","field","serialize","value","params","options"],"sources":["../../../../src/tx/builder/field-types/with-formatting.ts"],"sourcesContent":["export default function withFormatting<Input, Output, Binary, Params, Options>(\n  format: (v: Input | undefined, params: Params) => Input,\n  field: {\n    serialize: (value: Input, params: Params, options: Options) => Binary;\n    deserialize: (value: Binary) => Output;\n  },\n): {\n  serialize: (value: Input | undefined, params: Params, options: Options) => Binary;\n  deserialize: (value: Binary) => Output;\n} {\n  return {\n    ...field,\n\n    serialize(value, params, options) {\n      return field.serialize(format(value, params), params, options);\n    },\n  };\n}\n"],"mappings":"AAAA,eAAe,SAASA,cAAcA,CACpCC,MAAuD,EACvDC,KAGC,EAID;EACA,OAAO;IACL,GAAGA,KAAK;IAERC,SAASA,CAACC,KAAK,EAAEC,MAAM,EAAEC,OAAO,EAAE;MAChC,OAAOJ,KAAK,CAACC,SAAS,CAACF,MAAM,CAACG,KAAK,EAAEC,MAAM,CAAC,EAAEA,MAAM,EAAEC,OAAO,CAAC;IAChE;EACF,CAAC;AACH","ignoreList":[]}

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

@@ -13,6 +13,19 @@ type TxEncoding = Encoding.Transaction | Encoding.Poi | Encoding.StateTrees | En
  * @param params - Transaction params
  */
 export declare function buildTx(params: TxParams): Encoded.Transaction;
+/**
+ * Serializes a transaction that already exists — the result of an `unpackTx` — back to its
+ * `tx_`-encoded form.
+ *
+ * Use it instead of `buildTx` for a round trip. The values of such a transaction are fixed, and
+ * belong to the protocol parameters of the node it was built for: a node running a lower minimum
+ * gas price than the SDK release, a hyperchain or a devnet, produces a transaction that plain
+ * `buildTx` would refuse to serialize again because its fee is below the minimum this process
+ * computes. Nothing about it can be changed by re-serializing it, so nothing about it is checked.
+ * @category transaction builder
+ * @param params - Unpacked transaction, as returned by `unpackTx`
+ */
+export declare function rebuildUnpackedTx(params: TxUnpacked): Encoded.Transaction;
 export type BuildTxOptions<TxType extends Tag, OmitFields extends string> = Omit<TxParamsAsync & {
     tag: TxType;
 }, 'tag' | OmitFields>;

package/es/tx/builder/index.js

@@ -1,12 +1,14 @@
 import { decode, encode, Encoding } from '../../utils/encoder.js';
 import { hash } from '../../utils/crypto.js';
+import { serializeAsIsParam } from './field-types/interface.js';
 import { txSchema } from './schema.js';
 import { Tag } from './constants.js';
 import { buildContractId } from './helpers.js';
 import { getSchema as getSchemaCommon, packRecord, unpackRecord } from './common.js';
 import { ArgumentError } from '../../utils/errors.js';
 import { packEntry, unpackEntry } from './entry/index.js';
-
+import { checkParametersUsable, getCachedProtocolParameters } from './protocol-parameters.js';
+import { unwrapProxyIfPossible } from '../../utils/wrap-proxy.js';
 /**
  * JavaScript-based Transaction builder
  */
@@ -20,6 +22,11 @@ export function getSchema(tag, version) {
  * @param params - Transaction params
  */
 export function buildTx(params) {
+  // as trusted as `fee` is, see `checkParametersUsable`
+  const {
+    protocolParameters
+  } = params;
+  if (protocolParameters != null) checkParametersUsable(protocolParameters);
   return packRecord(txSchema, Tag, params, {
     // eslint-disable-next-line @typescript-eslint/no-use-before-define
     unpackTx,
@@ -31,6 +38,58 @@ export function buildTx(params) {
     packEntry
   }, Encoding.Transaction);
 }
+
+/**
+ * Serializes a transaction that already exists — the result of an `unpackTx` — back to its
+ * `tx_`-encoded form.
+ *
+ * Use it instead of `buildTx` for a round trip. The values of such a transaction are fixed, and
+ * belong to the protocol parameters of the node it was built for: a node running a lower minimum
+ * gas price than the SDK release, a hyperchain or a devnet, produces a transaction that plain
+ * `buildTx` would refuse to serialize again because its fee is below the minimum this process
+ * computes. Nothing about it can be changed by re-serializing it, so nothing about it is checked.
+ * @category transaction builder
+ * @param params - Unpacked transaction, as returned by `unpackTx`
+ */
+export function rebuildUnpackedTx(params) {
+  return buildTx({
+    ...params,
+    [serializeAsIsParam]: true
+  });
+}
+// the fields the protocol parameters price
+const parametrizedFields = ['fee', 'gasPrice', 'gasLimit'];
+
+/**
+ * The parameters are needed to compute a priced value the caller didn't provide, and to check one
+ * it did against what node accepts. A build that provides every priced field of its type, and
+ * nests no transaction that still has to be built, serializes to the same bytes with or without
+ * them — requesting them would turn a build that needs no node into one that waits for it, as it
+ * would for a caller that passes `fee` exactly to avoid the round trip.
+ */
+function needsProtocolParameters(schema, params) {
+  return schema.some(([key, field]) => {
+    const value = params[key];
+    if (parametrizedFields.includes(key)) return value == null;
+    // a nested transaction that is neither built (`tx_`) nor serialized (a buffer) yet is built
+    // here, and priced by these parameters in turn
+    if (field.nestedTransaction !== true) return false;
+    if (value == null || typeof value === 'string' || ArrayBuffer.isView(value)) return false;
+    // it is built here, but that doesn't mean anything in it is priced — the `SignedTx` wrapping
+    // an already serialized transaction that `AccountGeneralized` nests in its `GaMetaTx` has no
+    // priced field of its own
+    const nested = value;
+    let nestedSchema;
+    try {
+      nestedSchema = getSchema(nested.tag, nested.version);
+    } catch {
+      // an unknown tag or version fails later in `buildTx` with a better message than here
+      return true;
+    }
+    return needsProtocolParameters(nestedSchema, nested);
+  });
+}
+
 // TODO: require onNode because it is the only reason this builder is async [breaking change]
 /**
  * Build transaction async (may request node for additional data)
@@ -39,14 +98,42 @@ export function buildTx(params) {
  * @returns tx_-encoded transaction
  */
 export async function buildTxAsync(params) {
-  await Promise.all(getSchema(params.tag, params.version).map(async ([key, field]) => {
+  var _target$protocolParam;
+  // the caller may build another transaction out of the same object, and `prepare` writing the
+  // value it computed back would make the next build reuse them — the same nonce above all, and a
+  // `fee` that makes it skip the request for the parameters that priced this one
+  const paramsCopy = {
+    ...params
+  };
+  const {
+    onNode
+  } = paramsCopy;
+  const target = paramsCopy;
+  const schema = getSchema(paramsCopy.tag, paramsCopy.version);
+  // `onNode` of an sdk instance is a proxy that is not `null` even when no node is selected, and
+  // dereferencing it throws — a transaction that needs no node is still buildable in that case
+  const node = onNode != null ? unwrapProxyIfPossible(onNode) : undefined;
+  // started before the `prepare` calls below so that it runs in parallel with them: they read the
+  // parameters, but get this very request from the cache it registers synchronously. Below the
+  // `Promise.all` it would make `prepare` the originator and serialize the two requests
+  const parametersPromise = node != null && target.protocolParameters == null && needsProtocolParameters(schema, paramsCopy) ? getCachedProtocolParameters(node) : undefined;
+  // it is awaited after the `prepare` calls below, don't report it as an unhandled rejection if
+  // one of them throws first
+  parametersPromise?.catch(() => {});
+  await Promise.all(schema.map(async ([key, field]) => {
     if (field.prepare == null) return;
-    // @ts-expect-error the type of `params[key]` can't be determined accurately
-    params[key] = await field.prepare(params[key], params, params);
+    // @ts-expect-error the type of `paramsCopy[key]` can't be determined accurately
+    paramsCopy[key] = await field.prepare(paramsCopy[key], paramsCopy, paramsCopy);
   }));
+  const protocolParameters = (_target$protocolParam = target.protocolParameters) !== null && _target$protocolParam !== void 0 ? _target$protocolParam : await parametersPromise;
 
   // @ts-expect-error after preparation properties should be compatible with sync tx builder
-  return buildTx(params);
+  return buildTx({
+    ...paramsCopy,
+    ...(protocolParameters != null && {
+      protocolParameters
+    })
+  });
 }
 
 /**

package/es/tx/builder/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["decode","encode","Encoding","hash","txSchema","Tag","buildContractId","getSchema","getSchemaCommon","packRecord","unpackRecord","ArgumentError","packEntry","unpackEntry","tag","version","buildTx","params","unpackTx","rebuildTx","overrideParams","Transaction","buildTxAsync","Promise","all","map","key","field","prepare","encodedTx","txType","buildTxHash","rawTx","data","startsWith","TxHash","buildContractIdByContractTx","contractTx","SignedTx","ContractCreateTx","GaAttachTx","ownerId","nonce"],"sources":["../../../src/tx/builder/index.ts"],"sourcesContent":["import { decode, encode, Encoded, Encoding } from '../../utils/encoder.js';\nimport { hash } from '../../utils/crypto.js';\nimport { Field } from './field-types/interface.js';\nimport { txSchema } from './schema.js';\nimport { TxUnpacked, TxParams, TxParamsAsync } from './schema.generated.js';\nimport { Tag } from './constants.js';\nimport { buildContractId } from './helpers.js';\nimport { getSchema as getSchemaCommon, packRecord, unpackRecord } from './common.js';\nimport { ArgumentError } from '../../utils/errors.js';\nimport { packEntry, unpackEntry } from './entry/index.js';\n\n/**\n * JavaScript-based Transaction builder\n */\n\nexport function getSchema(tag: Tag, version?: number): Array<[string, Field]> {\n  return getSchemaCommon(txSchema, Tag, tag, version);\n}\n\ntype TxEncoding =\n  | Encoding.Transaction\n  | Encoding.Poi\n  | Encoding.StateTrees\n  | Encoding.CallStateTree;\n\n/**\n * Build transaction\n * @category transaction builder\n * @param params - Transaction params\n */\nexport function buildTx(params: TxParams): Encoded.Transaction {\n  return packRecord(\n    txSchema,\n    Tag,\n    params,\n    {\n      // eslint-disable-next-line @typescript-eslint/no-use-before-define\n      unpackTx,\n      buildTx,\n      rebuildTx: (overrideParams: any) => buildTx({ ...params, ...overrideParams }),\n      packEntry,\n    },\n    Encoding.Transaction,\n  );\n}\n\nexport type BuildTxOptions<TxType extends Tag, OmitFields extends string> = Omit<\n  TxParamsAsync & { tag: TxType },\n  'tag' | OmitFields\n>;\n\n// TODO: require onNode because it is the only reason this builder is async [breaking change]\n/**\n * Build transaction async (may request node for additional data)\n * @category transaction builder\n * @param params - Transaction params\n * @returns tx_-encoded transaction\n */\nexport async function buildTxAsync(params: TxParamsAsync): Promise<Encoded.Transaction> {\n  await Promise.all(\n    getSchema(params.tag, params.version).map(async ([key, field]) => {\n      if (field.prepare == null) return;\n      // @ts-expect-error the type of `params[key]` can't be determined accurately\n      params[key] = await field.prepare(params[key], params, params);\n    }),\n  );\n\n  // @ts-expect-error after preparation properties should be compatible with sync tx builder\n  return buildTx(params);\n}\n\n/**\n * Unpack transaction encoded as string\n * @category transaction builder\n * @param encodedTx - Encoded transaction\n * @param txType - Expected transaction type\n * @returns Transaction params\n */\nexport function unpackTx<TxType extends Tag>(\n  encodedTx: Encoded.Generic<TxEncoding>,\n  txType?: TxType,\n): TxUnpacked & { tag: TxType } {\n  return unpackRecord(txSchema, Tag, encodedTx, txType, { unpackTx, unpackEntry }) as any;\n}\n\n/**\n * Build a transaction hash\n * @category transaction builder\n * @param rawTx - base64 or rlp encoded transaction\n * @returns Transaction hash\n */\nexport function buildTxHash(rawTx: Encoded.Transaction | Uint8Array): Encoded.TxHash {\n  const data = typeof rawTx === 'string' && rawTx.startsWith('tx_') ? decode(rawTx) : rawTx;\n  return encode(hash(data), Encoding.TxHash);\n}\n\n/**\n * Build a contract public key by contractCreateTx, gaAttach or signedTx\n * @category contract\n * @param contractTx - Transaction\n * @returns Contract public key\n */\nexport function buildContractIdByContractTx(\n  contractTx: Encoded.Transaction,\n): Encoded.ContractAddress {\n  let params = unpackTx(contractTx);\n  if (Tag.SignedTx === params.tag) params = params.encodedTx;\n  if (Tag.ContractCreateTx !== params.tag && Tag.GaAttachTx !== params.tag) {\n    throw new ArgumentError('contractTx', 'a contractCreateTx or gaAttach', params.tag);\n  }\n  return buildContractId(params.ownerId, params.nonce);\n}\n"],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"index.js","names":["decode","encode","Encoding","hash","serializeAsIsParam","txSchema","Tag","buildContractId","getSchema","getSchemaCommon","packRecord","unpackRecord","ArgumentError","packEntry","unpackEntry","checkParametersUsable","getCachedProtocolParameters","unwrapProxyIfPossible","tag","version","buildTx","params","protocolParameters","unpackTx","rebuildTx","overrideParams","Transaction","rebuildUnpackedTx","parametrizedFields","needsProtocolParameters","schema","some","key","field","value","includes","nestedTransaction","ArrayBuffer","isView","nested","nestedSchema","buildTxAsync","_target$protocolParam","paramsCopy","onNode","target","node","undefined","parametersPromise","catch","Promise","all","map","prepare","encodedTx","txType","buildTxHash","rawTx","data","startsWith","TxHash","buildContractIdByContractTx","contractTx","SignedTx","ContractCreateTx","GaAttachTx","ownerId","nonce"],"sources":["../../../src/tx/builder/index.ts"],"sourcesContent":["import { decode, encode, Encoded, Encoding } from '../../utils/encoder.js';\nimport { hash } from '../../utils/crypto.js';\nimport { Field, serializeAsIsParam } from './field-types/interface.js';\nimport { txSchema } from './schema.js';\nimport { TxUnpacked, TxParams, TxParamsAsync } from './schema.generated.js';\nimport { Tag } from './constants.js';\nimport { buildContractId } from './helpers.js';\nimport { getSchema as getSchemaCommon, packRecord, unpackRecord } from './common.js';\nimport { ArgumentError } from '../../utils/errors.js';\nimport { packEntry, unpackEntry } from './entry/index.js';\nimport {\n  checkParametersUsable,\n  getCachedProtocolParameters,\n  ProtocolParameters,\n  ProtocolParametersOption,\n} from './protocol-parameters.js';\nimport { unwrapProxyIfPossible } from '../../utils/wrap-proxy.js';\nimport type Node from '../../Node.js';\n\n/**\n * JavaScript-based Transaction builder\n */\n\nexport function getSchema(tag: Tag, version?: number): Array<[string, Field]> {\n  return getSchemaCommon(txSchema, Tag, tag, version);\n}\n\ntype TxEncoding =\n  | Encoding.Transaction\n  | Encoding.Poi\n  | Encoding.StateTrees\n  | Encoding.CallStateTree;\n\n/**\n * Build transaction\n * @category transaction builder\n * @param params - Transaction params\n */\nexport function buildTx(params: TxParams): Encoded.Transaction {\n  // as trusted as `fee` is, see `checkParametersUsable`\n  const { protocolParameters } = params as ProtocolParametersOption;\n  if (protocolParameters != null) checkParametersUsable(protocolParameters);\n  return packRecord(\n    txSchema,\n    Tag,\n    params,\n    {\n      // eslint-disable-next-line @typescript-eslint/no-use-before-define\n      unpackTx,\n      buildTx,\n      rebuildTx: (overrideParams: any) => buildTx({ ...params, ...overrideParams }),\n      packEntry,\n    },\n    Encoding.Transaction,\n  );\n}\n\n/**\n * Serializes a transaction that already exists — the result of an `unpackTx` — back to its\n * `tx_`-encoded form.\n *\n * Use it instead of `buildTx` for a round trip. The values of such a transaction are fixed, and\n * belong to the protocol parameters of the node it was built for: a node running a lower minimum\n * gas price than the SDK release, a hyperchain or a devnet, produces a transaction that plain\n * `buildTx` would refuse to serialize again because its fee is below the minimum this process\n * computes. Nothing about it can be changed by re-serializing it, so nothing about it is checked.\n * @category transaction builder\n * @param params - Unpacked transaction, as returned by `unpackTx`\n */\nexport function rebuildUnpackedTx(params: TxUnpacked): Encoded.Transaction {\n  return buildTx({ ...params, [serializeAsIsParam]: true } as unknown as TxParams);\n}\n\nexport type BuildTxOptions<TxType extends Tag, OmitFields extends string> = Omit<\n  TxParamsAsync & { tag: TxType },\n  'tag' | OmitFields\n>;\n\n// the fields the protocol parameters price\nconst parametrizedFields = ['fee', 'gasPrice', 'gasLimit'];\n\n/**\n * The parameters are needed to compute a priced value the caller didn't provide, and to check one\n * it did against what node accepts. A build that provides every priced field of its type, and\n * nests no transaction that still has to be built, serializes to the same bytes with or without\n * them — requesting them would turn a build that needs no node into one that waits for it, as it\n * would for a caller that passes `fee` exactly to avoid the round trip.\n */\nfunction needsProtocolParameters(schema: Array<[string, Field]>, params: TxParamsAsync): boolean {\n  return schema.some(([key, field]) => {\n    const value = (params as unknown as Record<string, unknown>)[key];\n    if (parametrizedFields.includes(key)) return value == null;\n    // a nested transaction that is neither built (`tx_`) nor serialized (a buffer) yet is built\n    // here, and priced by these parameters in turn\n    if (field.nestedTransaction !== true) return false;\n    if (value == null || typeof value === 'string' || ArrayBuffer.isView(value)) return false;\n    // it is built here, but that doesn't mean anything in it is priced — the `SignedTx` wrapping\n    // an already serialized transaction that `AccountGeneralized` nests in its `GaMetaTx` has no\n    // priced field of its own\n    const nested = value as TxParamsAsync;\n    let nestedSchema;\n    try {\n      nestedSchema = getSchema(nested.tag, nested.version);\n    } catch {\n      // an unknown tag or version fails later in `buildTx` with a better message than here\n      return true;\n    }\n    return needsProtocolParameters(nestedSchema, nested);\n  });\n}\n\n// TODO: require onNode because it is the only reason this builder is async [breaking change]\n/**\n * Build transaction async (may request node for additional data)\n * @category transaction builder\n * @param params - Transaction params\n * @returns tx_-encoded transaction\n */\nexport async function buildTxAsync(params: TxParamsAsync): Promise<Encoded.Transaction> {\n  // the caller may build another transaction out of the same object, and `prepare` writing the\n  // value it computed back would make the next build reuse them — the same nonce above all, and a\n  // `fee` that makes it skip the request for the parameters that priced this one\n  const paramsCopy = { ...params };\n  const { onNode } = paramsCopy as { onNode?: Node };\n  const target = paramsCopy as { protocolParameters?: ProtocolParameters };\n  const schema = getSchema(paramsCopy.tag, paramsCopy.version);\n  // `onNode` of an sdk instance is a proxy that is not `null` even when no node is selected, and\n  // dereferencing it throws — a transaction that needs no node is still buildable in that case\n  const node = onNode != null ? unwrapProxyIfPossible(onNode) : undefined;\n  // started before the `prepare` calls below so that it runs in parallel with them: they read the\n  // parameters, but get this very request from the cache it registers synchronously. Below the\n  // `Promise.all` it would make `prepare` the originator and serialize the two requests\n  const parametersPromise =\n    node != null && target.protocolParameters == null && needsProtocolParameters(schema, paramsCopy)\n      ? getCachedProtocolParameters(node)\n      : undefined;\n  // it is awaited after the `prepare` calls below, don't report it as an unhandled rejection if\n  // one of them throws first\n  parametersPromise?.catch(() => {});\n\n  await Promise.all(\n    schema.map(async ([key, field]) => {\n      if (field.prepare == null) return;\n      // @ts-expect-error the type of `paramsCopy[key]` can't be determined accurately\n      paramsCopy[key] = await field.prepare(paramsCopy[key], paramsCopy, paramsCopy);\n    }),\n  );\n\n  const protocolParameters = target.protocolParameters ?? (await parametersPromise);\n\n  // @ts-expect-error after preparation properties should be compatible with sync tx builder\n  return buildTx({ ...paramsCopy, ...(protocolParameters != null && { protocolParameters }) });\n}\n\n/**\n * Unpack transaction encoded as string\n * @category transaction builder\n * @param encodedTx - Encoded transaction\n * @param txType - Expected transaction type\n * @returns Transaction params\n */\nexport function unpackTx<TxType extends Tag>(\n  encodedTx: Encoded.Generic<TxEncoding>,\n  txType?: TxType,\n): TxUnpacked & { tag: TxType } {\n  return unpackRecord(txSchema, Tag, encodedTx, txType, { unpackTx, unpackEntry }) as any;\n}\n\n/**\n * Build a transaction hash\n * @category transaction builder\n * @param rawTx - base64 or rlp encoded transaction\n * @returns Transaction hash\n */\nexport function buildTxHash(rawTx: Encoded.Transaction | Uint8Array): Encoded.TxHash {\n  const data = typeof rawTx === 'string' && rawTx.startsWith('tx_') ? decode(rawTx) : rawTx;\n  return encode(hash(data), Encoding.TxHash);\n}\n\n/**\n * Build a contract public key by contractCreateTx, gaAttach or signedTx\n * @category contract\n * @param contractTx - Transaction\n * @returns Contract public key\n */\nexport function buildContractIdByContractTx(\n  contractTx: Encoded.Transaction,\n): Encoded.ContractAddress {\n  let params = unpackTx(contractTx);\n  if (Tag.SignedTx === params.tag) params = params.encodedTx;\n  if (Tag.ContractCreateTx !== params.tag && Tag.GaAttachTx !== params.tag) {\n    throw new ArgumentError('contractTx', 'a contractCreateTx or gaAttach', params.tag);\n  }\n  return buildContractId(params.ownerId, params.nonce);\n}\n"],"mappings":"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","ignoreList":[]}

package/es/tx/builder/protocol-parameters.d.ts

@@ -0,0 +1,123 @@
+import { AbiVersion, Tag } from './constants.js';
+import type Node from '../../Node.js';
+/**
+ * Consensus parameters and node policy settings the transaction builder needs to produce a
+ * transaction the node would accept — see {@link getCachedProtocolParameters}.
+ * @category transaction builder
+ */
+export interface ProtocolParameters {
+    /**
+     * Consensus minimum gas price in aettos, the minimum transaction fee is the transaction's fee
+     * gas multiplied by this value
+     */
+    readonly minGasPrice: bigint;
+    /**
+     * Minimum gas price accepted by the miner of the node the SDK is connected to. A transaction
+     * below it is still valid, but this node won't mine it.
+     */
+    readonly minMinerGasPrice: bigint;
+    /** Gas per serialized transaction byte counted into the minimum fee */
+    readonly gasPerByte: number;
+    /**
+     * Maximum total gas the node the SDK is connected to accepts in a single micro block. Node
+     * policy rather than a consensus parameter, it may differ between nodes.
+     */
+    readonly blockGasLimit: number;
+    /**
+     * Maximum gas accepted for a generalized account authentication function by the node the SDK is
+     * connected to. Node policy rather than a consensus parameter, it may differ between nodes.
+     */
+    readonly maxAuthFunGas: number;
+    /** Base fee gas by transaction type, transactions not executing contract code */
+    readonly txBaseGas: Readonly<Partial<Record<Tag, number>>>;
+    /** Base fee gas of contract-executing transaction types, by ABI version */
+    readonly contractTxBaseGas: Readonly<Partial<Record<Tag, Readonly<Partial<Record<AbiVersion, number>>>>>>;
+    /**
+     * State rent gas fraction per key block by transaction type,
+     * state gas is `ceil(relativeTtl * part / whole)`
+     */
+    readonly stateGasPerBlock: Readonly<Partial<Record<Tag, Readonly<{
+        part: number;
+        whole: number;
+    }>>>>;
+}
+/**
+ * Transaction option to build a transaction against specific consensus parameters. `buildTxAsync`
+ * sets it to the parameters it requests from node, provide it to build a transaction offline for a
+ * node that doesn't run the protocol version the current SDK release was made for.
+ * @category transaction builder
+ */
+export interface ProtocolParametersOption {
+    protocolParameters?: ProtocolParameters;
+}
+/**
+ * Protocol parameters of Ceres as they were at the moment of the SDK release. Used to build
+ * transactions without a node connection, and on nodes that don't provide the protocol parameters
+ * endpoint yet.
+ * @category transaction builder
+ * @see {@link https://github.com/aeternity/protocol/blob/master/consensus/README.md#gas}
+ */
+export declare const defaultProtocolParameters: ProtocolParameters;
+/**
+ * `Math.max(...array)` passes every element as an argument and overflows the stack on an array
+ * node can make arbitrarily long — it reports one entry per transaction type and abi version.
+ */
+export declare function maxOf(numbers: number[]): number;
+/**
+ * Checks that parameters a caller provided in options can price a transaction at all — only values
+ * that would produce `NaN`, `Infinity`, or a division by zero, not their magnitude: options are the
+ * way out of the bounds {@link convertProtocolParameters} applies, bounding them here would leave
+ * no way to build against a network the SDK release doesn't know. They are as trusted as `fee` and
+ * `gasLimit`: must not come from untrusted input, this only turns an unusable value into an error
+ * naming the field. See `serializeAsIsParam`.
+ * @param parameters - Parameters provided in options
+ */
+export declare function checkParametersUsable(parameters: ProtocolParameters): void;
+/**
+ * Factor the gas price ceiling of `gas-price.ts` is lowered by, so that the worst case fee doesn't
+ * become the product of that ceiling and the fee gas bound of {@link convertProtocolParameters}.
+ * The gas limit raise is charged to the gas limit default instead ({@link getGasLimitDivisor}).
+ * It is 1 unless the parameters came from node.
+ *
+ * The biggest raise among all transaction types, not the one of the type being built — so a node
+ * repricing one type lowers the ceiling for every type. The ceiling is 100000 times the minimum
+ * gas price, far above the demand-based price this bounds in practice.
+ * @param parameters - Parameters a transaction is built against
+ */
+export declare function getGasPriceDivisor(parameters: ProtocolParameters): number;
+/**
+ * The cost of a contract transaction is `gasPrice * gasLimit`, and the gas limit the SDK defaults
+ * to comes from `blockGasLimit` — from `maxAuthFunGas` on a `GaMetaTx`. This is the factor node
+ * raises the one `tag` reads by, so that lowering the default by it keeps the product within the
+ * one of the SDK release. It is 1 unless the parameters came from node.
+ *
+ * Only the limit `tag` reads: charging the other one would shrink a gas limit because node raised
+ * something that transaction never reads. The fee gas raise is charged to the gas price ceiling
+ * ({@link getGasPriceDivisor}) instead.
+ * @param parameters - Parameters a transaction is built against
+ * @param tag - Type of the transaction the gas limit is defaulted for
+ */
+export declare function getGasLimitDivisor(parameters: ProtocolParameters, tag: Tag): number;
+/**
+ * Converts the node responses to the shape the transaction builder uses, rejecting values far
+ * above the ones the SDK was released with. Not a part of the public api, it is exported for
+ * tests — use {@link getCachedProtocolParameters}.
+ * @param response - Response of the `/v3/protocol-parameters` endpoint
+ * @param nodeSettings - Response of the `/v3/node-settings` endpoint
+ */
+export declare function convertProtocolParameters(response: Awaited<ReturnType<Node['getProtocolParameters']>>, nodeSettings: Awaited<ReturnType<Node['getNodeSettings']>>): ProtocolParameters;
+/**
+ * Requests protocol parameters from node, the result is cached per node instance.
+ *
+ * Falls back to {@link defaultProtocolParameters} for a node that doesn't provide the endpoints,
+ * can't be reached, or answers something this SDK release can't read. Rejects only when node
+ * reports parameters that would price a transaction far above the SDK release — see
+ * {@link ProtocolParametersOption} for the way out of that.
+ *
+ * The cache is keyed by the `Node` object, so code that constructs a `Node` per request (a
+ * serverless handler, an edge worker) requests the parameters again for each one. Keep one `Node`
+ * instance per endpoint to get the benefit of the cache.
+ * @category transaction builder
+ * @param nodeOrProxy - Node to request the parameters from
+ */
+export declare function getCachedProtocolParameters(nodeOrProxy: Node): Promise<ProtocolParameters>;