Merge pull request #16 from Entropy-Foundation/issue-14

Addresses Issue 14

README.md

@@ -25,6 +25,10 @@ Check [./src/example.ts](https://github.com/Entropy-Foundation/supra-l1-sdk/blob
 - [x] Transfer coin
 - [x] Publish Package
 - [X] `entry_function_payload` type tx
+- [X] Transaction payload generation
+- [X] Transaction simulation
+- [X] Transaction signing
+- [X] Transaction hash generation
 - [ ] `script_payload` type tx
 - [ ] Sponsor transaction
 - [ ] Multi-agent transaction

dist/browser/index.d.mts

@@ -5,21 +5,15 @@ interface AccountInfo {
     sequence_number: bigint;
     authentication_key: string;
 }
-interface AccountResources {
-    module: Array<[string, {
+type AccountResources = Array<Array<[
+    string,
+    {
         address: string;
+        module: string;
         name: string;
-    }]>;
-    struct_type: Array<[
-        string,
-        {
-            address: string;
-            module: string;
-            name: string;
-            type_args: Array<TxnBuilderTypes.StructTag>;
-        }
-    ]>;
-}
+        type_args: Array<TxnBuilderTypes.StructTag>;
+    }
+]>>;
 interface CoinInfo {
     name: string;
     symbol: string;
@@ -106,6 +100,19 @@ interface FaucetRequestResponse {
     status: TransactionStatus;
     transactionHash: string;
 }
+interface EnableTransactionWaitAndSimulationArgs {
+    enableWaitForTransaction?: boolean;
+    enableTransactionSimulation?: boolean;
+}
+interface OptionalTransactionPayloadArgs {
+    maxGas?: bigint;
+    gasUnitPrice?: bigint;
+    txExpiryTime?: bigint;
+}
+interface OptionalTransactionArgs {
+    optionalTransactionPayloadArgs?: OptionalTransactionPayloadArgs;
+    enableTransactionWaitAndSimulationArgs?: EnableTransactionWaitAndSimulationArgs;
+}
 
 /**
  * Provides methods for interacting with supra rpc node.
@@ -116,8 +123,15 @@ declare class SupraClient {
     constructor(url: string, chainId?: number);
     /**
      * Creates and initializes `SupraClient` instance
+     * The chain id will be fetched from the provided `url`
      * @param url rpc url of supra rpc node
      * @returns `SupraClient` initialized instance
+     * @example
+     * ```typescript
+     * let supraClient = await SupraClient.init(
+     *    "http://localhost:27001/"
+     * );
+     * ```
      */
     static init(url: string): Promise<SupraClient>;
     private sendRequest;
@@ -160,6 +174,13 @@ declare class SupraClient {
      * @param account Hex-encoded 32 byte Supra account address
      * @param resourceType Type of a resource
      * @returns Resource data
+     * @example
+     * ```typescript
+     * let supraCoinInfo = await supraClient.getResourceData(
+     *   new HexString("0x1"),
+     *   "0x1::coin::CoinInfo<0x1::supra_coin::SupraCoin>"
+     * )
+     * ```
      */
     getResourceData(account: HexString, resourceType: string): Promise<any>;
     /**
@@ -222,79 +243,137 @@ declare class SupraClient {
     getAccountCoinBalance(account: HexString, coinType: string): Promise<bigint>;
     private waitForTransactionCompletion;
     private sendTx;
+    /**
+     * Generate `ed25519_signature` for supra transaction using `RawTransaction`
+     * @param senderAccount Sender KeyPair
+     * @param rawTxn Raw transaction data
+     * @returns ed25519 signature in `HexString`
+     */
     static signSupraTransaction(senderAccount: AptosAccount, rawTxn: TxnBuilderTypes.RawTransaction): HexString;
     private getRawTxDataInJson;
-    getSendTxPayload(senderAccount: AptosAccount, rawTxn: TxnBuilderTypes.RawTransaction): Promise<SendTxPayload>;
+    /**
+     * Generate `SendTxPayload` using `RawTransaction` to send transaction request
+     * Generated data can be used to send transaction directly using `/rpc/v1/transactions/submit` endpoint of `rpc_node`
+     * @param senderAccount Sender KeyPair
+     * @param rawTxn Raw transaction data
+     * @returns `SendTxPayload`
+     */
+    getSendTxPayload(senderAccount: AptosAccount, rawTxn: TxnBuilderTypes.RawTransaction): SendTxPayload;
     /**
      * Send `entry_function_payload` type tx using serialized raw transaction data
      * @param senderAccount Sender KeyPair
      * @param serializedRawTransaction Serialized raw transaction data
-     * @param enableSimulation should enable simulation
-     * @param waitForTransactionCompletion should wait for transaction completion
+     * @param enableTransactionWaitAndSimulationArgs enable transaction wait and simulation arguments
      * @returns `TransactionResponse`
      */
-    sendTxUsingSerializedRawTransaction(senderAccount: AptosAccount, serializedRawTransaction: Uint8Array, enableSimulation?: boolean, waitForTransactionCompletion?: boolean): Promise<TransactionResponse>;
-    static createRawTxObject(senderAddr: HexString, senderSequenceNumber: bigint, moduleAddr: string, moduleName: string, functionName: string, functionTypeArgs: TxnBuilderTypes.TypeTag[], functionArgs: Uint8Array[], chainId: TxnBuilderTypes.ChainId, maxGas?: bigint | undefined, gasUnitPrice?: bigint | undefined, txExpiryTime?: bigint | undefined): Promise<TxnBuilderTypes.RawTransaction>;
+    sendTxUsingSerializedRawTransaction(senderAccount: AptosAccount, serializedRawTransaction: Uint8Array, enableTransactionWaitAndSimulationArgs?: EnableTransactionWaitAndSimulationArgs): Promise<TransactionResponse>;
+    /**
+     * Create raw transaction object for `entry_function_payload` type tx
+     * @param senderAddr Sender account address
+     * @param senderSequenceNumber Sender account sequence number
+     * @param moduleAddr Target module address
+     * @param moduleName Target module name
+     * @param functionName Target function name
+     * @param functionTypeArgs Target function type args
+     * @param functionArgs Target function args
+     * @param optionalTransactionPayloadArgs Optional arguments for transaction payload
+     * @returns Serialized raw transaction object
+     * @example
+     * ```typescript
+     * let supraCoinTransferRawTransaction = await supraClient.createRawTxObject(
+     *   senderAccount.address(),
+     *   (
+     *     await supraClient.getAccountInfo(senderAccount.address())
+     *   ).sequence_number,
+     *   "0000000000000000000000000000000000000000000000000000000000000001",
+     *   "supra_account",
+     *   "transfer",
+     *   [],
+     *   [receiverAddress.toUint8Array(), BCS.bcsSerializeUint64(10000)]
+     * );
+     * ```
+     */
+    createRawTxObject(senderAddr: HexString, senderSequenceNumber: bigint, moduleAddr: string, moduleName: string, functionName: string, functionTypeArgs: TxnBuilderTypes.TypeTag[], functionArgs: Uint8Array[], optionalTransactionPayloadArgs?: OptionalTransactionPayloadArgs): Promise<TxnBuilderTypes.RawTransaction>;
     /**
-     * Create serialized raw transaction object for `entry_function_payload` type tx
+     * Create serialized raw transaction for `entry_function_payload` type tx
+     * Under the hood the method utilizes `createRawTxObject` method to create a raw transaction
+     * and then it serializes using bcs serializer
      * @param senderAddr Sender account address
      * @param senderSequenceNumber Sender account sequence number
      * @param moduleAddr Target module address
      * @param moduleName Target module name
      * @param functionName Target function name
      * @param functionTypeArgs Target function type args
      * @param functionArgs Target function args
-     * @param chainId Supra network chain id
-     * @param maxGas Maximum gas for transaction
-     * @param gasUnitPrice Maximum gas unit price for transaction
-     * @param txExpiryTime Expiry time for transaction
+     * @param optionalTransactionPayloadArgs Optional arguments for transaction payload
      * @returns Serialized raw transaction object
      */
-    static createSerializedRawTxObject(senderAddr: HexString, senderSequenceNumber: bigint, moduleAddr: string, moduleName: string, functionName: string, functionTypeArgs: TxnBuilderTypes.TypeTag[], functionArgs: Uint8Array[], chainId: TxnBuilderTypes.ChainId, maxGas?: bigint, gasUnitPrice?: bigint, txExpiryTime?: bigint | undefined): Promise<Uint8Array>;
+    createSerializedRawTxObject(senderAddr: HexString, senderSequenceNumber: bigint, moduleAddr: string, moduleName: string, functionName: string, functionTypeArgs: TxnBuilderTypes.TypeTag[], functionArgs: Uint8Array[], optionalTransactionPayloadArgs?: OptionalTransactionPayloadArgs): Promise<Uint8Array>;
+    /**
+     * Create signed transaction payload
+     * @param senderAccount Sender KeyPair
+     * @param rawTxn Raw transaction payload
+     * @returns `SignedTransaction`
+     */
     static createSignedTransaction(senderAccount: AptosAccount, rawTxn: TxnBuilderTypes.RawTransaction): TxnBuilderTypes.SignedTransaction;
+    /**
+     * Generate transaction hash locally
+     * @param signedTransaction Signed transaction payload
+     * @returns `SignedTransaction`
+     * @example
+     * ```typescript
+     *  let supraCoinTransferSignedTransaction = SupraClient.createSignedTransaction(
+     *     senderAccount,
+     *     supraCoinTransferRawTransaction
+     *  );
+     *  console.log(
+     *     SupraClient.deriveTransactionHash(supraCoinTransferSignedTransaction)
+     *  );
+     * ```
+     */
     static deriveTransactionHash(signedTransaction: TxnBuilderTypes.SignedTransaction): string;
     /**
      * Transfer supra coin
      * @param senderAccount Sender KeyPair
      * @param receiverAccountAddr Receiver Supra Account address
      * @param amount Amount to transfer
-     * @param enableSimulation should enable simulation
-     * @param waitForTransactionCompletion should wait for transaction completion
+     * @param optionalTransactionArgs optional arguments for transaction
      * @returns `TransactionResponse`
      */
-    transferSupraCoin(senderAccount: AptosAccount, receiverAccountAddr: HexString, amount: bigint, enableSimulation?: boolean, waitForTransactionCompletion?: boolean): Promise<TransactionResponse>;
+    transferSupraCoin(senderAccount: AptosAccount, receiverAccountAddr: HexString, amount: bigint, optionalTransactionArgs?: OptionalTransactionArgs): Promise<TransactionResponse>;
     /**
-     * Transfer coin
+     * Transfer custom type of coin
      * @param senderAccount Sender KeyPair
      * @param receiverAccountAddr Receiver Supra Account address
      * @param amount Amount to transfer
-     * @param coinType Type of coin
-     * @param enableSimulation should enable simulation
-     * @param waitForTransactionCompletion should wait for transaction completion
+     * @param coinType Type of custom coin
+     * @param optionalTransactionArgs optional arguments for transaction
      * @returns `TransactionResponse`
      */
-    transferCoin(senderAccount: AptosAccount, receiverAccountAddr: HexString, amount: bigint, coinType: string, enableSimulation?: boolean, waitForTransactionCompletion?: boolean): Promise<TransactionResponse>;
+    transferCoin(senderAccount: AptosAccount, receiverAccountAddr: HexString, amount: bigint, coinType: string, optionalTransactionArgs?: OptionalTransactionArgs): Promise<TransactionResponse>;
     /**
      * Publish package or module on supra network
      * @param senderAccount Module Publisher KeyPair
      * @param packageMetadata Package Metadata
      * @param modulesCode module code
-     * @param enableSimulation should enable simulation
-     * @param waitForTransactionCompletion should wait for transaction completion
+     * @param optionalTransactionArgs optional arguments for transaction
      * @returns `TransactionResponse`
      */
-    publishPackage(senderAccount: AptosAccount, packageMetadata: Uint8Array, modulesCode: Uint8Array[], enableSimulation?: boolean, waitForTransactionCompletion?: boolean): Promise<TransactionResponse>;
+    publishPackage(senderAccount: AptosAccount, packageMetadata: Uint8Array, modulesCode: Uint8Array[], optionalTransactionArgs?: OptionalTransactionArgs): Promise<TransactionResponse>;
     /**
      * Simulate a transaction using the provided transaction payload
      * @param sendTxPayload Transaction payload
+     * @returns Transaction simulation result
      */
     simulateTx(sendTxPayload: SendTxPayload): Promise<any>;
     /**
      * Simulate a transaction using the provided Serialized raw transaction data
      * @param senderAccountAddress Tx sender account address
+     * @param senderAccountPubKey Tx sender account public key
      * @param serializedRawTransaction Serialized raw transaction data
+     * @returns Transaction simulation result
      */
     simulateTxUsingSerializedRawTransaction(senderAccountAddress: HexString, senderAccountPubKey: HexString, serializedRawTransaction: Uint8Array): Promise<any>;
 }
 
-export { type AccountInfo, type AccountResources, type CoinChange, type CoinInfo, type FaucetRequestResponse, type FunctionTypeArgs, type SendTxPayload, SupraClient, type TransactionDetail, type TransactionInsights, type TransactionResponse, TransactionStatus, TxTypeForTransactionInsights };
+export { type AccountInfo, type AccountResources, type CoinChange, type CoinInfo, type EnableTransactionWaitAndSimulationArgs, type FaucetRequestResponse, type FunctionTypeArgs, type OptionalTransactionArgs, type OptionalTransactionPayloadArgs, type SendTxPayload, SupraClient, type TransactionDetail, type TransactionInsights, type TransactionResponse, TransactionStatus, TxTypeForTransactionInsights };