feat!: export `ContractClient` et al. in `contract`; rename `SorobanRpc` to `rpc`

[chadoh]

Breaking Changes

• ContractClient functionality previously added in v11.3.0 was exported in a non-standard way. You can now import it as any other stellar-sdk module.

  - import { ContractClient } from '@stellar/stellar-sdk/lib/contract_client'
  + import { contract } from '@stellar/stellar-sdk'
  + const { Client } = contract

  Note that this top-level contract export is a container for ContractClient and related functionality. The ContractClient class is now available at contract.Client, as shown. Further note that there is a capitalized Contract export as well, which comes from stellar-base. You can remember which is which because capital-C Contract is a class, whereas lowercase-c contract is a container/module with a bunch of classes, functions, and types.

  Additionally, this is available from the /contract entrypoint, if your version of Node and TypeScript support the exports declaration. Finally, some of its exports have been renamed.

  import {
  -  ContractClient,
  +  Client,
   AssembledTransaction,
  -  ContractClientOptions,
  +  ClientOptions,
   SentTransaction,
  -} from '@stellar/stellar-sdk/lib/contract_client'
  +} from '@stellar/stellar-sdk/contract'

• The ContractSpec class is now nested under the contract module, and has been renamed to Spec.

  -import { ContractSpec } from '@stellar/stellar-sdk'
  +import { contract } from '@stellar/stellar-sdk'
  +const { Spec } = contract

  Alternatively, you can import this from the contract entrypoint, if your version of Node and TypeScript support the exports declaration.

  -import { ContractSpec } from '@stellar/stellar-sdk'
  +import { Spec } from '@stellar/stellar-sdk/contract'

• Previously, AssembledTransaction.signAndSend() would return a SentTransaction even if the transaction never finalized. That is, if it successfully sent the transaction to the network, but the transaction was still status: 'PENDING', then it would console.error an error message, but return the indeterminate transaction anyhow.

  It now throws a SentTransaction.Errors.TransactionStillPending error with that error message instead.

Deprecated

• SorobanRpc module is now also exported as rpc. You can import it with either name for now, but SorobanRpc will be removed in a future release.

  import { SorobanRpc } from '@stellar/stellar-sdk'
  +// OR
  +import { rpc } from '@stellar/stellar-sdk'

  You can also now import it at the /rpc entrypoint, if your version of Node and TypeScript support the exports declaration.

  -import { SorobanRpc } from '@stellar/stellar-sdk'
  -const { Api } = SorobanRpc
  +import { Api } from '@stellar/stellar-sdk/rpc'

Other

• This PR started as an attempt to appease eslint for the contract directory (previously the contract_client directory). While this turned out to be a bit premature (given that much other code in this repo doesn't pass our eslint rules), it's still nice cleanup. That's why you'll see .eslintrc.js changes and related code updates. Some notes on all this:
  • We had .eslintrc.js, src/.eslintrc.js, and src/soroban/.eslintrc.js. The second two were very similar. I made them identical and removed the more deeply nested one.
  • We have all TypeScript in src, but were only using Airbnb's non-TypeScript recommended settings. They recommend using both, for TypeScript projects. That's what I've done.
  • The valid-jsdoc rule was deprecated. They now recommend using the eslint-plugin-jsdoc. I've done that, and extended their recommended rules. I've overridden some rules. For example, I researched and found that documenting function params with @param doesn't actually show up in your in-editor typeahead/mouseover. So I turned off the rule that requires these. We should prefer TSDoc for params instead. I've added these throughout.
• I attempted to add some JSDoc comments to the export * as blah from 'whatever' lines in src/index.ts. These don't actually show up when you import these objects. We will need to research this more when we do a larger module reorganization later. For now, they're useful notes.

[socket-security[bot]]

🚨 Potential security issues detected. Learn more about Socket for GitHub ↗︎

To accept the risk, merge this PR and you will not be notified again.

Alert	Package	Note	Source
Debug access	npm/builtin-modules@3.3.0	Module: module Location: Package overview	package.json
Filesystem access	npm/eslint-plugin-jsdoc@48.2.4	Module: fs Location: Package overview	package.json

View full report↗︎

Next steps

What is debug access?

Uses debug, reflection and dynamic code execution features.

Removing the use of debug will reduce the risk of any reflection and dynamic code execution.

What is filesystem access?

Accesses the file system, and could potentially read sensitive data.

If a package must read the file system, clarify what it will read and ensure it reads only what it claims to. If appropriate, packages can leave file system access to consumers and operate on data passed to it instead.

Take a deeper look at the dependency

Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support [AT] socket [DOT] dev.

Remove the package

If you happen to install a dependency that Socket reports as Known Malware you should immediately remove it and select a different dependency. For other alert types, you may may wish to investigate alternative packages or consider if there are other ways to mitigate the specific risk posed by the dependency.

Mark a package as acceptable risk

To ignore an alert, reply with a comment starting with @SocketSecurity ignore followed by a space separated list of ecosystem/package-name@version specifiers. e.g. @SocketSecurity ignore npm/foo@1.0.0 or ignore all packages with @SocketSecurity ignore-all

• @SocketSecurity ignore npm/builtin-modules@3.3.0
• @SocketSecurity ignore npm/eslint-plugin-jsdoc@48.2.4

[chadoh]

Didn't realize just how unhappy ESLint is with basically all the code in this repo 🤔

I saw that src/.eslintrc.js and src/soroban/.eslintrc.js were basically duplicates of each other. I tweaked them to match (removed the no-unused-vars setting, to make that an error case, which seems like what we actually want? One had been set to warn and the other had disabled it.), then removed src/soroban/.eslintrc.js.

I also fixed some config issues that I introduced earlier, so you can lint the whole repo again. And find that we have:

2081 problems (1063 errors, 1018 warnings)

¯\_(ツ)_/¯

Good enough for now, I guess??

[chadoh]

I've confirmed that the new entrypoints are usable from the TS Bindings code in the CLI:

• https://github.com/stellar/soroban-cli/pull/1326

I think we need to make sure we like the new module organization and then we're good to go. The current reorganization is explained in the changelog entry. The gist:

• Add new ContractClient exported module, along with @stellar/stellar-sdk/ContractClient entrypoint
• Move ContractSpec to ContractClient.Spec, which can be imported as

  import { Spec } from '@stellar/stellar-sdk/ContractClient'

• Keep SorobanRpc as-is, though it is also now also exported as just Rpc, and is also available from its own entrypoint:

  import { Api } from '@stellar/stellar-sdk/Rpc'

Happy to roll this third thing back for now, since it's sort of irrelevant to the current change. I just wanted to see if it was possible, and it's a non-breaking change that could help us think through how to do a larger module reorganization after the next release is out.

[socket-security[bot]]

New dependencies detected. Learn more about Socket for GitHub ↗︎

Package	New capabilities	Transitives	Size	Publisher
npm/eslint-config-airbnb-typescript@18.0.0	Transitive: filesystem	+14	5.38 MB	iamturns
npm/eslint-plugin-jsdoc@48.2.4	filesystem Transitive: unsafe	+11	2.77 MB	gajus

View full report↗︎