Update misc. documentation and jsdocs (#720)

* Add guidance around versioning deprecation

.github/workflows/npm_publish.yml

@@ -32,6 +32,6 @@ jobs:
 
       - name: Deprecate the old package
         run: |
-          npm deprecate stellar-base@latest "⚠️ This package has moved to @stellar/stellar-base! 🚚"
+          npm deprecate stellar-base@"<= 10.0.1" "⚠️ This package has moved to @stellar/stellar-base! 🚚"
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

CONTRIBUTING.md

@@ -22,6 +22,8 @@ Once all of the PRs for a particular release are in, it's time to actually publi
 
  - [ ] Ensure that all of the PRs in this delta are accurately reflected in the [CHANGELOG](./CHANGELOG.md), broken down by impact and linking to the corresponding PRs. Update the file if necessary.
 
+ - [ ] Ensure that the version being deprecated in the `npm_publish.yml` Action matches the latest `package.json` version: we want to ensure everything in `stellar-base` gets deprecated, but `@stellar/stellar-base` is not.
+
  - [ ] Run `yarn preversion` to build and test an optimized bundle and ensure Typescript compatibility (one of the most common sources of bugs, since this library is written purely in JS but must be usable from TS).
 
  - [ ] Run `yarn version` to update the version number in the package.json (or modify the `"version"` field manually).

README.md

@@ -27,7 +27,7 @@ implementation in JavaScript that can be used on either Node.js or web browsers.
 Using yarn to include js-stellar-base in your own project:
 
 ```shell
-yarn add stellar-base
+yarn add @stellar/stellar-base
 ```
 
 For browsers, [use Bower to install it](#to-use-in-the-browser). It exports a

docs/readme.md

@@ -4,9 +4,7 @@ title: Getting Started
 
 # Overview
 
-The js-stellar-base library is the lowest-level stellar helper library. It can be used in a browser or in node.js. It is mainly used to read, create and
-sign [transactions](https://developers.stellar.org/docs/glossary/transactions/). This library is used and exposed by
-[js-stellar-sdk](https://github.com/stellar/js-stellar-sdk) but you can use it by itself if you don't need to communicate with Horizon.
+The js-stellar-base library is the lowest-level stellar helper library. It can be used in a browser or in node.js. It is mainly used to read, create, and sign [transactions](https://developers.stellar.org/docs/glossary/transactions/). This library is used and exposed by [stellar-sdk](https://github.com/stellar/js-stellar-sdk) but you can use it by itself if you don't need to communicate with Horizon.
 
 * [Building and Installing](../README.md) js-stellar-base
 * [Building Transactions](./reference/building-transactions.md)

src/auth.js

@@ -59,7 +59,12 @@ import { nativeToScVal } from './scval';
  *
  * @see authorizeInvocation
  * @example
- * import { Server, Transaction, Networks, authorizeEntry } from 'soroban-client';
+ * import {
+ *   SorobanRpc,
+ *   Transaction,
+ *   Networks,
+ *   authorizeEntry
+ * } from '@stellar/stellar-sdk';
  *
  * // Assume signPayloadCallback is a well-formed signing callback.
  * //
@@ -71,7 +76,7 @@ import { nativeToScVal } from './scval';
  * }
  *
  * function multiPartyAuth(
- *    server: Server,
+ *    server: SorobanRpc.Server,
  *    // assume this involves multi-party auth
  *    tx: Transaction,
  * ) {
@@ -83,10 +88,10 @@ import { nativeToScVal } from './scval';
  *              entry,
  *              signPayloadCallback,
  *              currentLedger + 1000,
- *              Networks.FUTURENET);
+ *              Networks.TESTNET);
  *          ));
  *
- *          return server.prepareTransaction(tx, Networks.FUTURENET, simResult);
+ *          return server.prepareTransaction(tx, simResult);
  *      })
  *      .then((preppedTx) => {
  *        preppedTx.sign(source);

src/invocation.js

@@ -58,7 +58,7 @@ import { scValToNative } from './scval';
  * `tx`, which we assume has an `Operation.invokeHostFunction` inside of it:
  *
  * ```typescript
- * import { Server, buildInvocationTree } from 'soroban-client';
+ * import { Server, buildInvocationTree } from '@stellar/stellar-sdk';
  *
  * const s = new Server("fill in accordingly");
  *

src/operations/extend_footprint_ttl.js

@@ -1,9 +1,9 @@
 import xdr from '../xdr';
 
 /**
- * Builds an operation to bump the expiration of a footprint (read and written
- * ledger keys). Its only parameter is the number of ledgers to extend
- * expiration for.
+ * Builds an operation to bump the time-to-live of a footprint (read and written
+ * ledger keys). Its only parameter is the new, absolute ledger sequence number
+ * at which the entry will expire.
  *
  * The footprint itself is derived from the transaction (see
  * {@link TransactionBuilder}'s `opts.sorobanData` parameter, which is a
@@ -14,12 +14,11 @@ import xdr from '../xdr';
  * @alias Operation.extendFootprintTtl
  *
  * @param {object} opts - object holding operation parameters
- * @param {number} opts.extendTo - the number of ledgers past the LCL
- *    (last closed ledger) by which to extend the validity of the ledger keys in
- *    this transaction
+ * @param {number} opts.extendTo - the absolute ledger sequence number at which
+ *     the transaction's ledger keys will now expire
  * @param {string} [opts.source] - an optional source account
  *
- * @returns {xdr.Operation} a Bump Footprint Expiration operation
+ * @returns {xdr.Operation} an Extend Footprint TTL operation
  *    (xdr.ExtendFootprintTTLOp)
  */
 export function extendFootprintTtl(opts) {

src/scval.js

@@ -101,7 +101,12 @@ import { ScInt, XdrLargeInt, scValToBigInt } from './numbers/index';
  * // ]
  *
  * @example
- * import { nativeToScVal, scValToNative, ScInt, xdr } from 'stellar-base';
+ * import {
+ *   nativeToScVal,
+ *   scValToNative,
+ *   ScInt,
+ *   xdr
+ * } from '@stellar/stellar-base';
  *
  * let gigaMap = {
  *   bool: true,

src/transaction_builder.js

@@ -51,7 +51,7 @@ export const TimeoutInfinite = 0;
  * source account.</p>
  *
  * <p><strong>Be careful about unsubmitted transactions!</strong> When you build
- * a transaction, stellar-sdk automatically increments the source account's
+ * a transaction, `stellar-sdk` automatically increments the source account's
  * sequence number. If you end up not submitting this transaction and submitting
  * another one instead, it'll fail due to the sequence number being wrong. So if
  * you decide not to use a built transaction, make sure to update the source