Update docs and minor adjustments to jsdocs

README.md

@@ -1,20 +1,30 @@
-
 # Stellar-Plus
+
 <p align="center">
   <a href="https://badge.fury.io/js/stellar-plus"><img src="https://badge.fury.io/js/stellar-plus.svg" alt="npm version" height="18"></a>
   <a href="https://www.npmjs.com/package/stellar-sdk">
     <img alt="Weekly Downloads" src="https://img.shields.io/npm/dw/stellar-plus" />
   </a>
 </p>
-stellar-plus is an all-in-one Javascript library for building and interacting with the Stellar network. It bundles the main resources from the community into an easy-to-use set of tools and capabilities.
 
-It provides:
+<figure>
+  <picture>
+    <source srcset="docs/.gitbook/assets/logo2.png" media="(prefers-color-scheme: dark)">
+    <img src="docs/.gitbook/assets/logo2.png" alt="" width="375" style="display: block; margin: 0 auto;">
+  </picture>
+  <figcaption></figcaption>
+</figure>
+
+Stellar-plus is a robust JavaScript library built by [Cheesecake Labs](./) and designed to streamline the development of applications on the Stellar network. By integrating the Stellar community's primary resources, Stellar-plus offers developers an efficient, easy-to-use toolkit. This library simplifies the complexities of Stellar network interaction, making it accessible for both novice and experienced developers alike.
 
-* **Account**: Handlers to create, load, and interact with stellar accounts, managing signatures and automatically integrating with Freighter Wallet for web applications.
-* **Asset**: Classic token handlers follow the standard token interface for triggering different asset capabilities as well as a suite of additional features for asset management and usage.
-* **Core**: Key engines for managing the different pipelines for building, submitting, and processing both Classic and Soroban transactions. These engines can be extended into your own tooling or used out-of-the-box with minimal configuration.
-* **Contracts**: Default contract client implementations for selected dApp use cases.
-* **RPC**: Handlers for connecting and using different RPC solutions, including a ready-to-use integration with Validation Cloud's RPC API.
+## Features
+
+- **Account Handling**: Seamless management of signatures throughout the transaction lifecycle.
+- **Asset Management**: Full suite of asset management capabilities, including standard and custom assets.
+- **Core Engines**: Essential for building, submitting, signing, and processing transactions on the Stellar network.
+- **Contract Development**: Simplifies the development of decentralized applications (dApps).
+- **RPC Integration**: Connects to and leverages various RPC services for a broader range of applications.
+- **Plugins and Extensions**: Supports plugins and tools to enhance functionality and tailor the library to specific needs.
 
 ## Quick start
 
@@ -35,15 +45,19 @@ npm install --save stellar-plus
 require/import it in your JavaScript:
 
 ```js
-var StellarPlus = require("stellar-plus");
+var StellarPlus = require('stellar-plus')
 ```
 
 or
 
 ```js
-import { StellarPlus } from "stellar-plus";
+import { StellarPlus } from 'stellar-plus'
 ```
 
 ## Documentation
 
 For the full documentation, refer to our [Gitbook Documentation](https://cheesecake-labs.gitbook.io/stellar-plus/?utm_source=github&utm_medium=codigo-fonte).
+
+- [Code of Conduct](https://github.com/cheesecakelabs/stellar-plus/blob/main/CODE_OF_CONDUCT.md)
+- [Contributing Guidelines](https://github.com/cheesecakelabs/stellar-plus/blob/main/CONTRIBUTING.md)
+- [MIT License](https://github.com/cheesecakelabs/stellar-plus/blob/main/LICENSE)

src/stellar-plus/account/account-handler/freighter/index.ts

@@ -128,7 +128,7 @@ export class FreighterAccountHandlerClient extends AccountBaseClient implements
    *
    * @param {xdr.SorobanAuthorizationEntry} entry - The soroban authorization entry to sign.
    * @param {number} validUntilLedgerSeq - The ledger sequence number until which the entry signature is valid.
-   *
+   * @param {string} networkPassphrase - The network passphrase for the network to sign the entry for.
    * @description - Signs the given Soroban authorization entry with the account's secret key.
    *
    * @returns {xdr.SorobanAuthorizationEntry} The signed entry.

src/stellar-plus/account/base/index.ts

@@ -8,7 +8,7 @@ export class AccountBaseClient extends AccountHelpers implements AccountBase {
    *
    * @args {} payload - The payload for the account. Additional parameters may be provided to enable different helpers.
    * @param {string} payload.publicKey The public key of the account.
-   * @param {NetworkConfig=} payload.networkConfig The network to use.
+   * @param {NetworkConfig=} payload.networkConfig The network config for the target network.
    *
    * @description - The base account is used for handling accounts with no management actions.
    */

src/stellar-plus/asset/classic/index.ts

@@ -26,10 +26,10 @@ export class ClassicAssetHandler implements IClassicAssetHandler {
   /**
    *
    * @param {string} code - The asset code.
-   * @param {string} issuerPublicKey - The public key of the asset issuer.
-   * @param {NetworkConfig} networkConfig - The network to use.
-   * @param {AccountHandler=} issuerAccount - The issuer account handler. When provided, it'll enable management functions and be used to sign transactions as the issuer.
-   * @param {TransactionSubmitter=} transactionSubmitter - The transaction submitter to use.
+   * @param {string | AccountHandler} issuerAccount - The issuer account. When an account handler is provided, it'll enable management functions and be used to sign transactions as the issuer.
+   * @param {NetworkConfig} networkConfig - The network configuration to use.
+   * @param {ClassicTransactionPipelineOptions} options - The options for the classic transaction pipeline.
+     @param {ClassicTransactionPipelineOptions} options.classicTransactionPipeline - The options for the classic transaction pipeline. These allow for custom configurations for how the transaction pipeline will operate for this asset.
    *
    * @description - The Classic asset handler is used for handling classic assets with user-based and management functionalities.
    *
@@ -92,9 +92,9 @@ export class ClassicAssetHandler implements IClassicAssetHandler {
     return this.code
   }
 
-  // /**
-  //  * @description - Not implemented in pure classic assets. Only available for Soroban assets.
-  //  */
+  /**
+   * @description - Not implemented in the current version for pure classic assets. Only available for Soroban assets.
+   */
 
   public async approve(): Promise<void> {
     throw new Error('Method not implemented.')
@@ -186,10 +186,10 @@ export class ClassicAssetHandler implements IClassicAssetHandler {
   //
 
   /**
-   *
+   * @args
    * @param {string} to - The account id to mint the asset to.
    * @param {i128} amount - The amount of the asset to mint.
-   * @param {TransactionInvocation} txInvocation - The transaction invocation object. The Issuer account will be automatically added as a signer.
+   * @param {TransactionInvocation} txInvocation - The transaction invocation object spread. The Issuer account will be automatically added as a signer.
    *
    * @description - Mints the given amount of the asset to the 'to' account.
    * @requires - The issuer account to be set in the asset.
@@ -241,7 +241,7 @@ export class ClassicAssetHandler implements IClassicAssetHandler {
    *
    * @param {string} to - The account id to mint the asset to.
    * @param {number} amount - The amount of the asset to mint.
-   * @param {TransactionInvocation} txInvocation - The transaction invocation object. The  The Issuer account will be automatically added as a signer.
+   * @param {TransactionInvocation} txInvocation - The transaction invocation object spread. The Issuer account will be automatically added as a signer.
    *
    * @requires - The issuer account to be set in the asset.
    * @requires - The 'to' account to be set as a signer in the transaction invocation.
@@ -289,7 +289,7 @@ export class ClassicAssetHandler implements IClassicAssetHandler {
   /**
    *
    * @param {string} to - The account id to add the trustline.
-   * @param {TransactionInvocation} txInvocation - The transaction invocation object.
+   * @param {TransactionInvocation} txInvocation - The transaction invocation object spread.
    *
    * @requires - The 'to' account to be set as a signer in the transaction invocation.
    *

src/stellar-plus/asset/soroban-token/index.ts

@@ -14,14 +14,19 @@ export class SorobanTokenHandler extends ContractEngine implements SorobanTokenI
    *
    * @args args
    * @param {NetworkConfig} args.networkConfig - Network to connect to
-   * @param {ContractSpec=} args.spec - Contract specification object
-   * @param {string=} args.contractId - Contract ID
-   * @param {RpcHandler=} args.rpcHandler - RPC Handler
+   * @param args.contractParameters - Contract parameters
+   * @param {ContractSpec=} args.contractParameters.spec - Contract specification
+   * @param {string=} args.contractParameters.contractId - Contract ID
    * @param {Buffer=} args.wasm - Contract WASM file as Buffer
    * @param {string=} args.wasmHash - Contract WASM hash identifier
+   * @param {Options=} args.options - Contract options
+   * @param {SorobanTransactionPipelineOptions=} args.options.sorobanTransactionPipeline - Soroban transaction pipeline options. Allows for customizing how transaction pipeline will be executed for this contract.
    *
    * @description Create a new SorobanTokenHandler instance to interact with a Soroban Token contract.
    * This class is a subclass of ContractEngine and implements the Soroban token interface.
+   * The contract spec is set to the default Soroban Token spec. When initializing the contract, the spec can be overridden with a custom spec.
+   * The contract ID, WASM file, and WASM hash can be provided to initialize the contract with the given parameters. At least one of these parameters must be provided.
+   *
    */
   constructor(args: SorobanTokenHandlerConstructorArgs) {
     super({

src/stellar-plus/asset/stellar-asset-contract/index.ts

@@ -6,6 +6,7 @@ import { SorobanTokenHandler } from 'stellar-plus/asset/soroban-token'
 import { SorobanTokenHandlerConstructorArgs } from 'stellar-plus/asset/soroban-token/types'
 import { SACConstructorArgs, SACHandler as SACHandlerType } from 'stellar-plus/asset/stellar-asset-contract/types'
 import { AssetTypes } from 'stellar-plus/asset/types'
+
 import { TransactionInvocation } from 'stellar-plus/core/types'
 
 export class SACHandler implements SACHandlerType {
@@ -20,15 +21,15 @@ export class SACHandler implements SACHandlerType {
    * @param {NetworkConfig} args.networkConfig - The network to connect to.
    * Parameters related to the classic asset.
    * @param {string} args.code - The asset code.
-   * @param {string} args.issuerPublicKey - The issuer public key.
-   * @param {AccountHandler=} args.issuerAccount - The issuer account.
-   * @param {TransactionSubmitter=} args.transactionSubmitter - The classic transaction submitter.
-   * Parameters related to the Soroban token.
-   * @param {ContractSpec=} args.spec - The contract specification object.
-   * @param {Buffer=} args.wasm - The contract wasm file as a buffer.
-   * @param {string=} args.wasmHash - The contract wasm hash id.
-   * @param {string=} args.contractId - The contract id.
-   * @param {RpcHandler=} args.rpcHandler - A custom Soroban RPC handler.
+   * @param {string | AccountHandler} args.issuerAccount - The issuer account. Can be a public key or an account handler. If it's an account handler, it will enable management functions.
+   * @param contractParameters - The contract parameters.
+   * @param {ContractSpec=} contractParameters.spec - The contract specification object.
+   * @param {Buffer=} contractParameters.wasm - The contract wasm file as a buffer.
+   * @param {string=} contractParameters.wasmHash - The contract wasm hash id.
+   * @param {string=} contractParameters.contractId - The contract id.
+   * @param options - The contract options.
+   * @param {SorobanTransactionPipelineOptions=} options.sorobanTransactionPipeline - The Soroban transaction pipeline.
+   * @param { ClassicTransactionPipelineOptions=} options.classicTransactionPipeline - The classic transaction pipeline.
    *
    *
    * @description - The Stellar Asset Contract handler. It combines the classic asset handler and the Soroban token handler.

src/stellar-plus/core/contract-engine/errors.ts

@@ -113,6 +113,15 @@ const contractCodeMissingLiveUntilLedgerSeq = (
   })
 }
 
+const contractEngineClassFailedToInitialize = () => {
+  return new StellarPlusError({
+    code: ContractEngineErrorCodes.CE009,
+    message: 'Contract engine class failed to initialize!',
+    source: 'ContractEngine',
+    details:
+      'Contract engine class failed to initialize because of missing parameters! The Contract Engine must be initialized with either the wasm file, the wasm hash, or the contract ID. Please review the initialization parameters and try again.',
+  })
+}
 
 const failedToUploadWasm = (error: StellarPlusError): StellarPlusError => {
   return new StellarPlusError({
@@ -155,6 +164,7 @@ export const CEError = {
   contractInstanceMissingLiveUntilLedgerSeq,
   contractCodeNotFound,
   contractCodeMissingLiveUntilLedgerSeq,
+  contractEngineClassFailedToInitialize,
   failedToUploadWasm,
   failedToDeployContract,
   failedToWrapAsset,

src/stellar-plus/core/contract-engine/index.ts

@@ -57,13 +57,13 @@ export class ContractEngine {
   /**
    *
    * @param {NetworkConfig} networkConfig - The network to use.
-   * @param {ContractSpec} spec - The contract specification.
-   * @param {string=} contractId - The contract id.
-   * @param {RpcHandler=} rpcHandler - A custom RPC handler to use when interacting with the network RPC server.
-   * @param {Options=}  options - A set of custom options to modify the behavior of the contract engine.
-   * @param {boolean=} options.debug - A flag to enable debug mode. This will toggle the extraction of transaction resources consumed with each transaction/simiulation.
-   * @param {CostHandler=} options.costHandler - A custom function to handle the transaction resources consumed with each transaction/simulation. Whn not provided, the default cost handler will be used and the resources will be logged to the console.
-   * @param {TransactionInvocation=} options.restoreTxInvocation - The transaction invocation object to use when automatically restoring the contract footprint. When this parameter is provided, whenever a simulation indicates that the contract footprint needs to be restored, the contract engine will automatically restore the footprint using the provided transaction invocation object.
+   * @param contractParameters - The contract parameters.
+   * @param {ContractSpec} contractParameters.spec - The contract specification object.
+   * @param {string=} contractParameters.contractId - The contract id.
+   * @param {Buffer=} contractParameters.wasm - The contract wasm file as a buffer.
+   * @param {string=} contractParameters.wasmHash - The contract wasm hash id.
+   * @param {Options=} options - A set of custom options to modify the behavior of the contract engine.
+   * @param {SorobanTransactionPipelineOptions=} options.sorobanTransactionPipeline - The Soroban transaction pipeline.
    * @description - The contract engine is used for interacting with contracts on the network. This class can be extended to create a contract client, abstracting away the Soroban integration.
    *
    * @example - The following example shows how to invoke a contract method that alters the state of the contract.