Adds Protocol 20 (Soroban) support to the XDR and API.

.github/workflows/bundle_size.yml

@@ -0,0 +1,30 @@
+name: Bundle Size
+
+on:
+ pull_request:
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+
+ - name: Install Node.js 16
+ uses: actions/setup-node@v3
+ with:
+ node-version: 16
+
+ # Workaround for some `yarn` nonsense, see:
+ # https://github.com/yarnpkg/yarn/issues/6312#issuecomment-429685210
+ - name: Install Dependencies
+ run: yarn install --network-concurrency 1
+
+ - name: Build All
+ run: yarn build:prod
+
+ - name: Report Bundle Size
+ uses: preactjs/compressed-size-action@v2
+ with:
+ repo-token: ${{ secrets.GITHUB_TOKEN }}
+ pattern: "dist/*.js"
+ compression: "none"

.github/workflows/gh_pages.yml

@@ -12,10 +12,10 @@ jobs:
  with:
  fetch-depth: 0
 
- - name: Install Node (14.x)
+ - name: Install Node (16.x)
  uses: actions/setup-node@v3
  with:
- node-version: '14.x'
+ node-version: 16
 
  - name: Install Dependencies
  run: yarn install

.github/workflows/npm_publish.yml

@@ -13,7 +13,7 @@ jobs:
  - name: Install Node
  uses: actions/setup-node@v3
  with:
- node-version: '14.x'
+ node-version: 16
  registry-url: 'https://registry.npmjs.org'
 
  - name: Install Depencencies
@@ -22,7 +22,7 @@ jobs:
  - name: Test & Build
  run: yarn preversion
 
- - name: Publish npm package
- run: yarn publish
+ - name: Publish release npm package
+ run: yarn publish --tag beta
  env:
  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/tests.yml

@@ -13,7 +13,7 @@ jobs:
  fail-fast: false
  max-parallel: 4
  matrix:
- node-version: [14, 16, 18]
+ node-version: [16, 18, 20]
 
  steps:
  - name: Checkout
@@ -29,9 +29,6 @@ jobs:
  - name: Install Dependencies
  run: yarn install --network-concurrency 1
 
- - name: Run Linter
- run: yarn lint
-
  - name: Build All
  run: yarn build:prod
 
@@ -40,3 +37,6 @@ jobs:
 
  - name: Run Browser Tests
  run: yarn test:browser
+
+ - name: Run Linter Checks
+ run: yarn fmt && yarn lint && (git diff-index --quiet HEAD; git diff)

.gitignore

@@ -4,6 +4,7 @@
 /tmp/
 /dist/
 /config/dist/
+/lib/
 /coverage/
 /jsdoc/
 .DS_Store

CHANGELOG.md

@@ -4,6 +4,39 @@
 ## Unreleased
 
 
+## [`v10.0.0-beta.0`](https://github.com/stellar/js-stellar-base/compare/v9.0.0...v10.0.0-beta.0): Protocol 20
+
+### Breaking Changes
+ * **Node 16 is the new minimum version** to use the SDKs.
+ * The XDR has been massively overhauled to support [Soroban in Protocol 20](https://soroban.stellar.org/docs/category/fundamentals-and-concepts), which means new operations, data structures, and a transaction format as well as new overlay features ([#538](https://github.com/stellar/js-stellar-base/pull/538)).
+
+The core data structure of Soroban is a generic type called an `ScVal` (**s**mart **c**ontract **val**ue, which is a union of types that can basically represent anything [numbers, strings, arrays, maps, contract bytecode, etc.]). You can refer to the XDR for details, and you can utilize new APIs to make dealing with these complex values easier:
+ - `nativeToScVal` helps convert native types to their closest Soroban equivalent
+ - `scValToNative` helps find the closest native JavaScript type(s) corresponding to a smart contract value
+ - `scValToBigInt` helps convert numeric `ScVal`s into native `bigint`s
+ - `ScInt` and `XdrLargeInt` help convert to and from `bigint`s to other types and form sized integer types for smart contract usage
+
+### Added
+The following are new APIs to deal with new Soroban constructs:
+ - **`Address`, which helps manage "smart" addresses in the Soroban context.** Addresses there (used for auth and identity purposes) can either be contracts (strkey `C...`) or accounts (strkey `G...`). This abstraction helps manage them and distinguish between them easily.
+ - **`Contract`, which helps manage contract identifiers.** The primary purpose is to build invocations of its methods via the generic `call(...)`, but it also provides utilities for converting to an `Address` or calculating its minimum footprint for state expiration.
+ - **Three new operations** have been added related to Soroban transactions:
+ * `invokeHostFunction` for calling contract code
+ * `bumpFootprintExpiration` for extending the state lifetime of Soroban data
+ * `restoreFootprint` for restoring expired, off-chain state back onto the ledger
+ - The `TransactionBuilder` now takes a `sorobanData` parameter (and has a corresponding `.setSorobanData()` builder method) which primarily describes the storage footprint of a Soroban (that is, which parts of the ledger state [in the form of `xdr.LedgerKey`s] it plans to read and write as part of the transaction).
+ * To facilitate building this out, there's a new `SorobanDataBuilder` factory to set fields individually
+ - The `TransactionBuilder` now has a `cloneFrom(tx, opts)` constructor method to create an instance from an existing transaction, also allowing parameter overrides via `opts`.
+ - The following are convenience methods for building out certain types of smart contract-related structures:
+ * `buildInvocationTree` and `walkInvocationTree` are both ways to visualize invocation calling trees better
+ * `authorizeInvocation` helps multiple parties sign invocation calling trees
+ * `humanizeEvents` helps make diagnostic events more readable
+ - We've added a GHA to track bundle size changes as PRs are made. This protocol upgrade adds +18% to the final, minified bundle size which is significant but acceptable given the size of the upgrade.
+
+### Fixes
+* Improves the error messages when passing invalid amounts to deposit and withdraw operations ([#679](https://github.com/stellar/js-stellar-base/pull/679)).
+
+
 ## [v9.0.0](https://github.com/stellar/js-stellar-base/compare/v8.2.2..v9.0.0)
 
 This is a large update and the following changelog incorporates ALL changes across the `beta.N` versions of this upgrade.
@@ -15,7 +48,6 @@ The browser bundle size has decreased **significantly**:
  * `stellar-base.min.js` is **340 KiB**, down from **1.2 MiB** previously.
  * the new, unminified `stellar-base.js` is **895 KiB**.
 
-
 ### Breaking Changes
 
 - The build system has been completely overhauled to support Webpack 5 ([#584](https://github.com/stellar/js-stellar-base/pull/584), [#585](https://github.com/stellar/js-stellar-base/pull/585)).

Makefile

@@ -1,15 +1,20 @@
-XDR_BASE_URL_CURR=https://github.com/stellar/stellar-xdr/raw/curr
+XDR_BASE_URL_CURR=https://github.com/stellar/stellar-xdr/raw/9ac02641139e6717924fdad716f6e958d0168491
 XDR_BASE_LOCAL_CURR=xdr/curr
 XDR_FILES_CURR= \
  Stellar-SCP.x \
  Stellar-ledger-entries.x \
  Stellar-ledger.x \
  Stellar-overlay.x \
  Stellar-transaction.x \
- Stellar-types.x
+ Stellar-types.x \
+ Stellar-contract.x \
+ Stellar-contract-env-meta.x \
+ Stellar-contract-meta.x \
+ Stellar-contract-spec.x \
+ Stellar-contract-config-setting.x
 XDR_FILES_LOCAL_CURR=$(addprefix xdr/curr/,$(XDR_FILES_CURR))
 
-XDR_BASE_URL_NEXT=https://github.com/stellar/stellar-xdr/raw/next
+XDR_BASE_URL_NEXT=https://github.com/stellar/stellar-xdr/raw/440dc9512b6e72cf84965641c5eb495d6043ed73
 XDR_BASE_LOCAL_NEXT=xdr/next
 XDR_FILES_NEXT= \
  Stellar-SCP.x \
@@ -20,7 +25,9 @@ XDR_FILES_NEXT= \
  Stellar-types.x \
  Stellar-contract.x \
  Stellar-contract-env-meta.x \
- Stellar-contract-spec.x
+ Stellar-contract-meta.x \
+ Stellar-contract-spec.x \
+ Stellar-contract-config-setting.x
 XDR_FILES_LOCAL_NEXT=$(addprefix xdr/next/,$(XDR_FILES_NEXT))
 
 XDRGEN_COMMIT=master
@@ -33,17 +40,17 @@ generate: src/generated/curr_generated.js types/curr.d.ts src/generated/next_gen
 src/generated/curr_generated.js: $(XDR_FILES_LOCAL_CURR)
  mkdir -p $(dir $@)
  > $@
- docker run -it --rm -v $$PWD:/wd -w /wd ruby /bin/bash -c '\
- gem install specific_install -v 0.3.7 && \
+ docker run -it --rm -v $$PWD:/wd -w /wd ruby:3.1 /bin/bash -c '\
+ gem install specific_install -v 0.3.8 && \
  gem specific_install https://github.com/stellar/xdrgen.git -b $(XDRGEN_COMMIT) && \
  xdrgen --language javascript --namespace curr --output src/generated $^ \
  '
 
 src/generated/next_generated.js: $(XDR_FILES_LOCAL_NEXT)
  mkdir -p $(dir $@)
  > $@
- docker run -it --rm -v $$PWD:/wd -w /wd ruby /bin/bash -c '\
- gem install specific_install -v 0.3.7 && \
+ docker run -it --rm -v $$PWD:/wd -w /wd ruby:3.1 /bin/bash -c '\
+ gem install specific_install -v 0.3.8 && \
  gem specific_install https://github.com/stellar/xdrgen.git -b $(XDRGEN_COMMIT) && \
  xdrgen --language javascript --namespace next --output src/generated $^ \
  '
@@ -53,7 +60,7 @@ types/curr.d.ts: src/generated/curr_generated.js
  apk add --update git && \
  git clone --depth 1 https://github.com/stellar/dts-xdr -b $(DTSXDR_COMMIT) --single-branch && \
  cd /dts-xdr && \
- yarn install && \
+ yarn install --network-concurrency 1 && \
  OUT=/wd/$@ npx jscodeshift -t src/transform.js /wd/$< && \
  cd /wd && \
  yarn run prettier --write /wd/$@ \
@@ -64,7 +71,7 @@ types/next.d.ts: src/generated/next_generated.js
  apk add --update git && \
  git clone --depth 1 https://github.com/stellar/dts-xdr -b $(DTSXDR_COMMIT) --single-branch && \
  cd /dts-xdr && \
- yarn install && \
+ yarn install --network-concurrency 1 && \
  OUT=/wd/$@ npx jscodeshift -t src/transform.js /wd/$< && \
  cd /wd && \
  yarn run prettier --write /wd/$@ \
@@ -83,6 +90,7 @@ $(XDR_FILES_LOCAL_NEXT):
 
 reset-xdr:
  rm -f xdr/*/*.x
+ rm -f src/generated/*.js
  rm -f types/curr.d.ts
  rm -f types/next.d.ts
  $(MAKE) generate

README.md

@@ -98,9 +98,9 @@ Make sure that you are using the latest version number. They can be found on the
 
 ### To develop and test js-stellar-base itself
 
-1. Install Node 14.x
+1. Install Node 16.x
 
-We support the oldest LTS release of Node, which is [currently 14.x](https://nodejs.org/en/about/releases/). Please likewise install and develop on Node 14 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 16.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.
 
 If you work on several projects that use different Node versions, you might find helpful to install a NodeJS version manager:
 

config/.eslintrc.js

@@ -1,6 +1,7 @@
 module.exports = {
  env: {
- es6: true
+ es6: true,
+ es2020: true
  },
  extends: ['airbnb-base', 'prettier'],
  plugins: ['@babel', 'prettier', 'prefer-import'],

config/webpack.config.browser.js

@@ -14,7 +14,6 @@ const config = {
  },
  resolve: {
  fallback: {
- crypto: require.resolve('crypto-browserify'),
  stream: require.resolve('stream-browserify'),
  buffer: require.resolve('buffer')
  },

package.json

@@ -1,9 +1,12 @@
 {
  "name": "stellar-base",
- "version": "9.0.0",
+ "version": "10.0.0-beta.0",
  "description": "Low-level support library for the Stellar network.",
  "main": "./lib/index.js",
- "browser": "./dist/stellar-base.min.js",
+ "browser": {
+ "main": "./dist/stellar-base.min.js",
+ "sodium-native": false
+ },
  "types": "./types/index.d.ts",
  "scripts": {
  "build": "yarn build:node && yarn build:browser",
@@ -13,14 +16,15 @@
  "build:browser:prod": "cross-env NODE_ENV=production yarn build:browser",
  "build:prod": "cross-env NODE_ENV=production yarn build",
  "test": "yarn build && yarn test:node && yarn test:browser",
- "test:node": "nyc --nycrc-path ./config/.nycrc mocha",
+ "test:node": "yarn _nyc mocha",
  "test:browser": "karma start ./config/karma.conf.js",
  "docs": "jsdoc -c ./config/.jsdoc.json --verbose",
  "lint": "eslint -c ./config/.eslintrc.js src/ && dtslint --localTs node_modules/typescript/lib types/",
  "preversion": "yarn clean && yarn fmt && yarn lint && yarn build:prod && yarn test",
  "fmt": "prettier --config ./config/prettier.config.js --ignore-path ./config/.prettierignore --write './**/*.js'",
  "prepare": "yarn build:prod",
- "clean": "rm -rf lib/ dist/ coverage/ .nyc_output/"
+ "clean": "rm -rf lib/ dist/ coverage/ .nyc_output/",
+ "_nyc": "nyc --nycrc-path ./config/.nycrc"
  },
  "mocha": {
  "require": [
@@ -52,9 +56,6 @@
  "yarn lint"
  ]
  },
- "browser": {
- "sodium-native": false
- },
  "repository": {
  "type": "git",
  "url": "https://github.com/stellar/js-stellar-base.git"
@@ -69,60 +70,59 @@
  },
  "homepage": "https://github.com/stellar/js-stellar-base",
  "devDependencies": {
- "@babel/cli": "^7.21.0",
- "@babel/core": "^7.12.0",
- "@babel/eslint-parser": "^7.21.3",
- "@babel/eslint-plugin": "^7.19.1",
- "@babel/preset-env": "^7.21.4",
- "@babel/register": "^7.21.0",
- "@definitelytyped/dtslint": "^0.0.163",
+ "@babel/cli": "^7.22.15",
+ "@babel/core": "^7.22.17",
+ "@babel/eslint-parser": "^7.22.15",
+ "@babel/eslint-plugin": "^7.22.10",
+ "@babel/preset-env": "^7.22.15",
+ "@babel/register": "^7.22.15",
+ "@definitelytyped/dtslint": "^0.0.177",
  "@istanbuljs/nyc-config-babel": "3.0.0",
- "@types/node": "^20.1.4",
- "@typescript-eslint/parser": "^5.59.6",
- "babel-loader": "^9.1.2",
+ "@types/node": "^20.6.0",
+ "@typescript-eslint/parser": "^6.7.0",
+ "babel-loader": "^9.1.3",
  "babel-plugin-istanbul": "^6.1.1",
- "buffer": "^6.0.3",
- "chai": "^4.3.7",
+ "chai": "^4.3.8",
  "cross-env": "^7.0.3",
- "eslint": "^8.37.0",
+ "eslint": "^8.49.0",
  "eslint-config-airbnb-base": "^15.0.0",
- "eslint-config-prettier": "^8.8.0",
- "eslint-plugin-import": "^2.25.2",
+ "eslint-config-prettier": "^9.0.0",
+ "eslint-plugin-import": "^2.28.1",
  "eslint-plugin-node": "^11.1.0",
  "eslint-plugin-prefer-import": "^0.0.1",
- "eslint-plugin-prettier": "^4.2.1",
+ "eslint-plugin-prettier": "^5.0.0",
  "eslint-webpack-plugin": "^4.0.0",
  "ghooks": "^2.0.4",
  "husky": "^8.0.3",
  "jsdoc": "^4.0.2",
- "karma": "^6.4.1",
+ "karma": "^6.4.2",
  "karma-chrome-launcher": "^3.1.0",
- "karma-coverage": "^2.2.0",
+ "karma-coverage": "^2.2.1",
  "karma-firefox-launcher": "^2.1.1",
  "karma-mocha": "^2.0.0",
  "karma-sinon-chai": "^2.0.2",
  "karma-webpack": "^5.0.0",
- "lint-staged": "^13.2.0",
+ "lint-staged": "^14.0.1",
  "minami": "^1.1.1",
  "mocha": "^10.2.0",
  "node-polyfill-webpack-plugin": "^2.0.1",
  "nyc": "^15.1.0",
- "prettier": "^2.8.7",
+ "prettier": "^3.0.3",
  "randombytes": "^2.1.0",
  "sinon": "^15.0.3",
  "sinon-chai": "^3.7.0",
  "taffydb": "^2.7.3",
- "terser-webpack-plugin": "^5.3.7",
+ "terser-webpack-plugin": "^5.3.8",
  "ts-node": "^10.9.1",
- "typescript": "^5.0.3",
+ "typescript": "^5.2.2",
  "webpack": "^5.82.1",
  "webpack-cli": "^5.1.1"
  },
  "dependencies": {
  "base32.js": "^0.1.0",
- "bignumber.js": "^9.1.1",
- "crypto-browserify": "^3.12.0",
- "js-xdr": "^2.0.0",
+ "bignumber.js": "^9.1.2",
+ "buffer": "^6.0.3",
+ "js-xdr": "^3.0.0",
  "sha.js": "^2.3.6",
  "tweetnacl": "^1.0.3"
  },