@stellar/stellar-base - npm Package Compare versions

Comparing version 14.0.4 to 14.1.0

lib/auth.js

@@ -29,6 +29,4 @@ "use strict";
  *
- * @returns {
- *    Promise<Uint8Array> |
- *    Promise<{signature: Uint8Array, publicKey: string}
- * }  the signature of the raw payload (which is the sha256 hash of the preimage
+ * @returns {Promise<Uint8Array | {signature: Uint8Array, publicKey: string}>}
+ *    the signature of the raw payload (which is the sha256 hash of the preimage
  *    bytes, so `hash(preimage.toXDR())`) either naked, implying it is signed
@@ -35,0 +33,0 @@ *    by the key corresponding to the public key in the entry you pass to

lib/transaction_builder.js

@@ -20,2 +20,7 @@ "use strict";
 var _memo = require("./memo");
+var _asset = require("./asset");
+var _scval = require("./scval");
+var _operation = require("./operation");
+var _address = require("./address");
+var _keypair = require("./keypair");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { "default": e }; }
@@ -36,3 +41,3 @@ function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : i + ""; }
-function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); } // eslint-disable-next-line no-unused-vars
 /**
@@ -58,2 +63,10 @@ * Minimum base fee for transactions. If this fee is below the network
 /**
+ * @typedef {object} SorobanFees
+ * @property {number} instructions - the number of instructions executed by the transaction
+ * @property {number} readBytes - the number of bytes read from the ledger by the transaction
+ * @property {number} writeBytes - the number of bytes written to the ledger by the transaction
+ * @property {bigint} resourceFee - the fee to be paid for the transaction, in stroops
+ */
+
+/**
  * <p>Transaction builder helps constructs a new `{@link Transaction}` using the
@@ -561,2 +574,146 @@ * given {@link Account} as the transaction's "source account". The transaction
     /**
+     * Creates and adds an invoke host function operation for transferring SAC tokens.
+     * This method removes the need for simulation by handling the creation of the
+     * appropriate authorization entries and ledger footprint for the transfer operation.
+     *
+     * @param {string} destination - the address of the recipient of the SAC transfer (should be a valid Stellar address or contract ID)
+     * @param {Asset} asset - the SAC asset to be transferred
+     * @param  {BigInt} amount - the amount of tokens to be transferred in 7 decimals. IE 1 token with 7 decimals of precision would be represented as "1_0000000"
+     * @param {SorobanFees} [sorobanFees] - optional Soroban fees for the transaction to override the default fees used
+     *
+     * @returns {TransactionBuilder}
+     */
+  }, {
+    key: "addSacTransferOperation",
+    value: function addSacTransferOperation(destination, asset, amount, sorobanFees) {
+      if (BigInt(amount) <= 0n) {
+        throw new Error('Amount must be a positive integer');
+      } else if (BigInt(amount) > _jsXdr.Hyper.MAX_VALUE) {
+        // The largest supported value for SAC is i64 however the contract interface uses i128 which is why we convert it to i128
+        throw new Error('Amount exceeds maximum value for i64');
+      }
+      if (sorobanFees) {
+        var instructions = sorobanFees.instructions,
+          readBytes = sorobanFees.readBytes,
+          writeBytes = sorobanFees.writeBytes,
+          resourceFee = sorobanFees.resourceFee;
+        var U32_MAX = 4294967295;
+        if (instructions <= 0 || instructions > U32_MAX) {
+          throw new Error("instructions must be greater than 0 and at most ".concat(U32_MAX));
+        }
+        if (readBytes <= 0 || readBytes > U32_MAX) {
+          throw new Error("readBytes must be greater than 0 and at most ".concat(U32_MAX));
+        }
+        if (writeBytes <= 0 || writeBytes > U32_MAX) {
+          throw new Error("writeBytes must be greater than 0 and at most ".concat(U32_MAX));
+        }
+        if (resourceFee <= 0n || resourceFee > _jsXdr.Hyper.MAX_VALUE) {
+          throw new Error('resourceFee must be greater than 0 and at most i64 max');
+        }
+      }
+      var isDestinationContract = _strkey.StrKey.isValidContract(destination);
+      if (!isDestinationContract) {
+        if (!_strkey.StrKey.isValidEd25519PublicKey(destination) && !_strkey.StrKey.isValidMed25519PublicKey(destination)) {
+          throw new Error('Invalid destination address. Must be a valid Stellar address or contract ID.');
+        }
+      }
+      if (destination === this.source.accountId()) {
+        throw new Error('Destination cannot be the same as the source account.');
+      }
+      var contractId = asset.contractId(this.networkPassphrase);
+      var functionName = 'transfer';
+      var source = this.source.accountId();
+      var args = [(0, _scval.nativeToScVal)(source, {
+        type: 'address'
+      }), (0, _scval.nativeToScVal)(destination, {
+        type: 'address'
+      }), (0, _scval.nativeToScVal)(amount, {
+        type: 'i128'
+      })];
+      var isAssetNative = asset.isNative();
+      var auths = new _xdr["default"].SorobanAuthorizationEntry({
+        credentials: _xdr["default"].SorobanCredentials.sorobanCredentialsSourceAccount(),
+        rootInvocation: new _xdr["default"].SorobanAuthorizedInvocation({
+          "function": _xdr["default"].SorobanAuthorizedFunction.sorobanAuthorizedFunctionTypeContractFn(new _xdr["default"].InvokeContractArgs({
+            contractAddress: _address.Address.fromString(contractId).toScAddress(),
+            functionName: functionName,
+            args: args
+          })),
+          subInvocations: []
+        })
+      });
+      var footprint = new _xdr["default"].LedgerFootprint({
+        readOnly: [_xdr["default"].LedgerKey.contractData(new _xdr["default"].LedgerKeyContractData({
+          contract: _address.Address.fromString(contractId).toScAddress(),
+          key: _xdr["default"].ScVal.scvLedgerKeyContractInstance(),
+          durability: _xdr["default"].ContractDataDurability.persistent()
+        }))],
+        readWrite: []
+      });
+
+      // Ledger entries for the destination account
+      if (isDestinationContract) {
+        footprint.readWrite().push(_xdr["default"].LedgerKey.contractData(new _xdr["default"].LedgerKeyContractData({
+          contract: _address.Address.fromString(contractId).toScAddress(),
+          key: _xdr["default"].ScVal.scvVec([(0, _scval.nativeToScVal)('Balance', {
+            type: 'symbol'
+          }), (0, _scval.nativeToScVal)(destination, {
+            type: 'address'
+          })]),
+          durability: _xdr["default"].ContractDataDurability.persistent()
+        })));
+        if (!isAssetNative) {
+          footprint.readOnly().push(_xdr["default"].LedgerKey.account(new _xdr["default"].LedgerKeyAccount({
+            accountId: _keypair.Keypair.fromPublicKey(asset.getIssuer()).xdrPublicKey()
+          })));
+        }
+      } else if (isAssetNative) {
+        footprint.readWrite().push(_xdr["default"].LedgerKey.account(new _xdr["default"].LedgerKeyAccount({
+          accountId: _keypair.Keypair.fromPublicKey(destination).xdrPublicKey()
+        })));
+      } else if (asset.getIssuer() !== destination) {
+        footprint.readWrite().push(_xdr["default"].LedgerKey.trustline(new _xdr["default"].LedgerKeyTrustLine({
+          accountId: _keypair.Keypair.fromPublicKey(destination).xdrPublicKey(),
+          asset: asset.toTrustLineXDRObject()
+        })));
+      }
+
+      // Ledger entries for the source account
+      if (asset.isNative()) {
+        footprint.readWrite().push(_xdr["default"].LedgerKey.account(new _xdr["default"].LedgerKeyAccount({
+          accountId: _keypair.Keypair.fromPublicKey(source).xdrPublicKey()
+        })));
+      } else if (asset.getIssuer() !== source) {
+        footprint.readWrite().push(_xdr["default"].LedgerKey.trustline(new _xdr["default"].LedgerKeyTrustLine({
+          accountId: _keypair.Keypair.fromPublicKey(source).xdrPublicKey(),
+          asset: asset.toTrustLineXDRObject()
+        })));
+      }
+      var defaultPaymentFees = {
+        instructions: 400000,
+        readBytes: 1000,
+        writeBytes: 1000,
+        resourceFee: BigInt(5000000)
+      };
+      var sorobanData = new _xdr["default"].SorobanTransactionData({
+        resources: new _xdr["default"].SorobanResources({
+          footprint: footprint,
+          instructions: sorobanFees ? sorobanFees.instructions : defaultPaymentFees.instructions,
+          diskReadBytes: sorobanFees ? sorobanFees.readBytes : defaultPaymentFees.readBytes,
+          writeBytes: sorobanFees ? sorobanFees.writeBytes : defaultPaymentFees.writeBytes
+        }),
+        ext: new _xdr["default"].SorobanTransactionDataExt(0),
+        resourceFee: new _xdr["default"].Int64(sorobanFees ? sorobanFees.resourceFee : defaultPaymentFees.resourceFee)
+      });
+      var operation = _operation.Operation.invokeContractFunction({
+        contract: contractId,
+        "function": functionName,
+        args: args,
+        auth: [auths]
+      });
+      this.setSorobanData(sorobanData);
+      return this.addOperation(operation);
+    }
+
+    /**
      * This will build the transaction.
@@ -617,2 +774,4 @@ * It will also increment the source account's sequence number by 1.
         attrs.ext = new _xdr["default"].TransactionExt(1, this.sorobanData);
+        // Soroban transactions pay the resource fee in addition to the regular fee, so we need to add it here.
+        attrs.fee = new _bignumber["default"](attrs.fee).plus(this.sorobanData.resourceFee()).toNumber();
       } else {
@@ -703,3 +862,2 @@ // @ts-ignore
       var minBaseFee = new _bignumber["default"](BASE_FEE);
-      var innerInclusionFee = new _bignumber["default"](innerTx.fee).div(innerOps);
       var resourceFee = new _bignumber["default"](0);
@@ -716,3 +874,2 @@
             resourceFee = new _bignumber["default"]((_sorobanData$resource = sorobanData === null || sorobanData === void 0 ? void 0 : sorobanData.resourceFee()) !== null && _sorobanData$resource !== void 0 ? _sorobanData$resource : 0);
-            innerInclusionFee = _bignumber["default"].max(minBaseFee, innerInclusionFee.minus(resourceFee));
             break;
@@ -723,2 +880,3 @@ }
       }
+      var innerInclusionFee = new _bignumber["default"](innerTx.fee).minus(resourceFee).div(innerOps);
       var base = new _bignumber["default"](baseFee);
@@ -725,0 +883,0 @@

package.json

 {
   "name": "@stellar/stellar-base",
-  "version": "14.0.4",
+  "version": "14.1.0",
   "description": "Low-level support library for the Stellar network.",
@@ -5,0 +5,0 @@ "main": "./lib/index.js",

README.md

@@ -6,3 +6,3 @@ # JS Stellar Base
 [![Coverage Status](https://coveralls.io/repos/stellar/js-stellar-base/badge.svg?branch=master&service=github)](https://coveralls.io/github/stellar/js-stellar-base?branch=master)
-[![Dependency Status](https://david-dm.org/stellar/js-stellar-base.svg)](https://david-dm.org/stellar/js-stellar-base)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/stellar/js-stellar-base)
 
@@ -58,3 +58,3 @@ The stellar-base library is the lowest-level stellar helper library. It consists
 ```js
-var StellarBase = require('@stellar/stellar-base');
+var StellarBase = require("@stellar/stellar-base");
 ```
@@ -103,11 +103,11 @@
 
-1. Install Node 18.x
+1. Install Node 20.x
 
-We support the oldest LTS release of Node, which is [currently 18.x](https://nodejs.org/en/about/releases/). Please likewise install and develop on Node 16 so you don't get surprised when your code works locally but breaks in CI.
+We support the oldest LTS release of Node, which is [currently 20.x](https://nodejs.org/en/about/releases/).
 
 If you work on several projects that use different Node versions, you might find helpful to install a NodeJS version manager:
 
-  - https://github.com/creationix/nvm
-  - https://github.com/wbyoung/avn
-  - https://github.com/asdf-vm/asdf
+- https://github.com/creationix/nvm
+- https://github.com/wbyoung/avn
+- https://github.com/asdf-vm/asdf
 
@@ -146,6 +146,2 @@ 2. Install Yarn
 
-If you're working on a file not in `src`, limit your code to Node 6.16 ES! See
-what's supported here: https://node.green/. (Our npm library must support
-earlier versions of Node, so the tests need to run on those versions.)
-
 #### Updating XDR definitions
@@ -162,6 +158,8 @@
 6. Add generator workarounds:
-  * `type Hash = Opaque[]` is a necessary alias that doesn't get generated
-  * `Hyper`, `UnsignedHyper`, and `ScSpecEventV0` need their signatures
-    fixed because linting wants an `Array` instead of a naked `[]`.
-  * Some constants aren't generated correctly (e.g, Ctrl+F `SCSYMBOL_LIMIT` in `src/curr_generated.js`)
+
+- `type Hash = Opaque[]` is a necessary alias that doesn't get generated
+- `Hyper`, `UnsignedHyper`, and `ScSpecEventV0` need their signatures
+  fixed because linting wants an `Array` instead of a naked `[]`.
+- Some constants aren't generated correctly (e.g, Ctrl+F `SCSYMBOL_LIMIT` in `src/curr_generated.js`)
+
 7. Finally, make code adjustments related to the XDR (these are usually revealed by running the tests).
@@ -168,0 +166,0 @@

types/index.d.ts

@@ -1065,2 +1065,13 @@ // TypeScript Version: 2.9
 
+/**
+ * Represents the fees associated with a Soroban transaction, including the number of instructions executed,
+ * the number of bytes read and written to the ledger, and the total resource fee in stroops.
+ */
+export interface SorobanFees {
+  instructions: number; 
+  readBytes: number;
+  writeBytes: number;
+  resourceFee: bigint;
+}
+
 export class TransactionBuilder {
@@ -1084,2 +1095,15 @@ constructor(
   setSorobanData(sorobanData: string | xdr.SorobanTransactionData): this;
+  /**
+   * Creates and adds an invoke host function operation for transferring SAC tokens.
+   * This method removes the need for simulation by handling the creation of the
+   * appropriate authorization entries and ledger footprint for the transfer operation.
+   *
+   * @param destination - the address of the recipient of the SAC transfer (should be a valid Stellar address or contract ID)
+   * @param asset - the SAC asset to be transferred
+   * @param amount - the amount of tokens to be transferred in 7 decimals. IE 1 token with 7 decimals of precision would be represented as "1_0000000"
+   * @param sorobanFees - optional Soroban fees for the transaction to override the default fees used
+   *
+   * @returns the TransactionBuilder instance with the SAC transfer operation added
+   */
+  addSacTransferOperation(destination: string, asset: Asset, amount: string | bigint, sorobanFees?: SorobanFees): this;
   build(): Transaction;
@@ -1086,0 +1110,0 @@ setNetworkPassphrase(networkPassphrase: string): this;

No alert changes

Improved metrics

Lines of code

79072

0.35%

Worsened metrics

Total package byte prevSize

3791718

-1.44%

Number of package files

81

-1.22%

Number of lines in readme file

211

-0.94%

No dependency changes