phantasma-sdk-ts 0.11.0 → 0.12.0

package/dist/cjs/rpc/interfaces/gas-config.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gasConfigFromRpc = gasConfigFromRpc;
+const gas_config_js_1 = require("../../types/carbon/blockchain/gas-config.js");
+/**
+ * Converts the getGasConfig JSON response to the wire-format GasConfig consumed by the Tier-1
+ * fee estimator. Throws on malformed numeric strings and on a v2 response missing tail fields:
+ * estimating fees from silently zeroed v2 prices would produce rejected transactions.
+ */
+function gasConfigFromRpc(result) {
+    const c = result.gasConfig;
+    if (!c) {
+        throw new Error('getGasConfig response has no gasConfig section');
+    }
+    const config = new gas_config_js_1.GasConfig({
+        version: c.version,
+        maxNameLength: c.maxNameLength,
+        maxTokenSymbolLength: c.maxTokenSymbolLength,
+        feeShift: c.feeShift,
+        maxStructureSize: c.maxStructureSize,
+        feeMultiplier: parseU64(c.feeMultiplier, 'feeMultiplier'),
+        gasTokenId: parseU64(c.gasTokenId, 'gasTokenId'),
+        dataTokenId: parseU64(c.dataTokenId, 'dataTokenId'),
+        minimumGasOffer: parseU64(c.minimumGasOffer, 'minimumGasOffer'),
+        dataEscrowPerRow: parseU64(c.dataEscrowPerRow, 'dataEscrowPerRow'),
+        gasFeeTransfer: parseU64(c.gasFeeTransfer, 'gasFeeTransfer'),
+        gasFeeQuery: parseU64(c.gasFeeQuery, 'gasFeeQuery'),
+        gasFeeCreateTokenBase: parseU64(c.gasFeeCreateTokenBase, 'gasFeeCreateTokenBase'),
+        gasFeeCreateTokenSymbol: parseU64(c.gasFeeCreateTokenSymbol, 'gasFeeCreateTokenSymbol'),
+        gasFeeCreateTokenSeries: parseU64(c.gasFeeCreateTokenSeries, 'gasFeeCreateTokenSeries'),
+        gasFeePerByte: parseU64(c.gasFeePerByte, 'gasFeePerByte'),
+        gasFeeRegisterName: parseU64(c.gasFeeRegisterName, 'gasFeeRegisterName'),
+        gasBurnRatioMul: parseU64(c.gasBurnRatioMul, 'gasBurnRatioMul'),
+        gasBurnRatioShift: c.gasBurnRatioShift,
+    });
+    if (config.version >= 1) {
+        config.minimumGasBill = parseU64(c.minimumGasBill, 'minimumGasBill');
+        config.gasProducerRatioMul = parseU64(c.gasProducerRatioMul, 'gasProducerRatioMul');
+        config.gasProducerRatioShift = requireByte(c.gasProducerRatioShift, 'gasProducerRatioShift');
+        config.gasDappRatioMul = parseU64(c.gasDappRatioMul, 'gasDappRatioMul');
+        config.gasDappRatioShift = requireByte(c.gasDappRatioShift, 'gasDappRatioShift');
+        config.policyFeeCreateTokenBase = parseU64(c.policyFeeCreateTokenBase, 'policyFeeCreateTokenBase');
+        config.policyFeeCreateTokenSymbol = parseU64(c.policyFeeCreateTokenSymbol, 'policyFeeCreateTokenSymbol');
+        config.policyFeeCreateTokenSeries = parseU64(c.policyFeeCreateTokenSeries, 'policyFeeCreateTokenSeries');
+        config.policyFeeRegisterName = parseU64(c.policyFeeRegisterName, 'policyFeeRegisterName');
+        config.legacyDataEscrowPerRow = parseU64(c.legacyDataEscrowPerRow, 'legacyDataEscrowPerRow');
+    }
+    return config;
+}
+function parseU64(value, fieldName) {
+    if (value === undefined || value === '') {
+        throw new Error(`getGasConfig field ${fieldName} is missing or empty`);
+    }
+    if (!/^\d+$/.test(value)) {
+        throw new Error(`getGasConfig field ${fieldName} is not a decimal integer: ${value}`);
+    }
+    return BigInt(value);
+}
+function requireByte(value, fieldName) {
+    if (value === undefined) {
+        throw new Error(`getGasConfig field ${fieldName} is missing`);
+    }
+    return value;
+}

package/dist/cjs/rpc/interfaces/index.js

@@ -30,6 +30,7 @@ __exportStar(require("./contract.js"), exports);
 __exportStar(require("./dapp.js"), exports);
 __exportStar(require("./event.js"), exports);
 __exportStar(require("./event-extended.js"), exports);
+__exportStar(require("./gas-config.js"), exports);
 __exportStar(require("./governance.js"), exports);
 __exportStar(require("./interop.js"), exports);
 __exportStar(require("./key-value.js"), exports);

package/dist/cjs/rpc/phantasma.js

@@ -416,6 +416,16 @@ class PhantasmaAPI {
         const params = [name, extended];
         return (await this.JSONRPC('getChain', params));
     }
+    /**
+     * Returns the current on-chain gas configuration plus the chain parameters fee estimation
+     * needs (block rate target, expiry window). Changes only via governance resolutions, so the
+     * result is safe to cache. Feed gasConfigFromRpc() into estimateNativeFee() for Tier-1 fee
+     * estimates.
+     */
+    async getGasConfig() {
+        const params = [];
+        return (await this.JSONRPC('getGasConfig', params));
+    }
     //Returns info about the nexus.
     // Warning: current Carbon RPC endpoint is stubbed and returns a default nexus object.
     async getNexus(extended = true) {

package/dist/cjs/types/carbon/blockchain/gas-config.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GasConfig = void 0;
+/**
+ * On-chain gas configuration (governance module). The gas-model-v2 extension fields serialize
+ * only for version >= 1, mirroring the node's data_blockchain.h wire format exactly: the
+ * version-0 byte image is frozen forever for historical replay, and a version>=1 image truncated
+ * to the v0 length fails to parse (the tail read throws on end of stream).
+ */
+class GasConfig {
+    constructor(init) {
+        this.version = 0;
+        this.maxNameLength = 0;
+        this.maxTokenSymbolLength = 0;
+        this.feeShift = 0;
+        this.maxStructureSize = 0;
+        this.feeMultiplier = 0n;
+        this.gasTokenId = 0n;
+        this.dataTokenId = 0n;
+        this.minimumGasOffer = 0n;
+        this.dataEscrowPerRow = 0n;
+        this.gasFeeTransfer = 0n;
+        this.gasFeeQuery = 0n;
+        this.gasFeeCreateTokenBase = 0n;
+        this.gasFeeCreateTokenSymbol = 0n;
+        this.gasFeeCreateTokenSeries = 0n;
+        this.gasFeePerByte = 0n;
+        this.gasFeeRegisterName = 0n;
+        this.gasBurnRatioMul = 0n;
+        this.gasBurnRatioShift = 0;
+        this.minimumGasBill = 0n;
+        this.gasProducerRatioMul = 0n;
+        this.gasProducerRatioShift = 0;
+        this.gasDappRatioMul = 0n;
+        this.gasDappRatioShift = 0;
+        this.policyFeeCreateTokenBase = 0n;
+        this.policyFeeCreateTokenSymbol = 0n;
+        this.policyFeeCreateTokenSeries = 0n;
+        this.policyFeeRegisterName = 0n;
+        this.legacyDataEscrowPerRow = 0n;
+        Object.assign(this, init);
+    }
+    /**
+     * True when this config activates the gas-model-v2 billing rules (config version >= 1). The
+     * gas model is gated by the config version, not by a chain feature level.
+     */
+    get hasGasModelV2() {
+        return this.version >= 1;
+    }
+    write(w) {
+        w.write1(this.version);
+        w.write1(this.maxNameLength);
+        w.write1(this.maxTokenSymbolLength);
+        w.write1(this.feeShift);
+        w.write4u(this.maxStructureSize);
+        w.write8u(this.feeMultiplier);
+        w.write8u(this.gasTokenId);
+        w.write8u(this.dataTokenId);
+        w.write8u(this.minimumGasOffer);
+        w.write8u(this.dataEscrowPerRow);
+        w.write8u(this.gasFeeTransfer);
+        w.write8u(this.gasFeeQuery);
+        w.write8u(this.gasFeeCreateTokenBase);
+        w.write8u(this.gasFeeCreateTokenSymbol);
+        w.write8u(this.gasFeeCreateTokenSeries);
+        w.write8u(this.gasFeePerByte);
+        w.write8u(this.gasFeeRegisterName);
+        w.write8u(this.gasBurnRatioMul);
+        w.write1(this.gasBurnRatioShift);
+        if (this.version === 0) {
+            // Version-0 wire image must stay byte-identical to the pre-v2 layout.
+            return;
+        }
+        w.write8u(this.minimumGasBill);
+        w.write8u(this.gasProducerRatioMul);
+        w.write1(this.gasProducerRatioShift);
+        w.write8u(this.gasDappRatioMul);
+        w.write1(this.gasDappRatioShift);
+        w.write8u(this.policyFeeCreateTokenBase);
+        w.write8u(this.policyFeeCreateTokenSymbol);
+        w.write8u(this.policyFeeCreateTokenSeries);
+        w.write8u(this.policyFeeRegisterName);
+        w.write8u(this.legacyDataEscrowPerRow);
+    }
+    read(r) {
+        this.version = r.read1();
+        this.maxNameLength = r.read1();
+        this.maxTokenSymbolLength = r.read1();
+        this.feeShift = r.read1();
+        this.maxStructureSize = r.read4u();
+        this.feeMultiplier = r.read8u();
+        this.gasTokenId = r.read8u();
+        this.dataTokenId = r.read8u();
+        this.minimumGasOffer = r.read8u();
+        this.dataEscrowPerRow = r.read8u();
+        this.gasFeeTransfer = r.read8u();
+        this.gasFeeQuery = r.read8u();
+        this.gasFeeCreateTokenBase = r.read8u();
+        this.gasFeeCreateTokenSymbol = r.read8u();
+        this.gasFeeCreateTokenSeries = r.read8u();
+        this.gasFeePerByte = r.read8u();
+        this.gasFeeRegisterName = r.read8u();
+        this.gasBurnRatioMul = r.read8u();
+        this.gasBurnRatioShift = r.read1();
+        if (this.version === 0) {
+            // Version-0 rows carry no v2 tail; zero it so a reused instance never leaks stale values.
+            this.minimumGasBill = 0n;
+            this.gasProducerRatioMul = 0n;
+            this.gasProducerRatioShift = 0;
+            this.gasDappRatioMul = 0n;
+            this.gasDappRatioShift = 0;
+            this.policyFeeCreateTokenBase = 0n;
+            this.policyFeeCreateTokenSymbol = 0n;
+            this.policyFeeCreateTokenSeries = 0n;
+            this.policyFeeRegisterName = 0n;
+            this.legacyDataEscrowPerRow = 0n;
+            return;
+        }
+        // version >= 1: the tail is mandatory; a truncated image throws (end of stream).
+        this.minimumGasBill = r.read8u();
+        this.gasProducerRatioMul = r.read8u();
+        this.gasProducerRatioShift = r.read1();
+        this.gasDappRatioMul = r.read8u();
+        this.gasDappRatioShift = r.read1();
+        this.policyFeeCreateTokenBase = r.read8u();
+        this.policyFeeCreateTokenSymbol = r.read8u();
+        this.policyFeeCreateTokenSeries = r.read8u();
+        this.policyFeeRegisterName = r.read8u();
+        this.legacyDataEscrowPerRow = r.read8u();
+    }
+    static read(r) {
+        const v = new GasConfig();
+        v.read(r);
+        return v;
+    }
+}
+exports.GasConfig = GasConfig;

package/dist/cjs/types/carbon/blockchain/index.js

@@ -19,6 +19,7 @@ __exportStar(require("./modules/index.js"), exports);
 __exportStar(require("./tx-helpers/index.js"), exports);
 __exportStar(require("./vm/index.js"), exports);
 __exportStar(require("./carbon-token-flags.js"), exports);
+__exportStar(require("./gas-config.js"), exports);
 __exportStar(require("./module-id.js"), exports);
 __exportStar(require("./signed-tx-msg.js"), exports);
 __exportStar(require("./tx-msg.js"), exports);

package/dist/cjs/types/carbon/blockchain/tx-helpers/index.js

@@ -19,3 +19,4 @@ __exportStar(require("./create-token-tx-helper.js"), exports);
 __exportStar(require("./fee-options.js"), exports);
 __exportStar(require("./mint-phantasma-non-fungible-tx-helper.js"), exports);
 __exportStar(require("./mint-non-fungible-tx-helper.js"), exports);
+__exportStar(require("./native-fee-estimator.js"), exports);

package/dist/cjs/types/carbon/blockchain/tx-helpers/native-fee-estimator.js

@@ -0,0 +1,268 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NATIVE_SIGNATURE_BYTES = exports.WITNESS_ARRAY_ENTRY_BYTES = exports.GAS_MODEL_V2_UNITS_PER_BLOCK_DATA_BYTE = exports.NativeFeeKind = void 0;
+exports.estimateNativeFee = estimateNativeFee;
+exports.envelopeBytesFor = envelopeBytesFor;
+/** Native operation kinds supported by the Tier-1 fee estimator. */
+var NativeFeeKind;
+(function (NativeFeeKind) {
+    /** Fungible token transfer (native TxTypes.TransferFungible / _GasPayer). */
+    NativeFeeKind["TransferFungible"] = "TransferFungible";
+    /** NFT transfer of `count` instances (TxTypes.TransferNonFungible_*). */
+    NativeFeeKind["TransferNonFungible"] = "TransferNonFungible";
+    /** Fungible mint (TxTypes.MintFungible or TokenContract.MintFungible call). */
+    NativeFeeKind["MintFungible"] = "MintFungible";
+    /** NFT mint of `count` instances (TxTypes.MintNonFungible or contract call). */
+    NativeFeeKind["MintNonFungible"] = "MintNonFungible";
+    /** Fungible burn (TxTypes.BurnFungible / _GasPayer). */
+    NativeFeeKind["BurnFungible"] = "BurnFungible";
+    /** NFT burn of `count` instances (TxTypes.BurnNonFungible / _GasPayer). */
+    NativeFeeKind["BurnNonFungible"] = "BurnNonFungible";
+    /** TokenContract.CreateToken call. Requires `symbolLength` when a symbol is set. */
+    NativeFeeKind["CreateToken"] = "CreateToken";
+    /** TokenContract.CreateTokenSeries call. */
+    NativeFeeKind["CreateTokenSeries"] = "CreateTokenSeries";
+    /** GovernanceContract.RegisterName call. Requires `nameLength`. */
+    NativeFeeKind["RegisterName"] = "RegisterName";
+    /**
+     * Generic Phantasma VM script transaction (AllowGas/SpendGas pattern: stake, marketplace,
+     * custom contract calls). Script opcode costs are not closed-form in Tier-1; the estimate
+     * budgets `scriptUnitsAllowance` VM work units on top of the byte fee. For an exact script
+     * bill use the node-side Tier-2 estimator once available.
+     */
+    NativeFeeKind["Script"] = "Script";
+})(NativeFeeKind || (exports.NativeFeeKind = NativeFeeKind = {}));
+/**
+ * Gas model v2 price of block-carried bytes, in gas units per byte. A versioned consensus
+ * constant of the v2 gas model (node data_blockchain.h kGasModelV2UnitsPerBlockDataByte),
+ * deliberately not part of the on-chain config.
+ */
+exports.GAS_MODEL_V2_UNITS_PER_BLOCK_DATA_BYTE = 25n;
+/** Serialized size of one witness-array entry (32-byte address + 64-byte signature). */
+exports.WITNESS_ARRAY_ENTRY_BYTES = 96;
+/** Serialized size of one bare signature (native TxTypes carry no witness array). */
+exports.NATIVE_SIGNATURE_BYTES = 64;
+const U64_MAX = 0xffffffffffffffffn;
+/**
+ * Tier-1 static fee calculator: closed-form gas/data offers for native operations, exact under
+ * both gas models (selected by GasConfig.version). Mirrors the validator billing formula
+ * (node blockchain.cpp settlement + token/governance contract gas sites); any change to those
+ * formulas ships as a new gas-model version, never silently.
+ *
+ * @param kind - Operation kind.
+ * @param config - Current chain gas config (see the getGasConfig RPC method).
+ * @param params - Optional inputs; omit for safe single-signer defaults.
+ */
+function estimateNativeFee(kind, config, params = {}) {
+    const count = params.count ?? 1;
+    if (!Number.isSafeInteger(count) || count < 1) {
+        throw new RangeError('count must be a positive integer');
+    }
+    const countU = BigInt(count);
+    const v2 = config.hasGasModelV2;
+    // Work units consumed by the operation itself (the ConsumeGas amounts in the token /
+    // governance contracts) and, under v2, the direct kcal-base policy fee that replaces the v1
+    // unit-priced product prices.
+    let workUnits;
+    let policyFee = 0n;
+    switch (kind) {
+        case NativeFeeKind.TransferFungible:
+        case NativeFeeKind.MintFungible:
+        case NativeFeeKind.BurnFungible:
+            workUnits = config.gasFeeTransfer;
+            break;
+        case NativeFeeKind.TransferNonFungible:
+        case NativeFeeKind.MintNonFungible:
+        case NativeFeeKind.BurnNonFungible:
+            workUnits = clampU64(config.gasFeeTransfer * countU);
+            break;
+        case NativeFeeKind.CreateToken: {
+            // Symbol price halves per character after the first; shift is validated by the chain
+            // against maxTokenSymbolLength, mirror that bound here.
+            const shift = symbolShift(params.symbolLength ?? 0, config.maxTokenSymbolLength, 'symbolLength');
+            const hasSymbol = (params.symbolLength ?? 0) > 0;
+            if (v2) {
+                workUnits = 0n;
+                policyFee = clampU64(config.policyFeeCreateTokenBase +
+                    (hasSymbol ? config.policyFeeCreateTokenSymbol >> shift : 0n));
+            }
+            else {
+                workUnits = clampU64(config.gasFeeCreateTokenBase + (hasSymbol ? config.gasFeeCreateTokenSymbol >> shift : 0n));
+            }
+            break;
+        }
+        case NativeFeeKind.CreateTokenSeries:
+            workUnits = v2 ? 0n : config.gasFeeCreateTokenSeries;
+            policyFee = v2 ? config.policyFeeCreateTokenSeries : 0n;
+            break;
+        case NativeFeeKind.RegisterName: {
+            const nameLength = params.nameLength ?? 0;
+            if (nameLength <= 0) {
+                throw new RangeError('nameLength is required for RegisterName');
+            }
+            const shift = symbolShift(nameLength, config.maxNameLength, 'nameLength');
+            workUnits = v2 ? 0n : config.gasFeeRegisterName >> shift;
+            policyFee = v2 ? config.policyFeeRegisterName >> shift : 0n;
+            break;
+        }
+        case NativeFeeKind.Script:
+            workUnits = params.scriptUnitsAllowance ?? 5000n;
+            break;
+        default:
+            throw new RangeError(`unknown fee kind: ${kind}`);
+    }
+    const rows = BigInt(params.freshRows ?? defaultFreshRows(kind, count, params.romRamBytes ?? 0));
+    if (rows < 0n) {
+        throw new RangeError('freshRows must not be negative');
+    }
+    const envelope = BigInt(params.envelopeBytes ?? defaultEnvelopeBytes(kind, count, params.romRamBytes ?? 0));
+    // Native TxTypes store no events in the block; script txs do (Notify), so budget some.
+    const eventBytes = kind === NativeFeeKind.Script ? 512n : 0n;
+    let expected;
+    let maxGas;
+    if (v2) {
+        // v2 formula: bill = mulShiftSat(workUnits + blockData*25, mult, shift) + policyFee,
+        // floored at minimumGasBill. blockData = envelope + events + net storage quanta (quanta are
+        // added to the byte count by the chain formula).
+        expected = billV2(workUnits, envelope, eventBytes, rows, policyFee, config);
+        // Offer headroom: +25% over the padded bill covers witness-size wiggle and event variance;
+        // deterministic and always refunded down to the actual bill.
+        const padded = billV2(workUnits, roundUp(envelope, 128n), eventBytes, rows, policyFee, config);
+        maxGas = clampU64(padded + padded / 4n);
+        if (maxGas < config.minimumGasBill)
+            maxGas = config.minimumGasBill;
+        if (maxGas < config.minimumGasOffer)
+            maxGas = config.minimumGasOffer;
+    }
+    else {
+        // v1 formula: bill = (workUnits * mult >> shift) + blockData * gasFeePerByte where
+        // blockData = payload + events + net storage quanta (no envelope term, no floor).
+        const work = mulShift(workUnits, config.feeMultiplier, config.feeShift);
+        const blockData = BigInt(params.payloadBytes ?? 0) + eventBytes + rows;
+        expected = clampU64(work + clampU64(blockData * config.gasFeePerByte));
+        // Offer shape mirrors the validator's own test-agent stdFee: a 2x minimum-offer pad plus a
+        // flat 1 KiB block-data allowance on top of the work term.
+        const byteAllowance = blockData > 1024n ? blockData : 1024n;
+        maxGas = clampU64(config.minimumGasOffer * 2n + work + clampU64(byteAllowance * config.gasFeePerByte));
+    }
+    const maxData = clampU64(rows * config.dataEscrowPerRow);
+    return { maxGas, maxData, expectedGasBill: expected };
+}
+/**
+ * Envelope size (signed tx bytes as carried in the block) from a serialized unsigned message
+ * length and the number of signers. Use with {@link NativeFeeParams.envelopeBytes} for exact v2
+ * estimates. Witness layout mirrors SignedTxMsg: native TxTypes append bare 64-byte signatures
+ * (one, or two for the _GasPayer variants); Call/Trade/Phantasma txs append a length-prefixed
+ * witness array (32-byte address + 64-byte signature per entry).
+ */
+function envelopeBytesFor(kind, serializedMessageLength, witnessCount = 1) {
+    if (!Number.isSafeInteger(serializedMessageLength) || serializedMessageLength < 0) {
+        throw new RangeError('serializedMessageLength must be a non-negative integer');
+    }
+    if (!Number.isSafeInteger(witnessCount) || witnessCount < 0) {
+        throw new RangeError('witnessCount must be a non-negative integer');
+    }
+    switch (kind) {
+        case NativeFeeKind.TransferFungible:
+        case NativeFeeKind.TransferNonFungible:
+        case NativeFeeKind.MintFungible:
+        case NativeFeeKind.MintNonFungible:
+        case NativeFeeKind.BurnFungible:
+        case NativeFeeKind.BurnNonFungible:
+            return serializedMessageLength + exports.NATIVE_SIGNATURE_BYTES * witnessCount;
+        default:
+            // CreateToken/CreateTokenSeries/RegisterName ride TxTypes.Call; Script rides
+            // TxTypes.Phantasma - both carry the witness array form.
+            return serializedMessageLength + 4 + exports.WITNESS_ARRAY_ENTRY_BYTES * witnessCount;
+    }
+}
+function billV2(workUnits, envelope, eventBytes, rows, policyFee, config) {
+    const blockData = envelope + eventBytes + rows;
+    const byteUnits = clampU64(blockData * exports.GAS_MODEL_V2_UNITS_PER_BLOCK_DATA_BYTE);
+    let bill = mulShift(clampU64(workUnits + byteUnits), config.feeMultiplier, config.feeShift);
+    bill = clampU64(bill + policyFee);
+    return bill < config.minimumGasBill ? config.minimumGasBill : bill;
+}
+// Chain fee scaling: (value * feeMultiplier) >> feeShift, saturating to u64. Matches the
+// validator's v2 MulShiftSaturateU64; for sane v1 configs (live values never overflow 64 bits)
+// it is also bit-identical to the v1 math.
+function mulShift(value, multiplier, shift) {
+    if (shift >= 64)
+        return 0n; // the chain clamps oversized shifts to a zero delta
+    return clampU64((value * multiplier) >> BigInt(shift));
+}
+function symbolShift(length, maxLength, paramName) {
+    if (!Number.isSafeInteger(length) || length < 0) {
+        throw new RangeError(`${paramName} must be a non-negative integer`);
+    }
+    if (length === 0)
+        return 0n;
+    const shift = length - 1;
+    // The chain asserts shift < maxNameLength / maxTokenSymbolLength; a longer input could never
+    // be admitted, so reject it here instead of quoting a fee for an impossible tx.
+    if (maxLength !== 0 && shift >= maxLength) {
+        throw new RangeError(`${paramName} ${length} exceeds the chain maximum ${maxLength}`);
+    }
+    return BigInt(shift);
+}
+// Worst-case paid rows the operation can create (drives maxData). Refund-only operations
+// (burns) need no escrow allowance: refunds never require maxData budget.
+function defaultFreshRows(kind, count, romRamBytes) {
+    switch (kind) {
+        case NativeFeeKind.TransferFungible:
+        case NativeFeeKind.MintFungible:
+            return 1; // recipient balance row may be fresh (SOUL/KCAL rows would be free)
+        case NativeFeeKind.TransferNonFungible:
+            // Per instance the chain deletes the sender's NFT-lookup row and creates the recipient's
+            // (creation escrows at the current price, the deletion refunds the old row's own deposit)
+            // + possibly a fresh recipient balance row.
+            return count + 1;
+        case NativeFeeKind.MintNonFungible:
+            // Per instance: owner row + lookup row + the instance state rows holding ROM/RAM (1 KiB
+            // quanta), plus possibly a fresh recipient balance row.
+            return count * (2 + Math.ceil(romRamBytes / 1024)) + 1;
+        case NativeFeeKind.BurnFungible:
+        case NativeFeeKind.BurnNonFungible:
+            return 0;
+        case NativeFeeKind.CreateToken:
+            return 8; // token info + symbol lookup + supply/config rows, metadata-dependent
+        case NativeFeeKind.CreateTokenSeries:
+            return 4;
+        case NativeFeeKind.RegisterName:
+            return 2; // name->address and address->name rows
+        case NativeFeeKind.Script:
+        default:
+            return 4;
+    }
+}
+// Conservative single-witness envelope defaults per kind; used only when the caller did not
+// measure the real signed size. Generous by design: under v2 an oversized estimate only raises
+// the refunded offer, never the settled bill.
+function defaultEnvelopeBytes(kind, count, romRamBytes) {
+    switch (kind) {
+        case NativeFeeKind.TransferFungible:
+        case NativeFeeKind.MintFungible:
+        case NativeFeeKind.BurnFungible:
+        case NativeFeeKind.RegisterName:
+            return 512;
+        case NativeFeeKind.TransferNonFungible:
+        case NativeFeeKind.BurnNonFungible:
+            return 512 + 8 * count; // 8 bytes per carried instance id
+        case NativeFeeKind.MintNonFungible:
+            return 512 + count * (64 + romRamBytes); // ROM/RAM ride the envelope
+        case NativeFeeKind.CreateToken:
+            return 4096; // token metadata (icons, descriptions) dominates
+        case NativeFeeKind.CreateTokenSeries:
+            return 2048;
+        case NativeFeeKind.Script:
+        default:
+            return 1024;
+    }
+}
+function roundUp(value, step) {
+    const rem = value % step;
+    return rem === 0n ? value : value + (step - rem);
+}
+function clampU64(value) {
+    return value > U64_MAX ? U64_MAX : value;
+}

package/dist/esm/rpc/interfaces/gas-config.js

@@ -0,0 +1,61 @@
+import { GasConfig } from '../../types/carbon/blockchain/gas-config.js';
+/**
+ * Converts the getGasConfig JSON response to the wire-format GasConfig consumed by the Tier-1
+ * fee estimator. Throws on malformed numeric strings and on a v2 response missing tail fields:
+ * estimating fees from silently zeroed v2 prices would produce rejected transactions.
+ */
+export function gasConfigFromRpc(result) {
+    const c = result.gasConfig;
+    if (!c) {
+        throw new Error('getGasConfig response has no gasConfig section');
+    }
+    const config = new GasConfig({
+        version: c.version,
+        maxNameLength: c.maxNameLength,
+        maxTokenSymbolLength: c.maxTokenSymbolLength,
+        feeShift: c.feeShift,
+        maxStructureSize: c.maxStructureSize,
+        feeMultiplier: parseU64(c.feeMultiplier, 'feeMultiplier'),
+        gasTokenId: parseU64(c.gasTokenId, 'gasTokenId'),
+        dataTokenId: parseU64(c.dataTokenId, 'dataTokenId'),
+        minimumGasOffer: parseU64(c.minimumGasOffer, 'minimumGasOffer'),
+        dataEscrowPerRow: parseU64(c.dataEscrowPerRow, 'dataEscrowPerRow'),
+        gasFeeTransfer: parseU64(c.gasFeeTransfer, 'gasFeeTransfer'),
+        gasFeeQuery: parseU64(c.gasFeeQuery, 'gasFeeQuery'),
+        gasFeeCreateTokenBase: parseU64(c.gasFeeCreateTokenBase, 'gasFeeCreateTokenBase'),
+        gasFeeCreateTokenSymbol: parseU64(c.gasFeeCreateTokenSymbol, 'gasFeeCreateTokenSymbol'),
+        gasFeeCreateTokenSeries: parseU64(c.gasFeeCreateTokenSeries, 'gasFeeCreateTokenSeries'),
+        gasFeePerByte: parseU64(c.gasFeePerByte, 'gasFeePerByte'),
+        gasFeeRegisterName: parseU64(c.gasFeeRegisterName, 'gasFeeRegisterName'),
+        gasBurnRatioMul: parseU64(c.gasBurnRatioMul, 'gasBurnRatioMul'),
+        gasBurnRatioShift: c.gasBurnRatioShift,
+    });
+    if (config.version >= 1) {
+        config.minimumGasBill = parseU64(c.minimumGasBill, 'minimumGasBill');
+        config.gasProducerRatioMul = parseU64(c.gasProducerRatioMul, 'gasProducerRatioMul');
+        config.gasProducerRatioShift = requireByte(c.gasProducerRatioShift, 'gasProducerRatioShift');
+        config.gasDappRatioMul = parseU64(c.gasDappRatioMul, 'gasDappRatioMul');
+        config.gasDappRatioShift = requireByte(c.gasDappRatioShift, 'gasDappRatioShift');
+        config.policyFeeCreateTokenBase = parseU64(c.policyFeeCreateTokenBase, 'policyFeeCreateTokenBase');
+        config.policyFeeCreateTokenSymbol = parseU64(c.policyFeeCreateTokenSymbol, 'policyFeeCreateTokenSymbol');
+        config.policyFeeCreateTokenSeries = parseU64(c.policyFeeCreateTokenSeries, 'policyFeeCreateTokenSeries');
+        config.policyFeeRegisterName = parseU64(c.policyFeeRegisterName, 'policyFeeRegisterName');
+        config.legacyDataEscrowPerRow = parseU64(c.legacyDataEscrowPerRow, 'legacyDataEscrowPerRow');
+    }
+    return config;
+}
+function parseU64(value, fieldName) {
+    if (value === undefined || value === '') {
+        throw new Error(`getGasConfig field ${fieldName} is missing or empty`);
+    }
+    if (!/^\d+$/.test(value)) {
+        throw new Error(`getGasConfig field ${fieldName} is not a decimal integer: ${value}`);
+    }
+    return BigInt(value);
+}
+function requireByte(value, fieldName) {
+    if (value === undefined) {
+        throw new Error(`getGasConfig field ${fieldName} is missing`);
+    }
+    return value;
+}

package/dist/esm/rpc/interfaces/index.js

@@ -14,6 +14,7 @@ export * from './contract.js';
 export * from './dapp.js';
 export * from './event.js';
 export * from './event-extended.js';
+export * from './gas-config.js';
 export * from './governance.js';
 export * from './interop.js';
 export * from './key-value.js';

package/dist/esm/rpc/phantasma.js

@@ -410,6 +410,16 @@ export class PhantasmaAPI {
         const params = [name, extended];
         return (await this.JSONRPC('getChain', params));
     }
+    /**
+     * Returns the current on-chain gas configuration plus the chain parameters fee estimation
+     * needs (block rate target, expiry window). Changes only via governance resolutions, so the
+     * result is safe to cache. Feed gasConfigFromRpc() into estimateNativeFee() for Tier-1 fee
+     * estimates.
+     */
+    async getGasConfig() {
+        const params = [];
+        return (await this.JSONRPC('getGasConfig', params));
+    }
     //Returns info about the nexus.
     // Warning: current Carbon RPC endpoint is stubbed and returns a default nexus object.
     async getNexus(extended = true) {