From b22a696819f76352d296def81ee7b90f7b829238 Mon Sep 17 00:00:00 2001 From: davidrollins12 Date: Thu, 17 Oct 2024 14:31:57 -0500 Subject: [PATCH 1/2] add groups and categories --- scripts/generateDocs.sh | 2 +- src/account/AbstractKeylessAccount.ts | 77 +++- src/account/Account.ts | 46 ++ src/account/Ed25519Account.ts | 26 ++ src/account/EphemeralKeyPair.ts | 30 ++ src/account/FederatedKeylessAccount.ts | 4 + src/account/KeylessAccount.ts | 12 + src/account/MultiKeyAccount.ts | 32 ++ src/account/SingleKeyAccount.ts | 28 ++ src/api/account.ts | 20 + src/api/ans.ts | 15 + src/api/aptos.ts | 3 + src/api/aptosConfig.ts | 16 + src/api/coin.ts | 3 + src/api/digitalAsset.ts | 26 ++ src/api/event.ts | 6 + src/api/faucet.ts | 3 + src/api/fungibleAsset.ts | 8 + src/api/general.ts | 12 + src/api/keyless.ts | 6 + src/api/object.ts | 3 + src/api/staking.ts | 5 + src/api/table.ts | 5 + src/api/transaction.ts | 16 + src/api/transactionSubmission/build.ts | 4 + src/api/transactionSubmission/helpers.ts | 2 + src/api/transactionSubmission/management.ts | 5 + src/api/transactionSubmission/sign.ts | 4 + src/api/transactionSubmission/simulate.ts | 4 + src/api/transactionSubmission/submit.ts | 4 + src/api/utils.ts | 1 + src/bcs/deserializer.ts | 42 ++ src/bcs/serializable/entryFunctionBytes.ts | 10 + src/bcs/serializable/fixedBytes.ts | 12 + src/bcs/serializable/movePrimitives.ts | 26 ++ src/bcs/serializable/moveStructs.ts | 56 +++ src/bcs/serializer.ts | 65 ++- src/cli/localNode.ts | 14 + src/cli/move.ts | 26 ++ src/client/core.ts | 4 + src/client/get.ts | 35 +- src/client/post.ts | 34 ++ src/client/types.ts | 12 + src/core/account/utils/address.ts | 6 + src/core/accountAddress.ts | 46 ++ src/core/authenticationKey.ts | 24 + src/core/common.ts | 14 + src/core/crypto/ed25519.ts | 58 +++ src/core/crypto/ephemeral.ts | 26 ++ src/core/crypto/federatedKeyless.ts | 16 + src/core/crypto/hdKey.ts | 29 ++ src/core/crypto/keyless.ts | 142 ++++++ src/core/crypto/multiEd25519.ts | 40 ++ src/core/crypto/multiKey.ts | 38 ++ src/core/crypto/poseidon.ts | 20 + src/core/crypto/privateKey.ts | 8 + src/core/crypto/proof.ts | 4 + src/core/crypto/publicKey.ts | 14 + src/core/crypto/secp256k1.ts | 48 ++ src/core/crypto/signature.ts | 8 + src/core/crypto/singleKey.ts | 30 ++ src/core/crypto/utils.ts | 2 + src/core/hex.ts | 20 + src/internal/account.ts | 20 + src/internal/ans.ts | 27 ++ src/internal/coin.ts | 1 + src/internal/digitalAsset.ts | 30 ++ src/internal/event.ts | 6 + src/internal/faucet.ts | 2 + src/internal/fungibleAsset.ts | 5 + src/internal/general.ts | 7 + src/internal/keyless.ts | 4 + src/internal/object.ts | 2 + src/internal/staking.ts | 4 + src/internal/table.ts | 3 + src/internal/transaction.ts | 16 + src/internal/transactionSubmission.ts | 13 + src/transactions/authenticator/account.ts | 26 ++ src/transactions/authenticator/transaction.ts | 20 + src/transactions/instances/chainId.ts | 8 + src/transactions/instances/identifier.ts | 8 + src/transactions/instances/moduleId.ts | 10 + .../instances/multiAgentTransaction.ts | 8 + src/transactions/instances/rawTransaction.ts | 30 ++ .../instances/rotationProofChallenge.ts | 6 + .../instances/signedTransaction.ts | 8 + .../instances/simpleTransaction.ts | 8 + .../instances/transactionArgument.ts | 16 + .../instances/transactionPayload.ts | 50 ++ .../management/accountSequenceNumber.ts | 16 + src/transactions/management/asyncQueue.ts | 16 + .../management/transactionWorker.ts | 47 +- .../transactionBuilder/helpers.ts | 92 +++- .../transactionBuilder/remoteAbi.ts | 20 + .../transactionBuilder/signingMessage.ts | 10 + .../transactionBuilder/transactionBuilder.ts | 59 ++- src/transactions/typeTag/index.ts | 82 ++++ src/transactions/typeTag/parser.ts | 24 + src/transactions/types.ts | 78 ++++ src/types/index.ts | 433 +++++++++++++++++- src/types/indexer.ts | 52 +++ src/types/keyless.ts | 12 + src/utils/apiEndpoints.ts | 30 ++ src/utils/const.ts | 25 +- src/utils/helpers.ts | 21 +- src/utils/memoize.ts | 6 + src/utils/normalizeBundle.ts | 9 +- 107 files changed, 2693 insertions(+), 34 deletions(-) diff --git a/scripts/generateDocs.sh b/scripts/generateDocs.sh index 08c9caf39..20c6d7799 100755 --- a/scripts/generateDocs.sh +++ b/scripts/generateDocs.sh @@ -17,7 +17,7 @@ fi # TODO: This uses the --skipErrorChecking flag as otherwise it incorrectly tries to compile the tests folder. # Remove this once test compiler errors are not intefering with docs generation. -npx typedoc src/index.ts --options typedoc.json --out "docs/@aptos-labs/ts-sdk-$npm_package_version" --plugin typedoc-plugin-missing-exports --cleanOutputDir --excludeInternal --includeVersion --skipErrorChecking +npx typedoc src/index.ts --options typedoc.json --out "docs/@aptos-labs/ts-sdk-$npm_package_version" --plugin typedoc-plugin-missing-exports --internalModule PrivateCode --cleanOutputDir --excludeInternal --includeVersion --skipErrorChecking # Update the main page INDEX_FILE='docs/index.md'; diff --git a/src/account/AbstractKeylessAccount.ts b/src/account/AbstractKeylessAccount.ts index e1162ddf8..4766b552e 100644 --- a/src/account/AbstractKeylessAccount.ts +++ b/src/account/AbstractKeylessAccount.ts @@ -27,69 +27,95 @@ import { FederatedKeylessPublicKey } from "../core/crypto/federatedKeyless"; /** * Account implementation for the Keyless authentication scheme. This abstract class is used for standard Keyless Accounts * and Federated Keyless Accounts. + * @group Implementation + * @category Account (On-Chain Model) */ export abstract class AbstractKeylessAccount extends Serializable implements Account { static readonly PEPPER_LENGTH: number = 31; /** * The KeylessPublicKey associated with the account + * @group Implementation + * @category Account (On-Chain Model) */ readonly publicKey: KeylessPublicKey | FederatedKeylessPublicKey; /** * The EphemeralKeyPair used to generate sign. + * @group Implementation + * @category Account (On-Chain Model) */ readonly ephemeralKeyPair: EphemeralKeyPair; /** * The claim on the JWT to identify a user. This is typically 'sub' or 'email'. + * @group Implementation + * @category Account (On-Chain Model) */ readonly uidKey: string; /** * The value of the uidKey claim on the JWT. This intended to be a stable user identifier. + * @group Implementation + * @category Account (On-Chain Model) */ readonly uidVal: string; /** * The value of the 'aud' claim on the JWT, also known as client ID. This is the identifier for the dApp's * OIDC registration with the identity provider. + * @group Implementation + * @category Account (On-Chain Model) */ readonly aud: string; /** * A value contains 31 bytes of entropy that preserves privacy of the account. Typically fetched from a pepper provider. + * @group Implementation + * @category Account (On-Chain Model) */ readonly pepper: Uint8Array; /** * Account address associated with the account + * @group Implementation + * @category Account (On-Chain Model) */ readonly accountAddress: AccountAddress; /** * The zero knowledge signature (if ready) which contains the proof used to validate the EphemeralKeyPair. + * @group Implementation + * @category Account (On-Chain Model) */ proof: ZeroKnowledgeSig | undefined; /** * The proof of the EphemeralKeyPair or a promise that provides the proof. This is used to allow for awaiting on * fetching the proof. + * @group Implementation + * @category Account (On-Chain Model) */ readonly proofOrPromise: ZeroKnowledgeSig | Promise; /** * Signing scheme used to sign transactions + * @group Implementation + * @category Account (On-Chain Model) */ readonly signingScheme: SigningScheme; /** * The JWT token used to derive the account + * @group Implementation + * @category Account (On-Chain Model) */ readonly jwt: string; /** * An event emitter used to assist in handling asynchronous proof fetching. + * @group Implementation + * @category Account (On-Chain Model) */ private readonly emitter: EventEmitter; @@ -142,6 +168,8 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc /** * This initializes the asynchronous proof fetch * @return + * @group Implementation + * @category Account (On-Chain Model) */ async init(promise: Promise) { try { @@ -171,6 +199,8 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc * Checks if the proof is expired. If so the account must be re-derived with a new EphemeralKeyPair * and JWT token. * @return boolean + * @group Implementation + * @category Account (On-Chain Model) */ isExpired(): boolean { return this.ephemeralKeyPair.isExpired(); @@ -180,6 +210,8 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc * Sign a message using Keyless. * @param message the message to sign, as binary input * @return the AccountAuthenticator containing the signature, together with the account's public key + * @group Implementation + * @category Account (On-Chain Model) */ signWithAuthenticator(message: HexInput): AccountAuthenticatorSingleKey { const signature = new AnySignature(this.sign(message)); @@ -191,6 +223,8 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc * Sign a transaction using Keyless. * @param transaction the raw transaction * @return the AccountAuthenticator containing the signature of the transaction, together with the account's public key + * @group Implementation + * @category Account (On-Chain Model) */ signTransactionWithAuthenticator(transaction: AnyRawTransaction): AccountAuthenticatorSingleKey { const signature = new AnySignature(this.signTransaction(transaction)); @@ -201,6 +235,8 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc /** * Waits for asynchronous proof fetching to finish. * @return + * @group Implementation + * @category Account (On-Chain Model) */ async waitForProofFetch() { if (this.proofOrPromise instanceof Promise) { @@ -212,6 +248,8 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc * Sign the given message using Keyless. * @param message in HexInput format * @returns Signature + * @group Implementation + * @category Account (On-Chain Model) */ sign(message: HexInput): KeylessSignature { const { expiryDateSecs } = this.ephemeralKeyPair; @@ -238,6 +276,8 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc * Signs the transaction and proof to guard against proof malleability. * @param transaction the transaction to be signed * @returns KeylessSignature + * @group Implementation + * @category Account (On-Chain Model) */ signTransaction(transaction: AnyRawTransaction): KeylessSignature { if (this.proof === undefined) { @@ -259,6 +299,8 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc * @param args.message the message that was signed. * @param args.signature the KeylessSignature to verify * @returns boolean + * @group Implementation + * @category Account (On-Chain Model) */ verifySignature(args: { message: HexInput; signature: KeylessSignature }): boolean { const { message, signature } = args; @@ -275,20 +317,28 @@ export abstract class AbstractKeylessAccount extends Serializable implements Acc /** * A container class to hold a transaction and a proof. It implements CryptoHashable which is used to create * the signing message for Keyless transactions. We sign over the proof to ensure non-malleability. + * @group Implementation + * @category Account (On-Chain Model) */ export class TransactionAndProof extends Serializable { /** * The transaction to sign. + * @group Implementation + * @category Account (On-Chain Model) */ transaction: AnyRawTransactionInstance; /** * The zero knowledge proof used in signing the transaction. + * @group Implementation + * @category Account (On-Chain Model) */ proof?: ZkProof; /** * The domain separator prefix used when hashing. + * @group Implementation + * @category Account (On-Chain Model) */ readonly domainSeparator = "APTOS::TransactionAndProof"; @@ -307,25 +357,42 @@ export class TransactionAndProof extends Serializable { * Hashes the bcs serialized from of the class. This is the typescript corollary to the BCSCryptoHash macro in aptos-core. * * @returns Uint8Array + * @group Implementation + * @category Account (On-Chain Model) */ hash(): Uint8Array { return generateSigningMessage(this.bcsToBytes(), this.domainSeparator); } } - +/** + * @group Implementation + * @category Account (On-Chain Model) + */ export type ProofFetchSuccess = { status: "Success"; }; - +/** + * @group Implementation + * @category Account (On-Chain Model) + */ export type ProofFetchFailure = { status: "Failed"; error: string; }; - +/** + * @group Implementation + * @category Account (On-Chain Model) + */ export type ProofFetchStatus = ProofFetchSuccess | ProofFetchFailure; - +/** + * @group Implementation + * @category Account (On-Chain Model) + */ export type ProofFetchCallback = (status: ProofFetchStatus) => Promise; - +/** + * @group Implementation + * @category Account (On-Chain Model) + */ export interface ProofFetchEvents { proofFetchFinish: (status: ProofFetchStatus) => void; } diff --git a/src/account/Account.ts b/src/account/Account.ts index 796512127..bfb94adb5 100644 --- a/src/account/Account.ts +++ b/src/account/Account.ts @@ -14,6 +14,8 @@ import { AnyRawTransaction } from "../transactions/types"; * @param privateKey - The private key used to create the account. * @param address - Optional address for the account. * @param legacy - Indicates whether to use legacy authentication (default is true). + * @group Implementation + * @category Account (On-Chain Model) */ export interface CreateEd25519AccountFromPrivateKeyArgs { privateKey: Ed25519PrivateKey; @@ -28,6 +30,8 @@ export interface CreateEd25519AccountFromPrivateKeyArgs { * @param privateKey - The Ed25519 private key used for account creation. * @param address - Optional account address input. * @param legacy - Must be false to enable the `SingleKey` authentication scheme. + * @group Implementation + * @category Account (On-Chain Model) */ export interface CreateEd25519SingleKeyAccountFromPrivateKeyArgs { privateKey: Ed25519PrivateKey; @@ -42,6 +46,8 @@ export interface CreateEd25519SingleKeyAccountFromPrivateKeyArgs { * @param privateKey - The private key used to create the account. * @param address - Optional address input for the account. * @param legacy - Always false; cannot be explicitly set to true. + * @group Implementation + * @category Account (On-Chain Model) */ export interface CreateSingleKeyAccountFromPrivateKeyArgs { privateKey: Exclude; @@ -55,6 +61,8 @@ export interface CreateSingleKeyAccountFromPrivateKeyArgs { * @param privateKey - The private key used to create the account. * @param address - Optional address for the account. * @param legacy - Optional flag indicating if the account is a legacy account. + * @group Implementation + * @category Account (On-Chain Model) */ export interface CreateAccountFromPrivateKeyArgs { privateKey: PrivateKey; @@ -67,6 +75,8 @@ export interface CreateAccountFromPrivateKeyArgs { * * @param scheme - The signing scheme to use for the account. * @param legacy - Indicates if the account should be created in legacy mode. + * @group Implementation + * @category Account (On-Chain Model) */ export interface GenerateEd25519AccountArgs { scheme?: SigningSchemeInput.Ed25519; @@ -79,6 +89,8 @@ export interface GenerateEd25519AccountArgs { * * @param scheme - Optional signing scheme input for the account. * @param legacy - Indicates whether to use legacy account generation. + * @group Implementation + * @category Account (On-Chain Model) */ export interface GenerateEd25519SingleKeyAccountArgs { scheme?: SigningSchemeInput.Ed25519; @@ -91,6 +103,8 @@ export interface GenerateEd25519SingleKeyAccountArgs { * * @param scheme - The signing scheme to use for the account. * @param legacy - Indicates whether to use legacy account generation (defaults to false). + * @group Implementation + * @category Account (On-Chain Model) */ export interface GenerateSingleKeyAccountArgs { scheme: Exclude; @@ -102,6 +116,8 @@ export interface GenerateSingleKeyAccountArgs { * * @param scheme - The signing scheme to use for account generation. * @param legacy - Indicates whether to use legacy account generation methods. + * @group Implementation + * @category Account (On-Chain Model) */ export interface GenerateAccountArgs { scheme?: SigningSchemeInput; @@ -113,6 +129,8 @@ export interface GenerateAccountArgs { * * @param path - The BIP44 derivation path for the key. * @param mnemonic - The mnemonic phrase used for key generation. + * @group Implementation + * @category Account (On-Chain Model) */ export interface PrivateKeyFromDerivationPathArgs { path: string; @@ -127,20 +145,28 @@ export interface PrivateKeyFromDerivationPathArgs { * abstract class, it should be treated as an interface and enforced using the `implements` keyword. * * Note: Generating an account instance does not create the account on-chain. + * @group Implementation + * @category Account (On-Chain Model) */ export abstract class Account { /** * Public key associated with the account + * @group Implementation + * @category Account (On-Chain Model) */ abstract readonly publicKey: AccountPublicKey; /** * Account address associated with the account + * @group Implementation + * @category Account (On-Chain Model) */ abstract readonly accountAddress: AccountAddress; /** * Signing scheme used to sign transactions + * @group Implementation + * @category Account (On-Chain Model) */ abstract signingScheme: SigningScheme; @@ -151,6 +177,8 @@ export abstract class Account { * @param args - The arguments for generating the account. * @param args.scheme - The signing scheme to use for account generation. Defaults to Ed25519. * @param args.legacy - Indicates whether to use the legacy account generation method. Defaults to true. + * @group Implementation + * @category Account (On-Chain Model) */ static generate(args?: GenerateEd25519AccountArgs): Ed25519Account; static generate(args: GenerateEd25519SingleKeyAccountArgs): SingleKeyAccount; @@ -174,6 +202,8 @@ export abstract class Account { * @param args.address - The address associated with the account. * @param args.legacy - A boolean indicating whether to create a legacy account (default is true). * @returns An instance of either Ed25519Account or SingleKeyAccount based on the provided private key. + * @group Implementation + * @category Account (On-Chain Model) */ static fromPrivateKey(args: CreateEd25519AccountFromPrivateKeyArgs): Ed25519Account; static fromPrivateKey(args: CreateEd25519SingleKeyAccountFromPrivateKeyArgs): SingleKeyAccount; @@ -202,6 +232,8 @@ export abstract class Account { * Ed25519 keypair. * * @returns Account + * @group Implementation + * @category Account (On-Chain Model) */ static fromPrivateKeyAndAddress(args: CreateAccountFromPrivateKeyArgs) { return this.fromPrivateKey(args); @@ -216,6 +248,8 @@ export abstract class Account { * @param args.mnemonic - The mnemonic phrase used to derive the account. * @param args.path - The derivation path used to generate the account. * @param args.legacy - A boolean indicating whether to use the legacy account generation method. Defaults to true. + * @group Implementation + * @category Account (On-Chain Model) */ static fromDerivationPath(args: GenerateEd25519AccountArgs & PrivateKeyFromDerivationPathArgs): Ed25519Account; static fromDerivationPath( @@ -240,6 +274,8 @@ export abstract class Account { * @param args - The arguments for retrieving the authentication key. * @param args.publicKey - The public key of the account. * @returns The authentication key for the associated account. + * @group Implementation + * @category Account (On-Chain Model) */ static authKey(args: { publicKey: AccountPublicKey }): AuthenticationKey { const { publicKey } = args; @@ -250,6 +286,8 @@ export abstract class Account { * Sign a message using the available signing capabilities. * @param message the signing message, as binary input * @return the AccountAuthenticator containing the signature, together with the account's public key + * @group Implementation + * @category Account (On-Chain Model) */ abstract signWithAuthenticator(message: HexInput): AccountAuthenticator; @@ -257,6 +295,8 @@ export abstract class Account { * Sign a transaction using the available signing capabilities. * @param transaction the raw transaction * @return the AccountAuthenticator containing the signature of the transaction, together with the account's public key + * @group Implementation + * @category Account (On-Chain Model) */ abstract signTransactionWithAuthenticator(transaction: AnyRawTransaction): AccountAuthenticator; @@ -264,6 +304,8 @@ export abstract class Account { * Sign the given message using the available signing capabilities. * @param message in HexInput format * @returns Signature + * @group Implementation + * @category Account (On-Chain Model) */ abstract sign(message: HexInput): Signature; @@ -271,6 +313,8 @@ export abstract class Account { * Sign the given transaction using the available signing capabilities. * @param transaction the transaction to be signed * @returns Signature + * @group Implementation + * @category Account (On-Chain Model) */ abstract signTransaction(transaction: AnyRawTransaction): Signature; @@ -282,6 +326,8 @@ export abstract class Account { * @param args.message - The raw message data in HexInput format. * @param args.signature - The signed message signature. * @returns A boolean indicating whether the signature is valid. + * @group Implementation + * @category Account (On-Chain Model) */ verifySignature(args: VerifySignatureArgs): boolean { return this.publicKey.verifySignature(args); diff --git a/src/account/Ed25519Account.ts b/src/account/Ed25519Account.ts index 6a7fc599e..e690aff99 100644 --- a/src/account/Ed25519Account.ts +++ b/src/account/Ed25519Account.ts @@ -11,6 +11,8 @@ import { generateSigningMessageForTransaction } from "../transactions/transactio * * @param privateKey - The private key used for signing. * @param address - Optional account address associated with the signer. + * @group Implementation + * @category Account (On-Chain Model) */ export interface Ed25519SignerConstructorArgs { privateKey: Ed25519PrivateKey; @@ -22,6 +24,8 @@ export interface Ed25519SignerConstructorArgs { * * @param path - The derivation path for the Ed25519 key. * @param mnemonic - The mnemonic phrase used to generate the key. + * @group Implementation + * @category Account (On-Chain Model) */ export interface Ed25519SignerFromDerivationPathArgs { path: string; @@ -33,6 +37,8 @@ export interface Ed25519SignerFromDerivationPathArgs { * * @param message - The message to be verified, represented in hexadecimal format. * @param signature - The Ed25519 signature to validate. + * @group Implementation + * @category Account (On-Chain Model) */ export interface VerifyEd25519SignatureArgs { message: HexInput; @@ -44,10 +50,14 @@ export interface VerifyEd25519SignatureArgs { * This class allows for the creation of accounts, signing messages and transactions, and verifying signatures. * * Note: Generating an instance of this class does not create the account on-chain. + * @group Implementation + * @category Account (On-Chain Model) */ export class Ed25519Account implements Account { /** * Private key associated with the account + * @group Implementation + * @category Account (On-Chain Model) */ readonly privateKey: Ed25519PrivateKey; @@ -66,6 +76,8 @@ export class Ed25519Account implements Account { * @param args - The constructor arguments for the Ed25519Signer. * @param args.privateKey - The private key used for signing. * @param args.address - The optional account address; if not provided, it will derive the address from the public key. + * @group Implementation + * @category Account (On-Chain Model) */ constructor(args: Ed25519SignerConstructorArgs) { const { privateKey, address } = args; @@ -79,6 +91,8 @@ export class Ed25519Account implements Account { * This function is useful for creating a signer that can be used for cryptographic operations. * * @returns {Ed25519Account} The newly generated Ed25519 account. + * @group Implementation + * @category Account (On-Chain Model) */ static generate(): Ed25519Account { const privateKey = Ed25519PrivateKey.generate(); @@ -92,6 +106,8 @@ export class Ed25519Account implements Account { * @param args.path - The BIP44 derive hardened path, e.g., m/44'/637'/0'/0'/0'. * Detailed description: {@link https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki} * @param args.mnemonic - The mnemonic seed phrase of the account. + * @group Implementation + * @category Account (On-Chain Model) */ static fromDerivationPath(args: Ed25519SignerFromDerivationPathArgs) { const { path, mnemonic } = args; @@ -108,6 +124,8 @@ export class Ed25519Account implements Account { * @param args.message - Raw message data in HexInput format. * @param args.signature - Signed message signature. * @returns A boolean indicating whether the signature is valid. + * @group Implementation + * @category Account (On-Chain Model) */ verifySignature(args: VerifyEd25519SignatureArgs): boolean { return this.publicKey.verifySignature(args); @@ -119,6 +137,8 @@ export class Ed25519Account implements Account { * * @param message - The signing message, represented as hexadecimal input. * @returns An AccountAuthenticator containing the signature and the account's public key. + * @group Implementation + * @category Account (On-Chain Model) */ signWithAuthenticator(message: HexInput): AccountAuthenticatorEd25519 { return new AccountAuthenticatorEd25519(this.publicKey, this.privateKey.sign(message)); @@ -130,6 +150,8 @@ export class Ed25519Account implements Account { * * @param transaction - The raw transaction to be signed. * @returns An AccountAuthenticator containing the signature and the public key. + * @group Implementation + * @category Account (On-Chain Model) */ signTransactionWithAuthenticator(transaction: AnyRawTransaction): AccountAuthenticatorEd25519 { return new AccountAuthenticatorEd25519(this.publicKey, this.signTransaction(transaction)); @@ -139,6 +161,8 @@ export class Ed25519Account implements Account { * Sign the given message using the account's Ed25519 private key. * @param message - The message to be signed in HexInput format. * @returns Signature - The resulting signature of the signed message. + * @group Implementation + * @category Account (On-Chain Model) */ sign(message: HexInput): Ed25519Signature { return this.privateKey.sign(message); @@ -150,6 +174,8 @@ export class Ed25519Account implements Account { * * @param transaction - The transaction to be signed. * @returns Signature - The resulting signature for the transaction. + * @group Implementation + * @category Account (On-Chain Model) */ signTransaction(transaction: AnyRawTransaction): Ed25519Signature { return this.sign(generateSigningMessageForTransaction(transaction)); diff --git a/src/account/EphemeralKeyPair.ts b/src/account/EphemeralKeyPair.ts index f01832efc..d33a5f3e6 100644 --- a/src/account/EphemeralKeyPair.ts +++ b/src/account/EphemeralKeyPair.ts @@ -24,6 +24,8 @@ const TWO_WEEKS_IN_SECONDS = 1_209_600; * This key pair is temporary and includes an expiration time. * For more details on how this class is used, refer to the documentation: * https://aptos.dev/guides/keyless-accounts/#1-present-the-user-with-a-sign-in-with-idp-button-on-the-ui + * @group Implementation + * @category Account (On-Chain Model) */ export class EphemeralKeyPair extends Serializable { static readonly BLINDER_LENGTH: number = 31; @@ -31,30 +33,40 @@ export class EphemeralKeyPair extends Serializable { /** * A byte array of length BLINDER_LENGTH used to obfuscate the public key from the IdP. * Used in calculating the nonce passed to the IdP and as a secret witness in proof generation. + * @group Implementation + * @category Account (On-Chain Model) */ readonly blinder: Uint8Array; /** * A timestamp in seconds indicating when the ephemeral key pair is expired. After expiry, a new * EphemeralKeyPair must be generated and a new JWT needs to be created. + * @group Implementation + * @category Account (On-Chain Model) */ readonly expiryDateSecs: number; /** * The value passed to the IdP when the user authenticates. It consists of a hash of the * ephemeral public key, expiry date, and blinder. + * @group Implementation + * @category Account (On-Chain Model) */ readonly nonce: string; /** * A private key used to sign transactions. This private key is not tied to any account on the chain as it * is ephemeral (not permanent) in nature. + * @group Implementation + * @category Account (On-Chain Model) */ private privateKey: PrivateKey; /** * A public key used to verify transactions. This public key is not tied to any account on the chain as it * is ephemeral (not permanent) in nature. + * @group Implementation + * @category Account (On-Chain Model) */ private publicKey: EphemeralPublicKey; @@ -67,6 +79,8 @@ export class EphemeralKeyPair extends Serializable { * @param args.privateKey - The private key used for creating the instance. * @param args.expiryDateSecs - Optional expiry date in seconds from the current time. Defaults to two weeks from now. * @param args.blinder - Optional blinder value. If not provided, a new blinder will be generated. + * @group Implementation + * @category Account (On-Chain Model) */ constructor(args: { privateKey: PrivateKey; expiryDateSecs?: number; blinder?: HexInput }) { super(); @@ -88,6 +102,8 @@ export class EphemeralKeyPair extends Serializable { /** * Returns the public key of the key pair. * @return EphemeralPublicKey + * @group Implementation + * @category Account (On-Chain Model) */ getPublicKey(): EphemeralPublicKey { return this.publicKey; @@ -96,6 +112,8 @@ export class EphemeralKeyPair extends Serializable { /** * Checks if the current time has surpassed the expiry date of the key pair. * @return boolean - Returns true if the key pair is expired, otherwise false. + * @group Implementation + * @category Account (On-Chain Model) */ isExpired(): boolean { const currentTimeSecs: number = Math.floor(Date.now() / 1000); @@ -107,6 +125,8 @@ export class EphemeralKeyPair extends Serializable { * This function is essential for preparing the object data for serialization processes. * * @param serializer - The serializer instance used to serialize the object's properties. + * @group Implementation + * @category Account (On-Chain Model) */ serialize(serializer: Serializer): void { serializer.serializeU32AsUleb128(this.publicKey.variant); @@ -120,6 +140,8 @@ export class EphemeralKeyPair extends Serializable { * This function helps in reconstructing an ephemeral key pair, which is essential for cryptographic operations. * * @param deserializer - The deserializer instance used to read the serialized data. + * @group Implementation + * @category Account (On-Chain Model) */ static deserialize(deserializer: Deserializer): EphemeralKeyPair { const variantIndex = deserializer.deserializeUleb128AsU32(); @@ -141,6 +163,8 @@ export class EphemeralKeyPair extends Serializable { * This function allows you to reconstruct an EphemeralKeyPair from its serialized byte representation. * * @param bytes - The byte array representing the serialized EphemeralKeyPair. + * @group Implementation + * @category Account (On-Chain Model) */ static fromBytes(bytes: Uint8Array): EphemeralKeyPair { return EphemeralKeyPair.deserialize(new Deserializer(bytes)); @@ -154,6 +178,8 @@ export class EphemeralKeyPair extends Serializable { * @param args.scheme - The type of key pair to use for the EphemeralKeyPair. Only Ed25519 is supported for now. * @param args.expiryDateSecs - The date of expiry for the key pair in seconds. * @returns An instance of EphemeralKeyPair containing the generated private key and expiry date. + * @group Implementation + * @category Account (On-Chain Model) */ static generate(args?: { scheme?: EphemeralPublicKeyVariant; expiryDateSecs?: number }): EphemeralKeyPair { let privateKey: PrivateKey; @@ -174,6 +200,8 @@ export class EphemeralKeyPair extends Serializable { * @param data - The data to be signed, provided in HexInput format. * @returns EphemeralSignature - The resulting ephemeral signature. * @throws Error - Throws an error if the EphemeralKeyPair has expired. + * @group Implementation + * @category Account (On-Chain Model) */ sign(data: HexInput): EphemeralSignature { if (this.isExpired()) { @@ -186,6 +214,8 @@ export class EphemeralKeyPair extends Serializable { /** * Generates a random byte array of length EphemeralKeyPair.BLINDER_LENGTH. * @returns Uint8Array A random byte array used for blinding. + * @group Implementation + * @category Account (On-Chain Model) */ function generateBlinder(): Uint8Array { return randomBytes(EphemeralKeyPair.BLINDER_LENGTH); diff --git a/src/account/FederatedKeylessAccount.ts b/src/account/FederatedKeylessAccount.ts index ac9a91428..097c928c7 100644 --- a/src/account/FederatedKeylessAccount.ts +++ b/src/account/FederatedKeylessAccount.ts @@ -21,10 +21,14 @@ import { AbstractKeylessAccount, ProofFetchCallback } from "./AbstractKeylessAcc * * When the proof expires or the JWT becomes invalid, the KeylessAccount must be instantiated again with a new JWT, * EphemeralKeyPair, and corresponding proof. + * @group Implementation + * @category Account (On-Chain Model) */ export class FederatedKeylessAccount extends AbstractKeylessAccount { /** * The FederatedKeylessPublicKey associated with the account + * @group Implementation + * @category Account (On-Chain Model) */ readonly publicKey: FederatedKeylessPublicKey; diff --git a/src/account/KeylessAccount.ts b/src/account/KeylessAccount.ts index 6c560f005..00495a83f 100644 --- a/src/account/KeylessAccount.ts +++ b/src/account/KeylessAccount.ts @@ -22,10 +22,14 @@ import { AbstractKeylessAccount, ProofFetchCallback } from "./AbstractKeylessAcc * * @static * @readonly PEPPER_LENGTH - The length of the pepper used for privacy preservation. + * @group Implementation + * @category Account (On-Chain Model) */ export class KeylessAccount extends AbstractKeylessAccount { /** * The KeylessPublicKey associated with the account + * @group Implementation + * @category Account (On-Chain Model) */ readonly publicKey: KeylessPublicKey; @@ -35,6 +39,8 @@ export class KeylessAccount extends AbstractKeylessAccount { * Creates an instance of the transaction with an optional proof. * * @param args.proof - An optional ZkProof associated with the transaction. + * @group Implementation + * @category Account (On-Chain Model) */ // TODO: Document rest of parameters private constructor(args: { @@ -59,6 +65,8 @@ export class KeylessAccount extends AbstractKeylessAccount { * This function ensures that both the transaction bytes and the proof are properly serialized. * * @param serializer - The serializer instance used to convert the transaction data into bytes. + * @group Implementation + * @category Account (On-Chain Model) */ serialize(serializer: Serializer): void { serializer.serializeStr(this.jwt); @@ -77,6 +85,8 @@ export class KeylessAccount extends AbstractKeylessAccount { * * @param deserializer - The deserializer instance used to retrieve the serialized data. * @returns A KeylessAccount instance created from the deserialized data. + * @group Implementation + * @category Account (On-Chain Model) */ static deserialize(deserializer: Deserializer): KeylessAccount { const jwt = deserializer.deserializeStr(); @@ -109,6 +119,8 @@ export class KeylessAccount extends AbstractKeylessAccount { * @param args.pepper - A hexadecimal input used for additional security. * @param args.uidKey - Optional key for user identification, defaults to "sub". * @param args.proofFetchCallback - Optional callback function for fetching proof. + * @group Implementation + * @category Account (On-Chain Model) */ static create(args: { address?: AccountAddress; diff --git a/src/account/MultiKeyAccount.ts b/src/account/MultiKeyAccount.ts index 6cb37d8ac..af54e3ada 100644 --- a/src/account/MultiKeyAccount.ts +++ b/src/account/MultiKeyAccount.ts @@ -14,6 +14,8 @@ import { AbstractKeylessAccount } from "./AbstractKeylessAccount"; * * @param message - The original message that was signed. * @param signature - The multi-key signature to be verified. + * @group Implementation + * @category Account (On-Chain Model) */ export interface VerifyMultiKeySignatureArgs { message: HexInput; @@ -27,20 +29,28 @@ export interface VerifyMultiKeySignatureArgs { * It signs messages using an array of M accounts, each corresponding to a public key in the {@link MultiKey}. * * Note: Generating a signer instance does not create the account on-chain. + * @group Implementation + * @category Account (On-Chain Model) */ export class MultiKeyAccount implements Account { /** * Public key associated with the account + * @group Implementation + * @category Account (On-Chain Model) */ readonly publicKey: MultiKey; /** * Account address associated with the account + * @group Implementation + * @category Account (On-Chain Model) */ readonly accountAddress: AccountAddress; /** * Signing scheme used to sign transactions + * @group Implementation + * @category Account (On-Chain Model) */ readonly signingScheme: SigningScheme; @@ -48,12 +58,16 @@ export class MultiKeyAccount implements Account { * The signers used to sign messages. These signers should correspond to public keys in the * MultiKeyAccount's public key. The number of signers should be equal or greater * than this.publicKey.signaturesRequired + * @group Implementation + * @category Account (On-Chain Model) */ readonly signers: Account[]; /** * An array of indices where for signer[i], signerIndicies[i] is the index of the corresponding public key in * publicKey.publicKeys. Used to derive the right public key to use for verification. + * @group Implementation + * @category Account (On-Chain Model) */ // TODO: Rename Indicies to Indices readonly signerIndicies: number[]; @@ -67,6 +81,8 @@ export class MultiKeyAccount implements Account { * @param args.multiKey - The multikey of the account consisting of N public keys and a number M representing the required signatures. * @param args.signers - An array of M signers that will be used to sign the transaction. * @param args.address - An optional account address input. If not provided, the derived address from the public key will be used. + * @group Implementation + * @category Account (On-Chain Model) */ constructor(args: { multiKey: MultiKey; signers: Account[]; address?: AccountAddressInput }) { const { multiKey, signers, address } = args; @@ -99,6 +115,8 @@ export class MultiKeyAccount implements Account { * @param args.signaturesRequired - The number of signatures required to authorize a transaction. * @param args.signers - An array of M signers that will be used to sign the transaction. * @returns MultiKeyAccount - The newly created MultiKeyAccount. + * @group Implementation + * @category Account (On-Chain Model) */ static fromPublicKeysAndSigners(args: { publicKeys: PublicKey[]; @@ -115,6 +133,8 @@ export class MultiKeyAccount implements Account { * * @param account - The account to check. * @returns A boolean indicating whether the account is a multi-key account. + * @group Implementation + * @category Account (On-Chain Model) */ static isMultiKeySigner(account: Account): account is MultiKeyAccount { return account instanceof MultiKeyAccount; @@ -125,6 +145,8 @@ export class MultiKeyAccount implements Account { * account's public key. * @param message - The signing message, represented as binary input in hexadecimal format. * @returns An instance of AccountAuthenticatorMultiKey that includes the signature and the public key. + * @group Implementation + * @category Account (On-Chain Model) */ signWithAuthenticator(message: HexInput): AccountAuthenticatorMultiKey { return new AccountAuthenticatorMultiKey(this.publicKey, this.sign(message)); @@ -135,6 +157,8 @@ export class MultiKeyAccount implements Account { * account's public key. * @param transaction - The raw transaction to be signed. * @returns An AccountAuthenticatorMultiKey containing the signature of the transaction along with the account's public key. + * @group Implementation + * @category Account (On-Chain Model) */ signTransactionWithAuthenticator(transaction: AnyRawTransaction): AccountAuthenticatorMultiKey { return new AccountAuthenticatorMultiKey(this.publicKey, this.signTransaction(transaction)); @@ -144,6 +168,8 @@ export class MultiKeyAccount implements Account { * Waits for any proofs on KeylessAccount signers to be fetched. This ensures that signing with the KeylessAccount does not * fail due to missing proofs. * @return {Promise} A promise that resolves when all proofs have been fetched. + * @group Implementation + * @category Account (On-Chain Model) */ async waitForProofFetch(): Promise { const keylessSigners = this.signers.filter( @@ -157,6 +183,8 @@ export class MultiKeyAccount implements Account { * Sign the given data using the MultiKeyAccount's signers. * @param data - The data to be signed in HexInput format. * @returns MultiKeySignature - The resulting multi-key signature. + * @group Implementation + * @category Account (On-Chain Model) */ sign(data: HexInput): MultiKeySignature { const signatures = []; @@ -172,6 +200,8 @@ export class MultiKeyAccount implements Account { * * @param transaction - The transaction to be signed. * @returns MultiKeySignature - An object containing the aggregated signatures and a bitmap of the signatures. + * @group Implementation + * @category Account (On-Chain Model) */ signTransaction(transaction: AnyRawTransaction): MultiKeySignature { const signatures = []; @@ -190,6 +220,8 @@ export class MultiKeyAccount implements Account { * @param args.message - The raw message data in HexInput format. * @param args.signature - The signed message MultiKeySignature containing multiple signatures. * @returns A boolean indicating whether the signatures are valid for the message. + * @group Implementation + * @category Account (On-Chain Model) */ verifySignature(args: VerifyMultiKeySignatureArgs): boolean { const { message, signature } = args; diff --git a/src/account/SingleKeyAccount.ts b/src/account/SingleKeyAccount.ts index 0e200dd84..56d13d1b3 100644 --- a/src/account/SingleKeyAccount.ts +++ b/src/account/SingleKeyAccount.ts @@ -11,6 +11,8 @@ import { AnyRawTransaction } from "../transactions/types"; * * @param privateKey - The private key used for signing. * @param address - Optional account address associated with the signer. + * @group Implementation + * @category Account (On-Chain Model) */ export interface SingleKeySignerConstructorArgs { privateKey: PrivateKey; @@ -21,6 +23,8 @@ export interface SingleKeySignerConstructorArgs { * Arguments for generating a single key signer. * * @param scheme - The signing scheme to be used. + * @group Implementation + * @category Account (On-Chain Model) */ export interface SingleKeySignerGenerateArgs { scheme?: SigningSchemeInput; @@ -28,6 +32,8 @@ export interface SingleKeySignerGenerateArgs { /** * The arguments for generating a single key signer from a specified derivation path. + * @group Implementation + * @category Account (On-Chain Model) */ export type SingleKeySignerFromDerivationPathArgs = SingleKeySignerGenerateArgs & { path: string; @@ -39,6 +45,8 @@ export type SingleKeySignerFromDerivationPathArgs = SingleKeySignerGenerateArgs * * @param message - The message to be verified, represented in hexadecimal format. * @param signature - The signature that corresponds to the message. + * @group Implementation + * @category Account (On-Chain Model) */ export interface VerifySingleKeySignatureArgs { message: HexInput; @@ -51,10 +59,14 @@ export interface VerifySingleKeySignatureArgs { * Currently, the only supported signature schemes are Ed25519 and Secp256k1. * * Note: Generating a signer instance does not create the account on-chain. + * @group Implementation + * @category Account (On-Chain Model) */ export class SingleKeyAccount implements Account { /** * Private key associated with the account + * @group Implementation + * @category Account (On-Chain Model) */ readonly privateKey: PrivateKey; @@ -71,6 +83,8 @@ export class SingleKeyAccount implements Account { * @param args - The constructor arguments for initializing the SingleKeySigner. * @param args.privateKey - The private key used for signing. * @param args.address - The optional account address; if not provided, it will derive the address from the public key. + * @group Implementation + * @category Account (On-Chain Model) */ constructor(args: SingleKeySignerConstructorArgs) { const { privateKey, address } = args; @@ -87,6 +101,8 @@ export class SingleKeyAccount implements Account { * @param args.scheme - The signing scheme to use for generating the private key. Defaults to SigningSchemeInput.Ed25519. * @returns An account with the generated private key based on the specified signing scheme. * @throws Error if an unsupported signature scheme is provided. + * @group Implementation + * @category Account (On-Chain Model) */ static generate(args: SingleKeySignerGenerateArgs = {}) { const { scheme = SigningSchemeInput.Ed25519 } = args; @@ -114,6 +130,8 @@ export class SingleKeyAccount implements Account { * (e.g. m/44'/637'/0'/0/0) for secp256k1. * Detailed description: {@link https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki} * @param args.mnemonic - The mnemonic seed phrase of the account. + * @group Implementation + * @category Account (On-Chain Model) */ static fromDerivationPath(args: SingleKeySignerFromDerivationPathArgs) { const { scheme = SigningSchemeInput.Ed25519, path, mnemonic } = args; @@ -138,6 +156,8 @@ export class SingleKeyAccount implements Account { * @param args.message - The raw message data in HexInput format. * @param args.signature - The signed message signature. * @returns A boolean indicating whether the signature is valid. + * @group Implementation + * @category Account (On-Chain Model) */ verifySignature(args: VerifySingleKeySignatureArgs): boolean { return this.publicKey.verifySignature(args); @@ -148,6 +168,8 @@ export class SingleKeyAccount implements Account { * account's public key. * @param message - The signing message, represented as binary input in hexadecimal format. * @returns An instance of AccountAuthenticatorSingleKey containing the signature and the public key. + * @group Implementation + * @category Account (On-Chain Model) */ signWithAuthenticator(message: HexInput): AccountAuthenticatorSingleKey { return new AccountAuthenticatorSingleKey(this.publicKey, this.sign(message)); @@ -158,6 +180,8 @@ export class SingleKeyAccount implements Account { * This function returns an AccountAuthenticator that contains the signature of the transaction along with the account's public key. * @param transaction - The raw transaction to be signed. * @returns An AccountAuthenticatorSingleKey containing the signature of the transaction and the account's public key. + * @group Implementation + * @category Account (On-Chain Model) */ signTransactionWithAuthenticator(transaction: AnyRawTransaction): AccountAuthenticatorSingleKey { return new AccountAuthenticatorSingleKey(this.publicKey, this.signTransaction(transaction)); @@ -167,6 +191,8 @@ export class SingleKeyAccount implements Account { * Sign the given message using the account's private key. * @param message - The message to be signed in HexInput format. * @returns A new AnySignature containing the signature of the message. + * @group Implementation + * @category Account (On-Chain Model) */ sign(message: HexInput): AnySignature { return new AnySignature(this.privateKey.sign(message)); @@ -178,6 +204,8 @@ export class SingleKeyAccount implements Account { * * @param transaction - The transaction to be signed. * @returns Signature - The resulting signature for the signed transaction. + * @group Implementation + * @category Account (On-Chain Model) */ signTransaction(transaction: AnyRawTransaction): AnySignature { return this.sign(generateSigningMessageForTransaction(transaction)); diff --git a/src/api/account.ts b/src/api/account.ts index 7eedd1e70..83dd296b0 100644 --- a/src/api/account.ts +++ b/src/api/account.ts @@ -50,6 +50,7 @@ import { memoizeAsync } from "../utils/memoize"; /** * A class to query all `Account` related queries on Aptos. + * @group Account */ export class Account { /** @@ -70,6 +71,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ constructor(readonly config: AptosConfig) {} @@ -94,6 +96,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountInfo(args: { accountAddress: AccountAddressInput }): Promise { return getInfo({ aptosConfig: this.config, ...args }); @@ -131,6 +134,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountModules(args: { accountAddress: AccountAddressInput; @@ -166,6 +170,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountModule(args: { accountAddress: AccountAddressInput; @@ -207,6 +212,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountTransactions(args: { accountAddress: AccountAddressInput; @@ -242,6 +248,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountResources(args: { accountAddress: AccountAddressInput; @@ -277,6 +284,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountResource(args: { accountAddress: AccountAddressInput; @@ -311,6 +319,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async lookupOriginalAccountAddress(args: { authenticationKey: AccountAddressInput; @@ -342,6 +351,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountTokensCount(args: { accountAddress: AccountAddressInput; @@ -391,6 +401,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountOwnedTokens(args: { accountAddress: AccountAddressInput; @@ -440,6 +451,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountOwnedTokensFromCollectionAddress(args: { accountAddress: AccountAddressInput; @@ -491,6 +503,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountCollectionsWithOwnedTokens(args: { accountAddress: AccountAddressInput; @@ -534,6 +547,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountTransactionsCount(args: { accountAddress: AccountAddressInput; @@ -582,6 +596,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountCoinsData(args: { accountAddress: AccountAddressInput; @@ -623,6 +638,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountCoinsCount(args: { accountAddress: AccountAddressInput; @@ -658,6 +674,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountAPTAmount(args: { accountAddress: AccountAddressInput; @@ -696,6 +713,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountCoinAmount(args: { accountAddress: AccountAddressInput; @@ -813,6 +831,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async getAccountOwnedObjects(args: { accountAddress: AccountAddressInput; @@ -860,6 +879,7 @@ export class Account { * } * runExample().catch(console.error); * ``` + * @group Account */ async deriveAccountFromPrivateKey(args: { privateKey: PrivateKey }): Promise { return deriveAccountFromPrivateKey({ aptosConfig: this.config, ...args }); diff --git a/src/api/ans.ts b/src/api/ans.ts index 9ed66b129..52dc8d1e7 100644 --- a/src/api/ans.ts +++ b/src/api/ans.ts @@ -30,6 +30,7 @@ import { SimpleTransaction } from "../transactions/instances/simpleTransaction"; /** * A class to handle all `ANS` operations. + * @group ANS */ export class ANS { /** @@ -56,6 +57,7 @@ export class ANS { * } * runExample().catch(console.error); * ``` + * @group ANS */ constructor(readonly config: AptosConfig) {} @@ -81,6 +83,7 @@ export class ANS { * } * runExample().catch(console.error); * ``` + * @group ANS */ async getOwnerAddress(args: { name: string }): Promise { return getOwnerAddress({ aptosConfig: this.config, ...args }); @@ -110,6 +113,7 @@ export class ANS { * } * runExample().catch(console.error); * ``` + * @group ANS */ async getExpiration(args: { name: string }): Promise { return getExpiration({ aptosConfig: this.config, ...args }); @@ -140,6 +144,7 @@ export class ANS { * } * runExample().catch(console.error); * ``` + * @group ANS */ async getTargetAddress(args: { name: string }): Promise { return getTargetAddress({ aptosConfig: this.config, ...args }); @@ -180,6 +185,7 @@ export class ANS { * } * runExample().catch(console.error); * ``` + * @group ANS */ async setTargetAddress(args: { sender: Account; @@ -212,6 +218,7 @@ export class ANS { * } * runExample().catch(console.error); * ``` + * @group ANS */ async getPrimaryName(args: { address: AccountAddressInput }): Promise { return getPrimaryName({ aptosConfig: this.config, ...args }); @@ -245,6 +252,7 @@ export class ANS { * } * runExample().catch(console.error); * ``` + * @group ANS */ async setPrimaryName(args: { sender: Account; @@ -299,6 +307,7 @@ export class ANS { * } * runExample().catch(console.error); * ``` + * @group ANS */ async registerName(args: Omit): Promise { return registerName({ aptosConfig: this.config, ...args }); @@ -334,6 +343,7 @@ export class ANS { * } * runExample().catch(console.error); * ``` + * @group ANS */ async renewDomain(args: { sender: Account; @@ -367,6 +377,7 @@ export class ANS { * } * runExample().catch(console.error); * ``` + * @group ANS */ async getName(args: { name: string }): Promise { return getName({ aptosConfig: this.config, ...args }); @@ -406,6 +417,7 @@ export class ANS { * } * runExample().catch(console.error); * ``` + * @group ANS */ async getAccountNames(args: GetAccountNamesArgs): Promise { return getAccountNames({ aptosConfig: this.config, ...args }); @@ -448,6 +460,7 @@ export class ANS { * } * runExample().catch(console.error); * ``` + * @group ANS */ async getAccountDomains(args: GetAccountDomainsArgs): Promise { return getAccountDomains({ aptosConfig: this.config, ...args }); @@ -488,6 +501,7 @@ export class ANS { * } * runExample().catch(console.error); * ``` + * @group ANS */ async getAccountSubdomains(args: GetAccountSubdomainsArgs): Promise { return getAccountSubdomains({ aptosConfig: this.config, ...args }); @@ -528,6 +542,7 @@ export class ANS { * } * runExample().catch(console.error); * ``` + * @group ANS */ async getDomainSubdomains(args: GetDomainSubdomainsArgs): Promise { return getDomainSubdomains({ aptosConfig: this.config, ...args }); diff --git a/src/api/aptos.ts b/src/api/aptos.ts index 297f6c343..23a114e38 100644 --- a/src/api/aptos.ts +++ b/src/api/aptos.ts @@ -39,6 +39,7 @@ import { AptosObject } from "./object"; * } * runExample().catch(console.error); * ``` + * @group Client */ export class Aptos { readonly config: AptosConfig; @@ -88,6 +89,7 @@ export class Aptos { * } * runExample().catch(console.error); * ``` + * @group Client */ constructor(settings?: AptosConfig) { this.config = new AptosConfig(settings); @@ -131,6 +133,7 @@ that we can combine to form a single class that contains all the methods and pro {@link https://www.typescriptlang.org/docs/handbook/mixins.html#alternative-pattern} Here, we combine any subclass and the Aptos class. + * @group Client */ function applyMixin(targetClass: any, baseClass: any, baseClassProp: string) { // Mixin instance methods diff --git a/src/api/aptosConfig.ts b/src/api/aptosConfig.ts index bea9c473a..1978c8aeb 100644 --- a/src/api/aptosConfig.ts +++ b/src/api/aptosConfig.ts @@ -32,60 +32,72 @@ import { AptosApiType } from "../utils/const"; * } * runExample().catch(console.error); * ``` + * @group Client */ export class AptosConfig { /** * The Network that this SDK is associated with. Defaults to DEVNET + * @group Client */ readonly network: Network; /** * The client instance the SDK uses. Defaults to `@aptos-labs/aptos-client + * @group Client */ readonly client: Client; /** * The optional hardcoded fullnode URL to send requests to instead of using the network + * @group Client */ readonly fullnode?: string; /** * The optional hardcoded faucet URL to send requests to instead of using the network + * @group Client */ readonly faucet?: string; /** * The optional hardcoded pepper service URL to send requests to instead of using the network + * @group Client */ readonly pepper?: string; /** * The optional hardcoded prover service URL to send requests to instead of using the network + * @group Client */ readonly prover?: string; /** * The optional hardcoded indexer URL to send requests to instead of using the network + * @group Client */ readonly indexer?: string; /** * Optional client configurations + * @group Client */ readonly clientConfig?: ClientConfig; /** * Optional specific Fullnode configurations + * @group Client */ readonly fullnodeConfig?: FullNodeConfig; /** * Optional specific Indexer configurations + * @group Client */ readonly indexerConfig?: IndexerConfig; /** * Optional specific Faucet configurations + * @group Client */ readonly faucetConfig?: FaucetConfig; @@ -119,6 +131,7 @@ export class AptosConfig { * } * runExample().catch(console.error); * ``` + * @group Client */ constructor(settings?: AptosSettings) { this.network = settings?.network ?? Network.DEVNET; @@ -154,6 +167,7 @@ export class AptosConfig { * } * runExample().catch(console.error); * ``` + * @group Client */ getRequestUrl(apiType: AptosApiType): string { switch (apiType) { @@ -204,6 +218,7 @@ export class AptosConfig { * } * runExample().catch(console.error); * ``` + * @group Client */ isPepperServiceRequest(url: string): boolean { return NetworkToPepperAPI[this.network] === url; @@ -228,6 +243,7 @@ export class AptosConfig { * * console.log(`Is the URL a known prover service? ${isProver}`); * ``` + * @group Client */ isProverServiceRequest(url: string): boolean { return NetworkToProverAPI[this.network] === url; diff --git a/src/api/coin.ts b/src/api/coin.ts index 2cd7a57ec..a2ba9b60f 100644 --- a/src/api/coin.ts +++ b/src/api/coin.ts @@ -10,6 +10,7 @@ import { AptosConfig } from "./aptosConfig"; /** * A class to handle all `Coin` operations. + * @group Coin */ export class Coin { /** @@ -31,6 +32,7 @@ export class Coin { * } * runExample().catch(console.error); * ``` + * @group Coin */ constructor(readonly config: AptosConfig) {} @@ -67,6 +69,7 @@ export class Coin { * } * runExample().catch(console.error); * ``` + * @group Coin */ async transferCoinTransaction(args: { sender: AccountAddressInput; diff --git a/src/api/digitalAsset.ts b/src/api/digitalAsset.ts index 36782495a..7d87c7226 100644 --- a/src/api/digitalAsset.ts +++ b/src/api/digitalAsset.ts @@ -52,6 +52,7 @@ import { SimpleTransaction } from "../transactions/instances/simpleTransaction"; /** * A class to query all `DigitalAsset` related queries on Aptos. + * @group DigitalAsset */ export class DigitalAsset { /** @@ -75,6 +76,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ constructor(readonly config: AptosConfig) {} @@ -111,6 +113,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async getCollectionData(args: { creatorAddress: AccountAddressInput; @@ -169,6 +172,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async getCollectionDataByCreatorAddressAndCollectionName(args: { creatorAddress: AccountAddressInput; @@ -217,6 +221,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async getCollectionDataByCreatorAddress(args: { creatorAddress: AccountAddressInput; @@ -257,6 +262,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async getCollectionDataByCollectionId(args: { collectionId: AccountAddressInput; @@ -299,6 +305,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async getCollectionId(args: { creatorAddress: AccountAddressInput; @@ -339,6 +346,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async getDigitalAssetData(args: { digitalAssetAddress: AccountAddressInput; @@ -378,6 +386,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async getCurrentDigitalAssetOwnership(args: { digitalAssetAddress: AccountAddressInput; @@ -417,6 +426,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async getOwnedDigitalAssets(args: { ownerAddress: AccountAddressInput; @@ -458,6 +468,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async getDigitalAssetActivity(args: { digitalAssetAddress: AccountAddressInput; @@ -519,6 +530,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async createCollectionTransaction( args: { @@ -569,6 +581,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async mintDigitalAssetTransaction(args: { creator: Account; @@ -616,6 +629,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async transferDigitalAssetTransaction(args: { sender: Account; @@ -667,6 +681,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async mintSoulBoundTransaction(args: { account: Account; @@ -712,6 +727,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async burnDigitalAssetTransaction(args: { creator: Account; @@ -752,6 +768,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async freezeDigitalAssetTransaferTransaction(args: { creator: Account; @@ -792,6 +809,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ // TODO: Rename Transafer to Transfer async unfreezeDigitalAssetTransaferTransaction(args: { @@ -834,6 +852,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async setDigitalAssetDescriptionTransaction(args: { creator: Account; @@ -879,6 +898,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async setDigitalAssetNameTransaction(args: { creator: Account; @@ -920,6 +940,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async setDigitalAssetURITransaction(args: { creator: Account; @@ -966,6 +987,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async addDigitalAssetPropertyTransaction(args: { creator: Account; @@ -1015,6 +1037,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async removeDigitalAssetPropertyTransaction(args: { creator: Account; @@ -1063,6 +1086,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async updateDigitalAssetPropertyTransaction(args: { creator: Account; @@ -1113,6 +1137,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async addDigitalAssetTypedPropertyTransaction(args: { creator: Account; @@ -1162,6 +1187,7 @@ export class DigitalAsset { * } * runExample().catch(console.error); * ``` + * @group DigitalAsset */ async updateDigitalAssetTypedPropertyTransaction(args: { creator: Account; diff --git a/src/api/event.ts b/src/api/event.ts index faf75685a..068379481 100644 --- a/src/api/event.ts +++ b/src/api/event.ts @@ -16,6 +16,7 @@ import { waitForIndexerOnVersion } from "./utils"; /** * A class to query all `Event` Aptos related queries. + * @group Event */ export class Event { /** @@ -39,6 +40,7 @@ export class Event { * } * runExample().catch(console.error); * ``` + * @group Event */ constructor(readonly config: AptosConfig) {} @@ -71,6 +73,7 @@ export class Event { * } * runExample().catch(console.error); * ``` + * @group Event */ async getModuleEventsByEventType(args: { eventType: MoveStructId; @@ -113,6 +116,7 @@ export class Event { * } * runExample().catch(console.error); * ``` + * @group Event */ async getAccountEventsByCreationNumber(args: { accountAddress: AccountAddressInput; @@ -156,6 +160,7 @@ export class Event { * } * runExample().catch(console.error); * ``` + * @group Event */ async getAccountEventsByEventType(args: { accountAddress: AccountAddressInput; @@ -209,6 +214,7 @@ export class Event { * } * runExample().catch(console.error); * ``` + * @group Event */ async getEvents(args?: { minimumLedgerVersion?: AnyNumber; diff --git a/src/api/faucet.ts b/src/api/faucet.ts index a0db10c16..701c2a084 100644 --- a/src/api/faucet.ts +++ b/src/api/faucet.ts @@ -10,6 +10,7 @@ import { ProcessorType } from "../utils"; /** * A class to query all `Faucet` related queries on Aptos. + * @group Faucet */ export class Faucet { /** @@ -32,6 +33,7 @@ export class Faucet { * } * runExample().catch(console.error); * ``` + * @group Faucet */ constructor(readonly config: AptosConfig) {} @@ -62,6 +64,7 @@ export class Faucet { * } * runExample().catch(console.error); * ``` + * @group Faucet */ async fundAccount(args: { accountAddress: AccountAddressInput; diff --git a/src/api/fungibleAsset.ts b/src/api/fungibleAsset.ts index f3bc2eff5..5439310b1 100644 --- a/src/api/fungibleAsset.ts +++ b/src/api/fungibleAsset.ts @@ -30,6 +30,7 @@ import { SimpleTransaction } from "../transactions/instances/simpleTransaction"; /** * A class for querying and managing fungible asset-related operations on the Aptos blockchain. + * @group FungibleAsset */ export class FungibleAsset { /** @@ -53,6 +54,7 @@ export class FungibleAsset { * } * runExample().catch(console.error); * ``` + * @group FungibleAsset */ constructor(readonly config: AptosConfig) {} @@ -79,6 +81,7 @@ export class FungibleAsset { * } * runExample().catch(console.error); * ``` + * @group FungibleAsset */ async getFungibleAssetMetadata(args?: { minimumLedgerVersion?: AnyNumber; @@ -119,6 +122,7 @@ export class FungibleAsset { * } * runExample().catch(console.error); * ``` + * @group FungibleAsset */ async getFungibleAssetMetadataByAssetType(args: { assetType: string; @@ -169,6 +173,7 @@ export class FungibleAsset { * } * runExample().catch(console.error); * ``` + * @group FungibleAsset */ async getFungibleAssetMetadataByCreatorAddress(args: { creatorAddress: AccountAddressInput; @@ -213,6 +218,7 @@ export class FungibleAsset { * } * runExample().catch(console.error); * ``` + * @group FungibleAsset */ async getFungibleAssetActivities(args?: { minimumLedgerVersion?: AnyNumber; @@ -250,6 +256,7 @@ export class FungibleAsset { * } * runExample().catch(console.error); * ``` + * @group FungibleAsset */ async getCurrentFungibleAssetBalances(args?: { minimumLedgerVersion?: AnyNumber; @@ -297,6 +304,7 @@ export class FungibleAsset { * } * runExample().catch(console.error); * ``` + * @group FungibleAsset */ async transferFungibleAsset(args: { sender: Account; diff --git a/src/api/general.ts b/src/api/general.ts index afcd0e27d..9dff1f311 100644 --- a/src/api/general.ts +++ b/src/api/general.ts @@ -26,6 +26,7 @@ import { InputViewFunctionData, InputViewFunctionJsonData } from "../transaction /** * A class to query various Aptos-related information and perform operations on the Aptos blockchain. + * @group General */ export class General { readonly config: AptosConfig; @@ -56,6 +57,7 @@ export class General { * } * runExample().catch(console.error); * ``` + * @group General */ constructor(config: AptosConfig) { this.config = config; @@ -81,6 +83,7 @@ export class General { * } * runExample().catch(console.error); * ``` + * @group General */ async getLedgerInfo(): Promise { return getLedgerInfo({ aptosConfig: this.config }); @@ -105,6 +108,7 @@ export class General { * * @returns The chain ID of the Aptos blockchain. * ``` + * @group General */ async getChainId(): Promise { const result = await this.getLedgerInfo(); @@ -135,6 +139,7 @@ export class General { * } * runExample().catch(console.error); * ``` + * @group General */ async getBlockByVersion(args: { ledgerVersion: AnyNumber; @@ -170,6 +175,7 @@ export class General { * } * runExample().catch(console.error); * ``` + * @group General */ async getBlockByHeight(args: { blockHeight: AnyNumber; options?: { withTransactions?: boolean } }): Promise { return getBlockByHeight({ aptosConfig: this.config, ...args }); @@ -190,6 +196,7 @@ export class General { * }) * * @returns an array of Move values + * @group General */ async view>(args: { payload: InputViewFunctionData; @@ -213,6 +220,7 @@ export class General { * }) * * @returns an array of Move values + * @group General */ async viewJson>(args: { payload: InputViewFunctionJsonData; @@ -243,6 +251,7 @@ export class General { * } * runExample().catch(console.error); * ``` + * @group General */ async getChainTopUserTransactions(args: { limit: number }): Promise { return getChainTopUserTransactions({ @@ -281,6 +290,7 @@ export class General { * } * runExample().catch(console.error); * ``` + * @group General */ async queryIndexer(args: { query: GraphqlQuery }): Promise { return queryIndexer({ @@ -307,6 +317,7 @@ export class General { * } * runExample().catch(console.error); * ``` + * @group General */ async getIndexerLastSuccessVersion(): Promise { return getIndexerLastSuccessVersion({ aptosConfig: this.config }); @@ -332,6 +343,7 @@ export class General { * } * runExample().catch(console.error); * ``` + * @group General */ async getProcessorStatus(processorType: ProcessorType): Promise { return getProcessorStatus({ aptosConfig: this.config, processorType }); diff --git a/src/api/keyless.ts b/src/api/keyless.ts index 5e1c53bb7..cc3b06a0e 100644 --- a/src/api/keyless.ts +++ b/src/api/keyless.ts @@ -19,6 +19,7 @@ import { AptosConfig } from "./aptosConfig"; * * More documentation on how to integrate Keyless Accounts see the below * [Aptos Keyless Integration Guide](https://aptos.dev/guides/keyless-accounts/#aptos-keyless-integration-guide). + * @group Keyless */ export class Keyless { /** @@ -42,6 +43,7 @@ export class Keyless { * } * runExample().catch(console.error); * ``` + * @group Keyless */ constructor(readonly config: AptosConfig) {} @@ -77,6 +79,7 @@ export class Keyless { * } * runExample().catch(console.error); * ``` + * @group Keyless */ async getPepper(args: { jwt: string; @@ -120,6 +123,7 @@ export class Keyless { * } * runExample().catch(console.error); * ``` + * @group Keyless */ async getProof(args: { jwt: string; @@ -186,6 +190,7 @@ export class Keyless { * } * runExample().catch(console.error); * ``` + * @group Keyless */ async deriveKeylessAccount(args: { jwt: string; @@ -209,6 +214,7 @@ export class Keyless { * @param args.jwksUrl the URL to find the corresponding JWKs. For supported IDP providers this parameter in not necessary. * * @returns The pending transaction that results from submission. + * @group Keyless */ async updateFederatedKeylessJwkSetTransaction(args: { sender: Account; diff --git a/src/api/object.ts b/src/api/object.ts index 7417ccd5b..7b4059af3 100644 --- a/src/api/object.ts +++ b/src/api/object.ts @@ -10,6 +10,7 @@ import { getObjectDataByObjectAddress } from "../internal/object"; /** * A class to query all `Object` related queries on Aptos. + * @group Object */ export class AptosObject { /** @@ -39,6 +40,7 @@ export class AptosObject { * } * runExample().catch(console.error); * ``` + * @group Object */ constructor(readonly config: AptosConfig) {} @@ -68,6 +70,7 @@ export class AptosObject { * } * runExample().catch(console.error); * ``` + * @group Object */ async getObjectDataByObjectAddress(args: { objectAddress: AccountAddressInput; diff --git a/src/api/staking.ts b/src/api/staking.ts index 5fd5d03c2..fe6a4c5e4 100644 --- a/src/api/staking.ts +++ b/src/api/staking.ts @@ -14,6 +14,7 @@ import { waitForIndexerOnVersion } from "./utils"; /** * A class to query all `Staking` related queries on Aptos. + * @group Staking */ export class Staking { /** @@ -39,6 +40,7 @@ export class Staking { * } * runExample().catch(console.error); * ``` + * @group Staking */ constructor(readonly config: AptosConfig) {} @@ -64,6 +66,7 @@ export class Staking { * } * runExample().catch(console.error); * ``` + * @group Staking */ async getNumberOfDelegators(args: { poolAddress: AccountAddressInput; @@ -99,6 +102,7 @@ export class Staking { * } * runExample().catch(console.error); * ``` + * @group Staking */ async getNumberOfDelegatorsForAllPools(args?: { minimumLedgerVersion?: AnyNumber; @@ -140,6 +144,7 @@ export class Staking { * } * runExample().catch(console.error); * ``` + * @group Staking */ async getDelegatedStakingActivities(args: { delegatorAddress: AccountAddressInput; diff --git a/src/api/table.ts b/src/api/table.ts index e458cf24a..426ee4119 100644 --- a/src/api/table.ts +++ b/src/api/table.ts @@ -16,6 +16,7 @@ import { waitForIndexerOnVersion } from "./utils"; /** * A class to query all `Table` Aptos related queries. + * @group Table */ export class Table { readonly config: AptosConfig; @@ -39,6 +40,7 @@ export class Table { * } * runExample().catch(console.error); * ``` + * @group Table */ constructor(config: AptosConfig) { this.config = config; @@ -79,6 +81,7 @@ export class Table { * } * runExample().catch(console.error); * ``` + * @group Table */ async getTableItem(args: { handle: string; data: TableItemRequest; options?: LedgerVersionArg }): Promise { return getTableItem({ aptosConfig: this.config, ...args }); @@ -124,6 +127,7 @@ export class Table { * ``` * * @returns GetTableItemsDataResponse + * @group Table */ async getTableItemsData(args: { minimumLedgerVersion?: AnyNumber; @@ -173,6 +177,7 @@ export class Table { * ``` * * @returns GetTableItemsMetadataResponse + * @group Table */ async getTableItemsMetadata(args: { minimumLedgerVersion?: AnyNumber; diff --git a/src/api/transaction.ts b/src/api/transaction.ts index 1aec8ad53..5fd26d034 100644 --- a/src/api/transaction.ts +++ b/src/api/transaction.ts @@ -126,6 +126,7 @@ import { SimpleTransaction } from "../transactions/instances/simpleTransaction"; * * example(); * ``` + * @group Transaction */ export class Transaction { readonly config: AptosConfig; @@ -159,6 +160,7 @@ export class Transaction { * } * runExample().catch(console.error); * ``` + * @group Transaction */ constructor(config: AptosConfig) { this.config = config; @@ -199,6 +201,7 @@ export class Transaction { * } * runExample().catch(console.error); * ``` + * @group Transaction */ async getTransactions(args?: { options?: PaginationArgs }): Promise { return getTransactions({ @@ -229,6 +232,7 @@ export class Transaction { * } * runExample().catch(console.error); * ``` + * @group Transaction */ async getTransactionByVersion(args: { ledgerVersion: AnyNumber }): Promise { return getTransactionByVersion({ @@ -259,6 +263,7 @@ export class Transaction { * } * runExample().catch(console.error); * ``` + * @group Transaction */ async getTransactionByHash(args: { transactionHash: HexInput }): Promise { return getTransactionByHash({ @@ -289,6 +294,7 @@ export class Transaction { * } * runExample().catch(console.error); * ``` + * @group Transaction */ async isPendingTransaction(args: { transactionHash: HexInput }): Promise { return isTransactionPending({ @@ -340,6 +346,7 @@ export class Transaction { * } * runExample().catch(console.error); * ``` + * @group Transaction */ async waitForTransaction(args: { transactionHash: HexInput; @@ -373,6 +380,7 @@ export class Transaction { * } * runExample().catch(console.error); * ``` + * @group Transaction */ async getGasPriceEstimation(): Promise { return getGasPriceEstimation({ @@ -407,6 +415,7 @@ export class Transaction { * } * runExample().catch(console.error); * ``` + * @group Transaction */ // eslint-disable-next-line class-methods-use-this getSigningMessage(args: { transaction: AnyRawTransaction }): Uint8Array { @@ -453,6 +462,7 @@ export class Transaction { * } * runExample().catch(console.error); * ``` + * @group Transaction */ async publishPackageTransaction(args: { account: AccountAddressInput; @@ -494,6 +504,7 @@ export class Transaction { * } * runExample().catch(console.error); * ``` + * @group Transaction */ async rotateAuthKey(args: { fromAccount: Account; toNewPrivateKey: PrivateKey }): Promise { return rotateAuthKey({ aptosConfig: this.config, ...args }); @@ -535,6 +546,7 @@ export class Transaction { * } * runExample().catch(console.error); * ``` + * @group Transaction */ // eslint-disable-next-line class-methods-use-this sign(args: { signer: Account; transaction: AnyRawTransaction }): AccountAuthenticator { @@ -578,6 +590,7 @@ export class Transaction { * } * runExample().catch(console.error); * ``` + * @group Transaction */ // eslint-disable-next-line class-methods-use-this signAsFeePayer(args: { signer: Account; transaction: AnyRawTransaction }): AccountAuthenticator { @@ -626,6 +639,7 @@ export class Transaction { * } * runExample().catch(console.error); * ``` + * @group Transaction */ async batchTransactionsForSingleAccount(args: { sender: Account; @@ -676,6 +690,7 @@ export class Transaction { * runExample().catch(console.error); * ``` * @return PendingTransactionResponse + * @group Transaction */ async signAndSubmitTransaction( args: FeePayerOrFeePayerAuthenticatorOrNeither & { @@ -706,6 +721,7 @@ export class Transaction { * }) * * @return PendingTransactionResponse + * @group Transaction */ async signAndSubmitAsFeePayer(args: { feePayer: Account; diff --git a/src/api/transactionSubmission/build.ts b/src/api/transactionSubmission/build.ts index e56fbbce0..2a2d00642 100644 --- a/src/api/transactionSubmission/build.ts +++ b/src/api/transactionSubmission/build.ts @@ -10,6 +10,7 @@ import { AptosConfig } from "../aptosConfig"; /** * A class to handle all `Build` transaction operations. + * @group Implementation */ export class Build { readonly config: AptosConfig; @@ -41,6 +42,7 @@ export class Build { * } * runExample().catch(console.error); * ``` + * @group Implementation */ constructor(config: AptosConfig) { this.config = config; @@ -83,6 +85,7 @@ export class Build { * } * runExample().catch(console.error); * ``` + * @group Implementation */ async simple(args: { sender: AccountAddressInput; @@ -133,6 +136,7 @@ export class Build { * } * runExample().catch(console.error); * ``` + * @group Implementation */ async multiAgent(args: { sender: AccountAddressInput; diff --git a/src/api/transactionSubmission/helpers.ts b/src/api/transactionSubmission/helpers.ts index 21bd71338..418878fc6 100644 --- a/src/api/transactionSubmission/helpers.ts +++ b/src/api/transactionSubmission/helpers.ts @@ -43,6 +43,7 @@ * } * runExample().catch(console.error); * ``` + * @group Implementation */ export function ValidateFeePayerDataOnSubmission(target: unknown, propertyKey: string, descriptor: PropertyDescriptor) { const originalMethod = descriptor.value; @@ -92,6 +93,7 @@ export function ValidateFeePayerDataOnSubmission(target: unknown, propertyKey: s * } * runExample().catch(console.error); * ``` + * @group Implementation */ export function ValidateFeePayerDataOnSimulation(target: unknown, propertyKey: string, descriptor: PropertyDescriptor) { const originalMethod = descriptor.value; diff --git a/src/api/transactionSubmission/management.ts b/src/api/transactionSubmission/management.ts index 5fa86eb03..9fbe50766 100644 --- a/src/api/transactionSubmission/management.ts +++ b/src/api/transactionSubmission/management.ts @@ -38,6 +38,7 @@ export class TransactionManagement extends EventEmitter * } * runExample().catch(console.error); * ``` + * @group Implementation */ constructor(config: AptosConfig) { super(); @@ -68,6 +69,7 @@ export class TransactionManagement extends EventEmitter * } * runExample().catch(console.error); * ``` + * @group Implementation */ private start(args: { sender: Account }): void { const { sender } = args; @@ -108,6 +110,7 @@ export class TransactionManagement extends EventEmitter * } * runExample().catch(console.error); * ``` + * @group Implementation */ private push(args: { data: InputGenerateTransactionPayloadData[]; @@ -153,6 +156,7 @@ export class TransactionManagement extends EventEmitter * } * runExample().catch(console.error); * ``` + * @group Implementation */ private registerToEvents() { // TODO - Should we ask events to listen to this as an input? @@ -188,6 +192,7 @@ export class TransactionManagement extends EventEmitter * @param args.options optional. Transaction generation configurations (excluding accountSequenceNumber) * * @return void. Throws if any error + * @group Implementation */ forSingleAccount(args: { sender: Account; diff --git a/src/api/transactionSubmission/sign.ts b/src/api/transactionSubmission/sign.ts index bd6f4f6bd..5df6a10a8 100644 --- a/src/api/transactionSubmission/sign.ts +++ b/src/api/transactionSubmission/sign.ts @@ -10,6 +10,7 @@ import { AptosConfig } from "../aptosConfig"; * A class to handle all `Sign` transaction operations. * * @param config - The configuration object for Aptos. + * @group Implementation */ export class Sign { readonly config: AptosConfig; @@ -32,6 +33,7 @@ export class Sign { * } * runExample().catch(console.error); * ``` + * @group Implementation */ constructor(config: AptosConfig) { this.config = config; @@ -72,6 +74,7 @@ export class Sign { * } * runExample().catch(console.error); * ``` + * @group Implementation */ // eslint-disable-next-line class-methods-use-this transaction(args: { signer: Account; transaction: AnyRawTransaction }): AccountAuthenticator { @@ -116,6 +119,7 @@ export class Sign { * } * runExample().catch(console.error); * ``` + * @group Implementation */ // eslint-disable-next-line class-methods-use-this transactionAsFeePayer(args: { signer: Account; transaction: AnyRawTransaction }): AccountAuthenticator { diff --git a/src/api/transactionSubmission/simulate.ts b/src/api/transactionSubmission/simulate.ts index c54300cff..b35e54944 100644 --- a/src/api/transactionSubmission/simulate.ts +++ b/src/api/transactionSubmission/simulate.ts @@ -10,6 +10,7 @@ import { ValidateFeePayerDataOnSimulation } from "./helpers"; /** * A class to handle all `Simulate` transaction operations. + * @group Implementation */ export class Simulate { readonly config: AptosConfig; @@ -37,6 +38,7 @@ export class Simulate { * } * runExample().catch(console.error); * ``` + * @group Implementation */ constructor(config: AptosConfig) { this.config = config; @@ -97,6 +99,7 @@ export class Simulate { * * example(); * ``` + * @group Implementation */ @ValidateFeePayerDataOnSimulation async simple(args: { @@ -173,6 +176,7 @@ export class Simulate { * * example(); * ``` + * @group Implementation */ @ValidateFeePayerDataOnSimulation async multiAgent(args: { diff --git a/src/api/transactionSubmission/submit.ts b/src/api/transactionSubmission/submit.ts index 04651d026..1836ec2b1 100644 --- a/src/api/transactionSubmission/submit.ts +++ b/src/api/transactionSubmission/submit.ts @@ -9,6 +9,7 @@ import { ValidateFeePayerDataOnSubmission } from "./helpers"; /** * A class to handle all `Submit` transaction operations. + * @group Implementation */ export class Submit { readonly config: AptosConfig; @@ -41,6 +42,7 @@ export class Submit { * } * runExample().catch(console.error); * ``` + * @group Implementation */ constructor(config: AptosConfig) { this.config = config; @@ -82,6 +84,7 @@ export class Submit { * } * runExample().catch(console.error); * ``` + * @group Implementation */ @ValidateFeePayerDataOnSubmission async simple(args: { @@ -135,6 +138,7 @@ export class Submit { * } * runExample().catch(console.error); * ``` + * @group Implementation */ @ValidateFeePayerDataOnSubmission async multiAgent(args: { diff --git a/src/api/utils.ts b/src/api/utils.ts index 315d23778..133dfc04c 100644 --- a/src/api/utils.ts +++ b/src/api/utils.ts @@ -31,6 +31,7 @@ import { AnyNumber } from "../types"; * } * runExample().catch(console.error); * ``` + * @group Implementation */ export async function waitForIndexerOnVersion(args: { config: AptosConfig; diff --git a/src/bcs/deserializer.ts b/src/bcs/deserializer.ts index d7c267ef0..b95b7d7a0 100644 --- a/src/bcs/deserializer.ts +++ b/src/bcs/deserializer.ts @@ -12,6 +12,8 @@ import { Uint8, Uint16, Uint32, Uint64, Uint128, Uint256 } from "../types"; * for static methods in interfaces. * * @template T - The type that this will deserialize into. + * @group Implementation + * @category BCS */ export interface Deserializable { /** @@ -28,6 +30,8 @@ export interface Deserializable { * // value is now an instance of MyClass * // equivalent to `const value = MyClass.deserialize(deserializer)` * ``` + * @group Implementation + * @category BCS */ deserialize(deserializer: Deserializer): T; } @@ -35,6 +39,8 @@ export interface Deserializable { /** * A class that provides methods for deserializing various data types from a byte buffer. * It supports deserialization of primitive types, strings, and complex objects using a BCS (Binary Common Serialization) layout. + * @group Implementation + * @category BCS */ export class Deserializer { private buffer: ArrayBuffer; @@ -46,6 +52,8 @@ export class Deserializer { * This prevents outside mutation of the buffer. * * @param data - The data to be copied into the internal buffer as a Uint8Array. + * @group Implementation + * @category BCS */ constructor(data: Uint8Array) { // copies data to prevent outside mutation of buffer. @@ -59,6 +67,8 @@ export class Deserializer { * * @param length - The number of bytes to read from the buffer. * @throws Throws an error if the read operation exceeds the buffer's length. + * @group Implementation + * @category BCS */ private read(length: number): ArrayBuffer { if (this.offset + length > this.buffer.byteLength) { @@ -76,6 +86,8 @@ export class Deserializer { * This information is useful to determine if there's more data to be read. * * @returns The number of bytes remaining in the buffer. + * @group Implementation + * @category BCS */ remaining(): number { return this.buffer.byteLength - this.offset; @@ -93,6 +105,8 @@ export class Deserializer { * const deserializer = new Deserializer(new Uint8Array([8, 49, 50, 51, 52, 97, 98, 99, 100])); * assert(deserializer.deserializeStr() === "1234abcd"); * ``` + * @group Implementation + * @category BCS */ deserializeStr(): string { const value = this.deserializeBytes(); @@ -112,6 +126,8 @@ export class Deserializer { * const deserializer = new Deserializer(new Uint8Array([1, 8, 49, 50, 51, 52, 97, 98, 99, 100])); * assert(deserializer.deserializeOptionStr() === "1234abcd"); * ``` + * @group Implementation + * @category BCS */ deserializeOptionStr(): string | undefined { const exists = this.deserializeBool(); @@ -135,6 +151,8 @@ export class Deserializer { * @param cls The BCS-deserializable class to deserialize the buffered bytes into. * * @returns The deserialized value of class type T or undefined if no value exists. + * @group Implementation + * @category BCS */ deserializeOption(cls: Deserializable): T | undefined { const exists = this.deserializeBool(); @@ -148,6 +166,8 @@ export class Deserializer { * encoded as a uleb128 integer, indicating the length of the bytes array. * * @returns {Uint8Array} The deserialized array of bytes. + * @group Implementation + * @category BCS */ deserializeBytes(): Uint8Array { const len = this.deserializeUleb128AsU32(); @@ -158,6 +178,8 @@ export class Deserializer { * Deserializes an array of bytes of a specified length. * * @param len - The number of bytes to read from the source. + * @group Implementation + * @category BCS */ deserializeFixedBytes(len: number): Uint8Array { return new Uint8Array(this.read(len)); @@ -171,6 +193,8 @@ export class Deserializer { * * @returns The deserialized boolean value. * @throws Throws an error if the boolean value is invalid. + * @group Implementation + * @category BCS */ deserializeBool(): boolean { const bool = new Uint8Array(this.read(1))[0]; @@ -186,6 +210,8 @@ export class Deserializer { * BCS layout for "uint8": One byte. Binary format in little-endian representation. * * @returns {number} The deserialized uint8 number. + * @group Implementation + * @category BCS */ deserializeU8(): Uint8 { return new DataView(this.read(1)).getUint8(0); @@ -200,6 +226,8 @@ export class Deserializer { * const deserializer = new Deserializer(new Uint8Array([0x34, 0x12])); * assert(deserializer.deserializeU16() === 4660); * ``` + * @group Implementation + * @category BCS */ deserializeU16(): Uint16 { return new DataView(this.read(2)).getUint16(0, true); @@ -214,6 +242,8 @@ export class Deserializer { * const deserializer = new Deserializer(new Uint8Array([0x78, 0x56, 0x34, 0x12])); * assert(deserializer.deserializeU32() === 305419896); * ``` + * @group Implementation + * @category BCS */ deserializeU32(): Uint32 { return new DataView(this.read(4)).getUint32(0, true); @@ -228,6 +258,8 @@ export class Deserializer { * const deserializer = new Deserializer(new Uint8Array([0x00, 0xEF, 0xCD, 0xAB, 0x78, 0x56, 0x34, 0x12])); * assert(deserializer.deserializeU64() === 1311768467750121216); * ``` + * @group Implementation + * @category BCS */ deserializeU64(): Uint64 { const low = this.deserializeU32(); @@ -242,6 +274,8 @@ export class Deserializer { * This function combines two 64-bit values to return a single uint128 value in little-endian format. * * @returns {BigInt} The deserialized uint128 number. + * @group Implementation + * @category BCS */ deserializeU128(): Uint128 { const low = this.deserializeU64(); @@ -257,6 +291,8 @@ export class Deserializer { * The BCS layout for "uint256" consists of thirty-two bytes in little-endian format. * * @returns {BigInt} The deserialized uint256 number. + * @group Implementation + * @category BCS */ deserializeU256(): Uint256 { const low = this.deserializeU128(); @@ -273,6 +309,8 @@ export class Deserializer { * * @throws {Error} Throws an error if the parsed value exceeds the maximum uint32 number. * @returns {number} The deserialized uint32 value. + * @group Implementation + * @category BCS */ deserializeUleb128AsU32(): Uint32 { let value: bigint = BigInt(0); @@ -307,6 +345,8 @@ export class Deserializer { * @param cls The BCS-deserializable class to deserialize the buffered bytes into. * * @returns the deserialized value of class type T + * @group Implementation + * @category BCS */ deserialize(cls: Deserializable): T { // NOTE: `deserialize` in `cls.deserialize(this)` here is a static method defined in `cls`, @@ -335,6 +375,8 @@ export class Deserializer { * const deserializer = new Deserializer(serializedBytes); * const deserializedAddresses = deserializer.deserializeVector(AccountAddress); * // deserializedAddresses is now an array of AccountAddress instances + * @group Implementation + * @category BCS */ deserializeVector(cls: Deserializable): Array { const length = this.deserializeUleb128AsU32(); diff --git a/src/bcs/serializable/entryFunctionBytes.ts b/src/bcs/serializable/entryFunctionBytes.ts index 204757da2..090278e6d 100644 --- a/src/bcs/serializable/entryFunctionBytes.ts +++ b/src/bcs/serializable/entryFunctionBytes.ts @@ -16,6 +16,8 @@ import { HexInput } from "../../types"; * If you wish to convert this class back to a TransactionArgument, you must know the type * of the argument beforehand, and use the appropriate class to deserialize the bytes within * an instance of this class. + * @group Implementation + * @category BCS */ export class EntryFunctionBytes extends Serializable implements EntryFunctionArgument { public readonly value: FixedBytes; @@ -24,6 +26,8 @@ export class EntryFunctionBytes extends Serializable implements EntryFunctionArg * Creates an instance of the class with a specified hexadecimal input value. * * @param value - The hexadecimal input to be converted into FixedBytes. + * @group Implementation + * @category BCS */ private constructor(value: HexInput) { super(); @@ -45,6 +49,8 @@ export class EntryFunctionBytes extends Serializable implements EntryFunctionArg * we must not serialize the length prefix. * * @param serializer - The serializer instance used to perform the serialization. + * @group Implementation + * @category BCS */ serialize(serializer: Serializer): void { serializer.serialize(this.value); @@ -62,6 +68,8 @@ export class EntryFunctionBytes extends Serializable implements EntryFunctionArg * This process includes serializing the length prefix of the byte vector. * * @param serializer - The serializer instance used to perform the serialization. + * @group Implementation + * @category BCS */ serializeForEntryFunction(serializer: Serializer): void { serializer.serializeU32AsUleb128(this.value.value.length); @@ -74,6 +82,8 @@ export class EntryFunctionBytes extends Serializable implements EntryFunctionArg * @param deserializer - The deserializer instance with the buffered bytes. * @param length - The length of the bytes to deserialize. * @returns An instance of this class, which will now only be usable as an EntryFunctionArgument. + * @group Implementation + * @category BCS */ static deserialize(deserializer: Deserializer, length: number): EntryFunctionBytes { const fixedBytes = FixedBytes.deserialize(deserializer, length); diff --git a/src/bcs/serializable/fixedBytes.ts b/src/bcs/serializable/fixedBytes.ts index d7e55d29e..ba32dfe8f 100644 --- a/src/bcs/serializable/fixedBytes.ts +++ b/src/bcs/serializable/fixedBytes.ts @@ -36,6 +36,8 @@ import { TransactionArgument } from "../../transactions/instances/transactionArg * @param value - HexInput representing a sequence of Uint8 bytes. * @returns A Serializable FixedBytes instance, which when serialized, does not prepend the length of the bytes. * @see EntryFunctionBytes + * @group Implementation + * @category BCS */ export class FixedBytes extends Serializable implements TransactionArgument { public value: Uint8Array; @@ -45,6 +47,8 @@ export class FixedBytes extends Serializable implements TransactionArgument { * The value is converted from hexadecimal format to a Uint8Array. * * @param value - The hexadecimal input to be converted. + * @group Implementation + * @category BCS */ constructor(value: HexInput) { super(); @@ -56,6 +60,8 @@ export class FixedBytes extends Serializable implements TransactionArgument { * This function is essential for converting the fixed bytes into a format suitable for storage or transmission. * * @param serializer - The serializer instance used for serialization. + * @group Implementation + * @category BCS */ serialize(serializer: Serializer): void { serializer.serializeFixedBytes(this.value); @@ -66,6 +72,8 @@ export class FixedBytes extends Serializable implements TransactionArgument { * This allows the instance to be converted into a format suitable for transmission or storage. * * @param serializer - The serializer used to perform the serialization. + * @group Implementation + * @category BCS */ serializeForEntryFunction(serializer: Serializer): void { serializer.serialize(this); @@ -76,6 +84,8 @@ export class FixedBytes extends Serializable implements TransactionArgument { * This function is essential for preparing data to be passed as arguments in script functions. * * @param serializer - The serializer instance used to perform the serialization. + * @group Implementation + * @category BCS */ serializeForScriptFunction(serializer: Serializer): void { serializer.serialize(this); @@ -87,6 +97,8 @@ export class FixedBytes extends Serializable implements TransactionArgument { * * @param deserializer - The deserializer instance used to read the byte data. * @param length - The length of the byte array to be deserialized. + * @group Implementation + * @category BCS */ static deserialize(deserializer: Deserializer, length: number): FixedBytes { const bytes = deserializer.deserializeFixedBytes(length); diff --git a/src/bcs/serializable/movePrimitives.ts b/src/bcs/serializable/movePrimitives.ts index 7980925d9..f6420f92f 100644 --- a/src/bcs/serializable/movePrimitives.ts +++ b/src/bcs/serializable/movePrimitives.ts @@ -20,6 +20,8 @@ import { AnyNumber, Uint16, Uint32, Uint8, ScriptTransactionArgumentVariants } f * the boolean value for different contexts, such as entry functions and script functions. * * @extends Serializable + * @group Implementation + * @category BCS */ export class Bool extends Serializable implements TransactionArgument { public readonly value: boolean; @@ -29,6 +31,8 @@ export class Bool extends Serializable implements TransactionArgument { * This ensures that the value is validated to be within the acceptable range. * * @param value - The number to be validated and assigned, which must be between 0 and MAX_U256_BIG_INT. + * @group Implementation + * @category BCS */ constructor(value: boolean) { super(); @@ -39,6 +43,8 @@ export class Bool extends Serializable implements TransactionArgument { * * @param value - The value to be checked for boolean type. * @throws {Error} Throws an error if the value is not a boolean. + * @group Implementation + * @category BCS */ ensureBoolean(value); this.value = value; @@ -49,6 +55,8 @@ export class Bool extends Serializable implements TransactionArgument { * This function is essential for converting the value into a format suitable for transmission or storage. * * @param serializer - The serializer instance used to perform the serialization. + * @group Implementation + * @category BCS */ serialize(serializer: Serializer): void { serializer.serializeBool(this.value); @@ -59,6 +67,8 @@ export class Bool extends Serializable implements TransactionArgument { * This allows the instance to be properly formatted for serialization in transactions. * * @param serializer - The serializer instance used to serialize the byte sequence. + * @group Implementation + * @category BCS */ serializeForEntryFunction(serializer: Serializer): void { const bcsBytes = this.bcsToBytes(); @@ -70,6 +80,8 @@ export class Bool extends Serializable implements TransactionArgument { * This allows for the conversion of the instance into a format suitable for transmission or storage. * * @param serializer - The serializer used to perform the serialization. + * @group Implementation + * @category BCS */ serializeForScriptFunction(serializer: Serializer): void { serializer.serializeU32AsUleb128(ScriptTransactionArgumentVariants.Bool); @@ -80,6 +92,8 @@ export class Bool extends Serializable implements TransactionArgument { * Deserializes a U256 value from the provided deserializer. * * @param deserializer - The deserializer instance used to read the U256 data. + * @group Implementation + * @category BCS */ // eslint-disable-next-line class-methods-use-this deserialize(deserializer: Deserializer) { @@ -96,6 +110,8 @@ export class Bool extends Serializable implements TransactionArgument { * This class extends the Serializable class and provides methods for serialization and deserialization of U8 values. * * @extends Serializable + * @group Implementation + * @category BCS */ export class U8 extends Serializable implements TransactionArgument { public readonly value: Uint8; @@ -131,6 +147,8 @@ export class U8 extends Serializable implements TransactionArgument { * and deserialization of the U16 value. * * @extends Serializable + * @group Implementation + * @category BCS */ export class U16 extends Serializable implements TransactionArgument { public readonly value: Uint16; @@ -165,6 +183,8 @@ export class U16 extends Serializable implements TransactionArgument { * This class ensures that the value is within the valid range for a U32. * * @extends Serializable + * @group Implementation + * @category BCS */ export class U32 extends Serializable implements TransactionArgument { public readonly value: Uint32; @@ -202,6 +222,8 @@ export class U32 extends Serializable implements TransactionArgument { * and script functions. * * @extends Serializable + * @group Implementation + * @category BCS */ export class U64 extends Serializable implements TransactionArgument { public readonly value: bigint; @@ -237,6 +259,8 @@ export class U64 extends Serializable implements TransactionArgument { * of U128 values, ensuring that the values are within the valid range. * * @extends Serializable + * @group Implementation + * @category BCS */ export class U128 extends Serializable implements TransactionArgument { public readonly value: bigint; @@ -272,6 +296,8 @@ export class U128 extends Serializable implements TransactionArgument { * ensuring that the values are within the valid range. * * @extends Serializable + * @group Implementation + * @category BCS */ export class U256 extends Serializable implements TransactionArgument { public readonly value: bigint; diff --git a/src/bcs/serializable/moveStructs.ts b/src/bcs/serializable/moveStructs.ts index 4c75828ef..a3ca7a02c 100644 --- a/src/bcs/serializable/moveStructs.ts +++ b/src/bcs/serializable/moveStructs.ts @@ -45,6 +45,8 @@ import { EntryFunctionArgument, TransactionArgument } from "../../transactions/i * @params * values: an Array of values where T is a class that implements Serializable * @returns a `MoveVector` with the values `values` + * @group Implementation + * @category BCS */ export class MoveVector extends Serializable @@ -57,6 +59,8 @@ export class MoveVector * This constructor sets up the internal vector based on the provided value. * * @param values - The initial value to be stored in the vector, or null to initialize an empty vector. + * @group Implementation + * @category BCS */ constructor(values: Array) { super(); @@ -68,6 +72,8 @@ export class MoveVector * This allows the data to be properly formatted for transmission or storage. * * @param serializer - The serializer instance used to serialize the byte sequence. + * @group Implementation + * @category BCS */ serializeForEntryFunction(serializer: Serializer): void { const bcsBytes = this.bcsToBytes(); @@ -77,11 +83,15 @@ export class MoveVector /** * NOTE: This function will only work when the inner values in the `MoveVector` are `U8`s. * @param serializer + * @group Implementation + * @category BCS */ /** * Serialize the string as a fixed byte string without the length prefix for use in a script function. * @param serializer - The serializer used to convert the byte vector into a format suitable for a script function. + * @group Implementation + * @category BCS */ serializeForScriptFunction(serializer: Serializer): void { // This checks if the type of a non-empty vector is of type other than U8. If so, we use the Serialized @@ -109,6 +119,8 @@ export class MoveVector * ```typescript * const v = MoveVector.U8([1, 2, 3, 4]); * ``` + * @group Implementation + * @category BCS */ static U8(values: Array | HexInput): MoveVector { let numbers: Array; @@ -142,6 +154,8 @@ export class MoveVector * ```typescript * const v = MoveVector.U16([1, 2, 3, 4]); * ``` + * @group Implementation + * @category BCS */ static U16(values: Array): MoveVector { @@ -161,6 +175,8 @@ export class MoveVector * ``` * const v = MoveVector.U32([1, 2, 3, 4]); * ``` + * @group Implementation + * @category BCS */ static U32(values: Array): MoveVector { @@ -179,6 +195,8 @@ export class MoveVector * ```typescript * const v = MoveVector.U64([1, 2, 3, 4]); * ``` + * @group Implementation + * @category BCS */ static U64(values: Array): MoveVector { return new MoveVector(values.map((v) => new U64(v))); @@ -195,6 +213,8 @@ export class MoveVector * ```typescript * const v = MoveVector.U128([1, 2, 3, 4]); * ``` + * @group Implementation + * @category BCS */ static U128(values: Array): MoveVector { return new MoveVector(values.map((v) => new U128(v))); @@ -212,6 +232,8 @@ export class MoveVector * ```typescript * const v = MoveVector.U256([1, 2, 3, 4]); * ``` + * @group Implementation + * @category BCS */ static U256(values: Array): MoveVector { return new MoveVector(values.map((v) => new U256(v))); @@ -228,6 +250,8 @@ export class MoveVector * * @example * * const v = MoveVector.Bool([true, false, true, false]); + * @group Implementation + * @category BCS */ static Bool(values: Array): MoveVector { return new MoveVector(values.map((v) => new Bool(v))); @@ -243,6 +267,8 @@ export class MoveVector * * @example * const v = MoveVector.MoveString(["hello", "world"]); + * @group Implementation + * @category BCS */ static MoveString(values: Array): MoveVector { return new MoveVector(values.map((v) => new MoveString(v))); @@ -253,6 +279,8 @@ export class MoveVector * This function will serialize the value if it is present. * * @param serializer - The serializer instance used to perform the serialization. + * @group Implementation + * @category BCS */ serialize(serializer: Serializer): void; serialize(serializer: Serializer): void { @@ -275,6 +303,8 @@ export class MoveVector * @param cls the class to typecast the input values to, must be a Serializable and Deserializable type. * @returns a MoveVector of the corresponding class T * + * @group Implementation + * @category BCS */ static deserialize( deserializer: Deserializer, @@ -295,6 +325,8 @@ export class MoveVector * and deserialization of byte data, as well as converting to a MoveVector. * * @extends Serializable + * @group Implementation + * @category BCS */ export class Serialized extends Serializable implements TransactionArgument { public readonly value: Uint8Array; @@ -326,6 +358,8 @@ export class Serialized extends Serializable implements TransactionArgument { * This function allows you to convert serialized data into a usable MoveVector format. * * @param cls - The class type of the elements in the MoveVector. + * @group Implementation + * @category BCS */ toMoveVector(cls: Deserializable): MoveVector { const deserializer = new Deserializer(this.bcsToBytes()); @@ -342,6 +376,8 @@ export class Serialized extends Serializable implements TransactionArgument { * functions and script functions. * * @extends Serializable + * @group Implementation + * @category BCS */ export class MoveString extends Serializable implements TransactionArgument { public value: string; @@ -411,6 +447,8 @@ export class MoveOption * @throws {Error} Throws an error if the MoveOption does not contain a value. * * @returns {T} The contained value if present. + * @group Implementation + * @category BCS */ unwrap(): T { if (!this.isSome()) { @@ -424,6 +462,8 @@ export class MoveOption * Check if the MoveOption has a value. * * @returns {boolean} Returns true if there is exactly one value in the MoveOption. + * @group Implementation + * @category BCS */ isSome(): boolean { return this.vec.values.length === 1; @@ -445,6 +485,8 @@ export class MoveOption * @params value: the value used to fill the MoveOption. If `value` is undefined * the resulting MoveOption's .isSome() method will return false. * @returns a MoveOption with an inner value `value` + * @group Implementation + * @category BCS */ static U8(value?: number | null): MoveOption { return new MoveOption(value !== null && value !== undefined ? new U8(value) : undefined); @@ -460,6 +502,8 @@ export class MoveOption * @params value: the value used to fill the MoveOption. If `value` is undefined * the resulting MoveOption's .isSome() method will return false. * @returns a MoveOption with an inner value `value` + * @group Implementation + * @category BCS */ static U16(value?: number | null): MoveOption { return new MoveOption(value !== null && value !== undefined ? new U16(value) : undefined); @@ -475,6 +519,8 @@ export class MoveOption * @params value: the value used to fill the MoveOption. If `value` is undefined * the resulting MoveOption's .isSome() method will return false. * @returns a MoveOption with an inner value `value` + * @group Implementation + * @category BCS */ static U32(value?: number | null): MoveOption { return new MoveOption(value !== null && value !== undefined ? new U32(value) : undefined); @@ -490,6 +536,8 @@ export class MoveOption * @params value: the value used to fill the MoveOption. If `value` is undefined * the resulting MoveOption's .isSome() method will return false. * @returns a MoveOption with an inner value `value` + * @group Implementation + * @category BCS */ static U64(value?: AnyNumber | null): MoveOption { return new MoveOption(value !== null && value !== undefined ? new U64(value) : undefined); @@ -505,6 +553,8 @@ export class MoveOption * @params value: the value used to fill the MoveOption. If `value` is undefined * the resulting MoveOption's .isSome() method will return false. * @returns a MoveOption with an inner value `value` + * @group Implementation + * @category BCS */ static U128(value?: AnyNumber | null): MoveOption { return new MoveOption(value !== null && value !== undefined ? new U128(value) : undefined); @@ -520,6 +570,8 @@ export class MoveOption * @params value: the value used to fill the MoveOption. If `value` is undefined * the resulting MoveOption's .isSome() method will return false. * @returns a MoveOption with an inner value `value` + * @group Implementation + * @category BCS */ static U256(value?: AnyNumber | null): MoveOption { return new MoveOption(value !== null && value !== undefined ? new U256(value) : undefined); @@ -535,6 +587,8 @@ export class MoveOption * @params value: the value used to fill the MoveOption. If `value` is undefined * the resulting MoveOption's .isSome() method will return false. * @returns a MoveOption with an inner value `value` + * @group Implementation + * @category BCS */ static Bool(value?: boolean | null): MoveOption { return new MoveOption(value !== null && value !== undefined ? new Bool(value) : undefined); @@ -551,6 +605,8 @@ export class MoveOption * @params value: the value used to fill the MoveOption. If `value` is undefined * the resulting MoveOption's .isSome() method will return false. * @returns a MoveOption with an inner value `value` + * @group Implementation + * @category BCS */ static MoveString(value?: string | null): MoveOption { return new MoveOption(value !== null && value !== undefined ? new MoveString(value) : undefined); diff --git a/src/bcs/serializer.ts b/src/bcs/serializer.ts index 427a3eb22..62bcd8801 100644 --- a/src/bcs/serializer.ts +++ b/src/bcs/serializer.ts @@ -17,6 +17,8 @@ import { AnyNumber, Uint16, Uint32, Uint8 } from "../types"; * This class serves as a base class for all serializable types. It facilitates * composable serialization of complex types and enables the serialization of * instances to their BCS (Binary Canonical Serialization) representation. + * @group Implementation + * @category BCS */ export abstract class Serializable { abstract serialize(serializer: Serializer): void; @@ -25,6 +27,8 @@ export abstract class Serializable { * Serializes a `Serializable` value to its BCS representation. * This function is the TypeScript SDK equivalent of `bcs::to_bytes` in Move. * @returns the BCS representation of the Serializable instance as a byte buffer. + * @group Implementation + * @category BCS */ bcsToBytes(): Uint8Array { const serializer = new Serializer(); @@ -36,6 +40,8 @@ export abstract class Serializable { * Converts the BCS-serialized bytes of a value into a Hex instance. * This function provides a Hex representation of the BCS-serialized data for easier handling and manipulation. * @returns A Hex instance with the BCS-serialized bytes loaded into its underlying Uint8Array. + * @group Implementation + * @category BCS */ bcsToHex(): Hex { const bcsBytes = this.bcsToBytes(); @@ -48,6 +54,8 @@ export abstract class Serializable { * It provides methods to serialize strings, bytes, numbers, and other serializable objects * using the Binary Coded Serialization (BCS) layout. The serialized data can be retrieved as a * Uint8Array. + * @group Implementation + * @category BCS */ export class Serializer { private buffer: ArrayBuffer; @@ -59,6 +67,8 @@ export class Serializer { * The `length` must be greater than 0. * * @param length - The size of the buffer in bytes. + * @group Implementation + * @category BCS */ constructor(length: number = 64) { if (length <= 0) { @@ -73,6 +83,8 @@ export class Serializer { * This function dynamically resizes the buffer if the current size is insufficient. * * @param bytes - The number of bytes to ensure the buffer can handle. + * @group Implementation + * @category BCS */ private ensureBufferWillHandleSize(bytes: number) { while (this.buffer.byteLength < this.offset + bytes) { @@ -86,6 +98,8 @@ export class Serializer { * Appends the specified values to the buffer, ensuring that the buffer can accommodate the new data. * * @param {Uint8Array} values - The values to be appended to the buffer. + * @group Implementation + * @category BCS */ protected appendToBuffer(values: Uint8Array) { this.ensureBufferWillHandleSize(values.length); @@ -100,6 +114,8 @@ export class Serializer { * @param fn.byteOffset - The byte offset at which to write the value. * @param fn.value - The numeric value to serialize into the buffer. * @param fn.littleEndian - Optional flag indicating whether to use little-endian byte order (defaults to true). + * @group Implementation + * @category BCS */ // TODO: JSDoc bytesLength and value private serializeWithFunction( @@ -129,6 +145,8 @@ export class Serializer { * serializer.serializeStr("1234abcd"); * assert(serializer.toUint8Array() === new Uint8Array([8, 49, 50, 51, 52, 97, 98, 99, 100])); * ``` + * @group Implementation + * @category BCS */ serializeStr(value: string) { const textEncoder = new TextEncoder(); @@ -142,6 +160,8 @@ export class Serializer { * BCS layout for "bytes": bytes_length | bytes * where bytes_length is a u32 integer encoded as a uleb128 integer, equal to the length of the bytes array. * @param value - The byte array to serialize. + * @group Implementation + * @category BCS */ serializeBytes(value: Uint8Array) { this.serializeU32AsUleb128(value.length); @@ -154,6 +174,8 @@ export class Serializer { * When deserializing, the number of bytes to deserialize needs to be passed in. * @param value - The Uint8Array to be serialized. + * @group Implementation + * @category BCS */ serializeFixedBytes(value: Uint8Array) { this.appendToBuffer(value); @@ -165,6 +187,8 @@ export class Serializer { * The BCS layout for a boolean uses one byte, where "0x01" represents true and "0x00" represents false. * * @param value - The boolean value to serialize. + * @group Implementation + * @category BCS */ serializeBool(value: boolean) { /** @@ -173,6 +197,8 @@ export class Serializer { * * @param value - The value to be checked for boolean type. * @throws {Error} Throws an error if the value is not a boolean. + * @group Implementation + * @category BCS */ ensureBoolean(value); const byteValue = value ? 1 : 0; @@ -184,6 +210,8 @@ export class Serializer { * BCS layout for "uint8": One byte. Binary format in little-endian representation. * * @param value - The Uint8 value to serialize. + * @group Implementation + * @category BCS */ @checkNumberRange(0, MAX_U8_NUMBER) serializeU8(value: Uint8) { @@ -193,6 +221,8 @@ export class Serializer { /** * Serializes a uint16 number. * + * @group Implementation + * @category BCS */ @@ -207,6 +237,8 @@ export class Serializer { * serializer.serializeU16(4660); * assert(serializer.toUint8Array() === new Uint8Array([0x34, 0x12])); * ``` + * @group Implementation + * @category BCS */ @checkNumberRange(0, MAX_U16_NUMBER) serializeU16(value: Uint16) { @@ -223,6 +255,8 @@ export class Serializer { * assert(serializer.toUint8Array() === new Uint8Array([0x78, 0x56, 0x34, 0x12])); * ``` * @param value - The 32-bit unsigned integer value to serialize. + * @group Implementation + * @category BCS */ @checkNumberRange(0, MAX_U32_NUMBER) serializeU32(value: Uint32) { @@ -240,6 +274,8 @@ export class Serializer { * serializer.serializeU64(1311768467750121216); * assert(serializer.toUint8Array() === new Uint8Array([0x00, 0xEF, 0xCD, 0xAB, 0x78, 0x56, 0x34, 0x12])); * ``` + * @group Implementation + * @category BCS */ @checkNumberRange(BigInt(0), MAX_U64_BIG_INT) serializeU64(value: AnyNumber) { @@ -255,6 +291,8 @@ export class Serializer { * Serializes a U128 value into a format suitable for storage or transmission. * * @param value - The U128 value to serialize, represented as a number. + * @group Implementation + * @category BCS */ @checkNumberRange(BigInt(0), MAX_U128_BIG_INT) serializeU128(value: AnyNumber) { @@ -271,6 +309,8 @@ export class Serializer { * This function is essential for encoding large numbers in a compact format suitable for transmission or storage. * * @param value - The U256 value to serialize, represented as an AnyNumber. + * @group Implementation + * @category BCS */ @checkNumberRange(BigInt(0), MAX_U256_BIG_INT) serializeU256(value: AnyNumber) { @@ -287,6 +327,8 @@ export class Serializer { * BCS uses uleb128 encoding in two cases: (1) lengths of variable-length sequences and (2) tags of enum values * * @param val - The 32-bit unsigned integer value to be serialized. + * @group Implementation + * @category BCS */ @checkNumberRange(0, MAX_U32_NUMBER) serializeU32AsUleb128(val: Uint32) { @@ -306,6 +348,8 @@ export class Serializer { * This function allows you to retrieve the byte representation of the buffer up to the current offset. * * @returns Uint8Array - The byte array representation of the buffer. + * @group Implementation + * @category BCS */ toUint8Array(): Uint8Array { return new Uint8Array(this.buffer).slice(0, this.offset); @@ -317,6 +361,8 @@ export class Serializer { * @param value The Serializable value to serialize. * * @returns the serializer instance + * @group Implementation + * @category BCS */ serialize(value: T): void { // NOTE: The `serialize` method called by `value` is defined in `value`'s @@ -342,6 +388,8 @@ export class Serializer { * // serializedBytes is now the BCS-serialized bytes * // The equivalent value in Move would be: * // `bcs::to_bytes(&vector
[@0x1, @0x2, @0xa, @0xb])`; + * @group Implementation + * @category BCS */ serializeVector(values: Array): void { this.serializeU32AsUleb128(values.length); @@ -367,6 +415,8 @@ export class Serializer { * serializer.serializeOption(undefined); * assert(serializer.toUint8Array() === new Uint8Array([0x00])); * ``` + * @group Implementation + * @category BCS */ serializeOption(value?: T): void { const hasValue = value !== undefined; @@ -385,6 +435,8 @@ export class Serializer { * BCS layout for undefined: 0 * * @param value - The optional string to serialize. If undefined, it will serialize as 0. + * @group Implementation + * @category BCS */ serializeOptionStr(value?: string): void { if (value === undefined) { @@ -396,12 +448,19 @@ export class Serializer { } } +/** + * @group Implementation + * @category BCS + */ export function ensureBoolean(value: unknown): asserts value is boolean { if (typeof value !== "boolean") { throw new Error(`${value} is not a boolean value`); } } - +/** + * @group Implementation + * @category BCS + */ export const outOfRangeErrorMessage = (value: AnyNumber, min: AnyNumber, max: AnyNumber) => `${value} is out of range: [${min}, ${max}]`; @@ -412,6 +471,8 @@ export const outOfRangeErrorMessage = (value: AnyNumber, min: AnyNumber, max: An * @param value - The number to validate. * @param minValue - The minimum allowable value (inclusive). * @param maxValue - The maximum allowable value (inclusive). + * @group Implementation + * @category BCS */ export function validateNumberInRange(value: T, minValue: T, maxValue: T) { const valueBigInt = BigInt(value); @@ -426,6 +487,8 @@ export function validateNumberInRange(value: T, minValue: T * * @param minValue - The input argument must be greater than or equal to this value. * @param maxValue - The input argument must be less than or equal to this value. + * @group Implementation + * @category BCS */ function checkNumberRange(minValue: T, maxValue: T) { return (target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => { diff --git a/src/cli/localNode.ts b/src/cli/localNode.ts index 885f3840f..6d9aa40d0 100644 --- a/src/cli/localNode.ts +++ b/src/cli/localNode.ts @@ -10,6 +10,8 @@ import { sleep } from "../utils/helpers"; * Represents a local node for running a testnet environment. * This class provides methods to start, stop, and check the status of the local testnet process. * It manages the lifecycle of the node process and ensures that it is operational before executing tests. + * @group Implementation + * @category CLI */ export class LocalNode { readonly MAXIMUM_WAIT_TIME_SEC = 75; @@ -29,6 +31,8 @@ export class LocalNode { * * @returns {Promise} A promise that resolves to true if the process was successfully killed. * @throws {Error} If there is an error while attempting to kill the process. + * @group Implementation + * @category CLI */ async stop(): Promise { await new Promise((resolve, reject) => { @@ -41,6 +45,8 @@ export class LocalNode { * @param callback - A function that is called after the termination attempt is complete. * @param callback.err - An error object if the termination failed; otherwise, null. * @param callback.resolve - A boolean indicating whether the termination was successful. + * @group Implementation + * @category CLI */ kill(this.process.pid, (err) => { if (err) { @@ -57,6 +63,8 @@ export class LocalNode { * If the local node process is already running, it returns without starting the process. * * @returns {Promise} A promise that resolves when the process is up. + * @group Implementation + * @category CLI */ async run(): Promise { const nodeIsUp = await this.checkIfProcessIsUp(); @@ -73,6 +81,8 @@ export class LocalNode { * @returns {void} * * @throws {Error} If there is an issue starting the local testnet. + * @group Implementation + * @category CLI */ start(): void { const cliCommand = "npx"; @@ -111,6 +121,8 @@ export class LocalNode { * This function continuously checks if the process is up and will throw an error if it fails to start. * * @returns Promise - Resolves to true if the process is up, otherwise throws an error. + * @group Implementation + * @category CLI */ async waitUntilProcessIsUp(): Promise { let operational = await this.checkIfProcessIsUp(); @@ -138,6 +150,8 @@ export class LocalNode { * Checks if the local testnet is up by querying the readiness endpoint. * * @returns Promise - A promise that resolves to true if the testnet is up, otherwise false. + * @group Implementation + * @category CLI */ async checkIfProcessIsUp(): Promise { try { diff --git a/src/cli/move.ts b/src/cli/move.ts index c184ef048..b55d17cff 100644 --- a/src/cli/move.ts +++ b/src/cli/move.ts @@ -8,6 +8,8 @@ import { Network } from "../utils"; * Class representing a Move package management utility for the Aptos blockchain. * This class provides methods to initialize directories, compile packages, run tests, publish modules, create objects, upgrade * packages, build transaction payloads, and run scripts. + * @group Implementation + * @category CLI */ export class Move { /** @@ -21,6 +23,8 @@ export class Move { * @param args.extraArguments - Optional extra arguments to include in the form of an array of strings. * Ex. ["--assume-yes","--gas-unit-price=10"] * @returns stdout + * @group Implementation + * @category CLI */ async init(args: { network?: Network; @@ -48,6 +52,8 @@ export class Move { * @param args.extraArguments - Optional extra arguments to include in the form of an array of strings. * Ex. ["--assume-yes","--gas-unit-price=10"] * @returns stdout + * @group Implementation + * @category CLI */ async compile(args: { packageDirectoryPath: string; @@ -78,6 +84,8 @@ export class Move { * @param args.extraArguments - Optional extra arguments to include in the form of an array of strings. * Ex. ["--assume-yes","--gas-unit-price=10"] * @returns The stdout output from running the tests. + * @group Implementation + * @category CLI */ async test(args: { packageDirectoryPath: string; @@ -109,6 +117,8 @@ export class Move { * @param args.extraArguments - Optional extra arguments to include in the form of an array of strings. * Ex. ["--assume-yes","--gas-unit-price=10"] * @returns stdout + * @group Implementation + * @category CLI */ async publish(args: { packageDirectoryPath: string; @@ -157,6 +167,8 @@ export class Move { * --named-addresses "launchpad_addr=0x123,initial_creator_addr=0x456" \ * --profile my_profile \ * --assume-yes + * @group Implementation + * @category CLI */ async createObjectAndPublishPackage(args: { packageDirectoryPath: string; @@ -202,6 +214,8 @@ export class Move { * @param args.extraArguments - Optional extra arguments to include in the form of an array of strings. * Ex. ["--assume-yes","--gas-unit-price=10"] * @returns stdout + * @group Implementation + * @category CLI */ async upgradeObjectPackage(args: { packageDirectoryPath: string; @@ -244,6 +258,8 @@ export class Move { * @param args.extraArguments - Optional extra arguments to include in the form of an array of strings. * Ex. ["--assume-yes","--gas-unit-price=10"] * * @returns stdout + * @group Implementation + * @category CLI */ async buildPublishPayload(args: { packageDirectoryPath: string; @@ -286,6 +302,8 @@ export class Move { * Ex. ["--assume-yes","--gas-unit-price=10"] * * @returns The standard output from running the script. + * @group Implementation + * @category CLI */ async runScript(args: { compiledScriptPath: string; @@ -316,6 +334,8 @@ export class Move { * @param args - An array of strings representing the command-line arguments to be passed to the command. * @param showStdout - Show the standard output generated by the command. * @returns The standard output generated by the command. + * @group Implementation + * @category CLI */ // eslint-disable-next-line class-methods-use-this private async runCommand(args: Array, showStdout: boolean = true): Promise<{ output: string }> { @@ -357,6 +377,8 @@ export class Move { * @param namedAddresses - A Map where the key is a string representing the name and the value is an AccountAddress. * Ex. {'alice' => '0x123', 'bob' => '0x456'} * @returns An array of named addresses formatted as strings separated by a comma. Ex. "alice=0x123,bob=0x456" + * @group Implementation + * @category CLI */ // eslint-disable-next-line class-methods-use-this private prepareNamedAddresses(namedAddresses: Map): Array { @@ -386,6 +408,8 @@ export class Move { * * @param namedAddresses - A record containing named addresses where the key is the name and the value is the AccountAddress. * @returns A Map where each key is a name and each value is the corresponding address. + * @group Implementation + * @category CLI */ // eslint-disable-next-line class-methods-use-this private parseNamedAddresses(namedAddresses: Record): Map { @@ -405,6 +429,8 @@ export class Move { * @param output - The output string containing the object address. * @returns The extracted object address. * @throws Error if the object address cannot be extracted from the output. + * @group Implementation + * @category CLI */ // eslint-disable-next-line class-methods-use-this private extractAddressFromOutput(output: string): string { diff --git a/src/client/core.ts b/src/client/core.ts index 76302294a..5d10e1ed9 100644 --- a/src/client/core.ts +++ b/src/client/core.ts @@ -24,6 +24,8 @@ import { AptosApiType } from "../utils"; * @param client - The client used to make the request. * * @returns The response from the request. + * @group Implementation + * @category Client */ export async function request(options: ClientRequest, client: Client): Promise> { const { url, method, body, contentType, params, overrides, originMethod } = options; @@ -62,6 +64,8 @@ export async function request(options: ClientRequest, client: Cli * @param aptosConfig - The configuration information for the SDK client instance. * @param apiType - The type of API being accessed, which determines how the response is handled. * @returns The response from the API request or throws an AptosApiError if the request fails. + * @group Implementation + * @category Client */ export async function aptosRequest( aptosRequestOpts: AptosRequest, diff --git a/src/client/get.ts b/src/client/get.ts index e353ce431..193e01123 100644 --- a/src/client/get.ts +++ b/src/client/get.ts @@ -6,44 +6,64 @@ import { AptosApiType } from "../utils/const"; /** * Options for making a GET request, including configuration for the API client. + * @group Implementation + * @category Client */ export type GetRequestOptions = { /** * The config for the API client + * @group Implementation + * @category Client */ aptosConfig: AptosConfig; /** * The type of API endpoint to call e.g. fullnode, indexer, etc + * @group Implementation + * @category Client */ type: AptosApiType; /** * The name of the API method + * @group Implementation + * @category Client */ originMethod: string; /** * The URL path to the API method + * @group Implementation + * @category Client */ path: string; /** * The content type of the request body + * @group Implementation + * @category Client */ contentType?: MimeType; /** * The accepted content type of the response of the API + * @group Implementation + * @category Client */ acceptType?: MimeType; /** * The query parameters for the request + * @group Implementation + * @category Client */ params?: Record; /** * Specific client overrides for this request to override aptosConfig + * @group Implementation + * @category Client */ overrides?: ClientConfig; }; /** * Options for making a request to the Aptos API, excluding the "type" field. + * @group Implementation + * @category Client */ export type GetAptosRequestOptions = Omit; @@ -60,6 +80,8 @@ export type GetAptosRequestOptions = Omit; * @param options.originMethod - The original method of the request. * @param options.type - The type of request being made. * @returns The response from the GET request. + * @group Implementation + * @category Client */ export async function get( options: GetRequestOptions, @@ -97,6 +119,8 @@ export async function get( * @param options.type - The type of API request being made. * * @returns A promise that resolves with the response from the Aptos full node. + * @group Implementation + * @category Client */ export async function getAptosFullNode( options: GetAptosRequestOptions, @@ -122,6 +146,8 @@ export async function getAptosFullNode( * @param options.param1 - Description of param1. * @param options.param2 - Description of param2. * @returns AptosResponse - The response from the Aptos Pepper service. + * @group Implementation + * @category Client */ export async function getAptosPepperService( options: GetAptosRequestOptions, @@ -129,7 +155,12 @@ export async function getAptosPepperService( return get({ ...options, type: AptosApiType.PEPPER }); } -/// This function is a helper for paginating using a function wrapping an API + +/** + * This function is a helper for paginating using a function wrapping an API + * @group Implementation + * @category Client + */ export async function paginateWithCursor, Res extends Array<{}>>( options: GetAptosRequestOptions, ): Promise { @@ -150,6 +181,8 @@ export async function paginateWithCursor, Res ex * the cursor is a "state key" from the API perspective. Client * should not need to "care" what it represents but just use it * to query the next chunk of data. + * @group Implementation + * @category Client */ cursor = response.headers["x-aptos-cursor"]; // Now that we have the cursor (if any), we remove the headers before diff --git a/src/client/post.ts b/src/client/post.ts index 9a12d714e..5e83808a7 100644 --- a/src/client/post.ts +++ b/src/client/post.ts @@ -9,48 +9,70 @@ import { AptosApiType } from "../utils/const"; /** * Options for making a POST request, including the API client configuration. + * @group Implementation + * @category Client */ export type PostRequestOptions = { /** * The config for the API client + * @group Implementation + * @category Client */ aptosConfig: AptosConfig; /** * The type of API endpoint to call e.g. fullnode, indexer, etc + * @group Implementation + * @category Client */ type: AptosApiType; /** * The name of the API method + * @group Implementation + * @category Client */ originMethod: string; /** * The URL path to the API method + * @group Implementation + * @category Client */ path: string; /** * The content type of the request body + * @group Implementation + * @category Client */ contentType?: MimeType; /** * The accepted content type of the response of the API + * @group Implementation + * @category Client */ acceptType?: MimeType; /** * The query parameters for the request + * @group Implementation + * @category Client */ params?: Record; /** * The body of the request, should match the content type of the request + * @group Implementation + * @category Client */ body?: any; /** * Specific client overrides for this request to override aptosConfig + * @group Implementation + * @category Client */ overrides?: ClientConfig; }; /** * Options for posting a request to Aptos, excluding the type field. + * @group Implementation + * @category Client */ export type PostAptosRequestOptions = Omit; @@ -68,6 +90,8 @@ export type PostAptosRequestOptions = Omit; * @param options.aptosConfig - Configuration settings for the Aptos request. * @param options.overrides - Any overrides for the default request behavior. * @returns The response from the POST request. + * @group Implementation + * @category Client */ export async function post( options: PostRequestOptions, @@ -101,6 +125,8 @@ export async function post( * @param options.aptosConfig.clientConfig - Client-specific configuration settings. * @param options.aptosConfig.fullnodeConfig - Full node-specific configuration settings. * @param options.overrides - Additional overrides for the request. + * @group Implementation + * @category Client */ export async function postAptosFullNode( options: PostAptosRequestOptions, @@ -129,6 +155,8 @@ export async function postAptosFullNode( * @param options.aptosConfig.indexerConfig - The indexer configuration settings. * @param options.overrides - Additional overrides for the request. * @param options.overrides.HEADERS - Custom headers to include in the request. + * @group Implementation + * @category Client */ export async function postAptosIndexer( options: PostAptosRequestOptions, @@ -157,6 +185,8 @@ export async function postAptosIndexer( * @param options.aptosConfig.clientConfig.HEADERS - Optional headers to include in the request. * @param options.aptosConfig.faucetConfig - The configuration settings specific to the faucet. * @param options.overrides - Additional overrides for the request configuration. + * @group Implementation + * @category Client */ export async function postAptosFaucet( options: PostAptosRequestOptions, @@ -191,6 +221,8 @@ export async function postAptosFaucet( * @param options.headers - The headers to include in the request. * @param options.body - The body of the request. * @returns A promise that resolves to the response from the pepper service. + * @group Implementation + * @category Client */ export async function postAptosPepperService( options: PostAptosRequestOptions, @@ -204,6 +236,8 @@ export async function postAptosPepperService( * @param options - The options for the request to the Aptos proving service. * @param options.type - The type of the request, which should be set to AptosApiType.PROVER. * @param options.data - The data to be included in the request. + * @group Implementation + * @category Client */ export async function postAptosProvingService( options: PostAptosRequestOptions, diff --git a/src/client/types.ts b/src/client/types.ts index ee397c94c..dc2dc64a2 100644 --- a/src/client/types.ts +++ b/src/client/types.ts @@ -14,6 +14,8 @@ import { AptosApiType } from "../utils/const.js"; * @param headers the response headers * @param config (optional) - the request object * @param request (optional) - the request object + * @group Implementation + * @category Client */ export interface AptosResponse { status: number; @@ -27,6 +29,8 @@ export interface AptosResponse { /** * Options for handling errors in the Aptos API. + * @group Implementation + * @category Client */ type AptosApiErrorOpts = { apiType: AptosApiType; @@ -44,6 +48,8 @@ type AptosApiErrorOpts = { * @param statusText - The message associated with the response status. * @param data - The response data returned from the API. * @param request - The original AptosRequest that triggered the error. + * @group Implementation + * @category Client */ export class AptosApiError extends Error { readonly url: string; @@ -65,6 +71,8 @@ export class AptosApiError extends Error { * @param opts.aptosResponse - The response object containing error details. * * @internal This constructor is for SDK internal use - do not instantiate outside the SDK codebase. + * @group Implementation + * @category Client */ constructor({ apiType, aptosRequest, aptosResponse }: AptosApiErrorOpts) { super(deriveErrorMessage({ apiType, aptosRequest, aptosResponse })); @@ -86,6 +94,8 @@ export class AptosApiError extends Error { * @param {AptosApiType} opts.apiType - The type of API being called. * @param {AptosRequest} opts.aptosRequest - The original request made to the Aptos API. * @param {AptosResponse} opts.aptosResponse - The response received from the Aptos API. + * @group Implementation + * @category Client */ function deriveErrorMessage({ apiType, aptosRequest, aptosResponse }: AptosApiErrorOpts): string { // extract the W3C trace_id from the response headers if it exists. Some services set this in the response, and it's useful for debugging. @@ -125,6 +135,8 @@ const SERIALIZED_PAYLOAD_TRIM_TO_MAX_LENGTH = 400; * @param payload - The payload to serialize, which can be of any type. * * @returns A string representation of the serialized payload, potentially truncated. + * @group Implementation + * @category Client */ function serializeAnyPayloadForErrorMessage(payload: any): string { const serializedPayload = JSON.stringify(payload); diff --git a/src/core/account/utils/address.ts b/src/core/account/utils/address.ts index 8273962e6..ce54d1da4 100644 --- a/src/core/account/utils/address.ts +++ b/src/core/account/utils/address.ts @@ -9,6 +9,8 @@ import { DeriveScheme } from "../../../types"; * @param seed The seed in either Uint8Array | string type * * @returns The object account address + * @group Implementation + * @category Account (On-Chain Model) */ export const createObjectAddress = (creatorAddress: AccountAddress, seed: Uint8Array | string): AccountAddress => { const creatorBytes = creatorAddress.bcsToBytes(); @@ -27,6 +29,8 @@ export const createObjectAddress = (creatorAddress: AccountAddress, seed: Uint8A * @param seed The seed in either Uint8Array | string type * * @returns The resource account address + * @group Implementation + * @category Account (On-Chain Model) */ export const createResourceAddress = (creatorAddress: AccountAddress, seed: Uint8Array | string): AccountAddress => { const creatorBytes = creatorAddress.bcsToBytes(); @@ -46,6 +50,8 @@ export const createResourceAddress = (creatorAddress: AccountAddress, seed: Uint * @param tokenName The token name * * @returns The token account address + * @group Implementation + * @category Account (On-Chain Model) */ export const createTokenAddress = ( creatorAddress: AccountAddress, diff --git a/src/core/accountAddress.ts b/src/core/accountAddress.ts index 949b181ba..870bb6d41 100644 --- a/src/core/accountAddress.ts +++ b/src/core/accountAddress.ts @@ -10,6 +10,8 @@ import { HexInput, ScriptTransactionArgumentVariants } from "../types"; /** * Provides reasons for an address was invalid. + * @group Implementation + * @category Serialization */ export enum AddressInvalidReason { INCORRECT_NUMBER_OF_BYTES = "incorrect_number_of_bytes", @@ -23,6 +25,8 @@ export enum AddressInvalidReason { /** * The input for an account address, which can be either a hexadecimal string or a standard account address. + * @group Implementation + * @category Serialization */ export type AccountAddressInput = HexInput | AccountAddress; @@ -41,20 +45,28 @@ export type AccountAddressInput = HexInput | AccountAddress; * * The comments in this class make frequent reference to the LONG and SHORT formats, * as well as "special" addresses. To learn what these refer to see AIP-40. + * @group Implementation + * @category Serialization */ export class AccountAddress extends Serializable implements TransactionArgument { /** * This is the internal representation of an account address. + * @group Implementation + * @category Serialization */ readonly data: Uint8Array; /** * The number of bytes that make up an account address. + * @group Implementation + * @category Serialization */ static readonly LENGTH: number = 32; /** * The length of an address string in LONG form without a leading 0x. + * @group Implementation + * @category Serialization */ static readonly LONG_STRING_LENGTH: number = 64; @@ -77,6 +89,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * * @param input A Uint8Array representing an account address. * @throws ParsingError if the input length is not equal to 32 bytes. + * @group Implementation + * @category Serialization */ constructor(input: Uint8Array) { super(); @@ -98,6 +112,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-40.md. * * @returns true if the address is special, false otherwise. + * @group Implementation + * @category Serialization */ isSpecial(): boolean { return ( @@ -115,6 +131,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * and other addresses in LONG form (0x + 64 characters). * * @returns AccountAddress as a string conforming to AIP-40. + * @group Implementation + * @category Serialization */ toString(): `0x${string}` { return `0x${this.toStringWithoutPrefix()}`; @@ -126,6 +144,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * NOTE: Prefer to use `toString` where possible. * * @returns AccountAddress as a string without the leading 0x. + * @group Implementation + * @category Serialization */ toStringWithoutPrefix(): string { let hex = bytesToHex(this.data); @@ -141,6 +161,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * NOTE: Prefer to use `toString` where possible, as it formats special addresses using the SHORT form (no leading 0s). * * @returns AccountAddress as a string in LONG form. + * @group Implementation + * @category Serialization */ toStringLong(): `0x${string}` { return `0x${this.toStringLongWithoutPrefix()}`; @@ -153,6 +175,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * NOTE: Prefer to use `toString` where possible, as it formats special addresses using the SHORT form (no leading 0s). * * @returns {string} The account address in LONG form. + * @group Implementation + * @category Serialization */ toStringLongWithoutPrefix(): string { return bytesToHex(this.data); @@ -163,6 +187,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * The inner data is already a Uint8Array, so no conversion takes place. * * @returns Hex data as Uint8Array + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { return this.data; @@ -178,6 +204,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * address.serialize(serializer); * const bytes = serializer.toUint8Array(); * // `bytes` is now the BCS-serialized address. + * @group Implementation + * @category Serialization */ serialize(serializer: Serializer): void { serializer.serializeFixedBytes(this.data); @@ -188,6 +216,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * This allows for the proper encoding of data when interacting with entry functions in the blockchain. * * @param serializer - The serializer instance used to convert the data into bytes. + * @group Implementation + * @category Serialization */ serializeForEntryFunction(serializer: Serializer): void { const bcsBytes = this.bcsToBytes(); @@ -199,6 +229,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * This process involves serializing the variant index and the instance data, making it suitable for transmission. * * @param serializer - The serializer instance used to perform the serialization. + * @group Implementation + * @category Serialization */ serializeForScriptFunction(serializer: Serializer): void { serializer.serializeU32AsUleb128(ScriptTransactionArgumentVariants.Address); @@ -215,6 +247,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * const deserializer = new Deserializer(bytes); * const address = AccountAddress.deserialize(deserializer); * // `address` is now an instance of AccountAddress. + * @group Implementation + * @category Serialization */ static deserialize(deserializer: Deserializer): AccountAddress { const bytes = deserializer.deserializeFixedBytes(AccountAddress.LENGTH); @@ -255,6 +289,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-40.md. * * @returns An instance of AccountAddress. + * @group Implementation + * @category Serialization */ static fromStringStrict(input: string): AccountAddress { // Assert the string starts with 0x. @@ -311,6 +347,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * @returns An instance of AccountAddress. * * @throws ParsingError if the hex string is too short, too long, or contains invalid characters. + * @group Implementation + * @category Serialization */ static fromString(input: string): AccountAddress { let parsedInput = input; @@ -357,6 +395,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * * @param input - The input to convert into an AccountAddress. This can be a string representation of an address, a Uint8Array, * or an existing AccountAddress. + * @group Implementation + * @category Serialization */ static from(input: AccountAddressInput): AccountAddress { if (typeof input === "string") { @@ -372,6 +412,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * Create an AccountAddress from various input types, including strings, Uint8Array, and AccountAddress instances. * * @param input - The input to convert into an AccountAddress, which can be a string, a Uint8Array, or an AccountAddress. + * @group Implementation + * @category Serialization */ static fromStrict(input: AccountAddressInput): AccountAddress { if (typeof input === "string") { @@ -395,6 +437,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * * @returns An object indicating whether the address is valid. If valid, valid = true; if not, valid = false with additional details. * If the address is invalid, invalidReason will explain why it is invalid, and invalidReasonMessage will provide the error message. + * @group Implementation + * @category Serialization */ static isValid(args: { input: AccountAddressInput; strict?: boolean }): ParsingResult { try { @@ -418,6 +462,8 @@ export class AccountAddress extends Serializable implements TransactionArgument * * @param other - The AccountAddress to compare to. * @returns true if the AccountAddresses are equal, false if not. + * @group Implementation + * @category Serialization */ equals(other: AccountAddress): boolean { if (this.data.length !== other.data.length) return false; diff --git a/src/core/authenticationKey.ts b/src/core/authenticationKey.ts index b8bb544f4..4875e26e0 100644 --- a/src/core/authenticationKey.ts +++ b/src/core/authenticationKey.ts @@ -17,17 +17,23 @@ import { Deserializer } from "../bcs/deserializer"; * @see {@link https://aptos.dev/concepts/accounts | Account Basics} * * Account addresses can be derived from the AuthenticationKey. + * @group Implementation + * @category Serialization */ export class AuthenticationKey extends Serializable { /** * An authentication key is always a SHA3-256 hash of data, and is always 32 bytes. * * The data to hash depends on the underlying public key type and the derivation scheme. + * @group Implementation + * @category Serialization */ static readonly LENGTH: number = 32; /** * The raw bytes of the authentication key. + * @group Implementation + * @category Serialization */ public readonly data: Hex; @@ -39,6 +45,8 @@ export class AuthenticationKey extends Serializable { * @param args.data - The hex input data to be used for the Authentication Key. * @throws {Error} Throws an error if the length of the provided hex input is not equal to the required Authentication Key * length. + * @group Implementation + * @category Serialization */ constructor(args: { data: HexInput }) { super(); @@ -54,6 +62,8 @@ export class AuthenticationKey extends Serializable { * Serializes the fixed bytes data into a format suitable for transmission or storage. * * @param serializer - The serializer instance used to perform the serialization. + * @group Implementation + * @category Serialization */ serialize(serializer: Serializer): void { serializer.serializeFixedBytes(this.data.toUint8Array()); @@ -63,6 +73,8 @@ export class AuthenticationKey extends Serializable { * Deserialize an AuthenticationKey from the byte buffer in a Deserializer instance. * @param deserializer - The deserializer to deserialize the AuthenticationKey from. * @returns An instance of AuthenticationKey. + * @group Implementation + * @category Serialization */ static deserialize(deserializer: Deserializer): AuthenticationKey { const bytes = deserializer.deserializeFixedBytes(AuthenticationKey.LENGTH); @@ -73,6 +85,8 @@ export class AuthenticationKey extends Serializable { * Converts the internal data representation to a string format. * * @returns {string} The string representation of the internal data. + * @group Implementation + * @category Serialization */ toString(): string { return this.data.toString(); @@ -84,6 +98,8 @@ export class AuthenticationKey extends Serializable { * This function is useful for obtaining a byte representation of the data, which can be utilized for serialization or transmission. * * @returns Uint8Array representation of the internal data. + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { return this.data.toUint8Array(); @@ -97,6 +113,8 @@ export class AuthenticationKey extends Serializable { * @param args.scheme - The authentication key scheme to use. * @param args.input - The input data in hexadecimal format to derive the key. * @returns An instance of AuthenticationKey containing the generated key data. + * @group Implementation + * @category Serialization */ static fromSchemeAndBytes(args: { scheme: AuthenticationKeyScheme; input: HexInput }): AuthenticationKey { const { scheme, input } = args; @@ -115,6 +133,8 @@ export class AuthenticationKey extends Serializable { * @param args - The arguments for deriving the authentication key. * @param args.publicKey - The public key used for the derivation. * @param args.scheme - The scheme to use for deriving the authentication key. + * @group Implementation + * @category Serialization */ public static fromPublicKeyAndScheme(args: { publicKey: AccountPublicKey; scheme: AuthenticationKeyScheme }) { const { publicKey } = args; @@ -127,6 +147,8 @@ export class AuthenticationKey extends Serializable { * @param args - The arguments for the function. * @param args.publicKey - The PublicKey to be converted. * @returns AuthenticationKey - The derived AuthenticationKey. + * @group Implementation + * @category Serialization */ static fromPublicKey(args: { publicKey: AccountPublicKey }): AuthenticationKey { const { publicKey } = args; @@ -137,6 +159,8 @@ export class AuthenticationKey extends Serializable { * Derives an account address from an AuthenticationKey by translating the AuthenticationKey bytes directly to an AccountAddress. * * @returns AccountAddress - The derived account address. + * @group Implementation + * @category Serialization */ derivedAddress(): AccountAddress { return new AccountAddress(this.data.toUint8Array()); diff --git a/src/core/common.ts b/src/core/common.ts index 3d80c587b..56b87666f 100644 --- a/src/core/common.ts +++ b/src/core/common.ts @@ -3,12 +3,16 @@ /** * This error is used to explain why parsing failed. + * @group Implementation + * @category Serialization */ export class ParsingError extends Error { /** * This provides a programmatic way to access why parsing failed. Downstream devs * might want to use this to build their own error messages if the default error * messages are not suitable for their use case. This should be an enum. + * @group Implementation + * @category Serialization */ public invalidReason: T; @@ -17,6 +21,8 @@ export class ParsingError extends Error { * * @param message The error message that describes the issue. * @param invalidReason The reason why the input is considered invalid. + * @group Implementation + * @category Serialization */ constructor(message: string, invalidReason: T) { super(message); @@ -27,20 +33,28 @@ export class ParsingError extends Error { /** * Whereas ParsingError is thrown when parsing fails, e.g. in a fromString function, * this type is returned from "defensive" functions like isValid. + * @group Implementation + * @category Serialization */ export type ParsingResult = { /** * True if valid, false otherwise. + * @group Implementation + * @category Serialization */ valid: boolean; /** * If valid is false, this will be a code explaining why parsing failed. + * @group Implementation + * @category Serialization */ invalidReason?: T; /** * If valid is false, this will be a string explaining why parsing failed. + * @group Implementation + * @category Serialization */ invalidReasonMessage?: string; }; diff --git a/src/core/crypto/ed25519.ts b/src/core/crypto/ed25519.ts index c6f88ad36..77748b59b 100644 --- a/src/core/crypto/ed25519.ts +++ b/src/core/crypto/ed25519.ts @@ -15,6 +15,8 @@ import { convertSigningMessage } from "./utils"; /** * L is the value that greater than or equal to will produce a non-canonical signature, and must be rejected + * @group Implementation + * @category Serialization */ const L: number[] = [ 0xed, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58, 0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9, 0xde, 0x14, 0x00, 0x00, 0x00, @@ -30,6 +32,8 @@ const L: number[] = [ * * Comes from Aptos Core * https://github.com/aptos-labs/aptos-core/blob/main/crates/aptos-crypto/src/ed25519/ed25519_sigs.rs#L47-L85 + * @group Implementation + * @category Serialization */ export function isCanonicalEd25519Signature(signature: Signature): boolean { const s = signature.toUint8Array().slice(32); @@ -53,16 +57,22 @@ export function isCanonicalEd25519Signature(signature: Signature): boolean { * * Ed25519 scheme is represented in the SDK as `Legacy authentication key` and also * as `AnyPublicKey` that represents any `Unified authentication key`. + * @group Implementation + * @category Serialization */ export class Ed25519PublicKey extends AccountPublicKey { /** * Length of an Ed25519 public key + * @group Implementation + * @category Serialization */ static readonly LENGTH: number = 32; /** * Bytes of the public key * @private + * @group Implementation + * @category Serialization */ private readonly key: Hex; @@ -72,6 +82,8 @@ export class Ed25519PublicKey extends AccountPublicKey { * * @param hexInput - The hex input representing the Ed25519 signature. * @throws Error if the signature length is not equal to Ed25519Signature.LENGTH. + * @group Implementation + * @category Serialization */ constructor(hexInput: HexInput) { super(); @@ -91,6 +103,8 @@ export class Ed25519PublicKey extends AccountPublicKey { * @param args - The arguments for verification. * @param args.message - A signed message as a Hex string or Uint8Array. * @param args.signature - The signature of the message. + * @group Implementation + * @category Serialization */ verifySignature(args: VerifySignatureArgs): boolean { const { message, signature } = args; @@ -111,6 +125,8 @@ export class Ed25519PublicKey extends AccountPublicKey { * This function is essential for creating a secure authentication key that can be used for further cryptographic operations. * * @returns {AuthenticationKey} The generated authentication key. + * @group Implementation + * @category Serialization */ authKey(): AuthenticationKey { return AuthenticationKey.fromSchemeAndBytes({ @@ -123,6 +139,8 @@ export class Ed25519PublicKey extends AccountPublicKey { * Convert the internal data representation to a Uint8Array. * * @returns Uint8Array representation of the data. + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { return this.key.toUint8Array(); @@ -137,6 +155,8 @@ export class Ed25519PublicKey extends AccountPublicKey { * This allows for the conversion of data into a format suitable for transmission or storage. * * @param serializer - The serializer instance used to perform the serialization. + * @group Implementation + * @category Serialization */ serialize(serializer: Serializer): void { serializer.serializeBytes(this.key.toUint8Array()); @@ -147,6 +167,8 @@ export class Ed25519PublicKey extends AccountPublicKey { * This function is used to convert serialized byte data into a usable Ed25519Signature instance. * * @param deserializer - The deserializer instance used to read the byte data. + * @group Implementation + * @category Serialization */ static deserialize(deserializer: Deserializer): Ed25519PublicKey { const bytes = deserializer.deserializeBytes(); @@ -161,6 +183,8 @@ export class Ed25519PublicKey extends AccountPublicKey { * @param publicKey - The public key to check. * @returns True if the public key is an instance of Ed25519PublicKey, otherwise false. * @deprecated use `instanceof Ed25519PublicKey` instead. + * @group Implementation + * @category Serialization */ static isPublicKey(publicKey: AccountPublicKey): publicKey is Ed25519PublicKey { return publicKey instanceof Ed25519PublicKey; @@ -173,6 +197,8 @@ export class Ed25519PublicKey extends AccountPublicKey { * * @param publicKey - The public key to validate. * @returns A boolean indicating whether the public key is a valid Ed25519 public key. + * @group Implementation + * @category Serialization */ static isInstance(publicKey: PublicKey): publicKey is Ed25519PublicKey { return "key" in publicKey && (publicKey.key as any)?.data?.length === Ed25519PublicKey.LENGTH; @@ -186,22 +212,30 @@ export class Ed25519PublicKey extends AccountPublicKey { * @readonly LENGTH - Length of an Ed25519 private key. * @static * @readonly SLIP_0010_SEED - The Ed25519 key seed to use for BIP-32 compatibility. + * @group Implementation + * @category Serialization */ export class Ed25519PrivateKey extends Serializable implements PrivateKey { /** * Length of an Ed25519 private key + * @group Implementation + * @category Serialization */ static readonly LENGTH: number = 32; /** * The Ed25519 key seed to use for BIP-32 compatibility * See more {@link https://github.com/satoshilabs/slips/blob/master/slip-0010.md} + * @group Implementation + * @category Serialization */ static readonly SLIP_0010_SEED = "ed25519 seed"; /** * The Ed25519 signing key * @private + * @group Implementation + * @category Serialization */ private readonly signingKey: Hex; @@ -211,6 +245,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey { * Create a new PrivateKey instance from a Uint8Array or String. * * @param hexInput HexInput (string or Uint8Array) + * @group Implementation + * @category Serialization */ constructor(hexInput: HexInput) { super(); @@ -228,6 +264,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey { * Generate a new random private key. * * @returns Ed25519PrivateKey A newly generated Ed25519 private key. + * @group Implementation + * @category Serialization */ static generate(): Ed25519PrivateKey { const keyPair = ed25519.utils.randomPrivateKey(); @@ -243,6 +281,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey { * @param path - The BIP44 path used for key derivation. * @param mnemonics - The mnemonic seed phrase from which the key will be derived. * @throws Error if the provided path is not a valid hardened path. + * @group Implementation + * @category Serialization */ static fromDerivationPath(path: string, mnemonics: string): Ed25519PrivateKey { if (!isValidHardenedPath(path)) { @@ -260,6 +300,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey { * @param seed - The seed phrase created by the mnemonics, represented as a Uint8Array. * @param offset - The offset used for key derivation, defaults to HARDENED_OFFSET. * @returns An instance of Ed25519PrivateKey derived from the specified path and seed. + * @group Implementation + * @category Serialization */ private static fromDerivationPathInner(path: string, seed: Uint8Array, offset = HARDENED_OFFSET): Ed25519PrivateKey { const { key, chainCode } = deriveKey(Ed25519PrivateKey.SLIP_0010_SEED, seed); @@ -282,6 +324,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey { * Derive the Ed25519PublicKey for this private key. * * @returns Ed25519PublicKey - The derived public key corresponding to the private key. + * @group Implementation + * @category Serialization */ publicKey(): Ed25519PublicKey { const bytes = ed25519.getPublicKey(this.signingKey.toUint8Array()); @@ -294,6 +338,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey { * * @param message - A message as a string or Uint8Array in HexInput format. * @returns A digital signature for the provided message. + * @group Implementation + * @category Serialization */ sign(message: HexInput): Ed25519Signature { const messageToSign = convertSigningMessage(message); @@ -306,6 +352,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey { * Get the private key in bytes (Uint8Array). * * @returns Uint8Array representation of the private key + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { return this.signingKey.toUint8Array(); @@ -315,6 +363,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey { * Get the private key as a hex string with the 0x prefix. * * @returns string representation of the private key. + * @group Implementation + * @category Serialization */ toString(): string { return this.signingKey.toString(); @@ -342,6 +392,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey { * @returns A boolean indicating whether the private key is an Ed25519PrivateKey. * * @deprecated Use `instanceof Ed25519PrivateKey` instead. + * @group Implementation + * @category Serialization */ static isPrivateKey(privateKey: PrivateKey): privateKey is Ed25519PrivateKey { return privateKey instanceof Ed25519PrivateKey; @@ -352,16 +404,22 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey { * Represents a signature of a message signed using an Ed25519 private key. * * @static LENGTH - Length of an Ed25519 signature, which is 64 bytes. + * @group Implementation + * @category Serialization */ export class Ed25519Signature extends Signature { /** * Length of an Ed25519 signature + * @group Implementation + * @category Serialization */ static readonly LENGTH = 64; /** * The signature bytes * @private + * @group Implementation + * @category Serialization */ private readonly data: Hex; diff --git a/src/core/crypto/ephemeral.ts b/src/core/crypto/ephemeral.ts index efd1a080d..1d6a21e8f 100644 --- a/src/core/crypto/ephemeral.ts +++ b/src/core/crypto/ephemeral.ts @@ -9,15 +9,21 @@ import { Hex } from "../hex"; * Represents ephemeral public keys for Aptos Keyless accounts. * * These keys are used only temporarily within Keyless accounts and are not utilized as public keys for account identification. + * @group Implementation + * @category Serialization */ export class EphemeralPublicKey extends PublicKey { /** * The public key itself + * @group Implementation + * @category Serialization */ public readonly publicKey: PublicKey; /** * An enum indicating the scheme of the ephemeral public key + * @group Implementation + * @category Serialization */ public readonly variant: EphemeralPublicKeyVariant; @@ -27,6 +33,8 @@ export class EphemeralPublicKey extends PublicKey { * * @param publicKey - The public key to be used for the ephemeral public key. * @throws Error if the signature type is unsupported. + * @group Implementation + * @category Serialization */ constructor(publicKey: PublicKey) { super(); @@ -45,6 +53,8 @@ export class EphemeralPublicKey extends PublicKey { * Get the public key in bytes as a Uint8Array. * * @returns Uint8Array representation of the public key. + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { return this.bcsToBytes(); @@ -57,6 +67,8 @@ export class EphemeralPublicKey extends PublicKey { * @param args.message - The message that was signed. * @param args.signature - The signature that was signed by the private key of the ephemeral public key. * @returns true if the signature is valid, otherwise false. + * @group Implementation + * @category Serialization */ verifySignature(args: { message: HexInput; signature: EphemeralSignature }): boolean { const { message, signature } = args; @@ -69,6 +81,8 @@ export class EphemeralPublicKey extends PublicKey { * * @param serializer - The serializer instance used to serialize the signature. * @throws Error if the signature type is unknown. + * @group Implementation + * @category Serialization */ serialize(serializer: Serializer): void { if (this.publicKey instanceof Ed25519PublicKey) { @@ -84,6 +98,8 @@ export class EphemeralPublicKey extends PublicKey { * This function allows you to retrieve an EphemeralSignature based on the deserialized data. * * @param deserializer - The deserializer instance used to read the serialized data. + * @group Implementation + * @category Serialization */ static deserialize(deserializer: Deserializer): EphemeralPublicKey { const index = deserializer.deserializeUleb128AsU32(); @@ -100,6 +116,8 @@ export class EphemeralPublicKey extends PublicKey { * * @param publicKey - The public key to check. * @returns A boolean indicating whether the public key is an ephemeral type. + * @group Implementation + * @category Serialization */ static isPublicKey(publicKey: PublicKey): publicKey is EphemeralPublicKey { return publicKey instanceof EphemeralPublicKey; @@ -110,10 +128,14 @@ export class EphemeralPublicKey extends PublicKey { * Represents ephemeral signatures used in Aptos Keyless accounts. * * These signatures are utilized within the KeylessSignature framework. + * @group Implementation + * @category Serialization */ export class EphemeralSignature extends Signature { /** * The signature signed by the private key of an EphemeralKeyPair + * @group Implementation + * @category Serialization */ public readonly signature: Signature; @@ -133,6 +155,8 @@ export class EphemeralSignature extends Signature { * Get the public key in bytes (Uint8Array). * * @returns Uint8Array representation of the public key + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { return this.bcsToBytes(); @@ -144,6 +168,8 @@ export class EphemeralSignature extends Signature { * further processing. * * @param hexInput - The hexadecimal input representing the ephemeral signature. + * @group Implementation + * @category Serialization */ static fromHex(hexInput: HexInput): EphemeralSignature { const data = Hex.fromHexInput(hexInput); diff --git a/src/core/crypto/federatedKeyless.ts b/src/core/crypto/federatedKeyless.ts index 583639f08..905e2532f 100644 --- a/src/core/crypto/federatedKeyless.ts +++ b/src/core/crypto/federatedKeyless.ts @@ -15,15 +15,21 @@ import { KeylessPublicKey, KeylessSignature } from "./keyless"; * These keys use an on-chain address as a source of truth for the JWK used to verify signatures. * * FederatedKeylessPublicKey authentication key is represented in the SDK as `AnyPublicKey`. + * @group Implementation + * @category Serialization */ export class FederatedKeylessPublicKey extends AccountPublicKey { /** * The address that contains the JWK set to be used for verification. + * @group Implementation + * @category Serialization */ readonly jwkAddress: AccountAddress; /** * The inner public key which contains the standard Keyless public key. + * @group Implementation + * @category Serialization */ readonly keylessPublicKey: KeylessPublicKey; @@ -37,6 +43,8 @@ export class FederatedKeylessPublicKey extends AccountPublicKey { * Get the authentication key for the federated keyless public key * * @returns AuthenticationKey + * @group Implementation + * @category Serialization */ authKey(): AuthenticationKey { const serializer = new Serializer(); @@ -52,6 +60,8 @@ export class FederatedKeylessPublicKey extends AccountPublicKey { * Get the public key in bytes (Uint8Array). * * @returns Uint8Array representation of the public key + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { return this.bcsToBytes(); @@ -61,6 +71,8 @@ export class FederatedKeylessPublicKey extends AccountPublicKey { * Get the public key as a hex string with the 0x prefix. * * @returns string representation of the public key + * @group Implementation + * @category Serialization */ toString(): string { return Hex.fromHexInput(this.toUint8Array()).toString(); @@ -72,6 +84,8 @@ export class FederatedKeylessPublicKey extends AccountPublicKey { * @param args.message message * @param args.signature The signature * @returns true if the signature is valid + * @group Implementation + * @category Serialization */ // eslint-disable-next-line @typescript-eslint/no-unused-vars, class-methods-use-this verifySignature(args: { message: HexInput; signature: KeylessSignature }): boolean { @@ -102,6 +116,8 @@ export class FederatedKeylessPublicKey extends AccountPublicKey { * @param args.aud the client ID of the application * @param args.pepper The pepper used to maintain privacy of the account * @returns FederatedKeylessPublicKey + * @group Implementation + * @category Serialization */ static create(args: { iss: string; diff --git a/src/core/crypto/hdKey.ts b/src/core/crypto/hdKey.ts index 7a6e20c69..1dcae6388 100644 --- a/src/core/crypto/hdKey.ts +++ b/src/core/crypto/hdKey.ts @@ -7,6 +7,8 @@ import * as bip39 from "@scure/bip39"; /** * Contains the derived cryptographic key as a Uint8Array. + * @group Implementation + * @category Serialization */ export type DerivedKeys = { key: Uint8Array; @@ -15,17 +17,30 @@ export type DerivedKeys = { /** * Aptos derive path is 637 + * @group Implementation + * @category Serialization */ export const APTOS_HARDENED_REGEX = /^m\/44'\/637'\/[0-9]+'\/[0-9]+'\/[0-9]+'?$/; + +/** + * @group Implementation + * @category Serialization + */ export const APTOS_BIP44_REGEX = /^m\/44'\/637'\/[0-9]+'\/[0-9]+\/[0-9]+$/; /** * Supported key types and their associated seeds. + * @group Implementation + * @category Serialization */ export enum KeyType { ED25519 = "ed25519 seed", } +/** + * @group Implementation + * @category Serialization + */ export const HARDENED_OFFSET = 0x80000000; /** @@ -37,6 +52,8 @@ export const HARDENED_OFFSET = 0x80000000; * Note that for Secp256k1, the last two components must be non-hardened. * * @param path - The path string to validate (e.g. `m/44'/637'/0'/0/0`). + * @group Implementation + * @category Serialization */ export function isValidBIP44Path(path: string): boolean { return APTOS_BIP44_REGEX.test(path); @@ -57,11 +74,17 @@ export function isValidBIP44Path(path: string): boolean { * with the hash function breaking the homomorphism. * * @param path - The derivation path string to validate (e.g. `m/44'/637'/0'/0'/0'`). + * @group Implementation + * @category Serialization */ export function isValidHardenedPath(path: string): boolean { return APTOS_HARDENED_REGEX.test(path); } +/** + * @group Implementation + * @category Serialization + */ export const deriveKey = (hashSeed: Uint8Array | string, data: Uint8Array | string): DerivedKeys => { const digest = hmac.create(sha512, hashSeed).update(data).digest(); return { @@ -76,6 +99,8 @@ export const deriveKey = (hashSeed: Uint8Array | string, data: Uint8Array | stri * @param chainCode * @param index * @constructor + * @group Implementation + * @category Serialization */ export const CKDPriv = ({ key, chainCode }: DerivedKeys, index: number): DerivedKeys => { const buffer = new ArrayBuffer(4); @@ -91,12 +116,16 @@ const removeApostrophes = (val: string): string => val.replace(/'/g, ""); /** * Splits derive path into segments * @param path + * @group Implementation + * @category Serialization */ export const splitPath = (path: string): Array => path.split("/").slice(1).map(removeApostrophes); /** * Normalizes the mnemonic by removing extra whitespace and making it lowercase * @param mnemonic the mnemonic seed phrase + * @group Implementation + * @category Serialization */ export const mnemonicToSeed = (mnemonic: string): Uint8Array => { const normalizedMnemonic = mnemonic diff --git a/src/core/crypto/keyless.ts b/src/core/crypto/keyless.ts index 4c27a335d..8143f12d5 100644 --- a/src/core/crypto/keyless.ts +++ b/src/core/crypto/keyless.ts @@ -26,13 +26,45 @@ import { getAptosFullNode } from "../../client"; import { memoizeAsync } from "../../utils/memoize"; import { AccountAddress } from "../accountAddress"; +/** + * @group Implementation + * @category Serialization + */ export const EPK_HORIZON_SECS = 10000000; +/** + * @group Implementation + * @category Serialization + */ export const MAX_AUD_VAL_BYTES = 120; +/** + * @group Implementation + * @category Serialization + */ export const MAX_UID_KEY_BYTES = 30; +/** + * @group Implementation + * @category Serialization + */ export const MAX_UID_VAL_BYTES = 330; +/** + * @group Implementation + * @category Serialization + */ export const MAX_ISS_VAL_BYTES = 120; +/** + * @group Implementation + * @category Serialization + */ export const MAX_EXTRA_FIELD_BYTES = 350; +/** + * @group Implementation + * @category Serialization + */ export const MAX_JWT_HEADER_B64_BYTES = 300; +/** + * @group Implementation + * @category Serialization + */ export const MAX_COMMITED_EPK_BYTES = 93; /** @@ -42,15 +74,21 @@ export const MAX_COMMITED_EPK_BYTES = 93; * including methods for generating and verifying signatures, as well as serialization * and deserialization of the key. The KeylessPublicKey is represented in the SDK * as `AnyPublicKey`. + * @group Implementation + * @category Serialization */ export class KeylessPublicKey extends AccountPublicKey { /** * The number of bytes that `idCommitment` should be + * @group Implementation + * @category Serialization */ static readonly ID_COMMITMENT_LENGTH: number = 32; /** * The value of the 'iss' claim on the JWT which identifies the OIDC provider. + * @group Implementation + * @category Serialization */ readonly iss: string; @@ -58,6 +96,8 @@ export class KeylessPublicKey extends AccountPublicKey { * A value representing a cryptographic commitment to a user identity. * * It is calculated from the aud, uidKey, uidVal, pepper. + * @group Implementation + * @category Serialization */ readonly idCommitment: Uint8Array; @@ -70,6 +110,8 @@ export class KeylessPublicKey extends AccountPublicKey { * @param args.deltaG2 - The hex representation of the delta G2 value. * @param args.gammaAbcG1 - An array containing two hex representations for gamma ABC G1 values. * @param args.gammaG2 - The hex representation of the gamma G2 value. + * @group Implementation + * @category Serialization */ // TODO: Fix the JSDoc for the below values constructor(iss: string, idCommitment: HexInput) { @@ -86,6 +128,8 @@ export class KeylessPublicKey extends AccountPublicKey { * Get the authentication key for the keyless public key. * * @returns AuthenticationKey - The authentication key derived from the keyless public key. + * @group Implementation + * @category Serialization */ authKey(): AuthenticationKey { const serializer = new Serializer(); @@ -101,6 +145,8 @@ export class KeylessPublicKey extends AccountPublicKey { * Get the public key in bytes as a Uint8Array. * * @returns Uint8Array representation of the public key. + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array; toUint8Array(): Uint8Array { @@ -111,6 +157,8 @@ export class KeylessPublicKey extends AccountPublicKey { * Get the public key as a hex string with the 0x prefix. * * @returns string representation of the public key + * @group Implementation + * @category Serialization */ toString(): string { return Hex.fromHexInput(this.toUint8Array()).toString(); @@ -123,6 +171,8 @@ export class KeylessPublicKey extends AccountPublicKey { * @param args.message - The message that was signed. * @param args.signature - The signature to verify against the message. * @returns true if the signature is valid; otherwise, false. + * @group Implementation + * @category Serialization */ // eslint-disable-next-line @typescript-eslint/no-unused-vars, class-methods-use-this verifySignature(args: { message: HexInput; signature: KeylessSignature }): boolean { @@ -139,6 +189,8 @@ export class KeylessPublicKey extends AccountPublicKey { * @param serializer.extraField - An optional additional field for serialization. * @param serializer.overrideAudVal - An optional override value for auditing. * @param serializer.trainingWheelsSignature - An optional signature for training wheels. + * @group Implementation + * @category Serialization */ serialize(serializer: Serializer): void { serializer.serializeStr(this.iss); @@ -151,6 +203,8 @@ export class KeylessPublicKey extends AccountPublicKey { * * @param deserializer - The deserializer instance used to read the serialized data. * @returns A new instance of ZeroKnowledgeSig. + * @group Implementation + * @category Serialization */ static deserialize(deserializer: Deserializer): KeylessPublicKey { const iss = deserializer.deserializeStr(); @@ -166,6 +220,8 @@ export class KeylessPublicKey extends AccountPublicKey { * @param deserializer.deserializeStr - A method to deserialize a string value. * @param deserializer.deserializeBytes - A method to deserialize byte data. * @returns A new instance of KeylessPublicKey. + * @group Implementation + * @category Serialization */ static load(deserializer: Deserializer): KeylessPublicKey { const iss = deserializer.deserializeStr(); @@ -178,6 +234,8 @@ export class KeylessPublicKey extends AccountPublicKey { * * @param publicKey - The public key to check. * @returns A boolean indicating whether the public key is a KeylessPublicKey instance. + * @group Implementation + * @category Serialization */ static isPublicKey(publicKey: PublicKey): publicKey is KeylessPublicKey { return publicKey instanceof KeylessPublicKey; @@ -192,6 +250,8 @@ export class KeylessPublicKey extends AccountPublicKey { * @param args.aud the client ID of the application * @param args.pepper The pepper used to maintain privacy of the account * @returns KeylessPublicKey + * @group Implementation + * @category Serialization */ static create(args: { iss: string; @@ -213,6 +273,8 @@ export class KeylessPublicKey extends AccountPublicKey { * @param args.pepper - The pepper value used in the key creation process. * @param args.uidKey - An optional key to retrieve the unique identifier from the JWT payload, defaults to "sub". * @returns A KeylessPublicKey instance created from the provided JWT and pepper. + * @group Implementation + * @category Serialization */ static fromJwtAndPepper(args: { jwt: string; pepper: HexInput; uidKey?: string }): KeylessPublicKey { const { jwt, pepper, uidKey = "sub" } = args; @@ -232,6 +294,8 @@ export class KeylessPublicKey extends AccountPublicKey { * * @param publicKey - The public key to validate. * @returns A boolean indicating whether the public key is a valid instance. + * @group Implementation + * @category Serialization */ static isInstance(publicKey: PublicKey) { return ( @@ -258,30 +322,42 @@ function computeIdCommitment(args: { uidKey: string; uidVal: string; aud: string /** * Represents a signature of a message signed via a Keyless Account, utilizing proofs or a JWT token for authentication. + * @group Implementation + * @category Serialization */ export class KeylessSignature extends Signature { /** * The inner signature ZeroKnowledgeSignature or OpenIdSignature + * @group Implementation + * @category Serialization */ readonly ephemeralCertificate: EphemeralCertificate; /** * The jwt header in the token used to create the proof/signature. In json string representation. + * @group Implementation + * @category Serialization */ readonly jwtHeader: string; /** * The expiry timestamp in seconds of the EphemeralKeyPair used to sign + * @group Implementation + * @category Serialization */ readonly expiryDateSecs: number; /** * The ephemeral public key used to verify the signature + * @group Implementation + * @category Serialization */ readonly ephemeralPublicKey: EphemeralPublicKey; /** * The signature resulting from signing with the private key of the EphemeralKeyPair + * @group Implementation + * @category Serialization */ readonly ephemeralSignature: EphemeralSignature; @@ -305,6 +381,8 @@ export class KeylessSignature extends Signature { * Get the signature in bytes (Uint8Array). * * @returns Uint8Array representation of the signature + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { return this.bcsToBytes(); @@ -362,12 +440,16 @@ export class KeylessSignature extends Signature { * This class can be extended to support additional signature types, such as OpenIdSignature. * * @extends Signature + * @group Implementation + * @category Serialization */ export class EphemeralCertificate extends Signature { public readonly signature: Signature; /** * Index of the underlying enum variant + * @group Implementation + * @category Serialization */ private readonly variant: EphemeralCertificateVariant; @@ -381,6 +463,8 @@ export class EphemeralCertificate extends Signature { * Get the public key in bytes (Uint8Array). * * @returns Uint8Array representation of the public key + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { return this.signature.toUint8Array(); @@ -407,6 +491,8 @@ export class EphemeralCertificate extends Signature { * This class is used for handling and serializing G1 bytes in cryptographic operations. * * @extends Serializable + * @group Implementation + * @category Serialization */ class G1Bytes extends Serializable { data: Uint8Array; @@ -434,6 +520,8 @@ class G1Bytes extends Serializable { * This class provides methods for serialization and deserialization of G2 bytes. * * @extends Serializable + * @group Implementation + * @category Serialization */ class G2Bytes extends Serializable { data: Uint8Array; @@ -461,20 +549,28 @@ class G2Bytes extends Serializable { * The points are the compressed serialization of affine representation of the proof. * * @extends Proof + * @group Implementation + * @category Serialization */ export class Groth16Zkp extends Proof { /** * The bytes of G1 proof point a + * @group Implementation + * @category Serialization */ a: G1Bytes; /** * The bytes of G2 proof point b + * @group Implementation + * @category Serialization */ b: G2Bytes; /** * The bytes of G1 proof point c + * @group Implementation + * @category Serialization */ c: G1Bytes; @@ -504,12 +600,16 @@ export class Groth16Zkp extends Proof { * Represents a container for different types of zero-knowledge proofs. * * @extends Serializable + * @group Implementation + * @category Serialization */ export class ZkProof extends Serializable { public readonly proof: Proof; /** * Index of the underlying enum variant + * @group Implementation + * @category Serialization */ private readonly variant: ZkpVariant; @@ -539,31 +639,43 @@ export class ZkProof extends Serializable { * Represents a zero-knowledge signature, encapsulating the proof and its associated metadata. * * @extends Signature + * @group Implementation + * @category Serialization */ export class ZeroKnowledgeSig extends Signature { /** * The proof + * @group Implementation + * @category Serialization */ readonly proof: ZkProof; /** * The max lifespan of the proof + * @group Implementation + * @category Serialization */ readonly expHorizonSecs: number; /** * A key value pair on the JWT token that can be specified on the signature which would reveal the value on chain. * Can be used to assert identity or other attributes. + * @group Implementation + * @category Serialization */ readonly extraField?: string; /** * The 'aud' value of the recovery service which is set when recovering an account. + * @group Implementation + * @category Serialization */ readonly overrideAudVal?: string; /** * The training wheels signature + * @group Implementation + * @category Serialization */ readonly trainingWheelsSignature?: EphemeralSignature; @@ -587,6 +699,8 @@ export class ZeroKnowledgeSig extends Signature { * Get the signature in bytes (Uint8Array). * * @returns Uint8Array representation of the signature + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { return this.bcsToBytes(); @@ -597,6 +711,8 @@ export class ZeroKnowledgeSig extends Signature { * * @param bytes - The bytes representing the serialized ZeroKnowledgeSig. * @returns ZeroKnowledgeSig - The deserialized ZeroKnowledgeSig object. + * @group Implementation + * @category Serialization */ static fromBytes(bytes: Uint8Array): ZeroKnowledgeSig { return ZeroKnowledgeSig.deserialize(new Deserializer(bytes)); @@ -626,16 +742,22 @@ export class ZeroKnowledgeSig extends Signature { * @remarks * This class encapsulates the verification key and the maximum lifespan of ephemeral key pairs, * which are essential for the functionality of Keyless accounts. + * @group Implementation + * @category Serialization */ export class KeylessConfiguration { /** * The verification key used to verify Groth16 proofs on chain + * @group Implementation + * @category Serialization */ // TODO: Rename to verificationKey readonly verficationKey: Groth16VerificationKey; /** * The maximum lifespan of an ephemeral key pair. This is configured on chain. + * @group Implementation + * @category Serialization */ readonly maxExpHorizonSecs: number; @@ -660,32 +782,44 @@ export class KeylessConfiguration { /** * Represents the verification key stored on-chain used to verify Groth16 proofs. + * @group Implementation + * @category Serialization */ class Groth16VerificationKey { // The docstrings below are borrowed from ark-groth16 /** * The `alpha * G`, where `G` is the generator of G1 + * @group Implementation + * @category Serialization */ readonly alphaG1: G1Bytes; /** * The `alpha * H`, where `H` is the generator of G2 + * @group Implementation + * @category Serialization */ readonly betaG2: G2Bytes; /** * The `delta * H`, where `H` is the generator of G2 + * @group Implementation + * @category Serialization */ readonly deltaG2: G2Bytes; /** * The `gamma^{-1} * (beta * a_i + alpha * b_i + c_i) * H`, where H is the generator of G1 + * @group Implementation + * @category Serialization */ readonly gammaAbcG1: G1Bytes[]; /** * The `gamma * H`, where `H` is the generator of G2 + * @group Implementation + * @category Serialization */ readonly gammaG2: G2Bytes; @@ -714,6 +848,8 @@ class Groth16VerificationKey { * @param res.gamma_abc_g1 - The gamma ABC G1 value from the response. * @param res.gamma_g2 - The gamma G2 value from the response. * @returns A Groth16VerificationKey instance constructed from the provided response data. + * @group Implementation + * @category Serialization */ static fromGroth16VerificationKeyResponse(res: Groth16VerificationKeyResponse): Groth16VerificationKey { return new Groth16VerificationKey({ @@ -735,6 +871,8 @@ class Groth16VerificationKey { * @param args.options - Optional parameters for the request. * @param args.options.ledgerVersion - The ledger version to query; if not provided, the latest version will be used. * @returns KeylessConfiguration - The configuration object containing the verifying key and maximum expiry horizon. + * @group Implementation + * @category Serialization */ export async function getKeylessConfig(args: { aptosConfig: AptosConfig; @@ -760,6 +898,8 @@ export async function getKeylessConfig(args: { * @param args.options - Optional parameters for the request. * @param args.options.ledgerVersion - The ledger version to query; if not provided, it will get the latest version. * @returns KeylessConfigurationResponse - The response containing the keyless configuration data. + * @group Implementation + * @category Serialization */ async function getKeylessConfigurationResource(args: { aptosConfig: AptosConfig; @@ -785,6 +925,8 @@ async function getKeylessConfigurationResource(args: { * @param args.options - Optional parameters for the request. * @param args.options.ledgerVersion - The ledger version to query; if not provided, it will get the latest version. * @returns Groth16VerificationKeyResponse - The response containing the Groth16 verification key data. + * @group Implementation + * @category Serialization */ async function getGroth16VerificationKeyResource(args: { aptosConfig: AptosConfig; diff --git a/src/core/crypto/multiEd25519.ts b/src/core/crypto/multiEd25519.ts index fcc376253..d1988ca50 100644 --- a/src/core/crypto/multiEd25519.ts +++ b/src/core/crypto/multiEd25519.ts @@ -16,30 +16,42 @@ import { Signature } from "./signature"; * for valid signatures. * * @see {@link https://aptos.dev/integration/creating-a-signed-transaction/ | Creating a Signed Transaction} + * @group Implementation + * @category Serialization */ export class MultiEd25519PublicKey extends AccountPublicKey { /** * Maximum number of public keys supported + * @group Implementation + * @category Serialization */ static readonly MAX_KEYS = 32; /** * Minimum number of public keys needed + * @group Implementation + * @category Serialization */ static readonly MIN_KEYS = 2; /** * Minimum threshold for the number of valid signatures required + * @group Implementation + * @category Serialization */ static readonly MIN_THRESHOLD = 1; /** * List of Ed25519 public keys for this LegacyMultiEd25519PublicKey + * @group Implementation + * @category Serialization */ public readonly publicKeys: Ed25519PublicKey[]; /** * The minimum number of valid signatures required, for the number of public keys specified + * @group Implementation + * @category Serialization */ public readonly threshold: number; @@ -53,6 +65,8 @@ export class MultiEd25519PublicKey extends AccountPublicKey { * @param args - A wrapper to let you choose the param order. * @param args.publicKeys A list of public keys * @param args.threshold At least "threshold" signatures must be valid + * @group Implementation + * @category Serialization */ constructor(args: { publicKeys: Ed25519PublicKey[]; threshold: number }) { super(); @@ -88,6 +102,8 @@ export class MultiEd25519PublicKey extends AccountPublicKey { * @param args.signature - The multi-signature containing multiple signatures and a bitmap indicating which signatures are valid. * @returns True if the signature is valid; otherwise, false. * @throws Error if the bitmap and signatures length mismatch or if there are not enough valid signatures. + * @group Implementation + * @category Serialization */ verifySignature(args: VerifySignatureArgs): boolean { const { message, signature } = args; @@ -129,6 +145,8 @@ export class MultiEd25519PublicKey extends AccountPublicKey { * This function is essential for creating a secure authentication key that can be used for various cryptographic operations. * * @returns {AuthenticationKey} The generated authentication key. + * @group Implementation + * @category Serialization */ authKey(): AuthenticationKey { return AuthenticationKey.fromSchemeAndBytes({ @@ -139,6 +157,8 @@ export class MultiEd25519PublicKey extends AccountPublicKey { /** * Converts a PublicKeys into Uint8Array (bytes) with: bytes = p1_bytes | ... | pn_bytes | threshold + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { const bytes = new Uint8Array(this.publicKeys.length * Ed25519PublicKey.LENGTH + 1); @@ -160,6 +180,8 @@ export class MultiEd25519PublicKey extends AccountPublicKey { * This allows for the conversion of the instance's data into a format suitable for transmission or storage. * * @param serializer - The serializer used to convert the instance into bytes. + * @group Implementation + * @category Serialization */ serialize(serializer: Serializer): void { serializer.serializeBytes(this.toUint8Array()); @@ -170,6 +192,8 @@ export class MultiEd25519PublicKey extends AccountPublicKey { * This function helps in reconstructing a MultiEd25519Signature object from its serialized byte representation. * * @param deserializer - The deserializer instance used to read the serialized data. + * @group Implementation + * @category Serialization */ static deserialize(deserializer: Deserializer): MultiEd25519PublicKey { const bytes = deserializer.deserializeBytes(); @@ -191,20 +215,28 @@ export class MultiEd25519PublicKey extends AccountPublicKey { * Represents the signature of a K-of-N Ed25519 multi-sig transaction. * * @see {@link https://aptos.dev/integration/creating-a-signed-transaction/#multisignature-transactions | Creating a Signed Transaction} + * @group Implementation + * @category Serialization */ export class MultiEd25519Signature extends Signature { /** * Maximum number of Ed25519 signatures supported + * @group Implementation + * @category Serialization */ static MAX_SIGNATURES_SUPPORTED = 32; /** * Number of bytes in the bitmap representing who signed the transaction (32-bits) + * @group Implementation + * @category Serialization */ static BITMAP_LEN: number = 4; /** * The list of underlying Ed25519 signatures + * @group Implementation + * @category Serialization */ public readonly signatures: Ed25519Signature[]; @@ -212,6 +244,8 @@ export class MultiEd25519Signature extends Signature { * 32-bit Bitmap representing who signed the transaction * * This is represented where each public key can be masked to determine whether the message was signed by that key. + * @group Implementation + * @category Serialization */ public readonly bitmap: Uint8Array; @@ -227,6 +261,8 @@ export class MultiEd25519Signature extends Signature { * Alternatively, you can specify an array of bitmap positions. * Valid position should range between 0 and 31. * @see MultiEd25519Signature.createBitmap + * @group Implementation + * @category Serialization */ constructor(args: { signatures: Ed25519Signature[]; bitmap: Uint8Array | number[] }) { super(); @@ -252,6 +288,8 @@ export class MultiEd25519Signature extends Signature { /** * Converts a MultiSignature into Uint8Array (bytes) with `bytes = s1_bytes | ... | sn_bytes | bitmap` + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { const bytes = new Uint8Array(this.signatures.length * Ed25519Signature.LENGTH + MultiEd25519Signature.BITMAP_LEN); @@ -303,6 +341,8 @@ export class MultiEd25519Signature extends Signature { * The result bitmap should be 0b1010000000000000000000000000001 * * @returns bitmap that is 32 bits long. + * @group Implementation + * @category Serialization */ static createBitmap(args: { bits: number[] }): Uint8Array { const { bits } = args; diff --git a/src/core/crypto/multiKey.ts b/src/core/crypto/multiKey.ts index 6d40ed6b3..6dd433599 100644 --- a/src/core/crypto/multiKey.ts +++ b/src/core/crypto/multiKey.ts @@ -11,6 +11,8 @@ import { AnyPublicKey, AnySignature } from "./singleKey"; * This function can help you determine the population count of a given byte value. * * @param byte - The byte value for which to count the number of set bits. + * @group Implementation + * @category Serialization */ /* eslint-disable no-bitwise */ function bitCount(byte: number) { @@ -29,15 +31,21 @@ function bitCount(byte: number) { * The public keys of each individual agent can be any type of public key supported by Aptos. * Since [AIP-55](https://github.com/aptos-foundation/AIPs/pull/263), Aptos supports * `Legacy` and `Unified` authentication keys. + * @group Implementation + * @category Serialization */ export class MultiKey extends AccountPublicKey { /** * List of any public keys + * @group Implementation + * @category Serialization */ public readonly publicKeys: AnyPublicKey[]; /** * The minimum number of valid signatures required, for the number of public keys specified + * @group Implementation + * @category Serialization */ public readonly signaturesRequired: number; @@ -52,6 +60,8 @@ export class MultiKey extends AccountPublicKey { * * @throws Error if the number of signatures exceeds the maximum supported, if the bitmap length is incorrect, or if the number * of signatures does not match the bitmap. + * @group Implementation + * @category Serialization */ // region Constructors constructor(args: { publicKeys: Array; signaturesRequired: number }) { @@ -89,6 +99,8 @@ export class MultiKey extends AccountPublicKey { * @param args - The arguments for verifying the signature. * @param args.message - The message that was signed. * @param args.signature - The signature to verify. + * @group Implementation + * @category Serialization */ // eslint-disable-next-line class-methods-use-this, @typescript-eslint/no-unused-vars verifySignature(args: VerifySignatureArgs): boolean { @@ -100,6 +112,8 @@ export class MultiKey extends AccountPublicKey { * This key can be used for secure authentication processes within the system. * * @returns {AuthenticationKey} The generated authentication key. + * @group Implementation + * @category Serialization */ authKey(): AuthenticationKey { return AuthenticationKey.fromSchemeAndBytes({ @@ -113,6 +127,8 @@ export class MultiKey extends AccountPublicKey { * This is useful for serializing data for transmission or storage. * * @returns Uint8Array representation of the instance. + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { return this.bcsToBytes(); @@ -127,6 +143,8 @@ export class MultiKey extends AccountPublicKey { * This allows the object to be converted into a format suitable for transmission or storage. * * @param serializer - The serializer instance used to perform the serialization. + * @group Implementation + * @category Serialization */ serialize(serializer: Serializer): void { serializer.serializeVector(this.publicKeys); @@ -138,6 +156,8 @@ export class MultiKey extends AccountPublicKey { * This function retrieves the signatures and bitmap necessary for creating a MultiKeySignature object. * * @param deserializer - The deserializer instance used to read the serialized data. + * @group Implementation + * @category Serialization */ static deserialize(deserializer: Deserializer): MultiKey { const keys = deserializer.deserializeVector(AnyPublicKey); @@ -154,6 +174,8 @@ export class MultiKey extends AccountPublicKey { * * @param args.bits array of the index mapping to the matching public keys * @returns Uint8array bit map + * @group Implementation + * @category Serialization */ createBitmap(args: { bits: number[] }): Uint8Array { const { bits } = args; @@ -198,6 +220,8 @@ export class MultiKey extends AccountPublicKey { * @param publicKey - The public key to find the index for. * @returns The corresponding index of the public key, if it exists. * @throws Error - If the public key is not found in the MultiKey. + * @group Implementation + * @category Serialization */ getIndex(publicKey: PublicKey): number { const anyPublicKey = publicKey instanceof AnyPublicKey ? publicKey : new AnyPublicKey(publicKey); @@ -221,20 +245,28 @@ export class MultiKey extends AccountPublicKey { * * It includes functionality to validate the number of signatures against a bitmap, * which indicates which public keys have signed the transaction. + * @group Implementation + * @category Serialization */ export class MultiKeySignature extends Signature { /** * Number of bytes in the bitmap representing who signed the transaction (32-bits) + * @group Implementation + * @category Serialization */ static BITMAP_LEN: number = 4; /** * Maximum number of Ed25519 signatures supported + * @group Implementation + * @category Serialization */ static MAX_SIGNATURES_SUPPORTED = MultiKeySignature.BITMAP_LEN * 8; /** * The list of underlying Ed25519 signatures + * @group Implementation + * @category Serialization */ public readonly signatures: AnySignature[]; @@ -242,6 +274,8 @@ export class MultiKeySignature extends Signature { * 32-bit Bitmap representing who signed the transaction * * This is represented where each public key can be masked to determine whether the message was signed by that key. + * @group Implementation + * @category Serialization */ public readonly bitmap: Uint8Array; @@ -254,6 +288,8 @@ export class MultiKeySignature extends Signature { * @param args.signatures A list of signatures * @param args.bitmap 4 bytes, at most 32 signatures are supported. If Nth bit value is `1`, the Nth * signature should be provided in `signatures`. Bits are read from left to right + * @group Implementation + * @category Serialization */ constructor(args: { signatures: Array; bitmap: Uint8Array | number[] }) { super(); @@ -295,6 +331,8 @@ export class MultiKeySignature extends Signature { * The result bitmap should be 0b1010000000000000000000000000001 * * @returns bitmap that is 32bit long + * @group Implementation + * @category Serialization */ static createBitmap(args: { bits: number[] }): Uint8Array { const { bits } = args; diff --git a/src/core/crypto/poseidon.ts b/src/core/crypto/poseidon.ts index bc7234c59..59e40712b 100644 --- a/src/core/crypto/poseidon.ts +++ b/src/core/crypto/poseidon.ts @@ -48,6 +48,8 @@ const MAX_NUM_INPUT_BYTES = (MAX_NUM_INPUT_SCALARS - 1) * BYTES_PACKED_PER_SCALA * @param str - The string to be hashed. * @param maxSizeBytes - The maximum size in bytes for the resulting hash. * @returns bigint - The result of the hash. + * @group Implementation + * @category Serialization */ export function hashStrToField(str: string, maxSizeBytes: number): bigint { const textEncoder = new TextEncoder(); @@ -62,6 +64,8 @@ export function hashStrToField(str: string, maxSizeBytes: number): bigint { * @param bytes - The byte array to be hashed. * @param maxSizeBytes - The maximum allowed size for the byte array. * @throws Error if the length of the inputted bytes exceeds the specified maximum size. + * @group Implementation + * @category Serialization */ function hashBytesWithLen(bytes: Uint8Array, maxSizeBytes: number): bigint { if (bytes.length > maxSizeBytes) { @@ -78,6 +82,8 @@ function hashBytesWithLen(bytes: Uint8Array, maxSizeBytes: number): bigint { * @param bytes - The byte array to be padded and packed. * @param maxSizeBytes - The maximum size in bytes that the input array can have. * @throws Error if the input byte array exceeds the specified maximum size. + * @group Implementation + * @category Serialization */ function padAndPackBytesNoLen(bytes: Uint8Array, maxSizeBytes: number): bigint[] { if (bytes.length > maxSizeBytes) { @@ -96,6 +102,8 @@ function padAndPackBytesNoLen(bytes: Uint8Array, maxSizeBytes: number): bigint[] * @param maxSizeBytes - The maximum allowed size for the byte array. * @throws Error if the length of the input bytes exceeds the maximum size. * @returns A new Uint8Array that contains the padded and packed bytes along with the length of the original byte array. + * @group Implementation + * @category Serialization */ export function padAndPackBytesWithLen(bytes: Uint8Array, maxSizeBytes: number): bigint[] { if (bytes.length > maxSizeBytes) { @@ -108,6 +116,8 @@ export function padAndPackBytesWithLen(bytes: Uint8Array, maxSizeBytes: number): * Packs a Uint8Array into an array of BigInts, ensuring the input does not exceed the maximum allowed bytes. * @param bytes - The Uint8Array to be packed. * @throws {Error} Throws an error if the input exceeds the maximum number of bytes allowed. + * @group Implementation + * @category Serialization */ function packBytes(bytes: Uint8Array): bigint[] { if (bytes.length > MAX_NUM_INPUT_BYTES) { @@ -123,6 +133,8 @@ function packBytes(bytes: Uint8Array): bigint[] { * @param array - The Uint8Array to be split into chunks. * @param chunkSize - The size of each chunk. * @returns An array of Uint8Array chunks. + * @group Implementation + * @category Serialization */ function chunkUint8Array(array: Uint8Array, chunkSize: number): Uint8Array[] { const result: Uint8Array[] = []; @@ -138,6 +150,8 @@ function chunkUint8Array(array: Uint8Array, chunkSize: number): Uint8Array[] { * * @param bytes - The byte array to convert. * @returns The resulting BigInt representation of the byte array. + * @group Implementation + * @category Serialization */ export function bytesToBigIntLE(bytes: Uint8Array): bigint { let result = BigInt(0); @@ -155,6 +169,8 @@ export function bytesToBigIntLE(bytes: Uint8Array): bigint { * @param value - The number to convert into bytes. * @param length - The desired length of the resulting byte array. * @returns A Uint8Array containing the little-endian representation of the bigint value. + * @group Implementation + * @category Serialization */ export function bigIntToBytesLE(value: bigint | number, length: number): Uint8Array { let val = BigInt(value); @@ -173,6 +189,8 @@ export function bigIntToBytesLE(value: bigint | number, length: number): Uint8Ar * @param inputArray - The Uint8Array to be padded. * @param paddedSize - The desired size of the padded array, which must be greater than or equal to the input array size. * @throws Error if paddedSize is less than the length of inputArray. + * @group Implementation + * @category Serialization */ function padUint8ArrayWithZeros(inputArray: Uint8Array, paddedSize: number): Uint8Array { if (paddedSize < inputArray.length) { @@ -200,6 +218,8 @@ function padUint8ArrayWithZeros(inputArray: Uint8Array, paddedSize: number): Uin * @param inputs - An array of elements to be hashed, which can be of type number, bigint, or string. * @returns bigint - The result of the hash. * @throws Error - Throws an error if the input length exceeds the maximum allowed. + * @group Implementation + * @category Serialization */ export function poseidonHash(inputs: (number | bigint | string)[]): bigint { if (inputs.length > numInputsToPoseidonFunc.length) { diff --git a/src/core/crypto/privateKey.ts b/src/core/crypto/privateKey.ts index 095560742..21009ae13 100644 --- a/src/core/crypto/privateKey.ts +++ b/src/core/crypto/privateKey.ts @@ -8,22 +8,30 @@ import { Signature } from "./signature"; * @method sign - Signs the given message with the private key. * @method publicKey - Derives the public key associated with the private key. * @method toUint8Array - Retrieves the private key in bytes. + * @group Implementation + * @category Serialization */ export interface PrivateKey { /** * Sign the given message with the private key to create a signature. * @param message - The message to be signed, provided in HexInput format. * @returns A Signature object representing the signed message. + * @group Implementation + * @category Serialization */ sign(message: HexInput): Signature; /** * Derive the public key associated with the private key. + * @group Implementation + * @category Serialization */ publicKey(): PublicKey; /** * Get the private key in bytes (Uint8Array). + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array; } diff --git a/src/core/crypto/proof.ts b/src/core/crypto/proof.ts index f1cdd632b..f8a81d410 100644 --- a/src/core/crypto/proof.ts +++ b/src/core/crypto/proof.ts @@ -4,12 +4,16 @@ import { Hex } from "../hex"; /** * An abstract representation of a cryptographic proof associated with specific * zero-knowledge proof schemes, such as Groth16 and PLONK. + * @group Implementation + * @category Serialization */ export abstract class Proof extends Serializable { /** * Get the proof as a hex string with a 0x prefix. * * @returns The proof represented as a hex string. + * @group Implementation + * @category Serialization */ toString(): string { const bytes = this.bcsToBytes(); diff --git a/src/core/crypto/publicKey.ts b/src/core/crypto/publicKey.ts index 16128b012..bbf29499b 100644 --- a/src/core/crypto/publicKey.ts +++ b/src/core/crypto/publicKey.ts @@ -9,6 +9,8 @@ import { Signature } from "./signature"; * * @param message - The original message that was signed. * @param signature - The signature to be verified against the message. + * @group Implementation + * @category Serialization */ export interface VerifySignatureArgs { message: HexInput; @@ -20,17 +22,23 @@ export interface VerifySignatureArgs { * * This class provides a common interface for verifying signatures associated with the public key. * It allows for the retrieval of the raw public key bytes and the public key in a hexadecimal string format. + * @group Implementation + * @category Serialization */ export abstract class PublicKey extends Serializable { /** * Verifies that the private key associated with this public key signed the message with the given signature. * @param args.message The message that was signed * @param args.signature The signature to verify + * @group Implementation + * @category Serialization */ abstract verifySignature(args: VerifySignatureArgs): boolean; /** * Get the raw public key bytes + * @group Implementation + * @category Serialization */ abstract toUint8Array(): Uint8Array; @@ -38,6 +46,8 @@ export abstract class PublicKey extends Serializable { * Get the public key as a hex string with a 0x prefix. * * @returns The public key in hex format. + * @group Implementation + * @category Serialization */ toString(): string { const bytes = this.toUint8Array(); @@ -51,10 +61,14 @@ export abstract class PublicKey extends Serializable { * Provides a common interface for deriving an authentication key. * * @abstract + * @group Implementation + * @category Serialization */ export abstract class AccountPublicKey extends PublicKey { /** * Get the authentication key associated with this public key + * @group Implementation + * @category Serialization */ abstract authKey(): AuthenticationKey; } diff --git a/src/core/crypto/secp256k1.ts b/src/core/crypto/secp256k1.ts index 0b9c5c0c6..0af31b025 100644 --- a/src/core/crypto/secp256k1.ts +++ b/src/core/crypto/secp256k1.ts @@ -19,6 +19,8 @@ import { convertSigningMessage } from "./utils"; * @extends PublicKey * @static * @property LENGTH - The length of the Secp256k1 public key in bytes. + * @group Implementation + * @category Serialization */ export class Secp256k1PublicKey extends PublicKey { // Secp256k1 ecdsa public keys contain a prefix indicating compression and two 32-byte coordinates. @@ -33,6 +35,8 @@ export class Secp256k1PublicKey extends PublicKey { * * @param hexInput - A HexInput (string or Uint8Array) representing the signature data. * @throws Error if the length of the signature data is not equal to Secp256k1Signature.LENGTH. + * @group Implementation + * @category Serialization */ constructor(hexInput: HexInput) { super(); @@ -53,6 +57,8 @@ export class Secp256k1PublicKey extends PublicKey { * @param args - The arguments for verifying the signature. * @param args.message - The message that was signed. * @param args.signature - The signature to verify against the public key. + * @group Implementation + * @category Serialization */ verifySignature(args: VerifySignatureArgs): boolean { const { message, signature } = args; @@ -67,6 +73,8 @@ export class Secp256k1PublicKey extends PublicKey { * Get the data as a Uint8Array representation. * * @returns Uint8Array representation of the data. + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { return this.key.toUint8Array(); @@ -81,6 +89,8 @@ export class Secp256k1PublicKey extends PublicKey { * This function is essential for converting data into a format suitable for transmission or storage. * * @param serializer - The serializer instance used to convert the data. + * @group Implementation + * @category Serialization */ serialize(serializer: Serializer): void { serializer.serializeBytes(this.key.toUint8Array()); @@ -91,6 +101,8 @@ export class Secp256k1PublicKey extends PublicKey { * This function allows you to reconstruct a Secp256k1Signature object from its serialized byte representation. * * @param deserializer - The deserializer instance used to read the serialized data. + * @group Implementation + * @category Serialization */ // eslint-disable-next-line class-methods-use-this deserialize(deserializer: Deserializer) { @@ -110,6 +122,8 @@ export class Secp256k1PublicKey extends PublicKey { * * @deprecated use `instanceof Secp256k1PublicKey` instead * @param publicKey - The public key to check. + * @group Implementation + * @category Serialization */ static isPublicKey(publicKey: PublicKey): publicKey is Secp256k1PublicKey { return publicKey instanceof Secp256k1PublicKey; @@ -121,6 +135,8 @@ export class Secp256k1PublicKey extends PublicKey { * * @param publicKey - The public key to validate. * @returns A boolean indicating whether the public key is a valid Secp256k1 public key. + * @group Implementation + * @category Serialization */ static isInstance(publicKey: PublicKey): publicKey is Secp256k1PublicKey { return "key" in publicKey && (publicKey.key as any)?.data?.length === Secp256k1PublicKey.LENGTH; @@ -130,16 +146,22 @@ export class Secp256k1PublicKey extends PublicKey { /** * Represents a Secp256k1 ECDSA private key, providing functionality to create, sign messages, * derive public keys, and serialize/deserialize the key. + * @group Implementation + * @category Serialization */ export class Secp256k1PrivateKey extends Serializable implements PrivateKey { /** * Length of Secp256k1 ecdsa private key + * @group Implementation + * @category Serialization */ static readonly LENGTH: number = 32; /** * The private key bytes * @private + * @group Implementation + * @category Serialization */ private readonly key: Hex; @@ -149,6 +171,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey { * Create a new PrivateKey instance from a Uint8Array or String. * * @param hexInput A HexInput (string or Uint8Array) + * @group Implementation + * @category Serialization */ constructor(hexInput: HexInput) { super(); @@ -165,6 +189,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey { * Generate a new random private key. * * @returns Secp256k1PrivateKey - A newly generated Secp256k1 private key. + * @group Implementation + * @category Serialization */ static generate(): Secp256k1PrivateKey { const hexInput = secp256k1.utils.randomPrivateKey(); @@ -180,6 +206,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey { * @returns The generated private key. * * @throws Error if the provided path is not a valid BIP44 path. + * @group Implementation + * @category Serialization */ static fromDerivationPath(path: string, mnemonics: string): Secp256k1PrivateKey { if (!isValidBIP44Path(path)) { @@ -196,6 +224,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey { * @param seed - The seed phrase created by the mnemonics, represented as a Uint8Array. * @returns The generated private key as an instance of Secp256k1PrivateKey. * @throws Error if the derived private key is invalid. + * @group Implementation + * @category Serialization */ private static fromDerivationPathInner(path: string, seed: Uint8Array): Secp256k1PrivateKey { const { privateKey } = HDKey.fromMasterSeed(seed).derive(path); @@ -217,6 +247,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey { * * @param message - A message in HexInput format to be signed. * @returns Signature - The generated signature for the provided message. + * @group Implementation + * @category Serialization */ sign(message: HexInput): Secp256k1Signature { const messageToSign = convertSigningMessage(message); @@ -230,6 +262,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey { * Derive the Secp256k1PublicKey from this private key. * * @returns Secp256k1PublicKey The derived public key. + * @group Implementation + * @category Serialization */ publicKey(): Secp256k1PublicKey { const bytes = secp256k1.getPublicKey(this.key.toUint8Array(), false); @@ -240,6 +274,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey { * Get the private key in bytes (Uint8Array). * * @returns + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { return this.key.toUint8Array(); @@ -249,6 +285,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey { * Get the private key as a string representation. * * @returns string representation of the private key + * @group Implementation + * @category Serialization */ toString(): string { return this.key.toString(); @@ -275,6 +313,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey { * @param privateKey - The private key to be checked. * * @deprecated use `instanceof Secp256k1PrivateKey` instead + * @group Implementation + * @category Serialization */ static isPrivateKey(privateKey: PrivateKey): privateKey is Secp256k1PrivateKey { return privateKey instanceof Secp256k1PrivateKey; @@ -287,16 +327,22 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey { * @static * @readonly * @length The length of Secp256k1 ECDSA signatures, which is 64 bytes. + * @group Implementation + * @category Serialization */ export class Secp256k1Signature extends Signature { /** * Secp256k1 ecdsa signatures are 256-bit. + * @group Implementation + * @category Serialization */ static readonly LENGTH = 64; /** * The signature bytes * @private + * @group Implementation + * @category Serialization */ private readonly data: Hex; @@ -306,6 +352,8 @@ export class Secp256k1Signature extends Signature { * Create a new Signature instance from a Uint8Array or String. * * @param hexInput A HexInput (string or Uint8Array) + * @group Implementation + * @category Serialization */ constructor(hexInput: HexInput) { super(); diff --git a/src/core/crypto/signature.ts b/src/core/crypto/signature.ts index b2f6725cc..de3333921 100644 --- a/src/core/crypto/signature.ts +++ b/src/core/crypto/signature.ts @@ -7,16 +7,22 @@ import { Hex } from "../hex"; * * This class represents the product of signing a message directly from a * PrivateKey and can be verified against a CryptoPublicKey. + * @group Implementation + * @category Serialization */ export abstract class Signature extends Serializable { /** * Get the raw signature bytes + * @group Implementation + * @category Serialization */ abstract toUint8Array(): Uint8Array; /** * Get the signature as a hex string with a 0x prefix e.g. 0x123456... * @returns The hex string representation of the signature. + * @group Implementation + * @category Serialization */ toString(): string { const bytes = this.toUint8Array(); @@ -30,6 +36,8 @@ export abstract class Signature extends Serializable { * * This is the product of signing a message through an account, * and can be verified against an AccountPublicKey. + * @group Implementation + * @category Serialization */ // export abstract class AccountSignature extends Serializable { // /** diff --git a/src/core/crypto/singleKey.ts b/src/core/crypto/singleKey.ts index 5c7424943..cfc6cf651 100644 --- a/src/core/crypto/singleKey.ts +++ b/src/core/crypto/singleKey.ts @@ -15,15 +15,21 @@ import { FederatedKeylessPublicKey } from "./federatedKeyless"; * `Legacy` and `Unified` authentication keys. * * Any unified authentication key is represented in the SDK as `AnyPublicKey`. + * @group Implementation + * @category Serialization */ export class AnyPublicKey extends AccountPublicKey { /** * Reference to the inner public key + * @group Implementation + * @category Serialization */ public readonly publicKey: PublicKey; /** * Index of the underlying enum variant + * @group Implementation + * @category Serialization */ public readonly variant: AnyPublicKeyVariant; @@ -35,6 +41,8 @@ export class AnyPublicKey extends AccountPublicKey { * * @param publicKey - The publicKey object which determines the variant to be used. * @throws Error if the provided signature type is unsupported. + * @group Implementation + * @category Serialization */ constructor(publicKey: PublicKey) { super(); @@ -64,6 +72,8 @@ export class AnyPublicKey extends AccountPublicKey { * @param args.message - The message that was signed. * @param args.signature - The signature to verify, which must be an instance of AnySignature. * @returns A boolean indicating whether the signature is valid for the given message. + * @group Implementation + * @category Serialization */ verifySignature(args: VerifySignatureArgs): boolean { const { message, signature } = args; @@ -82,6 +92,8 @@ export class AnyPublicKey extends AccountPublicKey { * This function is essential for creating a unique identifier for authentication purposes. * * @returns {AuthenticationKey} The generated authentication key. + * @group Implementation + * @category Serialization */ authKey(): AuthenticationKey { return AuthenticationKey.fromSchemeAndBytes({ @@ -97,6 +109,8 @@ export class AnyPublicKey extends AccountPublicKey { * Use AnySignature.bcsToBytes() instead. * * @returns Uint8Array representation of the signature. + * @group Implementation + * @category Serialization */ toUint8Array() { return this.bcsToBytes(); @@ -111,6 +125,8 @@ export class AnyPublicKey extends AccountPublicKey { * This function helps in converting the object into a format suitable for transmission or storage. * * @param serializer - The serializer instance used to perform the serialization. + * @group Implementation + * @category Serialization */ serialize(serializer: Serializer): void { serializer.serializeU32AsUleb128(this.variant); @@ -122,6 +138,8 @@ export class AnyPublicKey extends AccountPublicKey { * This function helps in reconstructing the AnySignature object from its serialized form, allowing for further processing or validation. * * @param deserializer - The deserializer instance used to read the serialized data. + * @group Implementation + * @category Serialization */ static deserialize(deserializer: Deserializer): AnyPublicKey { const variantIndex = deserializer.deserializeUleb128AsU32(); @@ -151,6 +169,8 @@ export class AnyPublicKey extends AccountPublicKey { * * @param publicKey - The public key to check. * @deprecated Use `instanceof AnyPublicKey` instead. + * @group Implementation + * @category Serialization */ static isPublicKey(publicKey: AccountPublicKey): publicKey is AnyPublicKey { return publicKey instanceof AnyPublicKey; @@ -160,6 +180,8 @@ export class AnyPublicKey extends AccountPublicKey { * Determines if the current public key is an instance of Ed25519PublicKey. * * @deprecated use `publicKey instanceof Ed25519PublicKey` instead. + * @group Implementation + * @category Serialization */ isEd25519(): boolean { return this.publicKey instanceof Ed25519PublicKey; @@ -169,6 +191,8 @@ export class AnyPublicKey extends AccountPublicKey { * Checks if the public key is an instance of Secp256k1PublicKey. * * @deprecated use `publicKey instanceof Secp256k1PublicKey` instead. + * @group Implementation + * @category Serialization */ isSecp256k1PublicKey(): boolean { return this.publicKey instanceof Secp256k1PublicKey; @@ -180,6 +204,8 @@ export class AnyPublicKey extends AccountPublicKey { * @param publicKey - The publicKey to be checked for validity. * @param publicKey.publicKey - The actual publicKey object that needs to be validated. * @returns True if the signature is a valid instance; otherwise, false. + * @group Implementation + * @category Serialization */ static isInstance(publicKey: PublicKey): publicKey is AnyPublicKey { return "publicKey" in publicKey && "variant" in publicKey; @@ -192,12 +218,16 @@ export class AnyPublicKey extends AccountPublicKey { * only be generated by a `SingleKeySigner` due to the shared authentication mechanism. * * @extends Signature + * @group Implementation + * @category Serialization */ export class AnySignature extends Signature { public readonly signature: Signature; /** * Index of the underlying enum variant + * @group Implementation + * @category Serialization */ private readonly variant: AnySignatureVariant; diff --git a/src/core/crypto/utils.ts b/src/core/crypto/utils.ts index f75ef679b..1e3fb1df4 100644 --- a/src/core/crypto/utils.ts +++ b/src/core/crypto/utils.ts @@ -7,6 +7,8 @@ import { Hex } from "../hex"; * @param message a message as a string or Uint8Array * * @returns a valid HexInput - string or Uint8Array + * @group Implementation + * @category Serialization */ export const convertSigningMessage = (message: HexInput): HexInput => { // if message is of type string, verify it is a valid Hex string diff --git a/src/core/hex.ts b/src/core/hex.ts index 1fef0881e..2f1128e37 100644 --- a/src/core/hex.ts +++ b/src/core/hex.ts @@ -7,6 +7,8 @@ import { HexInput } from "../types"; /** * Provides reasons for parsing failures related to hexadecimal values. + * @group Implementation + * @category Serialization */ export enum HexInvalidReason { TOO_SHORT = "too_short", @@ -37,6 +39,8 @@ export enum HexInvalidReason { * Other ways to chain the functions together: * - `Hex.fromHexString({ hexInput: "0x1f" }).toUint8Array()` * - `new Hex([1, 3]).toStringWithoutPrefix()` + * @group Implementation + * @category Serialization */ export class Hex { private readonly data: Uint8Array; @@ -45,6 +49,8 @@ export class Hex { * Create a new Hex instance from a Uint8Array. * * @param data - The Uint8Array containing the data to initialize the Hex instance. + * @group Implementation + * @category Serialization */ constructor(data: Uint8Array) { this.data = data; @@ -58,6 +64,8 @@ export class Hex { * Get the inner hex data as a Uint8Array. The inner data is already a Uint8Array, so no conversion takes place. * * @returns Hex data as Uint8Array + * @group Implementation + * @category Serialization */ toUint8Array(): Uint8Array { return this.data; @@ -67,6 +75,8 @@ export class Hex { * Get the hex data as a string without the 0x prefix. * * @returns Hex string without 0x prefix + * @group Implementation + * @category Serialization */ toStringWithoutPrefix(): string { return bytesToHex(this.data); @@ -76,6 +86,8 @@ export class Hex { * Get the hex data as a string with the 0x prefix. * * @returns Hex string with 0x prefix + * @group Implementation + * @category Serialization */ toString(): string { return `0x${this.toStringWithoutPrefix()}`; @@ -93,6 +105,8 @@ export class Hex { * @throws ParsingError - If the hex string is too short, has an odd number of characters, or contains invalid hex characters. * * @returns Hex - The resulting Hex instance created from the provided string. + * @group Implementation + * @category Serialization */ static fromHexString(str: string): Hex { let input = str; @@ -128,6 +142,8 @@ export class Hex { * * @param hexInput - A HexInput which can be a string or Uint8Array. * @returns A Hex instance created from the provided hexInput. + * @group Implementation + * @category Serialization */ static fromHexInput(hexInput: HexInput): Hex { if (hexInput instanceof Uint8Array) return new Hex(hexInput); @@ -147,6 +163,8 @@ export class Hex { * - valid: A boolean indicating whether the string is valid. * - invalidReason: The reason for invalidity if the string is not valid. * - invalidReasonMessage: A message explaining why the string is invalid. + * @group Implementation + * @category Serialization */ static isValid(str: string): ParsingResult { try { @@ -166,6 +184,8 @@ export class Hex { * * @param other The Hex instance to compare to. * @returns true if the Hex instances are equal, false if not. + * @group Implementation + * @category Serialization */ equals(other: Hex): boolean { if (this.data.length !== other.data.length) return false; diff --git a/src/internal/account.ts b/src/internal/account.ts index edf1c8e1a..4dc70ca09 100644 --- a/src/internal/account.ts +++ b/src/internal/account.ts @@ -6,6 +6,7 @@ * the {@link api/account}. By moving the methods out into a separate file, * other namespaces and processes can access these methods without depending on the entire * account namespace and without having a dependency cycle error. + * @group Implementation */ import { AptosConfig } from "../api/aptosConfig"; @@ -63,6 +64,7 @@ import { APTOS_COIN } from "../utils"; * @param args - The arguments for retrieving account information. * @param args.aptosConfig - The configuration object for Aptos. * @param args.accountAddress - The address of the account to retrieve information for. + * @group Implementation */ export async function getInfo(args: { aptosConfig: AptosConfig; @@ -87,6 +89,7 @@ export async function getInfo(args: { * @param args.options.limit - The maximum number of modules to retrieve (default is 1000). * @param args.options.offset - The starting point for pagination. * @param args.options.ledgerVersion - The specific ledger version to query. + * @group Implementation */ export async function getModules(args: { aptosConfig: AptosConfig; @@ -117,6 +120,7 @@ export async function getModules(args: { * @param args.options - Optional parameters for the request. * @param args.options.ledgerVersion - Specifies the ledger version of transactions. By default, the latest version will be used. * @returns The move module. + * @group Implementation */ export async function getModule(args: { aptosConfig: AptosConfig; @@ -146,6 +150,7 @@ export async function getModule(args: { * @param args.moduleName - The name of the module to retrieve. * @param args.options - Optional parameters for specifying the ledger version. * @param args.options.ledgerVersion - The specific ledger version to query. + * @group Implementation */ async function getModuleInner(args: { aptosConfig: AptosConfig; @@ -174,6 +179,7 @@ async function getModuleInner(args: { * @param args.options - Optional pagination parameters. * @param args.options.offset - The starting point for pagination. * @param args.options.limit - The maximum number of transactions to retrieve. + * @group Implementation */ export async function getTransactions(args: { aptosConfig: AptosConfig; @@ -199,6 +205,7 @@ export async function getTransactions(args: { * @param args.options.offset - The starting point for pagination. * @param args.options.limit - The maximum number of resources to retrieve (default is 999). * @param args.options.ledgerVersion - The specific ledger version to query. + * @group Implementation */ export async function getResources(args: { aptosConfig: AptosConfig; @@ -226,6 +233,7 @@ export async function getResources(args: { * @param args.accountAddress - The address of the account from which to retrieve the resource. * @param args.resourceType - The type of the resource to retrieve, specified as a MoveStructId. * @param args.options - Optional parameters for specifying the ledger version. + * @group Implementation */ export async function getResource(args: { aptosConfig: AptosConfig; @@ -252,6 +260,7 @@ export async function getResource(args: { * @param args.options - Optional parameters for specifying the ledger version. * @returns The original account address or the provided authentication key address if not found. * @throws Throws an error if the lookup fails for reasons other than the address not being found. + * @group Implementation */ export async function lookupOriginalAccountAddress(args: { aptosConfig: AptosConfig; @@ -306,6 +315,7 @@ export async function lookupOriginalAccountAddress(args: { * @param args.aptosConfig - The configuration settings for the Aptos network. * @param args.accountAddress - The address of the account for which to count the tokens. * @returns The count of tokens owned by the specified account. + * @group Implementation */ export async function getAccountTokensCount(args: { aptosConfig: AptosConfig; @@ -350,6 +360,7 @@ export async function getAccountTokensCount(args: { * @param args.options.limit - The maximum number of records to return. * @param args.options.orderBy - The criteria for ordering the results. * @returns A promise that resolves to the current token ownerships of the specified account. + * @group Implementation */ export async function getAccountOwnedTokens(args: { aptosConfig: AptosConfig; @@ -397,6 +408,7 @@ export async function getAccountOwnedTokens(args: { * @param args.collectionAddress - The address of the collection from which tokens are being retrieved. * @param args.options - Optional parameters for filtering and pagination, including token standard, pagination arguments, and * order by options. + * @group Implementation */ export async function getAccountOwnedTokensFromCollectionAddress(args: { aptosConfig: AptosConfig; @@ -453,6 +465,7 @@ export async function getAccountOwnedTokensFromCollectionAddress(args: { * @param args.options.offset - An optional offset for pagination. * @param args.options.limit - An optional limit for the number of results returned. * @param args.options.orderBy - An optional parameter to specify the order of the results. + * @group Implementation */ export async function getAccountCollectionsWithOwnedTokens(args: { aptosConfig: AptosConfig; @@ -501,6 +514,7 @@ export async function getAccountCollectionsWithOwnedTokens(args: { * @param args.aptosConfig - The configuration settings for Aptos. * @param args.accountAddress - The address of the account for which to retrieve the transaction count. * @returns The number of transactions associated with the specified account. + * @group Implementation */ export async function getAccountTransactionsCount(args: { aptosConfig: AptosConfig; @@ -536,6 +550,7 @@ export async function getAccountTransactionsCount(args: { * @param args.faMetadataAddress - Optional; the address of the fungible asset metadata. * @returns The amount of the specified coin held by the account, or 0 if none is found. * @throws Error if neither coinType nor faMetadataAddress is provided. + * @group Implementation */ export async function getAccountCoinAmount(args: { aptosConfig: AptosConfig; @@ -600,6 +615,7 @@ export async function getAccountCoinAmount(args: { * @param args.options.limit - The maximum number of items to return. * @param args.options.orderBy - The criteria for ordering the results. * @param args.options.where - Conditions to filter the results based on the current fungible asset balances. + * @group Implementation */ export async function getAccountCoinsData(args: { aptosConfig: AptosConfig; @@ -640,6 +656,7 @@ export async function getAccountCoinsData(args: { * @param args.aptosConfig - The configuration settings for the Aptos network. * @param args.accountAddress - The address of the account for which to retrieve the coin count. * @throws Error if the count of account coins cannot be retrieved. + * @group Implementation */ export async function getAccountCoinsCount(args: { aptosConfig: AptosConfig; @@ -677,6 +694,7 @@ export async function getAccountCoinsCount(args: { * @param args.options.limit - The maximum number of items to return. * @param args.options.orderBy - The criteria to order the results by. * @returns A promise that resolves to the current objects owned by the specified account. + * @group Implementation */ export async function getAccountOwnedObjects(args: { aptosConfig: AptosConfig; @@ -721,6 +739,7 @@ export async function getAccountOwnedObjects(args: { * @param args.aptosConfig - The Aptos configuration used for account lookup. * @param args.privateKey - The private key used to derive the account. * @throws Error if the account cannot be derived from the private key. + * @group Implementation */ export async function deriveAccountFromPrivateKey(args: { aptosConfig: AptosConfig; @@ -773,6 +792,7 @@ export async function deriveAccountFromPrivateKey(args: { * @returns A promise that resolves to a boolean indicating whether the account exists. * * @throws Throws an Error if there is an issue while looking for account information. + * @group Implementation */ export async function isAccountExist(args: { aptosConfig: AptosConfig; authKey: AuthenticationKey }): Promise { const { aptosConfig, authKey } = args; diff --git a/src/internal/ans.ts b/src/internal/ans.ts index 25e4194cf..6cc17acf8 100644 --- a/src/internal/ans.ts +++ b/src/internal/ans.ts @@ -6,6 +6,7 @@ * the {@link api/name}. By moving the methods out into a separate file, * other namespaces and processes can access these methods without depending on the entire * name namespace and without having a dependency cycle error. + * @group Implementation */ import { AptosConfig } from "../api/aptosConfig"; @@ -34,6 +35,7 @@ export const VALIDATION_RULES_DESCRIPTION = [ * * @param fragment - A fragment of a name, either the domain or subdomain. * @returns A boolean indicating if the fragment is a valid fragment. + * @group Implementation */ export function isValidANSSegment(fragment: string): boolean { if (!fragment) return false; @@ -48,6 +50,7 @@ export function isValidANSSegment(fragment: string): boolean { * Checks if an ANS name is valid or not. * * @param name - A string of the domain name, which can include or exclude the .apt suffix. + * @group Implementation */ export function isValidANSName(name: string): { domainName: string; subdomainName?: string } { const [first, second, ...rest] = name.replace(/\.apt$/, "").split("."); @@ -72,6 +75,7 @@ export function isValidANSName(name: string): { domainName: string; subdomainNam /** * Policy for determining how subdomains expire in relation to their parent domain. + * @group Implementation */ export enum SubdomainExpirationPolicy { Independent = 0, @@ -86,6 +90,7 @@ export enum SubdomainExpirationPolicy { * * @param name - An ANS name returned from one of the functions of the SDK. * @returns A boolean indicating whether the contract considers the name active or not. + * @group Implementation */ export function isActiveANSName(name: GetANSNameResponse[0]): boolean { if (!name) return false; @@ -125,6 +130,7 @@ const NetworkToAnsContract: Record = { * @param aptosConfig.network - The network for which to retrieve the ANS contract address. * * @throws Throws an error if the ANS contract is not deployed to the specified network. + * @group Implementation */ function getRouterAddress(aptosConfig: AptosConfig): string { const address = NetworkToAnsContract[aptosConfig.network]; @@ -147,6 +153,7 @@ const unwrapOption = (option: any): T | undefined => { * @param args.aptosConfig - The Aptos configuration object. * @param args.name - The name of the domain or subdomain to query. * @returns The account address of the owner, or undefined if not found. + * @group Implementation */ export async function getOwnerAddress(args: { aptosConfig: AptosConfig; @@ -176,6 +183,7 @@ export async function getOwnerAddress(args: { * @param sender - The account initiating the name registration. * @param name - The name to be registered. * @param expiration - The expiration policy for the name registration. + * @group Implementation */ export interface RegisterNameParameters { aptosConfig: AptosConfig; @@ -210,6 +218,7 @@ export interface RegisterNameParameters { * @throws Error if the subdomain expiration time exceeds the domain expiration time. * * @returns A transaction object representing the registration process. + * @group Implementation */ export async function registerName(args: RegisterNameParameters): Promise { const { aptosConfig, expiration, name, sender, targetAddress, toAddress, options, transferable } = args; @@ -296,6 +305,7 @@ export async function registerName(args: RegisterNameParameters): Promise { const { aptosConfig, name } = args; @@ -326,6 +336,7 @@ export async function getExpiration(args: { aptosConfig: AptosConfig; name: stri * @param args.aptosConfig - The Aptos configuration object. * @param args.address - The account address for which to retrieve the primary name. * @returns The primary name as a string, or undefined if no domain name exists. + * @group Implementation */ export async function getPrimaryName(args: { aptosConfig: AptosConfig; @@ -360,6 +371,7 @@ export async function getPrimaryName(args: { * @param args.name - The name to set as the primary name. If omitted, the function will clear the primary name. * @param args.options - Optional transaction generation options. * @returns A transaction object representing the operation. + * @group Implementation */ export async function setPrimaryName(args: { aptosConfig: AptosConfig; @@ -406,6 +418,7 @@ export async function setPrimaryName(args: { * @param args.aptosConfig - The Aptos configuration object. * @param args.name - The name of the domain, which may include a subdomain. * @returns The target address as an AccountAddress, or undefined if not found. + * @group Implementation */ export async function getTargetAddress(args: { aptosConfig: AptosConfig; @@ -439,6 +452,7 @@ export async function getTargetAddress(args: { * @param args.options - Optional parameters for generating the transaction. * * @returns A transaction object representing the set target address operation. + * @group Implementation */ export async function setTargetAddress(args: { aptosConfig: AptosConfig; @@ -471,6 +485,7 @@ export async function setTargetAddress(args: { * @param args.aptosConfig - The configuration object for Aptos. * @param args.name - The name to look up, which includes the domain and optional subdomain. * @returns The active Aptos name if it exists; otherwise, returns undefined. + * @group Implementation */ export async function getName(args: { aptosConfig: AptosConfig; @@ -509,6 +524,7 @@ export async function getName(args: { * Options for querying names, including pagination, ordering, and filtering criteria. * * @param options - Pagination and filtering options for the query. + * @group Implementation */ interface QueryNamesOptions { options?: PaginationArgs & OrderByArg & WhereArg; @@ -518,6 +534,7 @@ interface QueryNamesOptions { * Arguments for retrieving account names based on the specified account address. * * @param accountAddress - The address of the account for which names are to be retrieved. + * @group Implementation */ export interface GetAccountNamesArgs extends QueryNamesOptions { accountAddress: AccountAddressInput; @@ -536,6 +553,7 @@ export interface GetAccountNamesArgs extends QueryNamesOptions { * @param args.accountAddress - The address of the account for which to retrieve names. * * @returns An array of sanitized Aptos names associated with the specified account address. + * @group Implementation */ export async function getAccountNames( args: { aptosConfig: AptosConfig } & GetAccountNamesArgs, @@ -569,6 +587,7 @@ export async function getAccountNames( * Arguments for retrieving the domains associated with a specific account. * * @param accountAddress - The address of the account for which to fetch domains. + * @group Implementation */ export interface GetAccountDomainsArgs extends QueryNamesOptions { accountAddress: AccountAddressInput; @@ -589,6 +608,7 @@ export interface GetAccountDomainsArgs extends QueryNamesOptions { * @param args.options.where.subdomain - The specific subdomain to filter by. * * @returns An array of sanitized domain names owned by the specified account. + * @group Implementation */ export async function getAccountDomains( args: { aptosConfig: AptosConfig } & GetAccountDomainsArgs, @@ -623,6 +643,7 @@ export async function getAccountDomains( * Arguments for retrieving subdomains associated with a specific account. * * @param accountAddress - The address of the account for which to fetch subdomains. + * @group Implementation */ export interface GetAccountSubdomainsArgs extends QueryNamesOptions { accountAddress: AccountAddressInput; @@ -643,6 +664,7 @@ export interface GetAccountSubdomainsArgs extends QueryNamesOptions { * @param args.options.where.expiration_timestamp - The expiration timestamp to filter by. * @param args.options.where.subdomain - The subdomain condition to filter by. * @param args.accountAddress - The address of the account whose subdomains are being queried. + * @group Implementation */ export async function getAccountSubdomains( args: { aptosConfig: AptosConfig } & GetAccountSubdomainsArgs, @@ -677,6 +699,7 @@ export async function getAccountSubdomains( * Arguments for retrieving subdomains associated with a specific domain. * * @param domain - The domain for which to fetch subdomains. + * @group Implementation */ export interface GetDomainSubdomainsArgs extends QueryNamesOptions { domain: string; @@ -695,6 +718,7 @@ export interface GetDomainSubdomainsArgs extends QueryNamesOptions { * @param args.domain - The domain for which to retrieve subdomains. * * @returns An array of active subdomain names. + * @group Implementation */ export async function getDomainSubdomains( args: { aptosConfig: AptosConfig } & GetDomainSubdomainsArgs, @@ -733,6 +757,7 @@ export async function getDomainSubdomains( * @param args - The arguments for the function. * @param args.aptosConfig - An AptosConfig object containing the configuration settings. * @returns The expiration date in ISO 8601 format. + * @group Implementation */ async function getANSExpirationDate(args: { aptosConfig: AptosConfig }): Promise { const { aptosConfig } = args; @@ -761,6 +786,7 @@ async function getANSExpirationDate(args: { aptosConfig: AptosConfig }): Promise * @param args.years - The number of years to renew the domain for. Currently, only 1 year renewals are supported. (optional, default is 1) * @param args.options - Additional options for generating the transaction. (optional) * @throws Error if the name contains a subdomain or if the years parameter is not equal to 1. + * @group Implementation */ export async function renewDomain(args: { aptosConfig: AptosConfig; @@ -803,6 +829,7 @@ export async function renewDomain(args: { * * @param name - The ANS name response to sanitize. * @param name.expiration_timestamp - The expiration timestamp in ISO string format. + * @group Implementation */ function sanitizeANSName(name: GetANSNameResponse[0]): GetANSNameResponse[0] { return { diff --git a/src/internal/coin.ts b/src/internal/coin.ts index 270500061..307217a69 100644 --- a/src/internal/coin.ts +++ b/src/internal/coin.ts @@ -23,6 +23,7 @@ const coinTransferAbi: EntryFunctionABI = { * @param args.amount - The amount of coins to transfer. * @param args.coinType - (Optional) The type of coin to transfer, defaults to Aptos Coin if not specified. * @param args.options - (Optional) Options for generating the transaction. + * @group Implementation */ export async function transferCoinTransaction(args: { aptosConfig: AptosConfig; diff --git a/src/internal/digitalAsset.ts b/src/internal/digitalAsset.ts index f2f01415b..a647dd420 100644 --- a/src/internal/digitalAsset.ts +++ b/src/internal/digitalAsset.ts @@ -6,6 +6,7 @@ * the {@link api/digitalAsset}. By moving the methods out into a separate file, * other namespaces and processes can access these methods without depending on the entire * digitalAsset namespace and without having a dependency cycle error. + * @group Implementation */ import { AptosConfig } from "../api/aptosConfig"; @@ -77,6 +78,7 @@ const PropertyTypeMap = { /** * The keys of the PropertyTypeMap, representing different property types. + * @group Implementation */ export type PropertyType = keyof typeof PropertyTypeMap; @@ -84,6 +86,7 @@ export type PropertyType = keyof typeof PropertyTypeMap; * Accepted property value types for user input, including boolean, number, bigint, string, AccountAddress, and Uint8Array. * To pass in an Array, use Uint8Array type * for example `new MoveVector([new MoveString("hello"), new MoveString("world")]).bcsToBytes()` + * @group Implementation */ export type PropertyValue = boolean | number | bigint | string | AccountAddress | Uint8Array; @@ -99,6 +102,7 @@ const defaultDigitalAssetType = "0x4::token::Token"; * @param args.aptosConfig - The configuration settings for Aptos. * @param args.digitalAssetAddress - The address of the digital asset to retrieve data for. * @returns The data of the specified digital asset. + * @group Implementation */ export async function getDigitalAssetData(args: { aptosConfig: AptosConfig; @@ -133,6 +137,7 @@ export async function getDigitalAssetData(args: { * @param args.aptosConfig - The configuration settings for Aptos. * @param args.digitalAssetAddress - The address of the digital asset to query ownership for. * @returns The current ownership details of the specified digital asset. + * @group Implementation */ export async function getCurrentDigitalAssetOwnership(args: { aptosConfig: AptosConfig; @@ -173,6 +178,7 @@ export async function getCurrentDigitalAssetOwnership(args: { * @param args.options.orderBy - The criteria for ordering the results. * * @returns An array of digital assets currently owned by the specified account. + * @group Implementation */ export async function getOwnedDigitalAssets(args: { aptosConfig: AptosConfig; @@ -217,6 +223,7 @@ export async function getOwnedDigitalAssets(args: { * @param args.options.limit - The maximum number of records to return. * @param args.options.orderBy - The criteria to order the results by. * @returns A promise that resolves to an array of token activities for the specified digital asset. + * @group Implementation */ export async function getDigitalAssetActivity(args: { aptosConfig: AptosConfig; @@ -264,6 +271,7 @@ export async function getDigitalAssetActivity(args: { * @param tokensFreezableByCreator - Indicates if the creator can freeze tokens in the collection. * @param royaltyNumerator - The numerator for calculating royalties. * @param royaltyDenominator - The denominator for calculating royalties. + * @group Implementation */ export interface CreateCollectionOptions { maxSupply?: AnyNumber; @@ -324,6 +332,7 @@ const createCollectionAbi: EntryFunctionABI = { * @param args.tokensFreezableByCreator - Indicates if tokens can be frozen by the creator (optional, defaults to true). * @param args.royaltyNumerator - The numerator for calculating royalties (optional, defaults to 0). * @param args.royaltyDenominator - The denominator for calculating royalties (optional, defaults to 1). + * @group Implementation */ export async function createCollectionTransaction( args: { @@ -376,6 +385,7 @@ export async function createCollectionTransaction( * @param args.options.limit - The limit for pagination. * @param args.options.where - The conditions to filter the collections. * @returns The data of the current collections. + * @group Implementation */ export async function getCollectionData(args: { aptosConfig: AptosConfig; @@ -416,6 +426,7 @@ export async function getCollectionData(args: { * @param args.options - Optional parameters for filtering the results, including token standard and pagination options. * @param args.options.tokenStandard - The token standard to filter the results by (optional). * @param args.options.pagination - Pagination options for the results (optional). + * @group Implementation */ export async function getCollectionDataByCreatorAddressAndCollectionName(args: { aptosConfig: AptosConfig; @@ -447,6 +458,7 @@ export async function getCollectionDataByCreatorAddressAndCollectionName(args: { * @param args.options - Optional parameters for filtering the results. * @param args.options.tokenStandard - The token standard to filter the collections by. * @param args.options.pagination - Pagination options for the results. + * @group Implementation */ export async function getCollectionDataByCreatorAddress(args: { aptosConfig: AptosConfig; @@ -477,6 +489,7 @@ export async function getCollectionDataByCreatorAddress(args: { * @param args.options.tokenStandard - The standard of the token to filter the collection data. * @param args.options.page - The page number for pagination. * @param args.options.limit - The number of items per page for pagination. + * @group Implementation */ export async function getCollectionDataByCollectionId(args: { aptosConfig: AptosConfig; @@ -508,6 +521,7 @@ export async function getCollectionDataByCollectionId(args: { * @param args.options - Optional parameters for additional filtering. * @param args.options.tokenStandard - The token standard to filter the collection (default is "v2"). * @returns The ID of the specified collection. + * @group Implementation */ export async function getCollectionId(args: { aptosConfig: AptosConfig; @@ -559,6 +573,7 @@ const mintDigitalAssetAbi: EntryFunctionABI = { * @param [args.propertyTypes] - Optional array of property types corresponding to the asset's properties. * @param [args.propertyValues] - Optional array of property values for the asset's properties. * @param [args.options] - Optional transaction generation options. + * @group Implementation */ export async function mintDigitalAssetTransaction(args: { aptosConfig: AptosConfig; @@ -604,6 +619,7 @@ export async function mintDigitalAssetTransaction(args: { * @param propertyValues - An array of property values from which to extract the raw data. * @param propertyTypes - An array of strings representing the types of properties to retrieve. * @returns An array of Uint8Array containing the raw values for the specified property types. + * @group Implementation */ getPropertyValueRaw(propertyValues ?? [], convertedPropertyType ?? []), ], @@ -629,6 +645,7 @@ const transferDigitalAssetAbi: EntryFunctionABI = { * @param args.recipient - The address of the account receiving the digital asset. * @param args.digitalAssetType - (Optional) The type of the digital asset being transferred. * @param args.options - (Optional) Additional options for generating the transaction. + * @group Implementation */ export async function transferDigitalAssetTransaction(args: { aptosConfig: AptosConfig; @@ -683,6 +700,7 @@ const mintSoulBoundAbi: EntryFunctionABI = { * @param [args.propertyValues] - Optional array of property values that match the property keys and types. * @param [args.options] - Optional transaction generation options. * @throws Error if the counts of property keys, property types, and property values do not match. + * @group Implementation */ export async function mintSoulBoundTransaction(args: { aptosConfig: AptosConfig; @@ -753,6 +771,7 @@ const burnDigitalAssetAbi: EntryFunctionABI = { * @param args.digitalAssetAddress - The address of the digital asset to be burned. * @param args.digitalAssetType - Optional; the type of the digital asset being burned. * @param args.options - Optional; additional options for generating the transaction. + * @group Implementation */ export async function burnDigitalAssetTransaction(args: { aptosConfig: AptosConfig; @@ -790,6 +809,7 @@ const freezeDigitalAssetAbi: EntryFunctionABI = { * @param args.digitalAssetAddress - The address of the digital asset to be frozen. * @param args.digitalAssetType - (Optional) The type of the digital asset as a Move struct ID. * @param args.options - (Optional) Additional options for generating the transaction. + * @group Implementation */ export async function freezeDigitalAssetTransferTransaction(args: { aptosConfig: AptosConfig; @@ -826,6 +846,7 @@ const unfreezeDigitalAssetAbi: EntryFunctionABI = { * @param args.digitalAssetAddress - The address of the digital asset to be unfrozen. * @param args.digitalAssetType - (Optional) The type of the digital asset being unfrozen. * @param args.options - (Optional) Additional options for generating the transaction. + * @group Implementation */ export async function unfreezeDigitalAssetTransferTransaction(args: { aptosConfig: AptosConfig; @@ -863,6 +884,7 @@ const setDigitalAssetDescriptionAbi: EntryFunctionABI = { * @param args.digitalAssetAddress - The address of the digital asset whose description is being set. * @param args.digitalAssetType - (Optional) The type of the digital asset. * @param args.options - (Optional) Additional options for generating the transaction. + * @group Implementation */ export async function setDigitalAssetDescriptionTransaction(args: { aptosConfig: AptosConfig; @@ -902,6 +924,7 @@ const setDigitalAssetNameAbi: EntryFunctionABI = { * @param args.digitalAssetAddress - The address of the digital asset to update. * @param args.digitalAssetType - (Optional) The type of the digital asset, represented as a Move struct ID. * @param args.options - (Optional) Additional options for generating the transaction. + * @group Implementation */ export async function setDigitalAssetNameTransaction(args: { aptosConfig: AptosConfig; @@ -940,6 +963,7 @@ const setDigitalAssetURIAbi: EntryFunctionABI = { * @param args.digitalAssetAddress - The address of the digital asset whose URI is being set. * @param args.digitalAssetType - The optional type of the digital asset; defaults to a predefined type if not provided. * @param args.options - Optional settings for generating the transaction. + * @group Implementation */ export async function setDigitalAssetURITransaction(args: { aptosConfig: AptosConfig; @@ -986,6 +1010,7 @@ const addDigitalAssetPropertyAbi: EntryFunctionABI = { * @param args.digitalAssetAddress - The address of the digital asset to which the property is being added. * @param args.digitalAssetType - The optional type of the digital asset. * @param args.options - Optional transaction generation options. + * @group Implementation */ export async function addDigitalAssetPropertyTransaction(args: { aptosConfig: AptosConfig; @@ -1041,6 +1066,7 @@ const removeDigitalAssetPropertyAbi: EntryFunctionABI = { * @param args.digitalAssetAddress - The address of the digital asset from which the property will be removed. * @param args.digitalAssetType - The type of the digital asset (optional). * @param args.options - Additional options for generating the transaction (optional). + * @group Implementation */ export async function removeDigitalAssetPropertyTransaction(args: { aptosConfig: AptosConfig; @@ -1087,6 +1113,7 @@ const updateDigitalAssetPropertyAbi: EntryFunctionABI = { * @param args.digitalAssetAddress - The address of the digital asset to update. * @param args.digitalAssetType - (Optional) The type of the digital asset. * @param args.options - (Optional) Additional options for generating the transaction. + * @group Implementation */ export async function updateDigitalAssetPropertyTransaction(args: { aptosConfig: AptosConfig; @@ -1125,6 +1152,7 @@ export async function updateDigitalAssetPropertyTransaction(args: { * @param propertyValue - The value of the property to convert. * @param propertyType - The type of the property, which determines how the value is processed. * @returns The raw byte representation of the property value. + * @group Implementation */ getSinglePropertyValueRaw(propertyValue, PropertyTypeMap[propertyType]), ], @@ -1156,6 +1184,7 @@ const addDigitalAssetTypedPropertyAbi: EntryFunctionABI = { * @param args.digitalAssetAddress - The address of the digital asset to which the property is being added. * @param args.digitalAssetType - (Optional) The type of the digital asset. * @param args.options - (Optional) Additional options for generating the transaction. + * @group Implementation */ export async function addDigitalAssetTypedPropertyTransaction(args: { aptosConfig: AptosConfig; @@ -1211,6 +1240,7 @@ const updateDigitalAssetTypedPropertyAbi: EntryFunctionABI = { * @param args.digitalAssetAddress - The address of the digital asset to be updated. * @param args.digitalAssetType - Optional. The type of the digital asset, if not provided, defaults to the standard type. * @param args.options - Optional. Additional options for generating the transaction. + * @group Implementation */ export async function updateDigitalAssetTypedPropertyTransaction(args: { aptosConfig: AptosConfig; diff --git a/src/internal/event.ts b/src/internal/event.ts index daed4f1bd..1c730a720 100644 --- a/src/internal/event.ts +++ b/src/internal/event.ts @@ -6,6 +6,7 @@ * the {@link api/event}. By moving the methods out into a separate file, * other namespaces and processes can access these methods without depending on the entire * event namespace and without having a dependency cycle error. + * @group Implementation */ import { AptosConfig } from "../api/aptosConfig"; @@ -31,6 +32,7 @@ const checkEventTypeLength = (eventType?: InputMaybe) => { * @param args.aptosConfig - The configuration object for Aptos. * @param args.eventType - The MoveStructId representing the type of event to retrieve. * @param [args.options] - Optional pagination and ordering parameters for the event retrieval. + * @group Implementation */ export async function getModuleEventsByEventType(args: { aptosConfig: AptosConfig; @@ -64,6 +66,7 @@ export async function getModuleEventsByEventType(args: { * @param args.accountAddress - The address of the account for which events are being retrieved. * @param args.creationNumber - The creation number to filter events. * @param args.options - Optional pagination and ordering parameters for the event retrieval. + * @group Implementation */ export async function getAccountEventsByCreationNumber(args: { aptosConfig: AptosConfig; @@ -90,6 +93,7 @@ export async function getAccountEventsByCreationNumber(args: { * @param args.accountAddress - The address of the account for which to retrieve events. * @param args.eventType - The type of event to filter by. * @param args.options - Optional pagination and ordering parameters for the event retrieval. + * @group Implementation */ export async function getAccountEventsByEventType(args: { aptosConfig: AptosConfig; @@ -119,6 +123,7 @@ export async function getAccountEventsByEventType(args: { * @param [args.options.orderBy] - Defines the order in which to return the events. * @param [args.options.where] - Conditions to filter the events. * @param [args.options.where.indexed_type] - Filters events by the indexed type. + * @group Implementation */ export async function getEvents(args: { aptosConfig: AptosConfig; @@ -136,6 +141,7 @@ export async function getEvents(args: { * @param options.offset - The number of items to skip before starting to collect the result set. * @param options.limit - The maximum number of items to return. * @param options.orderBy - The criteria to sort the results. + * @group Implementation */ // eslint-disable-next-line no-underscore-dangle checkEventTypeLength(options?.where?.indexed_type?._eq); diff --git a/src/internal/faucet.ts b/src/internal/faucet.ts index 2624490df..91d64de1a 100644 --- a/src/internal/faucet.ts +++ b/src/internal/faucet.ts @@ -6,6 +6,7 @@ * the {@link api/faucet}. By moving the methods out into a separate file, * other namespaces and processes can access these methods without depending on the entire * faucet namespace and without having a dependency cycle error. + * @group Implementation */ import { AptosConfig } from "../api/aptosConfig"; @@ -28,6 +29,7 @@ import { waitForTransaction } from "./transaction"; * @param args.options.checkSuccess - A flag indicating whether to check if the transaction was successful. * * @throws Error if the transaction does not return a user transaction type. + * @group Implementation */ export async function fundAccount(args: { aptosConfig: AptosConfig; diff --git a/src/internal/fungibleAsset.ts b/src/internal/fungibleAsset.ts index 33033e9ba..f06791c4c 100644 --- a/src/internal/fungibleAsset.ts +++ b/src/internal/fungibleAsset.ts @@ -6,6 +6,7 @@ * the {@link api/fungible_asset}. By moving the methods out into a separate file, * other namespaces and processes can access these methods without depending on the entire * fungible_asset namespace and without having a dependency cycle error. + * @group Implementation */ import { AptosConfig } from "../api/aptosConfig"; @@ -55,6 +56,7 @@ import { SimpleTransaction } from "../transactions/instances/simpleTransaction"; * @param [args.options.limit] - The maximum number of results to return. * @param [args.options.offset] - The number of results to skip before starting to collect the result set. * @param [args.options.where] - Conditions to filter the results. + * @group Implementation */ export async function getFungibleAssetMetadata(args: { aptosConfig: AptosConfig; @@ -91,6 +93,7 @@ export async function getFungibleAssetMetadata(args: { * @param [args.options.offset] - The number of activities to skip before starting to collect the result set. * @param [args.options.where] - Conditions to filter the activities. * @returns A promise that resolves to an array of fungible asset activities. + * @group Implementation */ export async function getFungibleAssetActivities(args: { aptosConfig: AptosConfig; @@ -126,6 +129,7 @@ export async function getFungibleAssetActivities(args: { * @param args.options.offset - The number of results to skip before starting to collect the results. * @param args.options.where - Conditions to filter the results based on specific criteria. * @returns The current balances of fungible assets. + * @group Implementation */ export async function getCurrentFungibleAssetBalances(args: { aptosConfig: AptosConfig; @@ -167,6 +171,7 @@ const faTransferAbi: EntryFunctionABI = { * @param args.recipient - The address of the account receiving the asset. * @param args.amount - The amount of the fungible asset to transfer. * @param args.options - Optional settings for generating the transaction. + * @group Implementation */ export async function transferFungibleAsset(args: { aptosConfig: AptosConfig; diff --git a/src/internal/general.ts b/src/internal/general.ts index 9c1cbb7a6..03eae8679 100644 --- a/src/internal/general.ts +++ b/src/internal/general.ts @@ -6,6 +6,7 @@ * the {@link api/general}. By moving the methods out into a separate file, * other namespaces and processes can access these methods without depending on the entire * general namespace and without having a dependency cycle error. + * @group Implementation */ import { AptosConfig } from "../api/aptosConfig"; @@ -20,6 +21,7 @@ import { ProcessorType } from "../utils/const"; * * @param args - The arguments for retrieving ledger information. * @param args.aptosConfig - The configuration object for connecting to the Aptos network. + * @group Implementation */ export async function getLedgerInfo(args: { aptosConfig: AptosConfig }): Promise { const { aptosConfig } = args; @@ -38,6 +40,7 @@ export async function getLedgerInfo(args: { aptosConfig: AptosConfig }): Promise * @param args.aptosConfig - The configuration object for Aptos. * @param args.limit - The maximum number of transactions to retrieve. * @returns An array of user transactions. + * @group Implementation */ export async function getChainTopUserTransactions(args: { aptosConfig: AptosConfig; @@ -66,6 +69,7 @@ export async function getChainTopUserTransactions(args: { * @param args.query - The GraphQL query to be executed. * @param args.originMethod - An optional string to specify the origin method for tracking purposes. * @returns The data returned from the query execution. + * @group Implementation */ export async function queryIndexer(args: { aptosConfig: AptosConfig; @@ -89,6 +93,7 @@ export async function queryIndexer(args: { * @param args - The arguments for the function. * @param args.aptosConfig - The configuration object for Aptos. * @returns The statuses of the processors. + * @group Implementation */ export async function getProcessorStatuses(args: { aptosConfig: AptosConfig }): Promise { const { aptosConfig } = args; @@ -112,6 +117,7 @@ export async function getProcessorStatuses(args: { aptosConfig: AptosConfig }): * @param args - The arguments for the function. * @param args.aptosConfig - The configuration object for Aptos. * @returns The last success version as a BigInt. + * @group Implementation */ export async function getIndexerLastSuccessVersion(args: { aptosConfig: AptosConfig }): Promise { const response = await getProcessorStatuses({ aptosConfig: args.aptosConfig }); @@ -126,6 +132,7 @@ export async function getIndexerLastSuccessVersion(args: { aptosConfig: AptosCon * @param args.aptosConfig - The configuration object for connecting to the Aptos network. * @param args.processorType - The type of processor whose status you want to retrieve. * @returns The status of the specified processor. + * @group Implementation */ export async function getProcessorStatus(args: { aptosConfig: AptosConfig; diff --git a/src/internal/keyless.ts b/src/internal/keyless.ts index 0a4070d1f..5458cdf57 100644 --- a/src/internal/keyless.ts +++ b/src/internal/keyless.ts @@ -6,6 +6,7 @@ * the {@link api/keyless}. By moving the methods out into a separate file, * other namespaces and processes can access these methods without depending on the entire * keyless namespace and without having a dependency cycle error. + * @group Implementation */ import { jwtDecode, JwtPayload } from "jwt-decode"; import { AptosConfig } from "../api/aptosConfig"; @@ -40,6 +41,7 @@ import { SimpleTransaction } from "../transactions"; * @param args.uidKey - An optional unique identifier key (defaults to "sub"). * @param args.derivationPath - An optional derivation path for the key. * @returns A Uint8Array containing the fetched pepper value. + * @group Implementation */ export async function getPepper(args: { aptosConfig: AptosConfig; @@ -79,6 +81,7 @@ export async function getPepper(args: { * @param args.pepper - An optional hex input used to enhance security (default is generated if not provided). * @param args.uidKey - An optional string that specifies the unique identifier key (defaults to "sub"). * @throws Error if the pepper length is not valid or if the ephemeral key pair's lifespan exceeds the maximum allowed. + * @group Implementation */ export async function getProof(args: { aptosConfig: AptosConfig; @@ -144,6 +147,7 @@ export async function getProof(args: { * @param args.pepper - An optional hexadecimal input used for additional security. * @param args.proofFetchCallback - An optional callback function to handle the proof fetch outcome. * @returns A keyless account object. + * @group Implementation */ export async function deriveKeylessAccount(args: { aptosConfig: AptosConfig; diff --git a/src/internal/object.ts b/src/internal/object.ts index d5d378820..ac9e4d91d 100644 --- a/src/internal/object.ts +++ b/src/internal/object.ts @@ -17,6 +17,7 @@ import { queryIndexer } from "./general"; * @param [args.options.orderBy] - The criteria for ordering the results. * @param [args.options.where] - The conditions to filter the results. * @returns The current objects that match the specified criteria. + * @group Implementation */ export async function getObjectData(args: { aptosConfig: AptosConfig; @@ -50,6 +51,7 @@ export async function getObjectData(args: { * @param args.aptosConfig - The configuration for connecting to the Aptos blockchain. * @param args.objectAddress - The address of the object whose data is being retrieved. * @param args.options - Optional parameters for pagination and ordering of the results. + * @group Implementation */ export async function getObjectDataByObjectAddress(args: { aptosConfig: AptosConfig; diff --git a/src/internal/staking.ts b/src/internal/staking.ts index 450c42478..e1f4c9f2c 100644 --- a/src/internal/staking.ts +++ b/src/internal/staking.ts @@ -6,6 +6,7 @@ * the {@link api/staking}. By moving the methods out into a separate file, * other namespaces and processes can access these methods without depending on the entire * faucet namespace and without having a dependency cycle error. + * @group Implementation */ import { AptosConfig } from "../api/aptosConfig"; @@ -22,6 +23,7 @@ import { queryIndexer } from "./general"; * @param args.aptosConfig - The configuration object for Aptos. * @param args.poolAddress - The address of the pool for which to retrieve the number of delegators. * @returns The number of active delegators for the specified pool address. + * @group Implementation */ export async function getNumberOfDelegators(args: { aptosConfig: AptosConfig; @@ -48,6 +50,7 @@ export async function getNumberOfDelegators(args: { * @param [args.options] - Optional parameters for ordering the results. * @param args.options.orderBy - Specifies the order in which to return the results. * @returns The number of active delegators per pool. + * @group Implementation */ export async function getNumberOfDelegatorsForAllPools(args: { aptosConfig: AptosConfig; @@ -73,6 +76,7 @@ export async function getNumberOfDelegatorsForAllPools(args: { * @param args.delegatorAddress - The address of the delegator whose activities are being queried. * @param args.poolAddress - The address of the pool associated with the delegated staking activities. * @returns The delegated staking activities for the specified delegator and pool. + * @group Implementation */ export async function getDelegatedStakingActivities(args: { aptosConfig: AptosConfig; diff --git a/src/internal/table.ts b/src/internal/table.ts index cb0c3817c..915fafe2f 100644 --- a/src/internal/table.ts +++ b/src/internal/table.ts @@ -22,6 +22,7 @@ import { queryIndexer } from "./general"; * @param args.handle - The identifier for the table from which to retrieve the item. * @param args.data - The request data for the table item. * @param args.options - Optional parameters for the request, including ledger version. + * @group Implementation */ export async function getTableItem(args: { aptosConfig: AptosConfig; @@ -50,6 +51,7 @@ export async function getTableItem(args: { * @param args.options.limit - The maximum number of items to return. * @param args.options.where - Conditions to filter the table items. * @param args.options.orderBy - The criteria to sort the results. + * @group Implementation */ export async function getTableItemsData(args: { aptosConfig: AptosConfig; @@ -87,6 +89,7 @@ export async function getTableItemsData(args: { * @param args.options.where - Conditions to filter the results. * @param args.options.orderBy - The order in which to return the results. * @returns A promise that resolves to an array of table metadata. + * @group Implementation */ export async function getTableItemsMetadata(args: { aptosConfig: AptosConfig; diff --git a/src/internal/transaction.ts b/src/internal/transaction.ts index 171e41d37..75ad14a31 100644 --- a/src/internal/transaction.ts +++ b/src/internal/transaction.ts @@ -6,6 +6,7 @@ * the {@link api/transaction}. By moving the methods out into a separate file, * other namespaces and processes can access these methods without depending on the entire * transaction namespace and without having a dependency cycle error. + * @group Implementation */ import { AptosConfig } from "../api/aptosConfig"; @@ -34,6 +35,7 @@ import { getIndexerLastSuccessVersion, getProcessorStatus } from "./general"; * @param {Object} args.options - The options for pagination. * @param {number} args.options.offset - The number of transactions to skip before starting to collect the result set. * @param {number} args.options.limit - The maximum number of transactions to return. + * @group Implementation */ export async function getTransactions(args: { aptosConfig: AptosConfig; @@ -54,6 +56,7 @@ export async function getTransactions(args: { * * @param args - The configuration parameters for the Aptos network. * @param args.aptosConfig - The configuration object containing network details. + * @group Implementation */ export async function getGasPriceEstimation(args: { aptosConfig: AptosConfig }) { const { aptosConfig } = args; @@ -79,6 +82,7 @@ export async function getGasPriceEstimation(args: { aptosConfig: AptosConfig }) * @param args.aptosConfig - The configuration settings for the Aptos client. * @param args.ledgerVersion - The ledger version for which to retrieve the transaction. * @returns The transaction details for the specified ledger version. + * @group Implementation */ export async function getTransactionByVersion(args: { aptosConfig: AptosConfig; @@ -100,6 +104,7 @@ export async function getTransactionByVersion(args: { * @param args.aptosConfig - The configuration settings for the Aptos client. * @param args.transactionHash - The hash of the transaction to retrieve. * @returns A promise that resolves to the transaction details. + * @group Implementation */ export async function getTransactionByHash(args: { aptosConfig: AptosConfig; @@ -123,6 +128,7 @@ export async function getTransactionByHash(args: { * @param args.transactionHash - The hash of the transaction to check. * @returns A boolean indicating whether the transaction is pending. * @throws An error if the transaction cannot be retrieved due to reasons other than a 404 status. + * @group Implementation */ export async function isTransactionPending(args: { aptosConfig: AptosConfig; @@ -147,6 +153,7 @@ export async function isTransactionPending(args: { * @param args - The arguments for the function. * @param args.aptosConfig - The configuration settings for the Aptos client. * @param args.transactionHash - The hash of the transaction to wait for. + * @group Implementation */ export async function longWaitForTransaction(args: { aptosConfig: AptosConfig; @@ -174,6 +181,7 @@ export async function longWaitForTransaction(args: { * @returns A promise that resolves to the transaction response once the transaction is confirmed. * @throws WaitForTransactionError if the transaction times out or remains pending. * @throws FailedTransactionError if the transaction fails. + * @group Implementation */ export async function waitForTransaction(args: { aptosConfig: AptosConfig; @@ -196,6 +204,7 @@ export async function waitForTransaction(args: { * * @param e - The error object that occurred during the API call. * @throws {Error} Throws the last error if it exists; otherwise, throws a WaitForTransactionError indicating a timeout. + * @group Implementation */ function handleAPIError(e: any) { // In short, this means we will retry if it was an AptosApiError and the code was 404 or 5xx. @@ -291,6 +300,7 @@ export async function waitForTransaction(args: { * @param args.aptosConfig - The configuration object for Aptos. * @param args.minimumLedgerVersion - The minimum ledger version that the indexer should sync to. * @param args.processorType - (Optional) The type of processor to check the last success version from. + * @group Implementation */ export async function waitForIndexer(args: { aptosConfig: AptosConfig; @@ -337,6 +347,7 @@ export async function waitForIndexer(args: { * * @param message - A descriptive message for the error. * @param lastSubmittedTransaction - The last submitted transaction response, if available. + * @group Implementation */ export class WaitForTransactionError extends Error { public readonly lastSubmittedTransaction: TransactionResponse | undefined; @@ -346,6 +357,7 @@ export class WaitForTransactionError extends Error { * * @param message - The message associated with the transaction. * @param lastSubmittedTransaction - The transaction response object containing details about the transaction. + * @group Implementation */ constructor(message: string, lastSubmittedTransaction: TransactionResponse | undefined) { super(message); @@ -359,6 +371,7 @@ export class WaitForTransactionError extends Error { * * @param message - A description of the error. * @param transaction - The transaction response associated with the failure. + * @group Implementation */ export class FailedTransactionError extends Error { public readonly transaction: TransactionResponse; @@ -378,6 +391,7 @@ export class FailedTransactionError extends Error { * @param args.ledgerVersion - The ledger version of the block to retrieve. * @param args.options - Optional parameters for the request. * @param args.options.withTransactions - Indicates whether to include transactions in the block data. + * @group Implementation */ export async function getBlockByVersion(args: { aptosConfig: AptosConfig; @@ -404,6 +418,7 @@ export async function getBlockByVersion(args: { * @param args.options - Optional parameters for the request. * @param args.options.withTransactions - Indicates whether to include transactions in the block data. * @returns A promise that resolves to the block data, potentially including its transactions. + * @group Implementation */ export async function getBlockByHeight(args: { aptosConfig: AptosConfig; @@ -428,6 +443,7 @@ export async function getBlockByHeight(args: { * @param args.block - The block object that will be filled with transactions. * @param args.options - Optional settings for fetching transactions. * @param args.options.withTransactions - Indicates whether to include transactions in the block. + * @group Implementation */ async function fillBlockTransactions(args: { aptosConfig: AptosConfig; diff --git a/src/internal/transactionSubmission.ts b/src/internal/transactionSubmission.ts index f0ef49f84..ef1b4245f 100644 --- a/src/internal/transactionSubmission.ts +++ b/src/internal/transactionSubmission.ts @@ -3,6 +3,7 @@ * the {@link api/transaction}. By moving the methods out into a separate file, * other namespaces and processes can access these methods without depending on the entire * transaction namespace and without having a dependency cycle error. + * @group Implementation */ import { AptosConfig } from "../api/aptosConfig"; @@ -42,6 +43,7 @@ import { MultiAgentTransaction } from "../transactions/instances/multiAgentTrans * These are the possible function signature for `generateTransaction` function. * When we call `generateTransaction` function with the relevant type properties, * Typescript can infer the return type based on the appropriate function overload. + * @group Implementation */ export async function generateTransaction( args: { aptosConfig: AptosConfig } & InputGenerateSingleSignerRawTransactionData, @@ -88,6 +90,7 @@ export async function generateTransaction( * feePayerAddress?: AccountAddress * } * ``` + * @group Implementation */ export async function generateTransaction( args: { aptosConfig: AptosConfig } & InputGenerateTransactionData, @@ -105,6 +108,7 @@ export async function generateTransaction( * @param args.data - Input data required to generate the transaction payload, which may include bytecode, multisig address, * function name, function arguments, type arguments, and ABI. * @returns A promise that resolves to the generated transaction payload instance. + * @group Implementation */ export async function buildTransactionPayload( args: { aptosConfig: AptosConfig } & InputGenerateTransactionData, @@ -149,6 +153,7 @@ export async function buildTransactionPayload( * @param args.sender - The address of the sender of the transaction. * @param args.options - Additional options for the transaction. * @param payload - The payload of the transaction, which defines the action to be performed. + * @group Implementation */ export async function buildRawTransaction( args: { aptosConfig: AptosConfig } & InputGenerateTransactionData, @@ -188,6 +193,7 @@ export async function buildRawTransaction( * @param data - The input data for generating a transaction. * @param data.withFeePayer - Indicates whether a fee payer is included in the transaction input. * @returns A boolean value indicating if the transaction input has a fee payer. + * @group Implementation */ function isFeePayerTransactionInput(data: InputGenerateTransactionData): boolean { return data.withFeePayer === true; @@ -198,6 +204,7 @@ function isFeePayerTransactionInput(data: InputGenerateTransactionData): boolean * * @param data - The transaction input data to evaluate. * @param data.secondarySignerAddresses - An array of secondary signer addresses, indicating multiple agents. + * @group Implementation */ function isMultiAgentTransactionInput( data: InputGenerateTransactionData, @@ -214,6 +221,7 @@ function isMultiAgentTransactionInput( * @param args.transaction - AnyRawTransaction, as generated by `generateTransaction()`. * * @returns The message to be signed. + * @group Implementation */ export function getSigningMessage(args: { transaction: AnyRawTransaction }): Uint8Array { const { transaction } = args; @@ -228,6 +236,7 @@ export function getSigningMessage(args: { transaction: AnyRawTransaction }): Uin * @param args.transaction An instance of a RawTransaction, plus optional secondary/fee payer addresses. * * @return The signer AccountAuthenticator. + * @group Implementation */ export function signTransaction(args: { signer: Account; transaction: AnyRawTransaction }): AccountAuthenticator { const { signer, transaction } = args; @@ -265,6 +274,7 @@ export function signAsFeePayer(args: { signer: Account; transaction: AnyRawTrans * @param args.options.estimateGasUnitPrice Optional. Indicates whether to estimate the gas unit price. * @param args.options.estimateMaxGasAmount Optional. Indicates whether to estimate the maximum gas amount. * @param args.options.estimatePrioritizedGasUnitPrice Optional. Indicates whether to estimate the prioritized gas unit price. + * @group Implementation */ export async function simulateTransaction( args: { aptosConfig: AptosConfig } & InputSimulateTransactionData, @@ -304,6 +314,7 @@ export async function simulateTransaction( * @param args.secondarySignerAuthenticators - Optional. Authenticators for additional signers in a multi-signer transaction. * * @returns PendingTransactionResponse - The response containing the status of the submitted transaction. + * @group Implementation */ export async function submitTransaction( args: { @@ -391,6 +402,7 @@ const packagePublishAbi: EntryFunctionABI = { * @param args.metadataBytes - The metadata associated with the package, represented as hexadecimal input. * @param args.moduleBytecode - An array of module bytecode, each represented as hexadecimal input. * @param args.options - Optional parameters for generating the transaction. + * @group Implementation */ export async function publicPackageTransaction(args: { aptosConfig: AptosConfig; @@ -439,6 +451,7 @@ const rotateAuthKeyAbi: EntryFunctionABI = { * This function requires the current authentication key and the new private key to sign a challenge that validates the rotation. * * TODO: Need to refactor and move this function out of transactionSubmission. + * @group Implementation */ export async function rotateAuthKey(args: { aptosConfig: AptosConfig; diff --git a/src/transactions/authenticator/account.ts b/src/transactions/authenticator/account.ts index 5f633182f..4de374641 100644 --- a/src/transactions/authenticator/account.ts +++ b/src/transactions/authenticator/account.ts @@ -16,6 +16,8 @@ import { AccountAuthenticatorVariant } from "../../types"; * and deserialization of various authenticator types. * * @extends Serializable + * @group Implementation + * @category Transactions */ export abstract class AccountAuthenticator extends Serializable { abstract serialize(serializer: Serializer): void; @@ -25,6 +27,8 @@ export abstract class AccountAuthenticator extends Serializable { * This function helps in reconstructing the AccountAuthenticator object based on the variant index. * * @param deserializer - The deserializer instance used to read the serialized data. + * @group Implementation + * @category Transactions */ static deserialize(deserializer: Deserializer): AccountAuthenticator { const index = deserializer.deserializeUleb128AsU32(); @@ -46,6 +50,8 @@ export abstract class AccountAuthenticator extends Serializable { * Determines if the current instance is an Ed25519 account authenticator. * * @returns {boolean} True if the instance is of type AccountAuthenticatorEd25519, otherwise false. + * @group Implementation + * @category Transactions */ isEd25519(): this is AccountAuthenticatorEd25519 { return this instanceof AccountAuthenticatorEd25519; @@ -55,6 +61,8 @@ export abstract class AccountAuthenticator extends Serializable { * Determines if the current instance is of type AccountAuthenticatorMultiEd25519. * * @returns {boolean} True if the instance is a multi-signature Ed25519 account authenticator, otherwise false. + * @group Implementation + * @category Transactions */ isMultiEd25519(): this is AccountAuthenticatorMultiEd25519 { return this instanceof AccountAuthenticatorMultiEd25519; @@ -64,6 +72,8 @@ export abstract class AccountAuthenticator extends Serializable { * Determines if the current instance is of the type AccountAuthenticatorSingleKey. * * @returns {boolean} True if the instance is an AccountAuthenticatorSingleKey, otherwise false. + * @group Implementation + * @category Transactions */ isSingleKey(): this is AccountAuthenticatorSingleKey { return this instanceof AccountAuthenticatorSingleKey; @@ -73,6 +83,8 @@ export abstract class AccountAuthenticator extends Serializable { * Determine if the current instance is of type AccountAuthenticatorMultiKey. * * @returns {boolean} Returns true if the instance is an AccountAuthenticatorMultiKey, otherwise false. + * @group Implementation + * @category Transactions */ isMultiKey(): this is AccountAuthenticatorMultiKey { return this instanceof AccountAuthenticatorMultiKey; @@ -85,6 +97,8 @@ export abstract class AccountAuthenticator extends Serializable { * * @param public_key - The Ed25519 public key associated with the account. * @param signature - The Ed25519 signature for the account. + * @group Implementation + * @category Transactions */ export class AccountAuthenticatorEd25519 extends AccountAuthenticator { public readonly public_key: Ed25519PublicKey; @@ -96,6 +110,8 @@ export class AccountAuthenticatorEd25519 extends AccountAuthenticator { * * @param public_key The public key used for verification. * @param signature The signatures corresponding to the public keys. + * @group Implementation + * @category Transactions */ constructor(public_key: Ed25519PublicKey, signature: Ed25519Signature) { super(); @@ -108,6 +124,8 @@ export class AccountAuthenticatorEd25519 extends AccountAuthenticator { * This function captures the multi-key variant, public keys, and signatures for serialization. * * @param serializer - The serializer instance used to perform the serialization. + * @group Implementation + * @category Transactions */ serialize(serializer: Serializer): void { serializer.serializeU32AsUleb128(AccountAuthenticatorVariant.Ed25519); @@ -120,6 +138,8 @@ export class AccountAuthenticatorEd25519 extends AccountAuthenticator { * This function helps in reconstructing the authenticator object using the deserialized public keys and signatures. * * @param deserializer - The deserializer used to extract the necessary data for loading the authenticator. + * @group Implementation + * @category Transactions */ static load(deserializer: Deserializer): AccountAuthenticatorEd25519 { const public_key = Ed25519PublicKey.deserialize(deserializer); @@ -133,6 +153,8 @@ export class AccountAuthenticatorEd25519 extends AccountAuthenticator { * * @param public_key - The MultiEd25519 public key of the account. * @param signature - The MultiEd25519 signature of the account. + * @group Implementation + * @category Transactions */ export class AccountAuthenticatorMultiEd25519 extends AccountAuthenticator { public readonly public_key: MultiEd25519PublicKey; @@ -164,6 +186,8 @@ export class AccountAuthenticatorMultiEd25519 extends AccountAuthenticator { * * @param public_key - The public key used for authentication. * @param signature - The signature associated with the public key. + * @group Implementation + * @category Transactions */ export class AccountAuthenticatorSingleKey extends AccountAuthenticator { public readonly public_key: AnyPublicKey; @@ -194,6 +218,8 @@ export class AccountAuthenticatorSingleKey extends AccountAuthenticator { * * @param public_keys - The public keys used for authentication. * @param signatures - The signatures corresponding to the public keys. + * @group Implementation + * @category Transactions */ export class AccountAuthenticatorMultiKey extends AccountAuthenticator { public readonly public_keys: MultiKey; diff --git a/src/transactions/authenticator/transaction.ts b/src/transactions/authenticator/transaction.ts index a5c7d4d73..df690cc01 100644 --- a/src/transactions/authenticator/transaction.ts +++ b/src/transactions/authenticator/transaction.ts @@ -15,6 +15,8 @@ import { TransactionAuthenticatorVariant } from "../../types"; * This class provides methods for serializing and deserializing different types of transaction authenticators. * * @extends Serializable + * @group Implementation + * @category Transactions */ export abstract class TransactionAuthenticator extends Serializable { abstract serialize(serializer: Serializer): void; @@ -24,6 +26,8 @@ export abstract class TransactionAuthenticator extends Serializable { * This function helps in reconstructing the TransactionAuthenticator based on the variant index found in the serialized data. * * @param deserializer - The deserializer instance used to read the serialized data. + * @group Implementation + * @category Transactions */ static deserialize(deserializer: Deserializer): TransactionAuthenticator { const index = deserializer.deserializeUleb128AsU32(); @@ -52,6 +56,8 @@ export abstract class TransactionAuthenticator extends Serializable { * @param signature - The Ed25519 signature of a raw transaction. * @see {@link https://aptos.dev/integration/creating-a-signed-transaction | Creating a Signed Transaction} * for details about generating a signature. + * @group Implementation + * @category Transactions */ export class TransactionAuthenticatorEd25519 extends TransactionAuthenticator { public readonly public_key: Ed25519PublicKey; @@ -63,6 +69,8 @@ export class TransactionAuthenticatorEd25519 extends TransactionAuthenticator { * * @param public_key - The Ed25519PublicKey that will be used for authentication. * @param signature - The Ed25519Signature that will be used for authentication. + * @group Implementation + * @category Transactions */ constructor(public_key: Ed25519PublicKey, signature: Ed25519Signature) { super(); @@ -74,6 +82,8 @@ export class TransactionAuthenticatorEd25519 extends TransactionAuthenticator { * Serializes the transaction authenticator by encoding the sender information. * * @param serializer - The serializer instance used to perform the serialization. + * @group Implementation + * @category Transactions */ serialize(serializer: Serializer): void { serializer.serializeU32AsUleb128(TransactionAuthenticatorVariant.Ed25519); @@ -86,6 +96,8 @@ export class TransactionAuthenticatorEd25519 extends TransactionAuthenticator { * This function helps in deserializing the sender information to create a transaction authenticator. * * @param deserializer - The deserializer used to extract the sender data. + * @group Implementation + * @category Transactions */ static load(deserializer: Deserializer): TransactionAuthenticatorEd25519 { const public_key = Ed25519PublicKey.deserialize(deserializer); @@ -100,6 +112,8 @@ export class TransactionAuthenticatorEd25519 extends TransactionAuthenticator { * * @param public_key - The public key of the client involved in the transaction. * @param signature - The multi-signature of the raw transaction. + * @group Implementation + * @category Transactions */ export class TransactionAuthenticatorMultiEd25519 extends TransactionAuthenticator { public readonly public_key: MultiEd25519PublicKey; @@ -133,6 +147,8 @@ export class TransactionAuthenticatorMultiEd25519 extends TransactionAuthenticat * @param sender - The authenticator for the sender account. * @param secondary_signer_addresses - An array of addresses for the secondary signers. * @param secondary_signers - An array of authenticators for the secondary signer accounts. + * @group Implementation + * @category Transactions */ export class TransactionAuthenticatorMultiAgent extends TransactionAuthenticator { public readonly sender: AccountAuthenticator; @@ -176,6 +192,8 @@ export class TransactionAuthenticatorMultiAgent extends TransactionAuthenticator * @param secondary_signer_addresses - An array of addresses for secondary signers. * @param secondary_signers - An array of authenticators for secondary signers' accounts. * @param fee_payer - An object containing the fee payer's account address and authenticator. + * @group Implementation + * @category Transactions */ export class TransactionAuthenticatorFeePayer extends TransactionAuthenticator { public readonly sender: AccountAuthenticator; @@ -227,6 +245,8 @@ export class TransactionAuthenticatorFeePayer extends TransactionAuthenticator { * This class is responsible for managing the authentication of a transaction initiated by a single sender. * * @param sender - An instance of AccountAuthenticator that represents the account of the sender. + * @group Implementation + * @category Transactions */ export class TransactionAuthenticatorSingleSender extends TransactionAuthenticator { public readonly sender: AccountAuthenticator; diff --git a/src/transactions/instances/chainId.ts b/src/transactions/instances/chainId.ts index 2a475e3f3..8cd1624fc 100644 --- a/src/transactions/instances/chainId.ts +++ b/src/transactions/instances/chainId.ts @@ -8,6 +8,8 @@ import { Deserializer } from "../../bcs/deserializer"; * Represents a ChainId that can be serialized and deserialized. * * @extends Serializable + * @group Implementation + * @category Transactions */ export class ChainId extends Serializable { public readonly chainId: number; @@ -16,6 +18,8 @@ export class ChainId extends Serializable { * Initializes a new instance of the class with the specified chain ID. * * @param chainId - The ID of the blockchain network to be used. + * @group Implementation + * @category Transactions */ constructor(chainId: number) { super(); @@ -27,6 +31,8 @@ export class ChainId extends Serializable { * This function helps in converting the object into a format suitable for transmission or storage. * * @param serializer - The serializer instance used to perform the serialization. + * @group Implementation + * @category Transactions */ serialize(serializer: Serializer): void { serializer.serializeU8(this.chainId); @@ -37,6 +43,8 @@ export class ChainId extends Serializable { * This function allows you to reconstruct a ChainId object from serialized data. * * @param deserializer - The deserializer instance used to read the serialized data. + * @group Implementation + * @category Transactions */ static deserialize(deserializer: Deserializer): ChainId { const chainId = deserializer.deserializeU8(); diff --git a/src/transactions/instances/identifier.ts b/src/transactions/instances/identifier.ts index 2bc4bbb22..5d2fbfd81 100644 --- a/src/transactions/instances/identifier.ts +++ b/src/transactions/instances/identifier.ts @@ -10,6 +10,8 @@ import { Serializable, Serializer } from "../../bcs/serializer"; * the "function name" in "EntryFunction". * * @extends Serializable + * @group Implementation + * @category Transactions */ export class Identifier extends Serializable { public identifier: string; @@ -18,6 +20,8 @@ export class Identifier extends Serializable { * Creates an instance of the class with a specified identifier. * * @param identifier - The unique identifier for the instance. + * @group Implementation + * @category Transactions */ constructor(identifier: string) { super(); @@ -28,6 +32,8 @@ export class Identifier extends Serializable { * Serializes the identifier of the current instance using the provided serializer. * * @param serializer - The serializer instance used to perform the serialization. + * @group Implementation + * @category Transactions */ public serialize(serializer: Serializer): void { serializer.serializeStr(this.identifier); @@ -38,6 +44,8 @@ export class Identifier extends Serializable { * This function is useful for reconstructing an Identifier object from a serialized format. * * @param deserializer - The deserializer instance used to read the serialized data. + * @group Implementation + * @category Transactions */ static deserialize(deserializer: Deserializer): Identifier { const identifier = deserializer.deserializeStr(); diff --git a/src/transactions/instances/moduleId.ts b/src/transactions/instances/moduleId.ts index 6154b21fd..216afe730 100644 --- a/src/transactions/instances/moduleId.ts +++ b/src/transactions/instances/moduleId.ts @@ -10,6 +10,8 @@ import { MoveModuleId } from "../../types"; /** * Represents a ModuleId that can be serialized and deserialized. * A ModuleId consists of a module address (e.g., "0x1") and a module name (e.g., "coin"). + * @group Implementation + * @category Transactions */ export class ModuleId extends Serializable { public readonly address: AccountAddress; @@ -21,6 +23,8 @@ export class ModuleId extends Serializable { * * @param address - The account address, e.g., "0x1". * @param name - The module name under the specified address, e.g., "coin". + * @group Implementation + * @category Transactions */ constructor(address: AccountAddress, name: Identifier) { super(); @@ -33,6 +37,8 @@ export class ModuleId extends Serializable { * @param moduleId - A string literal representing the module identifier. * @throws Error if the provided moduleId is not in the correct format. * @returns ModuleId - The corresponding ModuleId object. + * @group Implementation + * @category Transactions */ static fromStr(moduleId: MoveModuleId): ModuleId { const parts = moduleId.split("::"); @@ -47,6 +53,8 @@ export class ModuleId extends Serializable { * This function is essential for converting the object's data into a format suitable for transmission or storage. * * @param serializer - The serializer instance used to perform the serialization. + * @group Implementation + * @category Transactions */ serialize(serializer: Serializer): void { this.address.serialize(serializer); @@ -58,6 +66,8 @@ export class ModuleId extends Serializable { * This function retrieves the account address and identifier to construct a ModuleId instance. * * @param deserializer - The deserializer instance used to read the data. + * @group Implementation + * @category Transactions */ static deserialize(deserializer: Deserializer): ModuleId { const address = AccountAddress.deserialize(deserializer); diff --git a/src/transactions/instances/multiAgentTransaction.ts b/src/transactions/instances/multiAgentTransaction.ts index b6712babe..3779d4bea 100644 --- a/src/transactions/instances/multiAgentTransaction.ts +++ b/src/transactions/instances/multiAgentTransaction.ts @@ -15,6 +15,8 @@ import { RawTransaction } from "./rawTransaction"; * @param rawTransaction The raw transaction to be executed. * @param secondarySignerAddresses An array of secondary signer addresses involved in the transaction. * @param feePayerAddress An optional account address that sponsors the transaction's gas fees. + * @group Implementation + * @category Transactions */ export class MultiAgentTransaction extends Serializable { public rawTransaction: RawTransaction; @@ -30,6 +32,8 @@ export class MultiAgentTransaction extends Serializable { * @param rawTransaction The raw transaction data. * @param secondarySignerAddresses An array of secondary signer addresses. * @param feePayerAddress An optional account address that sponsors the gas fees. + * @group Implementation + * @category Transactions */ constructor( rawTransaction: RawTransaction, @@ -47,6 +51,8 @@ export class MultiAgentTransaction extends Serializable { * This function is essential for preparing the transaction for transmission or storage in a serialized format. * * @param serializer - The serializer instance used to serialize the transaction data. + * @group Implementation + * @category Transactions */ serialize(serializer: Serializer): void { this.rawTransaction.serialize(serializer); @@ -67,6 +73,8 @@ export class MultiAgentTransaction extends Serializable { * signer addresses and the fee payer address if present. * * @param deserializer - The deserializer instance used to read the serialized data. + * @group Implementation + * @category Transactions */ static deserialize(deserializer: Deserializer): MultiAgentTransaction { const rawTransaction = RawTransaction.deserialize(deserializer); diff --git a/src/transactions/instances/rawTransaction.ts b/src/transactions/instances/rawTransaction.ts index 004653768..551cede80 100644 --- a/src/transactions/instances/rawTransaction.ts +++ b/src/transactions/instances/rawTransaction.ts @@ -14,6 +14,8 @@ import { TransactionVariants } from "../../types"; * Represents a raw transaction that can be serialized and deserialized. * Raw transactions contain the metadata and payloads that can be submitted to the Aptos chain for execution. * They must be signed before the Aptos chain can execute them. + * @group Implementation + * @category Transactions */ export class RawTransaction extends Serializable { public readonly sender: AccountAddress; @@ -44,6 +46,8 @@ export class RawTransaction extends Serializable { * @param gas_unit_price Price to be paid per gas unit. * @param expiration_timestamp_secs The blockchain timestamp at which the blockchain would discard this transaction. * @param chain_id The chain ID of the blockchain that this transaction is intended to be run on. + * @group Implementation + * @category Transactions */ constructor( sender: AccountAddress, @@ -70,6 +74,8 @@ export class RawTransaction extends Serializable { * This function is essential for preparing the transaction for transmission or storage in a serialized format. * * @param serializer - The serializer instance used to serialize the transaction data. + * @group Implementation + * @category Transactions */ serialize(serializer: Serializer): void { this.sender.serialize(serializer); @@ -86,6 +92,8 @@ export class RawTransaction extends Serializable { * This function retrieves the appropriate raw transaction based on the variant index provided by the deserializer. * * @param deserializer - An instance of the Deserializer used to read the serialized data. + * @group Implementation + * @category Transactions */ static deserialize(deserializer: Deserializer): RawTransaction { const sender = AccountAddress.deserialize(deserializer); @@ -111,15 +119,21 @@ export class RawTransaction extends Serializable { * Represents a raw transaction with associated data that can be serialized and deserialized. * * @extends Serializable + * @group Implementation + * @category Transactions */ export abstract class RawTransactionWithData extends Serializable { /** * Serialize a Raw Transaction With Data + * @group Implementation + * @category Transactions */ abstract serialize(serializer: Serializer): void; /** * Deserialize a Raw Transaction With Data + * @group Implementation + * @category Transactions */ static deserialize(deserializer: Deserializer): RawTransactionWithData { // index enum variant @@ -139,15 +153,21 @@ export abstract class RawTransactionWithData extends Serializable { * Represents a multi-agent transaction that can be serialized and deserialized. * * @extends RawTransactionWithData + * @group Implementation + * @category Transactions */ export class MultiAgentRawTransaction extends RawTransactionWithData { /** * The raw transaction + * @group Implementation + * @category Transactions */ public readonly raw_txn: RawTransaction; /** * The secondary signers on this transaction + * @group Implementation + * @category Transactions */ public readonly secondary_signer_addresses: Array; @@ -170,6 +190,8 @@ export class MultiAgentRawTransaction extends RawTransactionWithData { * * @param deserializer - The deserializer used to read the raw transaction data. * @returns A FeePayerRawTransaction object constructed from the deserialized data. + * @group Implementation + * @category Transactions */ static load(deserializer: Deserializer): MultiAgentRawTransaction { const rawTxn = RawTransaction.deserialize(deserializer); @@ -181,20 +203,28 @@ export class MultiAgentRawTransaction extends RawTransactionWithData { /** * Represents a Fee Payer Transaction that can be serialized and deserialized. + * @group Implementation + * @category Transactions */ export class FeePayerRawTransaction extends RawTransactionWithData { /** * The raw transaction + * @group Implementation + * @category Transactions */ public readonly raw_txn: RawTransaction; /** * The secondary signers on this transaction - optional and can be empty + * @group Implementation + * @category Transactions */ public readonly secondary_signer_addresses: Array; /** * The fee payer account address + * @group Implementation + * @category Transactions */ public readonly fee_payer_address: AccountAddress; diff --git a/src/transactions/instances/rotationProofChallenge.ts b/src/transactions/instances/rotationProofChallenge.ts index 5f889afc7..c51df5bae 100644 --- a/src/transactions/instances/rotationProofChallenge.ts +++ b/src/transactions/instances/rotationProofChallenge.ts @@ -9,6 +9,8 @@ import { MoveString, MoveVector, U64, U8 } from "../../bcs"; /** * Represents a challenge required for the account owner to sign in order to rotate the authentication key. + * @group Implementation + * @category Transactions */ export class RotationProofChallenge extends Serializable { // Resource account address @@ -41,6 +43,8 @@ export class RotationProofChallenge extends Serializable { * @param args.originator - The account address of the originator. * @param args.currentAuthKey - The current authentication key of the account. * @param args.newPublicKey - The new public key to be set for the account. + * @group Implementation + * @category Transactions */ constructor(args: { sequenceNumber: AnyNumber; @@ -67,6 +71,8 @@ export class RotationProofChallenge extends Serializable { * @param serializer.originator - The originator to serialize. * @param serializer.currentAuthKey - The current authentication key to serialize. * @param serializer.newPublicKey - The new public key to serialize. + * @group Implementation + * @category Transactions */ serialize(serializer: Serializer): void { serializer.serialize(this.accountAddress); diff --git a/src/transactions/instances/signedTransaction.ts b/src/transactions/instances/signedTransaction.ts index 84f3712c3..b2fdcbc78 100644 --- a/src/transactions/instances/signedTransaction.ts +++ b/src/transactions/instances/signedTransaction.ts @@ -17,6 +17,8 @@ import { RawTransaction } from "./rawTransaction"; * @param authenticator - Contains a client's public key and the signature of the raw transaction. * Authenticator can have three variations: single signature, multi-signature, and multi-agent. * @see {@link https://github.com/aptos-labs/aptos-core/blob/main/types/src/transaction/authenticator.rs} for details. + * @group Implementation + * @category Transactions */ export class SignedTransaction extends Serializable { public readonly raw_txn: RawTransaction; @@ -33,6 +35,8 @@ export class SignedTransaction extends Serializable { * flavors: single signature, multi-signature and multi-agent. * @see {@link https://aptos.dev/integration/creating-a-signed-transaction | Creating a Signed Transaction} * @see {@link https://github.com/aptos-labs/aptos-core/blob/main/types/src/transaction/authenticator.rs} for details. + * @group Implementation + * @category Transactions */ constructor(raw_txn: RawTransaction, authenticator: TransactionAuthenticator) { super(); @@ -45,6 +49,8 @@ export class SignedTransaction extends Serializable { * This function is essential for preparing the transaction data for transmission or storage. * * @param serializer - The serializer instance used to serialize the transaction and authenticator. + * @group Implementation + * @category Transactions */ serialize(serializer: Serializer): void { this.raw_txn.serialize(serializer); @@ -56,6 +62,8 @@ export class SignedTransaction extends Serializable { * This function allows you to reconstruct a SignedTransaction object from its serialized form, enabling further processing or validation. * * @param deserializer - The deserializer instance used to read the serialized data. + * @group Implementation + * @category Transactions */ static deserialize(deserializer: Deserializer): SignedTransaction { const raw_txn = RawTransaction.deserialize(deserializer); diff --git a/src/transactions/instances/simpleTransaction.ts b/src/transactions/instances/simpleTransaction.ts index 07cd52ad8..f592e8a05 100644 --- a/src/transactions/instances/simpleTransaction.ts +++ b/src/transactions/instances/simpleTransaction.ts @@ -16,6 +16,8 @@ import { RawTransaction } from "./rawTransaction"; * * @param rawTransaction - The Raw Transaction. * @param feePayerAddress - The optional sponsor Account Address. + * @group Implementation + * @category Transactions */ export class SimpleTransaction extends Serializable { public rawTransaction: RawTransaction; @@ -32,6 +34,8 @@ export class SimpleTransaction extends Serializable { * * @param rawTransaction The Raw Transaction. * @param feePayerAddress The optional sponsor Account Address to pay the gas fees. + * @group Implementation + * @category Transactions */ constructor(rawTransaction: RawTransaction, feePayerAddress?: AccountAddress) { super(); @@ -44,6 +48,8 @@ export class SimpleTransaction extends Serializable { * This function ensures that the raw transaction and fee payer address are properly serialized for further processing. * * @param serializer - The serializer instance used to serialize the transaction data. + * @group Implementation + * @category Transactions */ serialize(serializer: Serializer): void { this.rawTransaction.serialize(serializer); @@ -61,6 +67,8 @@ export class SimpleTransaction extends Serializable { * This function helps in reconstructing a SimpleTransaction object from its serialized form. * * @param deserializer - The deserializer instance used to read the serialized data. + * @group Implementation + * @category Transactions */ static deserialize(deserializer: Deserializer): SimpleTransaction { const rawTransaction = RawTransaction.deserialize(deserializer); diff --git a/src/transactions/instances/transactionArgument.ts b/src/transactions/instances/transactionArgument.ts index bfc997cd7..1edb6a119 100644 --- a/src/transactions/instances/transactionArgument.ts +++ b/src/transactions/instances/transactionArgument.ts @@ -9,12 +9,16 @@ export interface TransactionArgument extends EntryFunctionArgument, ScriptFuncti /** * Represents an argument for entry functions, providing methods to serialize the argument * to BCS-serialized bytes and convert it to different formats. + * @group Implementation + * @category Transactions */ export interface EntryFunctionArgument { /** * Serialize an argument to BCS-serialized bytes. * * @param serializer - The serializer instance used for serialization. + * @group Implementation + * @category Transactions */ serialize(serializer: Serializer): void; @@ -24,6 +28,8 @@ export interface EntryFunctionArgument { * the number of the following bytes followed by the BCS-serialized bytes for a typed argument. * * @param serializer - The serializer used to convert the argument. + * @group Implementation + * @category Transactions */ serializeForEntryFunction(serializer: Serializer): void; @@ -31,6 +37,8 @@ export interface EntryFunctionArgument { * Convert the argument to BCS-serialized bytes. * * @returns Uint8Array representing the BCS-serialized bytes of the argument. + * @group Implementation + * @category Transactions */ bcsToBytes(): Uint8Array; @@ -39,22 +47,30 @@ export interface EntryFunctionArgument { * This function is useful for obtaining a Hex instance that encapsulates the BCS-serialized bytes, * allowing for easier manipulation and representation of the data. * @returns A Hex instance containing the BCS-serialized bytes. + * @group Implementation + * @category Transactions */ bcsToHex(): Hex; } /** * Represents an argument for script functions, providing methods to serialize and convert to bytes. + * @group Implementation + * @category Transactions */ export interface ScriptFunctionArgument { /** * Serialize an argument to BCS-serialized bytes. + * @group Implementation + * @category Transactions */ serialize(serializer: Serializer): void; /** * Serialize an argument to BCS-serialized bytes as a type aware byte sequence. * The byte sequence contains an enum variant index followed by the BCS-serialized * bytes for a typed argument. + * @group Implementation + * @category Transactions */ serializeForScriptFunction(serializer: Serializer): void; diff --git a/src/transactions/instances/transactionPayload.ts b/src/transactions/instances/transactionPayload.ts index 3bf01823e..4319cc7d3 100644 --- a/src/transactions/instances/transactionPayload.ts +++ b/src/transactions/instances/transactionPayload.ts @@ -22,6 +22,8 @@ import { TypeTag } from "../typeTag"; * @param deserializer - The deserializer used to read the script transaction argument. * @returns The deserialized script transaction argument. * @throws Error if the variant index is unknown. + * @group Implementation + * @category Transactions */ export function deserializeFromScriptArgument(deserializer: Deserializer): TransactionArgument { // index enum variant @@ -58,15 +60,21 @@ export function deserializeFromScriptArgument(deserializer: Deserializer): Trans * This class serves as a base for different types of transaction payloads, allowing for * their serialization into a format suitable for transmission and deserialization back * into their original form. + * @group Implementation + * @category Transactions */ export abstract class TransactionPayload extends Serializable { /** * Serialize a Transaction Payload + * @group Implementation + * @category Transactions */ abstract serialize(serializer: Serializer): void; /** * Deserialize a Transaction Payload + * @group Implementation + * @category Transactions */ /** @@ -74,6 +82,8 @@ export abstract class TransactionPayload extends Serializable { * This function enables the reconstruction of a MultiSigTransactionPayload object from its serialized form. * * @param deserializer - The deserializer instance used to read the serialized data. + * @group Implementation + * @category Transactions */ static deserialize(deserializer: Deserializer): TransactionPayload { // index enum variant @@ -97,6 +107,8 @@ export abstract class TransactionPayload extends Serializable { * This class encapsulates a script that defines the logic for a transaction payload. * * @extends TransactionPayload + * @group Implementation + * @category Transactions */ export class TransactionPayloadScript extends TransactionPayload { public readonly script: Script; @@ -106,6 +118,8 @@ export class TransactionPayloadScript extends TransactionPayload { * * @param script - The payload of the multi-sig transaction. This can only be an EntryFunction for now, but Script might be * supported in the future. + * @group Implementation + * @category Transactions */ constructor(script: Script) { super(); @@ -116,6 +130,8 @@ export class TransactionPayloadScript extends TransactionPayload { * Serializes the transaction payload, enabling future support for multiple types of inner transaction payloads. * * @param serializer - The serializer instance used to serialize the transaction data. + * @group Implementation + * @category Transactions */ serialize(serializer: Serializer): void { serializer.serializeU32AsUleb128(TransactionPayloadVariants.Script); @@ -127,6 +143,8 @@ export class TransactionPayloadScript extends TransactionPayload { * This function helps in reconstructing a MultiSig transaction payload from its serialized form. * * @param deserializer - The deserializer used to read the serialized data. + * @group Implementation + * @category Transactions */ static load(deserializer: Deserializer): TransactionPayloadScript { const script = Script.deserialize(deserializer); @@ -138,6 +156,8 @@ export class TransactionPayloadScript extends TransactionPayload { * Represents a transaction payload entry function that can be serialized and deserialized. * * @extends TransactionPayload + * @group Implementation + * @category Transactions */ export class TransactionPayloadEntryFunction extends TransactionPayload { public readonly entryFunction: EntryFunction; @@ -160,6 +180,8 @@ export class TransactionPayloadEntryFunction extends TransactionPayload { /** * Represents a multi-signature transaction payload that can be serialized and deserialized. + * @group Implementation + * @category Transactions */ export class TransactionPayloadMultiSig extends TransactionPayload { public readonly multiSig: MultiSig; @@ -189,6 +211,8 @@ export class TransactionPayloadMultiSig extends TransactionPayload { * @param function_name - The name of the function (e.g., "transfer"). * @param type_args - Type arguments required by the Move function. * @param args - Arguments to the Move function. + * @group Implementation + * @category Transactions */ export class EntryFunction { public readonly module_name: ModuleId; @@ -217,6 +241,8 @@ export class EntryFunction { * ``` * public entry fun transfer(from: &signer, to: address, amount: u64) * ``` + * @group Implementation + * @category Transactions */ constructor( module_name: ModuleId, @@ -250,6 +276,8 @@ export class EntryFunction { * ``` * * @returns EntryFunction + * @group Implementation + * @category Transactions */ static build( module_id: MoveModuleId, @@ -287,6 +315,8 @@ export class EntryFunction { * @param deserializer * @returns A deserialized EntryFunction payload for a transaction. * + * @group Implementation + * @category Transactions */ static deserialize(deserializer: Deserializer): EntryFunction { const module_name = ModuleId.deserialize(deserializer); @@ -309,20 +339,28 @@ export class EntryFunction { /** * Represents a Script that can be serialized and deserialized. * Scripts contain the Move bytecode payload that can be submitted to the Aptos chain for execution. + * @group Implementation + * @category Transactions */ export class Script { /** * The move module bytecode + * @group Implementation + * @category Transactions */ public readonly bytecode: Uint8Array; /** * The type arguments that the bytecode function requires. + * @group Implementation + * @category Transactions */ public readonly type_args: Array; /** * The arguments that the bytecode function requires. + * @group Implementation + * @category Transactions */ public readonly args: Array; @@ -344,6 +382,8 @@ export class Script { * ``` * public(script) fun transfer(from: &signer, to: address, amount: u64) * ``` + * @group Implementation + * @category Transactions */ constructor(bytecode: Uint8Array, type_args: Array, args: Array) { this.bytecode = bytecode; @@ -381,6 +421,8 @@ export class Script { * * This class encapsulates the functionality to manage multi-signature transactions, including the address of the * multi-sig account and the associated transaction payload. + * @group Implementation + * @category Transactions */ export class MultiSig { public readonly multisig_address: AccountAddress; @@ -394,6 +436,8 @@ export class MultiSig { * * @param transaction_payload The payload of the multi-sig transaction. This is optional when executing a multi-sig * transaction whose payload is already stored on chain. + * @group Implementation + * @category Transactions */ constructor(multisig_address: AccountAddress, transaction_payload?: MultiSigTransactionPayload) { this.multisig_address = multisig_address; @@ -428,6 +472,8 @@ export class MultiSig { * This class is designed to encapsulate the transaction payload for multi-sig account transactions * as defined in the `multisig_account.move` module. Future enhancements may allow support for script * payloads as the `multisig_account.move` module evolves. + * @group Implementation + * @category Transactions */ export class MultiSigTransactionPayload extends Serializable { public readonly transaction_payload: EntryFunction; @@ -438,6 +484,8 @@ export class MultiSigTransactionPayload extends Serializable { * @param transaction_payload The payload of the multi-sig transaction. * This can only be EntryFunction for now but, * Script might be supported in the future. + * @group Implementation + * @category Transactions */ constructor(transaction_payload: EntryFunction) { super(); @@ -449,6 +497,8 @@ export class MultiSigTransactionPayload extends Serializable { * We can support multiple types of inner transaction payload in the future. * For now, it's only EntryFunction but if we support more types, * we need to serialize with the right enum values here + * @group Implementation + * @category Transactions */ serializer.serializeU32AsUleb128(0); this.transaction_payload.serialize(serializer); diff --git a/src/transactions/management/accountSequenceNumber.ts b/src/transactions/management/accountSequenceNumber.ts index f1772c756..25afad0be 100644 --- a/src/transactions/management/accountSequenceNumber.ts +++ b/src/transactions/management/accountSequenceNumber.ts @@ -21,6 +21,8 @@ * This only manages the distribution of sequence numbers it does not help handle transaction * failures. * If a transaction fails, you should call synchronize and wait for timeouts. + * @group Implementation + * @category Transactions */ import { AptosConfig } from "../../api/aptosConfig"; @@ -38,6 +40,8 @@ import { nowInSeconds, sleep } from "../../utils/helpers"; * @param maxWaitTime - The maximum time to wait for a transaction to commit. * @param maximumInFlight - The maximum number of transactions that can be in flight at once. * @param sleepTime - The time to wait before retrying to get the sequence number. + * @group Implementation + * @category Transactions */ export class AccountSequenceNumber { readonly aptosConfig: AptosConfig; @@ -61,6 +65,8 @@ export class AccountSequenceNumber { * The ideal solution is likely that each thread grabs the next number from an incremental integer. * When they complete, they increment that number and that entity is able to enter the `lock`. * That would guarantee ordering. + * @group Implementation + * @category Transactions */ lock = false; @@ -79,6 +85,8 @@ export class AccountSequenceNumber { * @param maxWaitTime - The maximum time to wait for a transaction to be processed, in milliseconds. * @param maximumInFlight - The maximum number of transactions that can be in flight at the same time. * @param sleepTime - The time to sleep between transaction checks, in milliseconds. + * @group Implementation + * @category Transactions */ constructor( aptosConfig: AptosConfig, @@ -99,6 +107,8 @@ export class AccountSequenceNumber { * This function ensures that the sequence number is updated and synchronized, handling potential delays in transaction commits. * * @returns {BigInt} The next available sequence number. + * @group Implementation + * @category Transactions */ async nextSequenceNumber(): Promise { /* eslint-disable no-await-in-loop */ @@ -146,6 +156,8 @@ export class AccountSequenceNumber { * @returns {Promise} A promise that resolves when the account has been initialized. * * @throws {Error} Throws an error if the account information cannot be retrieved. + * @group Implementation + * @category Transactions */ async initialize(): Promise { const { sequence_number: sequenceNumber } = await getInfo({ @@ -160,6 +172,8 @@ export class AccountSequenceNumber { * Updates this account's sequence number with the one on-chain. * * @returns The on-chain sequence number for this account. + * @group Implementation + * @category Transactions */ async update(): Promise { const { sequence_number: sequenceNumber } = await getInfo({ @@ -175,6 +189,8 @@ export class AccountSequenceNumber { * This function polls the network until all submitted transactions have either been committed or until the maximum wait time has elapsed. * * @throws {Error} Throws an error if there is an issue synchronizing the account sequence number with the one on-chain. + * @group Implementation + * @category Transactions */ async synchronize(): Promise { if (this.lastUncommintedNumber === this.currentNumber) return; diff --git a/src/transactions/management/asyncQueue.ts b/src/transactions/management/asyncQueue.ts index 6e64afd65..13f20ec4b 100644 --- a/src/transactions/management/asyncQueue.ts +++ b/src/transactions/management/asyncQueue.ts @@ -4,6 +4,8 @@ * It allows to enqueue items and dequeue them asynchronously. * This is not thread-safe, but it is async concurrency safe, and * it does not guarantee ordering for those that call into and await on enqueue. + * @group Implementation + * @category Transactions */ interface PendingDequeue { @@ -24,6 +26,8 @@ export class AsyncQueue { * immediately; otherwise, it adds the item to the queue. * * @param item - The item to be added to the queue. + * @group Implementation + * @category Transactions */ enqueue(item: T): void { this.cancelled = false; @@ -44,6 +48,8 @@ export class AsyncQueue { * If the queue is empty, it creates a new promise that will be resolved when an item is enqueued. * * @returns Promise + * @group Implementation + * @category Transactions */ async dequeue(): Promise { if (this.queue.length > 0) { @@ -59,6 +65,8 @@ export class AsyncQueue { * Determine whether the queue is empty. * * @returns boolean - Returns true if the queue has no elements, otherwise false. + * @group Implementation + * @category Transactions */ isEmpty(): boolean { return this.queue.length === 0; @@ -69,6 +77,8 @@ export class AsyncQueue { * This ensures that any awaiting code can handle the cancellation appropriately. * * @returns {void} + * @group Implementation + * @category Transactions */ cancel(): void { this.cancelled = true; @@ -86,6 +96,8 @@ export class AsyncQueue { * Determine whether the queue has been cancelled. * * @returns boolean - Returns true if the queue is cancelled, otherwise false. + * @group Implementation + * @category Transactions */ isCancelled(): boolean { return this.cancelled; @@ -95,6 +107,8 @@ export class AsyncQueue { * Retrieve the length of the pending dequeue. * * @returns number - The number of items currently in the pending dequeue. + * @group Implementation + * @category Transactions */ pendingDequeueLength(): number { return this.pendingDequeue.length; @@ -106,5 +120,7 @@ export class AsyncQueue { * This error extends the built-in Error class to provide additional context for cancellation events. * * @extends Error + * @group Implementation + * @category Transactions */ export class AsyncQueueCancelledError extends Error {} diff --git a/src/transactions/management/transactionWorker.ts b/src/transactions/management/transactionWorker.ts index 5f0380782..0e1bd6c48 100644 --- a/src/transactions/management/transactionWorker.ts +++ b/src/transactions/management/transactionWorker.ts @@ -11,10 +11,16 @@ import { AccountSequenceNumber } from "./accountSequenceNumber"; import { AsyncQueue, AsyncQueueCancelledError } from "./asyncQueue"; import { SimpleTransaction } from "../instances/simpleTransaction"; +/** + * @group Implementation + * @category Transactions + */ export const promiseFulfilledStatus = "fulfilled"; /** * Events emitted by the transaction worker during its operation, allowing the dapp to respond to various transaction states. + * @group Implementation + * @category Transactions */ export enum TransactionWorkerEventsEnum { // fired after a transaction gets sent to the chain @@ -31,11 +37,8 @@ export enum TransactionWorkerEventsEnum { /** * Defines the events emitted by the transaction worker during various stages of transaction processing. * - * @event transactionSent - Emitted when a transaction is successfully sent. - * @event transactionSendFailed - Emitted when sending a transaction fails. - * @event transactionExecuted - Emitted when a transaction is successfully executed. - * @event transactionExecutionFailed - Emitted when executing a transaction fails. - * @event executionFinish - Emitted when the execution process is finished. + * @group Implementation + * @category Transactions */ export interface TransactionWorkerEvents { transactionSent: (data: SuccessEventData) => void; @@ -47,6 +50,8 @@ export interface TransactionWorkerEvents { /** * The payload for when the worker has finished its job. + * @group Implementation + * @category Transactions */ export type ExecutionFinishEventData = { message: string; @@ -54,6 +59,8 @@ export type ExecutionFinishEventData = { /** * The payload for a success event. + * @group Implementation + * @category Transactions */ export type SuccessEventData = { message: string; @@ -62,6 +69,8 @@ export type SuccessEventData = { /** * The payload for a failure event. + * @group Implementation + * @category Transactions */ export type FailureEventData = { message: string; @@ -79,6 +88,8 @@ export type FailureEventData = { * 1) waits for resolution of the submission process or get pre-execution validation error * and 2) waits for the resolution of the execution process or get an execution error. * The worker fires events for any submission and/or execution success and/or failure. + * @group Implementation + * @category Transactions */ export class TransactionWorker extends EventEmitter { readonly aptosConfig: AptosConfig; @@ -98,6 +109,8 @@ export class TransactionWorker extends EventEmitter { * transactions payloads waiting to be generated and signed * * TODO support entry function payload from ABI builder + * @group Implementation + * @category Transactions */ transactionsQueue = new AsyncQueue< [InputGenerateTransactionPayloadData, InputGenerateTransactionOptions | undefined] @@ -105,16 +118,22 @@ export class TransactionWorker extends EventEmitter { /** * signed transactions waiting to be submitted + * @group Implementation + * @category Transactions */ outstandingTransactions = new AsyncQueue<[Promise, bigint]>(); /** * transactions that have been submitted to chain + * @group Implementation + * @category Transactions */ sentTransactions: Array<[string, bigint, any]> = []; /** * transactions that have been committed to chain + * @group Implementation + * @category Transactions */ executedTransactions: Array<[string, bigint, any]> = []; @@ -128,6 +147,8 @@ export class TransactionWorker extends EventEmitter { * @param maximumInFlight - The maximum number of transactions that can be submitted per account, default is 100. * @param sleepTime - The time to wait in seconds before re-evaluating if the maximum number of transactions are in flight, * default is 10 seconds. + * @group Implementation + * @category Transactions */ constructor( aptosConfig: AptosConfig, @@ -155,6 +176,8 @@ export class TransactionWorker extends EventEmitter { * This function continues to submit transactions until there are no more to process. * * @throws {Error} Throws an error if the transaction submission fails. + * @group Implementation + * @category Transactions */ async submitNextTransaction() { try { @@ -189,6 +212,8 @@ export class TransactionWorker extends EventEmitter { * @event TransactionWorkerEventsEnum.TransactionSendFailed - Emitted when a transaction fails to commit, along with the error * reason. * @event TransactionWorkerEventsEnum.ExecutionFinish - Emitted when the execution of transactions is complete. + * @group Implementation + * @category Transactions */ async processTransactions() { try { @@ -247,6 +272,8 @@ export class TransactionWorker extends EventEmitter { * Once a transaction has been sent to the chain, this function checks for its execution status. * @param sentTransaction - The transaction that was sent to the chain and is now waiting to be executed. * @param sequenceNumber - The account's sequence number that was sent with the transaction. + * @group Implementation + * @category Transactions */ async checkTransaction(sentTransaction: PromiseFulfilledResult, sequenceNumber: bigint) { try { @@ -287,6 +314,8 @@ export class TransactionWorker extends EventEmitter { * @param options.gasUnitPrice - Gas unit price for the transaction. * @param options.expireTimestamp - Expiration timestamp on the transaction. * @param options.accountSequenceNumber - The sequence number for the transaction. + * @group Implementation + * @category Transactions */ async push( transactionData: InputGenerateTransactionPayloadData, @@ -301,6 +330,8 @@ export class TransactionWorker extends EventEmitter { * @param account - An Aptos account used as the sender of the transaction. * @param sequenceNumber - A sequence number the transaction will be generated with. * @returns A signed transaction object or undefined if the transaction queue is empty. + * @group Implementation + * @category Transactions */ async generateNextTransaction(account: Account, sequenceNumber: bigint): Promise { if (this.transactionsQueue.isEmpty()) return undefined; @@ -317,6 +348,8 @@ export class TransactionWorker extends EventEmitter { * Starts transaction submission and processing by executing tasks from the queue until it is cancelled. * * @throws {Error} Throws an error if unable to start transaction batching. + * @group Implementation + * @category Transactions */ async run() { try { @@ -333,6 +366,8 @@ export class TransactionWorker extends EventEmitter { * Starts the transaction management process. * * @throws {Error} Throws an error if the worker has already started. + * @group Implementation + * @category Transactions */ start() { if (this.started) { @@ -348,6 +383,8 @@ export class TransactionWorker extends EventEmitter { * Stops the transaction management process. * * @throws {Error} Throws an error if the worker has already stopped. + * @group Implementation + * @category Transactions */ stop() { if (this.taskQueue.isCancelled()) { diff --git a/src/transactions/transactionBuilder/helpers.ts b/src/transactions/transactionBuilder/helpers.ts index 61dbee780..a4e74fbd4 100644 --- a/src/transactions/transactionBuilder/helpers.ts +++ b/src/transactions/transactionBuilder/helpers.ts @@ -18,6 +18,8 @@ import { MoveFunction, MoveFunctionId } from "../../types"; * * @param arg - The argument to check, which can be of various types. * @returns A boolean indicating whether the argument is a boolean. + * @group Implementation + * @category Transactions */ export function isBool(arg: SimpleEntryFunctionArgumentTypes): arg is boolean { return typeof arg === "boolean"; @@ -28,6 +30,8 @@ export function isBool(arg: SimpleEntryFunctionArgumentTypes): arg is boolean { * * @param arg - The value to be checked for string type. * @returns A boolean indicating whether the argument is a string. + * @group Implementation + * @category Transactions */ export function isString(arg: any): arg is string { return typeof arg === "string"; @@ -38,6 +42,8 @@ export function isString(arg: any): arg is string { * * @param arg - The argument to check, which can be of various types. * @returns A boolean indicating whether the argument is a number. + * @group Implementation + * @category Transactions */ export function isNumber(arg: SimpleEntryFunctionArgumentTypes): arg is number { return typeof arg === "number"; @@ -50,6 +56,8 @@ export function isNumber(arg: SimpleEntryFunctionArgumentTypes): arg is number { * * @param arg - The input value to be converted. This can be a number, a string representing a number, or any other type. * @returns Returns the converted number if the input is valid; otherwise, it returns undefined. + * @group Implementation + * @category Transactions */ export function convertNumber(arg: SimpleEntryFunctionArgumentTypes): number | undefined { if (isNumber(arg)) { @@ -66,6 +74,8 @@ export function convertNumber(arg: SimpleEntryFunctionArgumentTypes): number | u * Determines if the provided argument is a large number, which can be a number, bigint, or string representation of a number. * * @param arg - The argument to check, which can be of type number, bigint, or string. + * @group Implementation + * @category Transactions */ export function isLargeNumber(arg: SimpleEntryFunctionArgumentTypes): arg is number | bigint | string { return typeof arg === "number" || typeof arg === "bigint" || typeof arg === "string"; @@ -76,6 +86,8 @@ export function isLargeNumber(arg: SimpleEntryFunctionArgumentTypes): arg is num * * @param arg - The argument to check for emptiness. * @returns A boolean indicating whether the argument is empty. + * @group Implementation + * @category Transactions */ export function isEmptyOption(arg: SimpleEntryFunctionArgumentTypes): arg is null | undefined { return arg === null || arg === undefined; @@ -86,6 +98,8 @@ export function isEmptyOption(arg: SimpleEntryFunctionArgumentTypes): arg is nul * This function helps validate that the argument conforms to the expected types for entry function parameters. * * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes. + * @group Implementation + * @category Transactions */ export function isEncodedEntryFunctionArgument( arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes, @@ -95,6 +109,8 @@ export function isEncodedEntryFunctionArgument( * Determines if the provided argument is an instance of the Bool class. * * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes. + * @group Implementation + * @category Transactions */ isBcsBool(arg) || /** @@ -102,12 +118,16 @@ export function isEncodedEntryFunctionArgument( * This function helps validate the type of the argument passed to ensure it is a U8 type. * * @param arg - The argument to be checked, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes. + * @group Implementation + * @category Transactions */ isBcsU8(arg) || /** * Determines if the provided argument is an instance of U16. * * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes. + * @group Implementation + * @category Transactions */ isBcsU16(arg) || /** @@ -115,6 +135,8 @@ export function isEncodedEntryFunctionArgument( * * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes. * @returns A boolean indicating whether the argument is a U32 instance. + * @group Implementation + * @category Transactions */ isBcsU32(arg) || /** @@ -122,6 +144,8 @@ export function isEncodedEntryFunctionArgument( * This function helps validate that the argument conforms to the expected U64 type. * * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes. + * @group Implementation + * @category Transactions */ isBcsU64(arg) || /** @@ -129,6 +153,8 @@ export function isEncodedEntryFunctionArgument( * This function helps validate the type of the argument passed to ensure it is a U128 type. * * @param arg - The argument to be checked, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes. + * @group Implementation + * @category Transactions */ isBcsU128(arg) || /** @@ -136,6 +162,8 @@ export function isEncodedEntryFunctionArgument( * * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes. * @returns A boolean indicating whether the argument is a U256 instance. + * @group Implementation + * @category Transactions */ isBcsU256(arg) || /** @@ -143,12 +171,16 @@ export function isEncodedEntryFunctionArgument( * This function helps validate whether a given input corresponds to a valid BCS address type. * * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes. + * @group Implementation + * @category Transactions */ isBcsAddress(arg) || /** * Determine if the provided argument is an instance of MoveString. * * @param arg - The argument to check, which can be of types EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes. + * @group Implementation + * @category Transactions */ isBcsString(arg) || /** @@ -156,51 +188,83 @@ export function isEncodedEntryFunctionArgument( * This function helps to validate the type of the argument being passed. * * @param arg - The argument to check, which can be of type EntryFunctionArgumentTypes or SimpleEntryFunctionArgumentTypes. + * @group Implementation + * @category Transactions */ isBcsFixedBytes(arg) || arg instanceof MoveVector || arg instanceof MoveOption ); } - +/** + * @group Implementation + * @category Transactions + */ export function isBcsBool(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is Bool { return arg instanceof Bool; } - +/** + * @group Implementation + * @category Transactions + */ export function isBcsAddress( arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes, ): arg is AccountAddress { return arg instanceof AccountAddress; } - +/** + * @group Implementation + * @category Transactions + */ export function isBcsString(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is MoveString { return arg instanceof MoveString; } - +/** + * @group Implementation + * @category Transactions + */ export function isBcsFixedBytes(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is FixedBytes { return arg instanceof FixedBytes; } - +/** + * @group Implementation + * @category Transactions + */ export function isBcsU8(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U8 { return arg instanceof U8; } - +/** + * @group Implementation + * @category Transactions + */ export function isBcsU16(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U16 { return arg instanceof U16; } - +/** + * @group Implementation + * @category Transactions + */ export function isBcsU32(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U32 { return arg instanceof U32; } - +/** + * @group Implementation + * @category Transactions + */ export function isBcsU64(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U64 { return arg instanceof U64; } - +/** + * @group Implementation + * @category Transactions + */ export function isBcsU128(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U128 { return arg instanceof U128; } - +/** + * @group Implementation + * @category Transactions + */ export function isBcsU256(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionArgumentTypes): arg is U256 { return arg instanceof U256; } @@ -212,6 +276,8 @@ export function isBcsU256(arg: EntryFunctionArgumentTypes | SimpleEntryFunctionA * @param arg.bytecode - The bytecode of the script, present if the input is script data. * @param arg.function - The function associated with the transaction, which is relevant for standard payloads. * @param arg.args - The arguments for the function, applicable in the context of standard payloads. + * @group Implementation + * @category Transactions */ export function isScriptDataInput( arg: InputGenerateTransactionPayloadDataWithRemoteABI | InputGenerateTransactionPayloadData, @@ -225,6 +291,8 @@ export function isScriptDataInput( * * @param expectedType - The type that was expected for the argument. * @param position - The position of the argument that caused the type mismatch. + * @group Implementation + * @category Transactions */ export function throwTypeMismatch(expectedType: string, position: number) { throw new Error(`Type mismatch for argument ${position}, expected '${expectedType}'`); @@ -239,6 +307,8 @@ export function throwTypeMismatch(expectedType: string, position: number) { * * @param functionAbi - The ABI of the function to analyze. * @returns The index of the first non-signer argument, or the length of the parameters array if none are found. + * @group Implementation + * @category Transactions */ export function findFirstNonSignerArg(functionAbi: MoveFunction): number { const index = functionAbi.params.findIndex((param) => param !== "signer" && param !== "&signer"); @@ -255,6 +325,8 @@ export function findFirstNonSignerArg(functionAbi: MoveFunction): number { * @param functionArg - The function identifier string in the format "moduleAddress::moduleName::functionName". * @returns An object containing the module address, module name, and function name. * @throws Error if the function identifier does not contain exactly three parts. + * @group Implementation + * @category Transactions */ export function getFunctionParts(functionArg: MoveFunctionId) { const funcNameParts = functionArg.split("::"); diff --git a/src/transactions/transactionBuilder/remoteAbi.ts b/src/transactions/transactionBuilder/remoteAbi.ts index 92707f66d..14cfd7e02 100644 --- a/src/transactions/transactionBuilder/remoteAbi.ts +++ b/src/transactions/transactionBuilder/remoteAbi.ts @@ -54,6 +54,8 @@ const TEXT_ENCODER = new TextEncoder(); * * @param typeArguments - An optional array of type arguments that may include string representations. * @returns An array of TypeTag objects derived from the provided type arguments. + * @group Implementation + * @category Transactions */ export function standardizeTypeTags(typeArguments?: Array): Array { return ( @@ -75,6 +77,8 @@ export function standardizeTypeTags(typeArguments?: Array): Array< * @param moduleName - The name of the module containing the function. * @param functionName - The name of the function whose ABI is to be fetched. * @param aptosConfig - The configuration settings for Aptos. + * @group Implementation + * @category Transactions */ export async function fetchFunctionAbi( moduleAddress: string, @@ -102,6 +106,8 @@ export async function fetchFunctionAbi( * @param aptosConfig - The configuration settings for Aptos. * @returns An object containing the number of signers, type parameters, and function parameters. * @throws Error if the ABI cannot be found or if the function is not an entry function. + * @group Implementation + * @category Transactions */ export async function fetchEntryFunctionAbi( moduleAddress: string, @@ -145,6 +151,8 @@ export async function fetchEntryFunctionAbi( * @param aptosConfig - The configuration settings for Aptos. * @returns An object containing the type parameters, parameters, and return types of the view function. * @throws Error if the ABI cannot be found or if the function is not a view function. + * @group Implementation + * @category Transactions */ export async function fetchViewFunctionAbi( moduleAddress: string, @@ -192,6 +200,8 @@ export async function fetchViewFunctionAbi( * @param arg - The argument to be converted, which can be of various types. * @param position - The index of the argument in the function's parameter list. * @param genericTypeParams - An array of type tags for any generic type parameters. + * @group Implementation + * @category Transactions */ export function convertArgument( functionName: string, @@ -217,6 +227,8 @@ export function convertArgument( * @param param - The expected type tag for the argument. * @param position - The position of the argument in the function call. * @param genericTypeParams - An array of generic type parameters that may be used for conversion. + * @group Implementation + * @category Transactions */ export function checkOrConvertArgument( arg: SimpleEntryFunctionArgumentTypes | EntryFunctionArgumentTypes, @@ -235,6 +247,8 @@ export function checkOrConvertArgument( * @param typeArgs - The expected type arguments. * @param arg - The argument to be checked. * @param position - The position of the argument in the context of the check. + * @group Implementation + * @category Transactions */ checkType(param, arg, position); return arg; @@ -253,6 +267,8 @@ export function checkOrConvertArgument( * @param param - The type tag that defines the expected type of the argument. * @param position - The position of the argument in the function call, used for error reporting. * @param genericTypeParams - An array of type tags for generic type parameters, used when the parameter type is generic. + * @group Implementation + * @category Transactions */ function parseArg( arg: SimpleEntryFunctionArgumentTypes, @@ -274,6 +290,8 @@ function parseArg( * * @param moveOption - The name of the move option that caused the type mismatch. * @param position - The position where the error occurred. + * @group Implementation + * @category Transactions */ throwTypeMismatch("boolean", position); } @@ -425,6 +443,8 @@ function parseArg( * @param param * @param arg * @param position + * @group Implementation + * @category Transactions */ function checkType(param: TypeTag, arg: EntryFunctionArgumentTypes, position: number) { if (param.isBool()) { diff --git a/src/transactions/transactionBuilder/signingMessage.ts b/src/transactions/transactionBuilder/signingMessage.ts index 87332464a..f355d116f 100644 --- a/src/transactions/transactionBuilder/signingMessage.ts +++ b/src/transactions/transactionBuilder/signingMessage.ts @@ -3,6 +3,8 @@ /** * This file handles the generation of the signing message. + * @group Implementation + * @category Transactions */ import { sha3_256 as sha3Hash } from "@noble/hashes/sha3"; import { RAW_TRANSACTION_SALT, RAW_TRANSACTION_WITH_DATA_SALT } from "../../utils/const"; @@ -21,6 +23,8 @@ import { Serializable } from "../../bcs"; * - rawTransaction - The raw transaction data. * * @returns FeePayerRawTransaction | MultiAgentRawTransaction | RawTransaction + * @group Implementation + * @category Transactions */ export function deriveTransactionType(transaction: AnyRawTransaction): AnyRawTransactionInstance { if (transaction.feePayerAddress) { @@ -45,6 +49,8 @@ export function deriveTransactionType(transaction: AnyRawTransaction): AnyRawTra * @param domainSeparator - A domain separator that starts with 'APTOS::'. * * @returns The Uint8Array of the signing message. + * @group Implementation + * @category Transactions */ export function generateSigningMessage(bytes: Uint8Array, domainSeparator: string): Uint8Array { const hash = sha3Hash.create(); @@ -76,6 +82,8 @@ export function generateSigningMessage(bytes: Uint8Array, domainSeparator: strin * @param serializable - An object that has a BCS serialized form. * * @returns The Uint8Array of the signing message. + * @group Implementation + * @category Transactions */ export function generateSigningMessageForSerializable(serializable: Serializable): Uint8Array { return generateSigningMessage(serializable.bcsToBytes(), `APTOS::${serializable.constructor.name}`); @@ -88,6 +96,8 @@ export function generateSigningMessageForSerializable(serializable: Serializable * @param transaction - A transaction that is to be signed, which can include a fee payer address or secondary signer addresses. * * @returns The Uint8Array of the signing message. + * @group Implementation + * @category Transactions */ export function generateSigningMessageForTransaction(transaction: AnyRawTransaction): Uint8Array { const rawTxn = deriveTransactionType(transaction); diff --git a/src/transactions/transactionBuilder/transactionBuilder.ts b/src/transactions/transactionBuilder/transactionBuilder.ts index be4509b69..1bd05ee39 100644 --- a/src/transactions/transactionBuilder/transactionBuilder.ts +++ b/src/transactions/transactionBuilder/transactionBuilder.ts @@ -94,11 +94,21 @@ import { MultiAgentTransaction } from "../instances/multiAgentTransaction"; * * @returns TransactionPayload - The generated transaction payload, which can be of type TransactionPayloadScript, * TransactionPayloadMultiSig, or TransactionPayloadEntryFunction. + * @group Implementation + * @category Transactions */ export async function generateTransactionPayload(args: InputScriptData): Promise; +/** + * @group Implementation + * @category Transactions + */ export async function generateTransactionPayload( args: InputEntryFunctionDataWithRemoteABI, ): Promise; +/** + * @group Implementation + * @category Transactions + */ export async function generateTransactionPayload( args: InputMultiSigDataWithRemoteABI, ): Promise; @@ -112,6 +122,8 @@ export async function generateTransactionPayload( * @param args.data GenerateTransactionPayloadData * * @return TransactionPayload + * @group Implementation + * @category Transactions */ export async function generateTransactionPayload( args: InputGenerateTransactionPayloadDataWithRemoteABI, @@ -147,9 +159,19 @@ export async function generateTransactionPayload( * @param args.multisigAddress - (Optional) The address for a multisig transaction if applicable. * * @throws Error if the type argument count does not match the ABI or if the number of function arguments is incorrect. + * @group Implementation + * @category Transactions */ export function generateTransactionPayloadWithABI(args: InputEntryFunctionDataWithABI): TransactionPayloadEntryFunction; +/** + * @group Implementation + * @category Transactions + */ export function generateTransactionPayloadWithABI(args: InputMultiSigDataWithABI): TransactionPayloadMultiSig; +/** + * @group Implementation + * @category Transactions + */ export function generateTransactionPayloadWithABI( args: InputGenerateTransactionPayloadDataWithABI, ): AnyTransactionPayloadInstance { @@ -178,6 +200,8 @@ export function generateTransactionPayloadWithABI( * @param arg - The argument to be converted. * @param i - The index of the argument in the function call. * @param typeArguments - Additional type arguments that may be required for the conversion. + * @group Implementation + * @category Transactions */ // TODO: Fix JSDoc convertArgument(args.function, functionAbi, arg, i, typeArguments), @@ -221,6 +245,8 @@ export function generateTransactionPayloadWithABI( * @param args.abi - The ABI (Application Binary Interface) of the module. * * @returns The generated payload for the view function call. + * @group Implementation + * @category Transactions */ export async function generateViewFunctionPayload(args: InputViewFunctionDataWithRemoteABI): Promise { const { moduleAddress, moduleName, functionName } = getFunctionParts(args.function); @@ -252,6 +278,8 @@ export async function generateViewFunctionPayload(args: InputViewFunctionDataWit * * @throws Error if the type argument count does not match the ABI or if the function arguments * do not match the expected parameters defined in the ABI. + * @group Implementation + * @category Transactions */ export function generateViewFunctionPayloadWithABI(args: InputViewFunctionDataWithABI): EntryFunction { const functionAbi = args.abi; @@ -292,6 +320,8 @@ export function generateViewFunctionPayloadWithABI(args: InputViewFunctionDataWi * @param args.typeArguments - The type arguments that will be standardized. * @param args.functionArguments - The arguments for the function being called. * @returns A new instance of TransactionPayloadScript. + * @group Implementation + * @category Transactions */ function generateTransactionPayloadScript(args: InputScriptData) { return new TransactionPayloadScript( @@ -314,6 +344,8 @@ function generateTransactionPayloadScript(args: InputScriptData) { * @param args.feePayerAddress - The address of the fee payer for sponsored transactions. * * @returns RawTransaction - The generated raw transaction. + * @group Implementation + * @category Transactions */ export async function generateRawTransaction(args: { aptosConfig: AptosConfig; @@ -352,6 +384,8 @@ export async function generateRawTransaction(args: { /** * Check if is sponsored transaction to honor AIP-52 * {@link https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-52.md} + * @group Implementation + * @category Transactions */ if (feePayerAddress && AccountAddress.from(feePayerAddress).equals(AccountAddress.ZERO)) { // Handle sponsored transaction generation with the option that @@ -401,8 +435,14 @@ export async function generateRawTransaction(args: { * @param args.secondarySignerAddresses - Optional. An array of addresses for additional signers in a multi-signature transaction. * @param args.feePayerAddress - Optional. The address of the fee payer for sponsored transactions. * @returns An instance of a transaction, which may include secondary signer addresses and a fee payer address. + * @group Implementation + * @category Transactions */ export async function buildTransaction(args: InputGenerateSingleSignerRawTransactionArgs): Promise; +/** + * @group Implementation + * @category Transactions + */ export async function buildTransaction(args: InputGenerateMultiAgentRawTransactionArgs): Promise; /** @@ -426,6 +466,8 @@ export async function buildTransaction(args: InputGenerateMultiAgentRawTransacti * feePayerAddress?: AccountAddress * } * ``` + * @group Implementation + * @category Transactions */ export async function buildTransaction(args: InputGenerateRawTransactionArgs): Promise { const { aptosConfig, sender, payload, options, feePayerAddress } = args; @@ -465,6 +507,8 @@ export async function buildTransaction(args: InputGenerateRawTransactionArgs): P * @param args.options - Optional. Additional options for simulating the transaction. * * @returns A signed serialized transaction that can be simulated. + * @group Implementation + * @category Transactions */ export function generateSignedTransactionForSimulation(args: InputSimulateTransactionData): Uint8Array { const { signerPublicKey, transaction, secondarySignersPublicKeys, feePayerPublicKey } = args; @@ -548,7 +592,10 @@ export function generateSignedTransactionForSimulation(args: InputSimulateTransa } return new SignedTransaction(transaction.rawTransaction, transactionAuthenticator).bcsToBytes(); } - +/** + * @group Implementation + * @category Transactions + */ export function getAuthenticatorForSimulation(publicKey: PublicKey) { // Wrap the public key types below with AnyPublicKey as they are only support through single sender. // Learn more about AnyPublicKey here - https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-55.md @@ -606,6 +653,8 @@ export function getAuthenticatorForSimulation(publicKey: PublicKey) { * * @throws Error if the feePayerAuthenticator is not provided for a fee payer transaction. * @throws Error if additionalSignersAuthenticators are not provided for a multi-signer transaction. + * @group Implementation + * @category Transactions */ export function generateSignedTransaction(args: InputSubmitTransactionData): Uint8Array { const { transaction, feePayerAuthenticator, additionalSignersAuthenticators } = args; @@ -651,6 +700,8 @@ export function generateSignedTransaction(args: InputSubmitTransactionData): Uin /** * Hashes the set of values using a SHA-3 256 hash algorithm. * @param input - An array of UTF-8 strings or Uint8Array byte arrays to be hashed. + * @group Implementation + * @category Transactions */ export function hashValues(input: (Uint8Array | string)[]): Uint8Array { const hash = sha3Hash.create(); @@ -662,6 +713,8 @@ export function hashValues(input: (Uint8Array | string)[]): Uint8Array { /** * The domain separated prefix for hashing transactions + * @group Implementation + * @category Transactions */ const TRANSACTION_PREFIX = hashValues(["APTOS::Transaction"]); @@ -674,6 +727,8 @@ const TRANSACTION_PREFIX = hashValues(["APTOS::Transaction"]); * @param args.payload - The payload containing the transaction details. * @param args.sender - The address of the sender initiating the transaction. * @param args.sequenceNumber - The sequence number of the transaction for the sender. + * @group Implementation + * @category Transactions */ export function generateUserTransactionHash(args: InputSubmitTransactionData): string { const signedTransaction = generateSignedTransaction(args); @@ -694,6 +749,8 @@ export function generateUserTransactionHash(args: InputSubmitTransactionData): s * @param aptosConfig - Configuration settings for Aptos. * @param abi - An optional ABI to use if already available. * @param fetch - A function to fetch the ABI if it is not provided. + * @group Implementation + * @category Transactions */ async function fetchAbi({ key, diff --git a/src/transactions/typeTag/index.ts b/src/transactions/typeTag/index.ts index 91fc83068..a5e823d19 100644 --- a/src/transactions/typeTag/index.ts +++ b/src/transactions/typeTag/index.ts @@ -16,6 +16,8 @@ import { TypeTagVariants } from "../../types"; * to determine the specific type of the tag at runtime. * * @extends Serializable + * @group Implementation + * @category Transactions */ export abstract class TypeTag extends Serializable { abstract serialize(serializer: Serializer): void; @@ -25,6 +27,8 @@ export abstract class TypeTag extends Serializable { * This function allows you to reconstruct a StructTag object from its serialized form. * * @param deserializer - The deserializer instance used to read the serialized data. + * @group Implementation + * @category Transactions */ deserialize(deserializer: Deserializer): StructTag { const address = AccountAddress.deserialize(deserializer); @@ -73,6 +77,8 @@ export abstract class TypeTag extends Serializable { * Determines if the current instance is of type TypeTagBool. * * @returns {boolean} True if the instance is a TypeTagBool, otherwise false. + * @group Implementation + * @category Transactions */ isBool(): this is TypeTagBool { return this instanceof TypeTagBool; @@ -82,6 +88,8 @@ export abstract class TypeTag extends Serializable { * Determines if the current instance is of type TypeTagAddress. * * @returns {boolean} True if the instance is a TypeTagAddress, otherwise false. + * @group Implementation + * @category Transactions */ isAddress(): this is TypeTagAddress { return this instanceof TypeTagAddress; @@ -91,6 +99,8 @@ export abstract class TypeTag extends Serializable { * Determines if the current instance is of type TypeTagGeneric. * * @returns {boolean} Returns true if the instance is a TypeTagGeneric, otherwise false. + * @group Implementation + * @category Transactions */ isGeneric(): this is TypeTagGeneric { return this instanceof TypeTagGeneric; @@ -100,6 +110,8 @@ export abstract class TypeTag extends Serializable { * Determine if the current instance is a TypeTagSigner. * * @returns {boolean} Returns true if the instance is a TypeTagSigner, otherwise false. + * @group Implementation + * @category Transactions */ isSigner(): this is TypeTagSigner { return this instanceof TypeTagSigner; @@ -110,6 +122,8 @@ export abstract class TypeTag extends Serializable { * This can help determine the specific type of data structure being used. * * @returns {boolean} True if the instance is of type TypeTagVector, otherwise false. + * @group Implementation + * @category Transactions */ isVector(): this is TypeTagVector { return this instanceof TypeTagVector; @@ -119,6 +133,8 @@ export abstract class TypeTag extends Serializable { * Determines if the current instance is a structure type. * * @returns {boolean} True if the instance is of type TypeTagStruct, otherwise false. + * @group Implementation + * @category Transactions */ isStruct(): this is TypeTagStruct { return this instanceof TypeTagStruct; @@ -128,6 +144,8 @@ export abstract class TypeTag extends Serializable { * Determines if the current instance is of type `TypeTagU8`. * * @returns {boolean} Returns true if the instance is of type `TypeTagU8`, otherwise false. + * @group Implementation + * @category Transactions */ isU8(): this is TypeTagU8 { return this instanceof TypeTagU8; @@ -137,6 +155,8 @@ export abstract class TypeTag extends Serializable { * Checks if the current instance is of type TypeTagU16. * * @returns {boolean} True if the instance is TypeTagU16, otherwise false. + * @group Implementation + * @category Transactions */ isU16(): this is TypeTagU16 { return this instanceof TypeTagU16; @@ -146,6 +166,8 @@ export abstract class TypeTag extends Serializable { * Checks if the current instance is of type TypeTagU32. * * @returns {boolean} Returns true if the instance is TypeTagU32, otherwise false. + * @group Implementation + * @category Transactions */ isU32(): this is TypeTagU32 { return this instanceof TypeTagU32; @@ -155,6 +177,8 @@ export abstract class TypeTag extends Serializable { * Checks if the current instance is of type TypeTagU64. * * @returns {boolean} True if the instance is a TypeTagU64, otherwise false. + * @group Implementation + * @category Transactions */ isU64(): this is TypeTagU64 { return this instanceof TypeTagU64; @@ -164,6 +188,8 @@ export abstract class TypeTag extends Serializable { * Determines if the current instance is of the TypeTagU128 type. * * @returns {boolean} True if the instance is of TypeTagU128, otherwise false. + * @group Implementation + * @category Transactions */ isU128(): this is TypeTagU128 { return this instanceof TypeTagU128; @@ -173,6 +199,8 @@ export abstract class TypeTag extends Serializable { * Checks if the current instance is of type TypeTagU256. * * @returns {boolean} Returns true if the instance is of type TypeTagU256, otherwise false. + * @group Implementation + * @category Transactions */ isU256(): this is TypeTagU256 { return this instanceof TypeTagU256; @@ -200,12 +228,16 @@ export abstract class TypeTag extends Serializable { * type tag. * * @extends TypeTag + * @group Implementation + * @category Transactions */ export class TypeTagBool extends TypeTag { /** * Returns the string representation of the object. * * @returns {string} The string representation of the object. + * @group Implementation + * @category Transactions */ toString(): string { return "bool"; @@ -216,6 +248,8 @@ export class TypeTagBool extends TypeTag { * This function ensures that the address, module name, name, and type arguments are properly serialized. * * @param serializer - The serializer instance used to serialize the properties. + * @group Implementation + * @category Transactions */ serialize(serializer: Serializer): void { serializer.serializeU32AsUleb128(TypeTagVariants.Bool); @@ -225,6 +259,8 @@ export class TypeTagBool extends TypeTag { * Deserializes a StructTag and returns a new TypeTagStruct instance. * * @param _deserializer - The deserializer used to read the StructTag data. + * @group Implementation + * @category Transactions */ static load(_deserializer: Deserializer): TypeTagBool { return new TypeTagBool(); @@ -237,6 +273,8 @@ export class TypeTagBool extends TypeTag { * for serialization and deserialization specific to the u8 type. * * @extends TypeTag + * @group Implementation + * @category Transactions */ export class TypeTagU8 extends TypeTag { toString(): string { @@ -257,6 +295,8 @@ export class TypeTagU8 extends TypeTag { * This class extends the base TypeTag class and provides methods for serialization and deserialization. * * @extends TypeTag + * @group Implementation + * @category Transactions */ export class TypeTagU16 extends TypeTag { toString(): string { @@ -278,6 +318,8 @@ export class TypeTagU16 extends TypeTag { * and deserialization specific to the u32 type. * * @extends TypeTag + * @group Implementation + * @category Transactions */ export class TypeTagU32 extends TypeTag { toString(): string { @@ -298,6 +340,8 @@ export class TypeTagU32 extends TypeTag { * This class extends the base TypeTag class and provides methods for serialization and deserialization. * * @extends TypeTag + * @group Implementation + * @category Transactions */ export class TypeTagU64 extends TypeTag { toString(): string { @@ -318,6 +362,8 @@ export class TypeTagU64 extends TypeTag { * This class extends the base TypeTag class and provides methods for serialization and deserialization. * * @extends TypeTag + * @group Implementation + * @category Transactions */ export class TypeTagU128 extends TypeTag { toString(): string { @@ -338,6 +384,8 @@ export class TypeTagU128 extends TypeTag { * This class extends the base TypeTag class and provides methods for serialization and deserialization. * * @extends TypeTag + * @group Implementation + * @category Transactions */ export class TypeTagU256 extends TypeTag { toString(): string { @@ -359,6 +407,8 @@ export class TypeTagU256 extends TypeTag { * to serialize the address type and load it from a deserializer. * * @extends TypeTag + * @group Implementation + * @category Transactions */ export class TypeTagAddress extends TypeTag { toString(): string { @@ -380,6 +430,8 @@ export class TypeTagAddress extends TypeTag { * related to the signer type. * * @extends TypeTag + * @group Implementation + * @category Transactions */ export class TypeTagSigner extends TypeTag { toString(): string { @@ -401,6 +453,8 @@ export class TypeTagSigner extends TypeTag { * to serialize and deserialize type tag references. * * @extends TypeTag + * @group Implementation + * @category Transactions */ export class TypeTagReference extends TypeTag { toString(): `&${string}` { @@ -411,6 +465,8 @@ export class TypeTagReference extends TypeTag { * Initializes a new instance of the class with the specified parameters. * * @param value - The TypeTag to reference. + * @group Implementation + * @category Transactions */ constructor(public readonly value: TypeTag) { super(); @@ -431,6 +487,8 @@ export class TypeTagReference extends TypeTag { * Generics are not serialized into a real type, so they cannot be used as a type directly. * * @extends TypeTag + * @group Implementation + * @category Transactions */ export class TypeTagGeneric extends TypeTag { toString(): `T${number}` { @@ -459,6 +517,8 @@ export class TypeTagGeneric extends TypeTag { * deserialization, and string representation of the vector type tag. * * @extends TypeTag + * @group Implementation + * @category Transactions */ export class TypeTagVector extends TypeTag { toString(): `vector<${string}>` { @@ -473,6 +533,8 @@ export class TypeTagVector extends TypeTag { * Creates a new TypeTagVector instance with a TypeTagU8 type. * * @returns {TypeTagVector} A new TypeTagVector initialized with TypeTagU8. + * @group Implementation + * @category Transactions */ static u8(): TypeTagVector { return new TypeTagVector(new TypeTagU8()); @@ -495,6 +557,8 @@ export class TypeTagVector extends TypeTag { * module name, and type arguments, and provides methods for serialization and type checking. * * @param value - The StructTag instance containing the details of the structured type. + * @group Implementation + * @category Transactions */ export class TypeTagStruct extends TypeTag { toString(): `0x${string}::${string}::${string}` { @@ -530,6 +594,8 @@ export class TypeTagStruct extends TypeTag { * @param moduleName - The name of the module to compare against the type tag. * @param structName - The name of the struct to compare against the type tag. * @returns True if the address, module name, and struct name match the type tag; otherwise, false. + * @group Implementation + * @category Transactions */ isTypeTag(address: AccountAddress, moduleName: string, structName: string): boolean { return ( @@ -544,6 +610,8 @@ export class TypeTagStruct extends TypeTag { * This function can help ensure that the data being processed is in the correct format before further operations. * * @returns {boolean} Returns true if the value is a string, otherwise false. + * @group Implementation + * @category Transactions */ isString(): boolean { return this.isTypeTag(AccountAddress.ONE, "string", "String"); @@ -553,6 +621,8 @@ export class TypeTagStruct extends TypeTag { * Checks if the specified account address is of type "option". * * @returns {boolean} Returns true if the account address is an option type, otherwise false. + * @group Implementation + * @category Transactions */ isOption(): boolean { return this.isTypeTag(AccountAddress.ONE, "option", "Option"); @@ -563,6 +633,8 @@ export class TypeTagStruct extends TypeTag { * This function helps determine if a value can be treated as an object type in the context of the SDK. * * @returns {boolean} Returns true if the value is an object, otherwise false. + * @group Implementation + * @category Transactions */ isObject(): boolean { return this.isTypeTag(AccountAddress.ONE, "object", "Object"); @@ -578,6 +650,8 @@ export class TypeTagStruct extends TypeTag { * @property {Identifier} moduleName - The name of the module that contains the struct. * @property {Identifier} name - The name of the struct. * @property {Array} typeArgs - An array of type arguments associated with the struct. + * @group Implementation + * @category Transactions */ export class StructTag extends Serializable { public readonly address: AccountAddress; @@ -616,6 +690,8 @@ export class StructTag extends Serializable { * Retrieves the StructTag for the AptosCoin, which represents the Aptos Coin in the Aptos blockchain. * * @returns {StructTag} The StructTag for the AptosCoin. + * @group Implementation + * @category Transactions */ export function aptosCoinStructTag(): StructTag { return new StructTag(AccountAddress.ONE, new Identifier("aptos_coin"), new Identifier("AptosCoin"), []); @@ -625,6 +701,8 @@ export function aptosCoinStructTag(): StructTag { * Returns a new StructTag representing a string type. * * @returns {StructTag} A StructTag for the string type. + * @group Implementation + * @category Transactions */ export function stringStructTag(): StructTag { return new StructTag(AccountAddress.ONE, new Identifier("string"), new Identifier("String"), []); @@ -635,6 +713,8 @@ export function stringStructTag(): StructTag { * This can help in defining a specific instance of an Option type in your application. * * @param typeArg - The type tag that specifies the type of the value contained in the Option. + * @group Implementation + * @category Transactions */ export function optionStructTag(typeArg: TypeTag): StructTag { return new StructTag(AccountAddress.ONE, new Identifier("option"), new Identifier("Option"), [typeArg]); @@ -645,6 +725,8 @@ export function optionStructTag(typeArg: TypeTag): StructTag { * This function helps in defining a structured representation of an Object with a specific type. * * @param typeArg - The type tag that specifies the type of the Object. + * @group Implementation + * @category Transactions */ export function objectStructTag(typeArg: TypeTag): StructTag { return new StructTag(AccountAddress.ONE, new Identifier("object"), new Identifier("Object"), [typeArg]); diff --git a/src/transactions/typeTag/parser.ts b/src/transactions/typeTag/parser.ts index 25cb18b2d..88db750af 100644 --- a/src/transactions/typeTag/parser.ts +++ b/src/transactions/typeTag/parser.ts @@ -24,6 +24,8 @@ import { Identifier } from "../instances/identifier"; /** * Determines if the provided string is a valid Move identifier, which can only contain alphanumeric characters and underscores. * @param str - The string to validate as a Move identifier. + * @group Implementation + * @category Transactions */ function isValidIdentifier(str: string) { return !!str.match(/^[_a-zA-Z0-9]+$/); @@ -32,6 +34,8 @@ function isValidIdentifier(str: string) { /** * Determines if the provided character is a whitespace character. This function only works for single characters. * @param char - The character to check for whitespace. + * @group Implementation + * @category Transactions */ function isValidWhitespaceCharacter(char: string) { return !!char.match(/\s/); @@ -40,6 +44,8 @@ function isValidWhitespaceCharacter(char: string) { /** * Determines if a given string represents a generic type from the ABI, specifically in the format T0, T1, etc. * @param str - The string to evaluate for generic type format. + * @group Implementation + * @category Transactions */ function isGeneric(str: string) { return !!str.match(/^T[0-9]+$/); @@ -48,6 +54,8 @@ function isGeneric(str: string) { /** * Determines if the provided string is a reference type, which is indicated by starting with an ampersand (&). * @param str - The string to evaluate for reference type. + * @group Implementation + * @category Transactions */ function isRef(str: string) { return !!str.match(/^&.+$/); @@ -57,6 +65,8 @@ function isRef(str: string) { * Determines if the provided string represents a primitive type. * @param str - The string to evaluate as a potential primitive type. * @returns A boolean indicating whether the string is a primitive type. + * @group Implementation + * @category Transactions */ function isPrimitive(str: string) { switch (str) { @@ -81,6 +91,8 @@ function isPrimitive(str: string) { * @param tagStr - The string from which to consume whitespace. * @param pos - The position in the string to start consuming whitespace from. * @returns The new position in the string after consuming whitespace. + * @group Implementation + * @category Transactions */ function consumeWhitespace(tagStr: string, pos: number) { let i = pos; @@ -97,6 +109,8 @@ function consumeWhitespace(tagStr: string, pos: number) { /** * State for TypeTag parsing, maintained on a stack to track the current parsing state. + * @group Implementation + * @category Transactions */ type TypeTagState = { savedExpectedTypes: number; @@ -106,6 +120,8 @@ type TypeTagState = { /** * Error types related to parsing type tags, indicating various issues encountered during the parsing process. + * @group Implementation + * @category Transactions */ export enum TypeTagParserErrorType { InvalidTypeTag = "unknown type", @@ -131,6 +147,8 @@ export enum TypeTagParserErrorType { * * @param typeTagStr - The type tag string that failed to be parsed. * @param invalidReason - The reason why the type tag string is considered invalid. + * @group Implementation + * @category Transactions */ export class TypeTagParserError extends Error { /** @@ -139,6 +157,8 @@ export class TypeTagParserError extends Error { * * @param typeTagStr - The string representation of the type tag that failed to parse. * @param invalidReason - The reason why the type tag is considered invalid. + * @group Implementation + * @category Transactions */ constructor(typeTagStr: string, invalidReason: TypeTagParserErrorType) { super(`Failed to parse typeTag '${typeTagStr}', ${invalidReason}`); @@ -167,6 +187,8 @@ export class TypeTagParserError extends Error { * @param options.allowGenerics - A flag indicating whether to allow generics in the parsing process. * @returns The parsed type tag representation. * @throws TypeTagParserError if the type string is malformed or does not conform to expected formats. + * @group Implementation + * @category Transactions */ export function parseTypeTag(typeStr: string, options?: { allowGenerics?: boolean }) { const allowGenerics = options?.allowGenerics ?? false; @@ -301,6 +323,8 @@ export function parseTypeTag(typeStr: string, options?: { allowGenerics?: boolea * @param str - The string representation of the type tag to parse. * @param types - An array of TypeTag instances that represent internal types associated with the type tag. * @param allowGenerics - A boolean indicating whether generics are allowed in the parsing of the type tag. + * @group Implementation + * @category Transactions */ function parseTypeTagInner(str: string, types: Array, allowGenerics: boolean): TypeTag { const trimmedStr = str.trim(); diff --git a/src/transactions/types.ts b/src/transactions/types.ts index 5fdd85b41..478c3feea 100644 --- a/src/transactions/types.ts +++ b/src/transactions/types.ts @@ -24,6 +24,8 @@ import { Serialized } from "../bcs"; /** * Entry function arguments for building a raw transaction using remote ABI, supporting various data types including primitives and arrays. + * @group Implementation + * @category Transactions */ export type SimpleEntryFunctionArgumentTypes = | boolean @@ -38,6 +40,8 @@ export type SimpleEntryFunctionArgumentTypes = /** * Entry function arguments for building a raw transaction using BCS serialized arguments. + * @group Implementation + * @category Transactions */ export type EntryFunctionArgumentTypes = | Bool @@ -55,6 +59,8 @@ export type EntryFunctionArgumentTypes = /** * Script function arguments for building raw transactions using BCS serialized arguments. + * @group Implementation + * @category Transactions */ export type ScriptFunctionArgumentTypes = | Bool @@ -88,11 +94,15 @@ export type ScriptFunctionArgumentTypes = * - vector * - address::module::struct * - address::module::struct + * @group Implementation + * @category Transactions */ export type TypeArgument = TypeTag | string; /** * Holds all return interfaces for generating different transaction types. + * @group Implementation + * @category Transactions */ export type AnyRawTransactionInstance = RawTransaction | MultiAgentRawTransaction | FeePayerRawTransaction; @@ -100,6 +110,8 @@ export type AnyRawTransactionInstance = RawTransaction | MultiAgentRawTransactio /** * Optional options to set when generating a transaction, including a maximum gas amount. + * @group Implementation + * @category Transactions */ export type InputGenerateTransactionOptions = { maxGasAmount?: number; @@ -111,6 +123,8 @@ export type InputGenerateTransactionOptions = { /** * The transaction payload type generated from the `generateTransactionPayload()` function, which can be an entry function, * script, or multi-signature payload. + * @group Implementation + * @category Transactions */ export type AnyTransactionPayloadInstance = | TransactionPayloadEntryFunction @@ -119,12 +133,16 @@ export type AnyTransactionPayloadInstance = /** * The data needed to generate a transaction payload for Entry Function, Script, or Multi Sig types. + * @group Implementation + * @category Transactions */ export type InputGenerateTransactionPayloadData = InputEntryFunctionData | InputScriptData | InputMultiSigData; /** * The payload for generating a transaction, which can be either script data, entry function data with remote ABI, or * multi-signature data. + * @group Implementation + * @category Transactions */ export type InputGenerateTransactionPayloadDataWithRemoteABI = | InputScriptData @@ -133,6 +151,8 @@ export type InputGenerateTransactionPayloadDataWithRemoteABI = /** * The data needed to generate an Entry Function payload. + * @group Implementation + * @category Transactions */ export type InputEntryFunctionData = { function: MoveFunctionId; @@ -143,11 +163,15 @@ export type InputEntryFunctionData = { /** * The payload for generating a transaction, which can be either an entry function or a multi-signature transaction. + * @group Implementation + * @category Transactions */ export type InputGenerateTransactionPayloadDataWithABI = InputEntryFunctionDataWithABI | InputMultiSigDataWithABI; /** * The input data for an entry function, including its associated ABI. + * @group Implementation + * @category Transactions */ export type InputEntryFunctionDataWithABI = Omit & { abi: EntryFunctionABI; @@ -155,6 +179,8 @@ export type InputEntryFunctionDataWithABI = Omit /** * The data needed to generate a Multi Sig payload, including the multisig address. + * @group Implementation + * @category Transactions */ export type InputMultiSigDataWithABI = { multisigAddress: AccountAddressInput; @@ -162,10 +188,14 @@ export type InputMultiSigDataWithABI = { /** * Combines input function data with Aptos configuration for remote ABI interactions. + * @group Implementation + * @category Transactions */ export type InputEntryFunctionDataWithRemoteABI = InputEntryFunctionData & { aptosConfig: AptosConfig }; /** * The data needed to generate a Multi Sig payload + * @group Implementation + * @category Transactions */ export type InputMultiSigData = { multisigAddress: AccountAddressInput; @@ -173,6 +203,8 @@ export type InputMultiSigData = { /** * The data needed to generate a Multi Sig payload, including the multisig address. + * @group Implementation + * @category Transactions */ export type InputMultiSigDataWithRemoteABI = { multisigAddress: AccountAddressInput; @@ -180,6 +212,8 @@ export type InputMultiSigDataWithRemoteABI = { /** * The data needed to generate a Script payload. + * @group Implementation + * @category Transactions */ export type InputScriptData = { bytecode: HexInput; @@ -189,6 +223,8 @@ export type InputScriptData = { /** * The data needed to generate a View Function payload. + * @group Implementation + * @category Transactions */ export type InputViewFunctionData = { function: MoveFunctionId; @@ -199,6 +235,8 @@ export type InputViewFunctionData = { /** * The data needed to generate a View Function payload in JSON format. + * @group Implementation + * @category Transactions */ export type InputViewFunctionJsonData = { function: MoveFunctionId; @@ -208,6 +246,8 @@ export type InputViewFunctionJsonData = { /** * The payload sent to the fullnode for a JSON view request. + * @group Implementation + * @category Transactions */ export type ViewFunctionJsonPayload = { function: MoveFunctionId; @@ -217,16 +257,22 @@ export type ViewFunctionJsonPayload = { /** * Data required to create a view function payload and retrieve the remote ABI, including Aptos configuration. + * @group Implementation + * @category Transactions */ export type InputViewFunctionDataWithRemoteABI = InputViewFunctionData & { aptosConfig: AptosConfig }; /** * Data needed to generate a view function, including the fetched ABI. + * @group Implementation + * @category Transactions */ export type InputViewFunctionDataWithABI = InputViewFunctionData & { abi: ViewFunctionABI }; /** * Data needed for a generic function ABI, applicable to both view and entry functions. + * @group Implementation + * @category Transactions */ export type FunctionABI = { typeParameters: Array; @@ -235,6 +281,8 @@ export type FunctionABI = { /** * Interface for an Entry function's ABI, enabling type checking and input conversion for ABI-based transaction submissions. + * @group Implementation + * @category Transactions */ export type EntryFunctionABI = FunctionABI & { signers?: number; @@ -242,6 +290,8 @@ export type EntryFunctionABI = FunctionABI & { /** * Interface for a view function's ABI, providing type checking and input conversion for ABI-based transaction submissions. + * @group Implementation + * @category Transactions */ export type ViewFunctionABI = FunctionABI & { returnTypes: Array; @@ -255,6 +305,8 @@ export type ViewFunctionABI = FunctionABI & { * @param payload - The transaction payload. * @param options - Optional transaction generation options. * @param feePayerAddress - Optional address of the fee payer. + * @group Implementation + * @category Transactions */ export interface InputGenerateSingleSignerRawTransactionArgs { aptosConfig: AptosConfig; @@ -273,6 +325,8 @@ export interface InputGenerateSingleSignerRawTransactionArgs { * @param secondarySignerAddresses - List of secondary signer addresses. * @param options - Optional settings for transaction generation. * @param feePayerAddress - Optional address of the fee payer. + * @group Implementation + * @category Transactions */ export interface InputGenerateMultiAgentRawTransactionArgs { aptosConfig: AptosConfig; @@ -285,6 +339,8 @@ export interface InputGenerateMultiAgentRawTransactionArgs { /** * A unified type for generating various transaction types. + * @group Implementation + * @category Transactions */ export type InputGenerateRawTransactionArgs = | InputGenerateSingleSignerRawTransactionArgs @@ -292,6 +348,8 @@ export type InputGenerateRawTransactionArgs = /** * Unified type that holds all the return interfaces when generating different transaction types + * @group Implementation + * @category Transactions */ export type AnyRawTransaction = SimpleTransaction | MultiAgentTransaction; @@ -299,22 +357,32 @@ export type AnyRawTransaction = SimpleTransaction | MultiAgentTransaction; /** * The data required to simulate a transaction, typically generated by `generateTransaction()`. + * @group Implementation + * @category Transactions */ export type InputSimulateTransactionData = { /** * The transaction to simulate, probably generated by `generateTransaction()` + * @group Implementation + * @category Transactions */ transaction: AnyRawTransaction; /** * For a single signer transaction + * @group Implementation + * @category Transactions */ signerPublicKey: PublicKey; /** * For a fee payer or multi-agent transaction that requires additional signers in + * @group Implementation + * @category Transactions */ secondarySignersPublicKeys?: Array; /** * For a fee payer transaction (aka Sponsored Transaction) + * @group Implementation + * @category Transactions */ feePayerPublicKey?: PublicKey; options?: InputSimulateTransactionOptions; @@ -322,6 +390,8 @@ export type InputSimulateTransactionData = { /** * Options for simulating a transaction input, including whether to estimate the gas unit price. + * @group Implementation + * @category Transactions */ export type InputSimulateTransactionOptions = { estimateGasUnitPrice?: boolean; @@ -339,6 +409,8 @@ export type InputSimulateTransactionOptions = { * @param options - Optional transaction options. * @param withFeePayer - Indicates if the fee payer is included. * @param secondarySignerAddresses - Addresses for any secondary signers (not used in single signer transactions). + * @group Implementation + * @category Transactions */ export interface InputGenerateSingleSignerRawTransactionData { sender: AccountAddressInput; @@ -356,6 +428,8 @@ export interface InputGenerateSingleSignerRawTransactionData { * @param secondarySignerAddresses - An array of addresses for secondary signers. * @param options - Optional transaction options. * @param withFeePayer - Indicates if a fee payer is included. + * @group Implementation + * @category Transactions */ export interface InputGenerateMultiAgentRawTransactionData { sender: AccountAddressInput; @@ -367,6 +441,8 @@ export interface InputGenerateMultiAgentRawTransactionData { /** * Unified type holding user data input interfaces for generating various transaction types. + * @group Implementation + * @category Transactions */ export type InputGenerateTransactionData = | InputGenerateSingleSignerRawTransactionData @@ -379,6 +455,8 @@ export type InputGenerateTransactionData = * @param senderAuthenticator - The authenticator for the sender's account. * @param feePayerAuthenticator - Optional authenticator for the fee payer's account. * @param additionalSignersAuthenticators - Optional array of authenticators for additional signers. + * @group Implementation + * @category Transactions */ export interface InputSubmitTransactionData { transaction: AnyRawTransaction; diff --git a/src/types/index.ts b/src/types/index.ts index 5d19efd13..a8b00dfa6 100644 --- a/src/types/index.ts +++ b/src/types/index.ts @@ -8,18 +8,26 @@ export * from "./indexer"; /** * Different MIME types used for data interchange in transactions and responses. + * @group Implementation + * @category Types */ export enum MimeType { /** * JSON representation, used for transaction submission and accept type JSON output + * @group Implementation + * @category Types */ JSON = "application/json", /** * BCS representation, used for accept type BCS output + * @group Implementation + * @category Types */ BCS = "application/x-bcs", /** * BCS representation, used for transaction submission in BCS input + * @group Implementation + * @category Types */ BCS_SIGNED_TRANSACTION = "application/x.aptos.signed_transaction+bcs", BCS_VIEW_FUNCTION = "application/x.aptos.view_function+bcs", @@ -27,12 +35,16 @@ export enum MimeType { /** * Hexadecimal data input for functions, supporting both string and Uint8Array formats. + * @group Implementation + * @category Types */ export type HexInput = string | Uint8Array; /** * Variants of type tags used in the system, encompassing various data types and structures. * {@link https://github.com/aptos-labs/aptos-core/blob/main/third_party/move/move-core/types/src/language_storage.rs#L27} + * @group Implementation + * @category Types */ export enum TypeTagVariants { Bool = 0, @@ -53,6 +65,8 @@ export enum TypeTagVariants { /** * Variants of script transaction arguments used in Rust, encompassing various data types for transaction processing. * {@link https://github.com/aptos-labs/aptos-core/blob/main/third_party/move/move-core/types/src/transaction_argument.rs#L11} + * @group Implementation + * @category Types */ export enum ScriptTransactionArgumentVariants { U8 = 0, @@ -70,6 +84,8 @@ export enum ScriptTransactionArgumentVariants { /** * The payload for various transaction types in the system. * {@link https://github.com/aptos-labs/aptos-core/blob/main/types/src/transaction/mod.rs#L478} + * @group Implementation + * @category Types */ export enum TransactionPayloadVariants { Script = 0, @@ -80,6 +96,8 @@ export enum TransactionPayloadVariants { /** * Variants of transactions used in the system. * {@link https://github.com/aptos-labs/aptos-core/blob/main/types/src/transaction/mod.rs#L440} + * @group Implementation + * @category Types */ export enum TransactionVariants { MultiAgentTransaction = 0, @@ -89,6 +107,8 @@ export enum TransactionVariants { /** * Variants of transaction authenticators used in the system. * {@link https://github.com/aptos-labs/aptos-core/blob/main/types/src/transaction/authenticator.rs#L44} + * @group Implementation + * @category Types */ export enum TransactionAuthenticatorVariant { Ed25519 = 0, @@ -101,6 +121,8 @@ export enum TransactionAuthenticatorVariant { /** * Variants of account authenticators used in transactions. * {@link https://github.com/aptos-labs/aptos-core/blob/main/types/src/transaction/authenticator.rs#L414} + * @group Implementation + * @category Types */ export enum AccountAuthenticatorVariant { Ed25519 = 0, @@ -111,6 +133,8 @@ export enum AccountAuthenticatorVariant { /** * Variants of public keys used in cryptographic operations. + * @group Implementation + * @category Types */ export enum AnyPublicKeyVariant { Ed25519 = 0, @@ -121,6 +145,8 @@ export enum AnyPublicKeyVariant { /** * Variants of signature types used for cryptographic operations. + * @group Implementation + * @category Types */ export enum AnySignatureVariant { Ed25519 = 0, @@ -130,6 +156,8 @@ export enum AnySignatureVariant { /** * Variants of ephemeral public keys used in cryptographic operations. + * @group Implementation + * @category Types */ export enum EphemeralPublicKeyVariant { Ed25519 = 0, @@ -137,6 +165,8 @@ export enum EphemeralPublicKeyVariant { /** * Variants of ephemeral signatures used for secure communication. + * @group Implementation + * @category Types */ export enum EphemeralSignatureVariant { Ed25519 = 0, @@ -144,6 +174,8 @@ export enum EphemeralSignatureVariant { /** * Variants of ephemeral certificates used in secure transactions. + * @group Implementation + * @category Types */ export enum EphemeralCertificateVariant { ZkProof = 0, @@ -151,6 +183,8 @@ export enum EphemeralCertificateVariant { /** * Variants of zero-knowledge proofs used in cryptographic operations. + * @group Implementation + * @category Types */ export enum ZkpVariant { Groth16 = 0, @@ -158,41 +192,57 @@ export enum ZkpVariant { /** * BCS types + * @group Implementation + * @category Types */ export type Uint8 = number; /** * A 16-bit unsigned integer. + * @group Implementation + * @category Types */ export type Uint16 = number; /** * A 32-bit unsigned integer. + * @group Implementation + * @category Types */ export type Uint32 = number; /** * A 64-bit unsigned integer value. + * @group Implementation + * @category Types */ export type Uint64 = bigint; /** * A 128-bit unsigned integer used for precise arithmetic operations. + * @group Implementation + * @category Types */ export type Uint128 = bigint; /** * A 256-bit unsigned integer used for precise numerical calculations. + * @group Implementation + * @category Types */ export type Uint256 = bigint; /** * A number or a bigint value. + * @group Implementation + * @category Types */ export type AnyNumber = number | bigint; /** * Configuration options for initializing the SDK, allowing customization of its behavior and interaction with the Aptos network. + * @group Implementation + * @category Types */ export type AptosSettings = { readonly network?: Network; @@ -222,6 +272,8 @@ export type AptosSettings = { * Defines the parameters for paginating query results, including the starting position and maximum number of items to return. * @param offset Specifies the starting position of the query result. Default is 0. * @param limit Specifies the maximum number of items to return. Default is 25. + * @group Implementation + * @category Types */ export interface PaginationArgs { offset?: AnyNumber; @@ -232,15 +284,23 @@ export interface PaginationArgs { * Represents the arguments for specifying a token standard. * * @param tokenStandard - Optional standard of the token. + * @group Implementation + * @category Types */ export interface TokenStandardArg { tokenStandard?: TokenStandard; } - +/** + * @group Implementation + * @category Types + */ export interface OrderByArg { orderBy?: OrderBy; } - +/** + * @group Implementation + * @category Types + */ export interface WhereArg { where?: T; } @@ -251,6 +311,8 @@ export interface WhereArg { /** * A configuration object for requests to the server, including API key, extra headers, and cookie handling options. + * @group Implementation + * @category Types */ export type ClientConfig = ClientHeadersType & { WITH_CREDENTIALS?: boolean; @@ -259,16 +321,22 @@ export type ClientConfig = ClientHeadersType & { /** * A configuration object for a Fullnode, allowing for the inclusion of extra headers in requests. + * @group Implementation + * @category Types */ export type FullNodeConfig = ClientHeadersType; /** * An Indexer configuration object for sending requests with additional headers. + * @group Implementation + * @category Types */ export type IndexerConfig = ClientHeadersType; /** * A configuration object for a faucet, including optional authentication and headers for requests. + * @group Implementation + * @category Types */ export type FaucetConfig = ClientHeadersType & { AUTH_TOKEN?: string; @@ -276,6 +344,8 @@ export type FaucetConfig = ClientHeadersType & { /** * General type definition for client headers. + * @group Implementation + * @category Types */ export type ClientHeadersType = { HEADERS?: Record; @@ -286,6 +356,8 @@ export type ClientHeadersType = { * * @param Req - The type of the request payload. * @param Res - The type of the response payload. + * @group Implementation + * @category Types */ export interface ClientRequest { url: string; @@ -297,7 +369,10 @@ export interface ClientRequest { overrides?: ClientConfig & FullNodeConfig & IndexerConfig & FaucetConfig; headers?: Record; } - +/** + * @group Implementation + * @category Types + */ export interface ClientResponse { status: number; statusText: string; @@ -307,7 +382,10 @@ export interface ClientResponse { response?: any; headers?: any; } - +/** + * @group Implementation + * @category Types + */ export interface Client { /** * Sends a request to the specified URL with the given options. @@ -322,6 +400,8 @@ export interface Client { * @param requestOptions.params - Optional parameters to include in the request. * @param requestOptions.originMethod - An optional method to specify the origin of the request. * @param requestOptions.overrides - Optional configuration overrides for the request. + * @group Implementation + * @category Types */ provider(requestOptions: ClientRequest): Promise>; } @@ -338,6 +418,8 @@ export interface Client { * @param params (optional) - query params to add to the request * @param originMethod (optional) - the local method the request came from * @param overrides (optional) - a `ClientConfig` object type to override request data + * @group Implementation + * @category Types */ export type AptosRequest = { url: string; @@ -353,6 +435,8 @@ export type AptosRequest = { /** * The ledger version of transactions, defaulting to the latest version if not specified. + * @group Implementation + * @category Types */ export type LedgerVersionArg = { ledgerVersion?: AnyNumber; @@ -360,26 +444,39 @@ export type LedgerVersionArg = { /** * RESPONSE TYPES + * @group Implementation + * @category Types */ /** * The output of the estimate gas API, including the deprioritized estimate for the gas unit price. + * @group Implementation + * @category Types */ export type GasEstimation = { /** * The deprioritized estimate for the gas unit price + * @group Implementation + * @category Types */ deprioritized_gas_estimate?: number; /** * The current estimate for the gas unit price + * @group Implementation + * @category Types */ gas_estimate: number; /** * The prioritized estimate for the gas unit price + * @group Implementation + * @category Types */ prioritized_gas_estimate?: number; }; - +/** + * @group Implementation + * @category Types + */ export type MoveResource = { type: MoveStructId; data: T; @@ -387,6 +484,8 @@ export type MoveResource = { /** * The data associated with an account, including its sequence number. + * @group Implementation + * @category Types */ export type AccountData = { sequence_number: string; @@ -395,6 +494,8 @@ export type AccountData = { /** * A Move module containing an address. + * @group Implementation + * @category Types */ export type MoveModuleBytecode = { bytecode: string; @@ -407,6 +508,8 @@ export type MoveModuleBytecode = { /** * Different types of transaction responses that can occur in the system. + * @group Implementation + * @category Types */ export enum TransactionResponseType { Pending = "pending_transaction", @@ -420,11 +523,15 @@ export enum TransactionResponseType { /** * The response for a transaction, which can be either pending or committed. + * @group Implementation + * @category Types */ export type TransactionResponse = PendingTransactionResponse | CommittedTransactionResponse; /** * The response for a committed transaction, which can be one of several transaction types. + * @group Implementation + * @category Types */ export type CommittedTransactionResponse = | UserTransactionResponse @@ -439,6 +546,8 @@ export type CommittedTransactionResponse = * * @param response - The transaction response to evaluate. * @returns A boolean indicating whether the transaction is pending. + * @group Implementation + * @category Types */ export function isPendingTransactionResponse(response: TransactionResponse): response is PendingTransactionResponse { return response.type === TransactionResponseType.Pending; @@ -449,6 +558,8 @@ export function isPendingTransactionResponse(response: TransactionResponse): res * * @param response - The transaction response to evaluate. * @returns A boolean indicating whether the transaction is of type User. + * @group Implementation + * @category Types */ export function isUserTransactionResponse(response: TransactionResponse): response is UserTransactionResponse { return response.type === TransactionResponseType.User; @@ -459,6 +570,8 @@ export function isUserTransactionResponse(response: TransactionResponse): respon * * @param response - The transaction response to evaluate. * @returns A boolean indicating whether the transaction is a Genesis transaction. + * @group Implementation + * @category Types */ export function isGenesisTransactionResponse(response: TransactionResponse): response is GenesisTransactionResponse { return response.type === TransactionResponseType.Genesis; @@ -469,6 +582,8 @@ export function isGenesisTransactionResponse(response: TransactionResponse): res * * @param response - The transaction response to evaluate. * @returns A boolean indicating whether the response is a BlockMetadata transaction. + * @group Implementation + * @category Types */ export function isBlockMetadataTransactionResponse( response: TransactionResponse, @@ -481,6 +596,8 @@ export function isBlockMetadataTransactionResponse( * * @param response - The transaction response to evaluate. * @returns A boolean indicating whether the transaction response is of type StateCheckpoint. + * @group Implementation + * @category Types */ export function isStateCheckpointTransactionResponse( response: TransactionResponse, @@ -493,6 +610,8 @@ export function isStateCheckpointTransactionResponse( * * @param response - The transaction response to evaluate. * @returns A boolean indicating whether the transaction response is a Validator type. + * @group Implementation + * @category Types */ export function isValidatorTransactionResponse( response: TransactionResponse, @@ -505,6 +624,8 @@ export function isValidatorTransactionResponse( * * @param response - The transaction response to evaluate. * @returns A boolean indicating whether the response is a Block Epilogue transaction. + * @group Implementation + * @category Types */ export function isBlockEpilogueTransactionResponse( response: TransactionResponse, @@ -514,6 +635,8 @@ export function isBlockEpilogueTransactionResponse( /** * The response for a pending transaction, indicating that the transaction is still being processed. + * @group Implementation + * @category Types */ export type PendingTransactionResponse = { type: TransactionResponseType.Pending; @@ -529,6 +652,8 @@ export type PendingTransactionResponse = { /** * The response structure for a user transaction. + * @group Implementation + * @category Types */ export type UserTransactionResponse = { type: TransactionResponseType.User; @@ -540,15 +665,21 @@ export type UserTransactionResponse = { gas_used: string; /** * Whether the transaction was successful + * @group Implementation + * @category Types */ success: boolean; /** * The VM status of the transaction, can tell useful information in a failure + * @group Implementation + * @category Types */ vm_status: string; accumulator_root_hash: string; /** * Final state of resources changed by the transaction + * @group Implementation + * @category Types */ changes: Array; sender: string; @@ -560,6 +691,8 @@ export type UserTransactionResponse = { signature?: TransactionSignature; /** * Events generated by the transaction + * @group Implementation + * @category Types */ events: Array; timestamp: string; @@ -567,6 +700,8 @@ export type UserTransactionResponse = { /** * The response for a genesis transaction, indicating the type of transaction. + * @group Implementation + * @category Types */ export type GenesisTransactionResponse = { type: TransactionResponseType.Genesis; @@ -578,26 +713,36 @@ export type GenesisTransactionResponse = { gas_used: string; /** * Whether the transaction was successful + * @group Implementation + * @category Types */ success: boolean; /** * The VM status of the transaction, can tell useful information in a failure + * @group Implementation + * @category Types */ vm_status: string; accumulator_root_hash: string; /** * Final state of resources changed by the transaction + * @group Implementation + * @category Types */ changes: Array; payload: GenesisPayload; /** * Events emitted during genesis + * @group Implementation + * @category Types */ events: Array; }; /** * The structure representing a blockchain block with its height. + * @group Implementation + * @category Types */ export type BlockMetadataTransactionResponse = { type: TransactionResponseType.BlockMetadata; @@ -609,15 +754,21 @@ export type BlockMetadataTransactionResponse = { gas_used: string; /** * Whether the transaction was successful + * @group Implementation + * @category Types */ success: boolean; /** * The VM status of the transaction, can tell useful information in a failure + * @group Implementation + * @category Types */ vm_status: string; accumulator_root_hash: string; /** * Final state of resources changed by the transaction + * @group Implementation + * @category Types */ changes: Array; id: string; @@ -625,15 +776,21 @@ export type BlockMetadataTransactionResponse = { round: string; /** * The events emitted at the block creation + * @group Implementation + * @category Types */ events: Array; /** * Previous block votes + * @group Implementation + * @category Types */ previous_block_votes_bitvec: Array; proposer: string; /** * The indices of the proposers who failed to propose + * @group Implementation + * @category Types */ failed_proposer_indices: Array; timestamp: string; @@ -641,6 +798,8 @@ export type BlockMetadataTransactionResponse = { /** * The response for a state checkpoint transaction, indicating the type of transaction. + * @group Implementation + * @category Types */ export type StateCheckpointTransactionResponse = { type: TransactionResponseType.StateCheckpoint; @@ -652,15 +811,21 @@ export type StateCheckpointTransactionResponse = { gas_used: string; /** * Whether the transaction was successful + * @group Implementation + * @category Types */ success: boolean; /** * The VM status of the transaction, can tell useful information in a failure + * @group Implementation + * @category Types */ vm_status: string; accumulator_root_hash: string; /** * Final state of resources changed by the transaction + * @group Implementation + * @category Types */ changes: Array; timestamp: string; @@ -668,6 +833,8 @@ export type StateCheckpointTransactionResponse = { /** * The response for a validator transaction, indicating the type of transaction. + * @group Implementation + * @category Types */ export type ValidatorTransactionResponse = { type: TransactionResponseType.Validator; @@ -679,19 +846,27 @@ export type ValidatorTransactionResponse = { gas_used: string; /** * Whether the transaction was successful + * @group Implementation + * @category Types */ success: boolean; /** * The VM status of the transaction, can tell useful information in a failure + * @group Implementation + * @category Types */ vm_status: string; accumulator_root_hash: string; /** * Final state of resources changed by the transaction + * @group Implementation + * @category Types */ changes: Array; /** * The events emitted by the validator transaction + * @group Implementation + * @category Types */ events: Array; timestamp: string; @@ -699,6 +874,8 @@ export type ValidatorTransactionResponse = { /** * Describes the gas state of the block, indicating whether the block gas limit has been reached. + * @group Implementation + * @category Types */ export type BlockEndInfo = { block_gas_limit_reached: boolean; @@ -709,6 +886,8 @@ export type BlockEndInfo = { /** * A transaction executed at the end of a block that tracks data from the entire block. + * @group Implementation + * @category Types */ export type BlockEpilogueTransactionResponse = { type: TransactionResponseType.BlockEpilogue; @@ -720,15 +899,21 @@ export type BlockEpilogueTransactionResponse = { gas_used: string; /** * Whether the transaction was successful + * @group Implementation + * @category Types */ success: boolean; /** * The VM status of the transaction, can tell useful information in a failure + * @group Implementation + * @category Types */ vm_status: string; accumulator_root_hash: string; /** * Final state of resources changed by the transaction + * @group Implementation + * @category Types */ changes: Array; timestamp: string; @@ -737,10 +922,14 @@ export type BlockEpilogueTransactionResponse = { /** * WRITESET CHANGE TYPES + * @group Implementation + * @category Types */ /** * A union type that encompasses both script and direct write sets for data operations. + * @group Implementation + * @category Types */ export type WriteSetChange = | WriteSetChangeDeleteModule @@ -752,12 +941,16 @@ export type WriteSetChange = /** * The structure for a module deletion change in a write set. + * @group Implementation + * @category Types */ export type WriteSetChangeDeleteModule = { type: string; address: string; /** * State key hash + * @group Implementation + * @category Types */ state_key_hash: string; module: MoveModuleId; @@ -765,6 +958,8 @@ export type WriteSetChangeDeleteModule = { /** * The payload for a resource deletion in a write set change. + * @group Implementation + * @category Types */ export type WriteSetChangeDeleteResource = { type: string; @@ -775,6 +970,8 @@ export type WriteSetChangeDeleteResource = { /** * The payload for a write set change that deletes a table item. + * @group Implementation + * @category Types */ export type WriteSetChangeDeleteTableItem = { type: string; @@ -786,6 +983,8 @@ export type WriteSetChangeDeleteTableItem = { /** * The structure for a write module change in a write set. + * @group Implementation + * @category Types */ export type WriteSetChangeWriteModule = { type: string; @@ -796,6 +995,8 @@ export type WriteSetChangeWriteModule = { /** * The resource associated with a write set change, identified by its type. + * @group Implementation + * @category Types */ export type WriteSetChangeWriteResource = { type: string; @@ -806,6 +1007,8 @@ export type WriteSetChangeWriteResource = { /** * The structure for a write operation on a table in a write set change. + * @group Implementation + * @category Types */ export type WriteSetChangeWriteTableItem = { type: string; @@ -818,79 +1021,111 @@ export type WriteSetChangeWriteTableItem = { /** * The decoded data for a table, including its key in JSON format. + * @group Implementation + * @category Types */ export type DecodedTableData = { /** * Key of table in JSON + * @group Implementation + * @category Types */ key: any; /** * Type of key + * @group Implementation + * @category Types */ key_type: string; /** * Value of table in JSON + * @group Implementation + * @category Types */ value: any; /** * Type of value + * @group Implementation + * @category Types */ value_type: string; }; /** * Data for a deleted table entry. + * @group Implementation + * @category Types */ export type DeletedTableData = { /** * Deleted key + * @group Implementation + * @category Types */ key: any; /** * Deleted key type + * @group Implementation + * @category Types */ key_type: string; }; /** * The payload for a transaction response, which can be an entry function, script, or multisig payload. + * @group Implementation + * @category Types */ export type TransactionPayloadResponse = EntryFunctionPayloadResponse | ScriptPayloadResponse | MultisigPayloadResponse; /** * The response payload for an entry function, containing the type of the entry. + * @group Implementation + * @category Types */ export type EntryFunctionPayloadResponse = { type: string; function: MoveFunctionId; /** * Type arguments of the function + * @group Implementation + * @category Types */ type_arguments: Array; /** * Arguments of the function + * @group Implementation + * @category Types */ arguments: Array; }; /** * The payload for a script response, containing the type of the script. + * @group Implementation + * @category Types */ export type ScriptPayloadResponse = { type: string; code: MoveScriptBytecode; /** * Type arguments of the function + * @group Implementation + * @category Types */ type_arguments: Array; /** * Arguments of the function + * @group Implementation + * @category Types */ arguments: Array; }; /** * The response payload for a multisig transaction, containing the type of the transaction. + * @group Implementation + * @category Types */ export type MultisigPayloadResponse = { type: string; @@ -900,6 +1135,8 @@ export type MultisigPayloadResponse = { /** * The payload for the genesis block containing the type of the payload. + * @group Implementation + * @category Types */ export type GenesisPayload = { type: string; @@ -908,6 +1145,8 @@ export type GenesisPayload = { /** * The bytecode for a Move script. + * @group Implementation + * @category Types */ export type MoveScriptBytecode = { bytecode: string; @@ -916,6 +1155,8 @@ export type MoveScriptBytecode = { /** * JSON representations of transaction signatures returned from the node API. + * @group Implementation + * @category Types */ export type TransactionSignature = | TransactionEd25519Signature @@ -931,6 +1172,8 @@ export type TransactionSignature = * * @param signature - The transaction signature to be checked. * @returns A boolean indicating whether the signature is an Ed25519 signature. + * @group Implementation + * @category Types */ export function isEd25519Signature(signature: TransactionSignature): signature is TransactionFeePayerSignature { return "signature" in signature && signature.signature === "ed25519_signature"; @@ -941,6 +1184,8 @@ export function isEd25519Signature(signature: TransactionSignature): signature i * * @param signature - The transaction signature to validate. * @returns A boolean indicating whether the signature is a secp256k1 ECDSA signature. + * @group Implementation + * @category Types */ export function isSecp256k1Signature(signature: TransactionSignature): signature is TransactionFeePayerSignature { return "signature" in signature && signature.signature === "secp256k1_ecdsa_signature"; @@ -951,6 +1196,8 @@ export function isSecp256k1Signature(signature: TransactionSignature): signature * * @param signature - The transaction signature to evaluate. * @returns A boolean indicating whether the signature is a multi-agent signature. + * @group Implementation + * @category Types */ export function isMultiAgentSignature(signature: TransactionSignature): signature is TransactionMultiAgentSignature { return signature.type === "multi_agent_signature"; @@ -961,6 +1208,8 @@ export function isMultiAgentSignature(signature: TransactionSignature): signatur * * @param signature - The transaction signature to evaluate. * @returns A boolean indicating whether the signature is a fee payer signature. + * @group Implementation + * @category Types */ export function isFeePayerSignature(signature: TransactionSignature): signature is TransactionFeePayerSignature { return signature.type === "fee_payer_signature"; @@ -971,6 +1220,8 @@ export function isFeePayerSignature(signature: TransactionSignature): signature * * @param signature - The transaction signature to check. * @returns A boolean indicating whether the signature is a multi-ed25519 signature. + * @group Implementation + * @category Types */ export function isMultiEd25519Signature( signature: TransactionSignature, @@ -980,6 +1231,8 @@ export function isMultiEd25519Signature( /** * The signature for a transaction using the Ed25519 algorithm. + * @group Implementation + * @category Types */ export type TransactionEd25519Signature = { type: string; @@ -989,6 +1242,8 @@ export type TransactionEd25519Signature = { /** * The structure for a Secp256k1 signature in a transaction. + * @group Implementation + * @category Types */ export type TransactionSecp256k1Signature = { type: string; @@ -998,19 +1253,27 @@ export type TransactionSecp256k1Signature = { /** * The structure for a multi-signature transaction using Ed25519. + * @group Implementation + * @category Types */ export type TransactionMultiEd25519Signature = { type: "multi_ed25519_signature"; /** * The public keys for the Ed25519 signature + * @group Implementation + * @category Types */ public_keys: Array; /** * Signature associated with the public keys in the same order + * @group Implementation + * @category Types */ signatures: Array; /** * The number of signatures required for a successful transaction + * @group Implementation + * @category Types */ threshold: number; bitmap: string; @@ -1018,32 +1281,44 @@ export type TransactionMultiEd25519Signature = { /** * The structure for a multi-agent signature in a transaction. + * @group Implementation + * @category Types */ export type TransactionMultiAgentSignature = { type: "multi_agent_signature"; sender: AccountSignature; /** * The other involved parties' addresses + * @group Implementation + * @category Types */ secondary_signer_addresses: Array; /** * The associated signatures, in the same order as the secondary addresses + * @group Implementation + * @category Types */ secondary_signers: Array; }; /** * The signature of the fee payer in a transaction. + * @group Implementation + * @category Types */ export type TransactionFeePayerSignature = { type: "fee_payer_signature"; sender: AccountSignature; /** * The other involved parties' addresses + * @group Implementation + * @category Types */ secondary_signer_addresses: Array; /** * The associated signatures, in the same order as the secondary addresses + * @group Implementation + * @category Types */ secondary_signers: Array; fee_payer_address: string; @@ -1052,16 +1327,24 @@ export type TransactionFeePayerSignature = { /** * The union of all single account signatures, including Ed25519, Secp256k1, and MultiEd25519 signatures. + * @group Implementation + * @category Types */ export type AccountSignature = | TransactionEd25519Signature | TransactionSecp256k1Signature | TransactionMultiEd25519Signature; +/** + * @group Implementation + * @category Types + */ export type WriteSet = ScriptWriteSet | DirectWriteSet; /** * The set of properties for writing scripts, including the type of script. + * @group Implementation + * @category Types */ export type ScriptWriteSet = { type: string; @@ -1071,6 +1354,8 @@ export type ScriptWriteSet = { /** * The set of direct write operations, identified by a type string. + * @group Implementation + * @category Types */ export type DirectWriteSet = { type: string; @@ -1080,87 +1365,124 @@ export type DirectWriteSet = { /** * The structure for an event's unique identifier, including its creation number. + * @group Implementation + * @category Types */ /** * The structure for an event, identified by a unique GUID. + * @group Implementation + * @category Types */ export type EventGuid = { creation_number: string; account_address: string; }; - +/** + * @group Implementation + * @category Types + */ export type Event = { guid: EventGuid; sequence_number: string; type: string; /** * The JSON representation of the event + * @group Implementation + * @category Types */ data: any; }; /** * A number representing a Move uint8 type. + * @group Implementation + * @category Types */ export type MoveUint8Type = number; /** * A 16-bit unsigned integer used in the Move programming language. + * @group Implementation + * @category Types */ export type MoveUint16Type = number; /** * A 32-bit unsigned integer type used in Move programming. + * @group Implementation + * @category Types */ export type MoveUint32Type = number; /** * A string representation of a 64-bit unsigned integer used in Move programming. + * @group Implementation + * @category Types */ export type MoveUint64Type = string; /** * A string representing a 128-bit unsigned integer in the Move programming language. + * @group Implementation + * @category Types */ export type MoveUint128Type = string; /** * A string representation of a 256-bit unsigned integer used in Move programming. + * @group Implementation + * @category Types */ export type MoveUint256Type = string; /** * A string representing a Move address. + * @group Implementation + * @category Types */ export type MoveAddressType = string; /** * The type for identifying objects to be moved within the system. + * @group Implementation + * @category Types */ export type MoveObjectType = string; /** * The type for move options, which can be a MoveType, null, or undefined. + * @group Implementation + * @category Types */ export type MoveOptionType = MoveType | null | undefined; /** * A structure representing a move with a name. + * @group Implementation + * @category Types */ export type MoveStructId = `${string}::${string}::${string}`; /** * The move function containing its name. Same as MoveStructId since it reads weird to take a StructId for a Function. + * @group Implementation + * @category Types */ export type MoveFunctionId = MoveStructId; // TODO: Add support for looking up ABI to add proper typing +/** + * @group Implementation + * @category Types + */ export type MoveStructType = {}; /** * A union type that encompasses various data types used in Move, including primitive types, address types, object types, and * arrays of MoveType. + * @group Implementation + * @category Types */ export type MoveType = | boolean @@ -1198,6 +1520,8 @@ export type MoveType = * `Vector -> Array` * * `Option -> MoveValue | null | undefined` + * @group Implementation + * @category Types */ export type MoveValue = | boolean @@ -1217,11 +1541,15 @@ export type MoveValue = /** * A string representation of a Move module, formatted as `module_name::function_name`. * Module names are case-sensitive. + * @group Implementation + * @category Types */ export type MoveModuleId = `${string}::${string}`; /** * Specifies the visibility levels for move functions, controlling access permissions. + * @group Implementation + * @category Types */ export enum MoveFunctionVisibility { PRIVATE = "private", @@ -1231,6 +1559,8 @@ export enum MoveFunctionVisibility { /** * Abilities related to moving items within the system. + * @group Implementation + * @category Types */ export enum MoveAbility { STORE = "store", @@ -1241,6 +1571,8 @@ export enum MoveAbility { /** * Move abilities associated with the generic type parameter of a function. + * @group Implementation + * @category Types */ export type MoveFunctionGenericTypeParam = { constraints: Array; @@ -1248,6 +1580,8 @@ export type MoveFunctionGenericTypeParam = { /** * A field in a Move struct, identified by its name. + * @group Implementation + * @category Types */ export type MoveStructField = { name: string; @@ -1256,83 +1590,117 @@ export type MoveStructField = { /** * A Move module + * @group Implementation + * @category Types */ export type MoveModule = { address: string; name: string; /** * Friends of the module + * @group Implementation + * @category Types */ friends: Array; /** * Public functions of the module + * @group Implementation + * @category Types */ exposed_functions: Array; /** * Structs of the module + * @group Implementation + * @category Types */ structs: Array; }; /** * A move struct + * @group Implementation + * @category Types */ export type MoveStruct = { name: string; /** * Whether the struct is a native struct of Move + * @group Implementation + * @category Types */ is_native: boolean; /** * Whether the struct is a module event (aka v2 event). This will be false for v1 * events because the value is derived from the #[event] attribute on the struct in * the Move source code. This attribute is only relevant for v2 events. + * @group Implementation + * @category Types */ is_event: boolean; /** * Abilities associated with the struct + * @group Implementation + * @category Types */ abilities: Array; /** * Generic types associated with the struct + * @group Implementation + * @category Types */ generic_type_params: Array; /** * Fields associated with the struct + * @group Implementation + * @category Types */ fields: Array; }; /** * Move function + * @group Implementation + * @category Types */ export type MoveFunction = { name: string; visibility: MoveFunctionVisibility; /** * Whether the function can be called as an entry function directly in a transaction + * @group Implementation + * @category Types */ is_entry: boolean; /** * Whether the function is a view function or not + * @group Implementation + * @category Types */ is_view: boolean; /** * Generic type params associated with the Move function + * @group Implementation + * @category Types */ generic_type_params: Array; /** * Parameters associated with the move function + * @group Implementation + * @category Types */ params: Array; /** * Return type of the function + * @group Implementation + * @category Types */ return: Array; }; /** * Roles that can be assigned within the system, indicating different levels of access and functionality. + * @group Implementation + * @category Types */ export enum RoleType { VALIDATOR = "validator", @@ -1341,10 +1709,14 @@ export enum RoleType { /** * Information about the current blockchain ledger, including its chain ID. + * @group Implementation + * @category Types */ export type LedgerInfo = { /** * Chain ID of the current chain + * @group Implementation + * @category Types */ chain_id: number; epoch: string; @@ -1357,12 +1729,16 @@ export type LedgerInfo = { /** * Git hash of the build of the API endpoint. Can be used to determine the exact * software version used by the API endpoint. + * @group Implementation + * @category Types */ git_hash?: string; }; /** * A Block type + * @group Implementation + * @category Types */ export type Block = { block_height: string; @@ -1372,6 +1748,8 @@ export type Block = { last_version: string; /** * The transactions in the block in sequential order + * @group Implementation + * @category Types */ transactions?: Array; }; @@ -1380,35 +1758,49 @@ export type Block = { /** * The request payload for the GetTableItem API. + * @group Implementation + * @category Types */ export type TableItemRequest = { key_type: MoveValue; value_type: MoveValue; /** * The value of the table item's key + * @group Implementation + * @category Types */ key: any; }; /** * A list of supported Authentication Key schemes in Aptos, consisting of combinations of signing schemes and derive schemes. + * @group Implementation + * @category Types */ export type AuthenticationKeyScheme = SigningScheme | DeriveScheme; /** * Different schemes for signing keys used in cryptographic operations. + * @group Implementation + * @category Types */ export enum SigningScheme { /** * For Ed25519PublicKey + * @group Implementation + * @category Types */ Ed25519 = 0, /** * For MultiEd25519PublicKey + * @group Implementation + * @category Types */ MultiEd25519 = 1, /** * For SingleKey ecdsa + * @group Implementation + * @category Types */ SingleKey = 2, @@ -1417,46 +1809,66 @@ export enum SigningScheme { /** * Specifies the signing schemes available for cryptographic operations. + * @group Implementation + * @category Types */ export enum SigningSchemeInput { /** * For Ed25519PublicKey + * @group Implementation + * @category Types */ Ed25519 = 0, /** * For Secp256k1Ecdsa + * @group Implementation + * @category Types */ Secp256k1Ecdsa = 2, } /** * Specifies the schemes for deriving account addresses from various data sources. + * @group Implementation + * @category Types */ export enum DeriveScheme { /** * Derives an address using an AUID, used for objects + * @group Implementation + * @category Types */ DeriveAuid = 251, /** * Derives an address from another object address + * @group Implementation + * @category Types */ DeriveObjectAddressFromObject = 252, /** * Derives an address from a GUID, used for objects + * @group Implementation + * @category Types */ DeriveObjectAddressFromGuid = 253, /** * Derives an address from seed bytes, used for named objects + * @group Implementation + * @category Types */ DeriveObjectAddressFromSeed = 254, /** * Derives an address from seed bytes, used for resource accounts + * @group Implementation + * @category Types */ DeriveResourceAccountAddress = 255, } /** * Options for configuring the behavior of the waitForTransaction() function. + * @group Implementation + * @category Types */ export type WaitForTransactionOptions = { timeoutSecs?: number; @@ -1467,6 +1879,8 @@ export type WaitForTransactionOptions = { /** * Input type to generate an account using the Ed25519 signing scheme. + * @group Implementation + * @category Types */ export type GenerateAccountWithEd25519 = { scheme: SigningSchemeInput.Ed25519; @@ -1475,10 +1889,15 @@ export type GenerateAccountWithEd25519 = { /** * Input type to generate an account with a Single Signer using Secp256k1. + * @group Implementation + * @category Types */ export type GenerateAccountWithSingleSignerSecp256k1Key = { scheme: SigningSchemeInput.Secp256k1Ecdsa; legacy?: false; }; - +/** + * @group Implementation + * @category Types + */ export type GenerateAccount = GenerateAccountWithEd25519 | GenerateAccountWithSingleSignerSecp256k1Key; diff --git a/src/types/indexer.ts b/src/types/indexer.ts index 67a9d87c1..75cefc469 100644 --- a/src/types/indexer.ts +++ b/src/types/indexer.ts @@ -9,6 +9,8 @@ * * These types are used as the return type when making the actual request (usually * under the /internal/ folder) + * @group Implementation + * @category Types */ import { @@ -43,120 +45,166 @@ import { * * These types are used as the return type when calling a sdk api function * that calls the function that queries the server (usually under the /api/ folder) + * @group Implementation + * @category Types */ export type GetObjectDataQueryResponse = GetObjectDataQuery["current_objects"]; /** * The response structure for querying tokens owned by an account. + * @group Implementation + * @category Types */ export type GetAccountOwnedTokensQueryResponse = GetAccountOwnedTokensQuery["current_token_ownerships_v2"]; /** * The response containing the current token ownerships for an account from a specific collection. + * @group Implementation + * @category Types */ export type GetAccountOwnedTokensFromCollectionResponse = GetAccountOwnedTokensFromCollectionQuery["current_token_ownerships_v2"]; /** * The response structure for retrieving account collections associated with owned tokens. + * @group Implementation + * @category Types */ export type GetAccountCollectionsWithOwnedTokenResponse = GetAccountCollectionsWithOwnedTokensQuery["current_collection_ownership_v2_view"]; /** * The current balances of fungible assets for an account. + * @group Implementation + * @category Types */ export type GetAccountCoinsDataResponse = GetAccountCoinsDataQuery["current_fungible_asset_balances"]; /** * The response structure for retrieving user transactions from the top of the blockchain. + * @group Implementation + * @category Types */ export type GetChainTopUserTransactionsResponse = GetChainTopUserTransactionsQuery["user_transactions"]; /** * The response containing the events from the GetEventsQuery. + * @group Implementation + * @category Types */ export type GetEventsResponse = GetEventsQuery["events"]; /** * The number of active delegators per pool in response to a query. + * @group Implementation + * @category Types */ export type GetNumberOfDelegatorsResponse = GetNumberOfDelegatorsQuery["num_active_delegator_per_pool"]; /** * The response containing the delegated staking activities from the query. + * @group Implementation + * @category Types */ export type GetDelegatedStakingActivitiesResponse = GetDelegatedStakingActivitiesQuery["delegated_staking_activities"]; /** * The response structure for retrieving data from the current collections. + * @group Implementation + * @category Types */ export type GetCollectionDataResponse = GetCollectionDataQuery["current_collections_v2"][0]; /** * The response structure for retrieving token data, containing the current token information. + * @group Implementation + * @category Types */ export type GetTokenDataResponse = GetTokenDataQuery["current_token_datas_v2"][0]; /** * The status of the processor as returned by the GetProcessorStatusQuery. + * @group Implementation + * @category Types */ export type GetProcessorStatusResponse = GetProcessorStatusQuery["processor_status"]; /** * The response containing metadata for a fungible asset. + * @group Implementation + * @category Types */ export type GetFungibleAssetMetadataResponse = GetFungibleAssetMetadataQuery["fungible_asset_metadata"]; /** * The response containing the activities related to fungible assets. + * @group Implementation + * @category Types */ export type GetFungibleAssetActivitiesResponse = GetFungibleAssetActivitiesQuery["fungible_asset_activities"]; /** * The current balances of fungible assets for a specific query. + * @group Implementation + * @category Types */ export type GetCurrentFungibleAssetBalancesResponse = GetCurrentFungibleAssetBalancesQuery["current_fungible_asset_balances"]; /** * The response structure for retrieving token activity data. + * @group Implementation + * @category Types */ export type GetTokenActivityResponse = GetTokenActivityQuery["token_activities_v2"]; /** * The response structure for retrieving the current token ownership details. + * @group Implementation + * @category Types */ export type GetCurrentTokenOwnershipResponse = GetCurrentTokenOwnershipQuery["current_token_ownerships_v2"][0]; /** * The response containing the current token ownerships for a user. + * @group Implementation + * @category Types */ export type GetOwnedTokensResponse = GetCurrentTokenOwnershipQuery["current_token_ownerships_v2"]; /** * The response structure for retrieving items from a table. + * @group Implementation + * @category Types */ export type GetTableItemsDataResponse = GetTableItemsDataQuery["table_items"]; /** * The metadata for table items retrieved from a query. + * @group Implementation + * @category Types */ export type GetTableItemsMetadataResponse = GetTableItemsMetadataQuery["table_metadatas"]; /** * The response containing the current Aptos names from the GetNamesQuery. + * @group Implementation + * @category Types */ export type GetANSNameResponse = GetNamesQuery["current_aptos_names"]; /** * A generic type that being passed by each function and holds an * array of properties we can sort the query by + * @group Implementation + * @category Types */ export type OrderBy = Array<{ [K in keyof T]?: OrderByValue }>; /** * Specifies the order direction for sorting, including options for handling null values. + * @group Implementation + * @category Types */ export type OrderByValue = | "asc" @@ -168,11 +216,15 @@ export type OrderByValue = /** * The token standard to query for, which can be either version "v1" or "v2". + * @group Implementation + * @category Types */ export type TokenStandard = "v1" | "v2"; /** * The GraphQL query to pass into the `queryIndexer` function. + * @group Implementation + * @category Types */ export type GraphqlQuery = { query: string; diff --git a/src/types/keyless.ts b/src/types/keyless.ts index 8fea27df0..b35ab3bbb 100644 --- a/src/types/keyless.ts +++ b/src/types/keyless.ts @@ -1,5 +1,7 @@ /** * The payload for a prover request, containing a Base64-encoded JWT. + * @group Implementation + * @category Types */ export type ProverRequest = { jwt_b64: string; @@ -13,6 +15,8 @@ export type ProverRequest = { /** * The response from the prover containing the proof data. + * @group Implementation + * @category Types */ export type ProverResponse = { proof: { a: string; b: string; c: string }; @@ -22,6 +26,8 @@ export type ProverResponse = { /** * The request payload for fetching data, containing a base64 encoded JWT. + * @group Implementation + * @category Types */ export type PepperFetchRequest = { jwt_b64: number; @@ -34,11 +40,15 @@ export type PepperFetchRequest = { /** * The response object containing the fetched pepper string. + * @group Implementation + * @category Types */ export type PepperFetchResponse = { pepper: string; address: string }; /** * The response for keyless configuration containing the maximum committed EPK bytes. + * @group Implementation + * @category Types */ export type KeylessConfigurationResponse = { max_commited_epk_bytes: number; @@ -53,6 +63,8 @@ export type KeylessConfigurationResponse = { /** * The response containing the Groth16 verification key, including the alpha_g1 component. + * @group Implementation + * @category Types */ export type Groth16VerificationKeyResponse = { alpha_g1: string; diff --git a/src/utils/apiEndpoints.ts b/src/utils/apiEndpoints.ts index 6e5ec2b2a..1a20ab404 100644 --- a/src/utils/apiEndpoints.ts +++ b/src/utils/apiEndpoints.ts @@ -1,6 +1,10 @@ // Copyright © Aptos Foundation // SPDX-License-Identifier: Apache-2.0 +/** + * @group Implementation + * @category Network + */ export const NetworkToIndexerAPI: Record = { mainnet: "https://api.mainnet.aptoslabs.com/v1/graphql", testnet: "https://api.testnet.aptoslabs.com/v1/graphql", @@ -8,6 +12,10 @@ export const NetworkToIndexerAPI: Record = { local: "http://127.0.0.1:8090/v1/graphql", }; +/** + * @group Implementation + * @category Network + */ export const NetworkToNodeAPI: Record = { mainnet: "https://api.mainnet.aptoslabs.com/v1", testnet: "https://api.testnet.aptoslabs.com/v1", @@ -15,6 +23,10 @@ export const NetworkToNodeAPI: Record = { local: "http://127.0.0.1:8080/v1", }; +/** + * @group Implementation + * @category Network + */ export const NetworkToFaucetAPI: Record = { mainnet: "https://faucet.mainnet.aptoslabs.com", testnet: "https://faucet.testnet.aptoslabs.com", @@ -22,6 +34,10 @@ export const NetworkToFaucetAPI: Record = { local: "http://127.0.0.1:8081", }; +/** + * @group Implementation + * @category Network + */ export const NetworkToPepperAPI: Record = { mainnet: "https://api.mainnet.aptoslabs.com/keyless/pepper/v0", testnet: "https://api.testnet.aptoslabs.com/keyless/pepper/v0", @@ -30,6 +46,10 @@ export const NetworkToPepperAPI: Record = { local: "https://api.devnet.aptoslabs.com/keyless/pepper/v0", }; +/** + * @group Implementation + * @category Network + */ export const NetworkToProverAPI: Record = { mainnet: "https://api.mainnet.aptoslabs.com/keyless/prover/v0", testnet: "https://api.testnet.aptoslabs.com/keyless/prover/v0", @@ -40,6 +60,8 @@ export const NetworkToProverAPI: Record = { /** * Different network environments for connecting to services, ranging from production to development setups. + * @group Implementation + * @category Network */ export enum Network { MAINNET = "mainnet", @@ -49,12 +71,20 @@ export enum Network { CUSTOM = "custom", } +/** + * @group Implementation + * @category Network + */ export const NetworkToChainId: Record = { mainnet: 1, testnet: 2, local: 4, }; +/** + * @group Implementation + * @category Network + */ export const NetworkToNetworkName: Record = { mainnet: Network.MAINNET, testnet: Network.TESTNET, diff --git a/src/utils/const.ts b/src/utils/const.ts index 05ae5c2a6..d7b7b5d0e 100644 --- a/src/utils/const.ts +++ b/src/utils/const.ts @@ -3,6 +3,8 @@ /** * Types of API endpoints used for routing requests in the Aptos network. + * @group Implementation + * @category Utils */ export enum AptosApiType { FULLNODE = "Fullnode", @@ -19,6 +21,8 @@ export enum AptosApiType { * * Note that max gas amount varies based on the transaction. A larger transaction will go over this * default gas amount, and the value will need to be changed for the specific transaction. + * @group Implementation + * @category Utils */ export const DEFAULT_MAX_GAS_AMOUNT = 200000; @@ -29,6 +33,8 @@ export const DEFAULT_MAX_GAS_AMOUNT = 200000; * * Note that the transaction expiration time varies based on network connection and network load. It may need to be * increased for the transaction to be processed. + * @group Implementation + * @category Utils */ export const DEFAULT_TXN_EXP_SEC_FROM_NOW = 20; @@ -37,21 +43,38 @@ export const DEFAULT_TXN_EXP_SEC_FROM_NOW = 20; * * This time is the amount of time that the SDK will wait for a transaction to be processed when waiting for * the results of the transaction. It may take longer based on network connection and network load. + * @group Implementation + * @category Utils */ export const DEFAULT_TXN_TIMEOUT_SEC = 20; /** * The default gas currency for the network. + * @group Implementation + * @category Utils */ export const APTOS_COIN = "0x1::aptos_coin::AptosCoin"; +/** + * @group Implementation + * @category Utils + */ export const APTOS_FA = "0x000000000000000000000000000000000000000000000000000000000000000a"; - +/** + * @group Implementation + * @category Utils + */ export const RAW_TRANSACTION_SALT = "APTOS::RawTransaction"; +/** + * @group Implementation + * @category Utils + */ export const RAW_TRANSACTION_WITH_DATA_SALT = "APTOS::RawTransactionWithData"; /** * Supported processor types for the indexer API, sourced from the processor_status table in the indexer database. * {@link https://cloud.hasura.io/public/graphiql?endpoint=https://api.mainnet.aptoslabs.com/v1/graphql} + * @group Implementation + * @category Utils */ export enum ProcessorType { ACCOUNT_TRANSACTION_PROCESSOR = "account_transactions_processor", diff --git a/src/utils/helpers.ts b/src/utils/helpers.ts index cb0960980..3d72ea62b 100644 --- a/src/utils/helpers.ts +++ b/src/utils/helpers.ts @@ -9,13 +9,18 @@ import { MoveStructId } from "../types"; * This function can be used to introduce delays in asynchronous operations. * * @param timeMs - The time in milliseconds to sleep. + * @group Implementation + * @category Utils */ export async function sleep(timeMs: number): Promise { return new Promise((resolve) => { setTimeout(resolve, timeMs); }); } - +/** + * @group Implementation + * @category Utils + */ export const nowInSeconds = () => Math.floor(Date.now() / 1000); /** @@ -23,6 +28,8 @@ export const nowInSeconds = () => Math.floor(Date.now() / 1000); * This function is useful for normalizing timestamps to hourly intervals. * * @param timestampInSeconds - The timestamp in seconds to be floored. + * @group Implementation + * @category Utils */ export function floorToWholeHour(timestampInSeconds: number): number { const date = new Date(timestampInSeconds * 1000); @@ -39,6 +46,8 @@ export function floorToWholeHour(timestampInSeconds: number): number { * * @param base64Url - The base64 URL-encoded string to decode. * @returns The decoded string. + * @group Implementation + * @category Utils */ export function base64UrlDecode(base64Url: string): string { // Replace base64url-specific characters @@ -59,6 +68,8 @@ export function base64UrlDecode(base64Url: string): string { * @param value The value in human-readable format * @param decimal The token decimal * @returns The value in the smallest units + * @group Implementation + * @category Utils */ export const convertAmountFromHumanReadableToOnChain = (value: number, decimal: number) => value * 10 ** decimal; @@ -72,6 +83,8 @@ export const convertAmountFromHumanReadableToOnChain = (value: number, decimal: * @param value The value in human-readable format * @param decimal The token decimal * @returns The value in the smallest units + * @group Implementation + * @category Utils */ export const convertAmountFromOnChainToHumanReadable = (value: number, decimal: number) => value / 10 ** decimal; @@ -82,6 +95,8 @@ export const convertAmountFromOnChainToHumanReadable = (value: number, decimal: * * @param hex The hex string to convert (e.g. `0x6170746f735f636f696e`) * @returns The ascii string + * @group Implementation + * @category Utils */ const hexToAscii = (hex: string) => { let str = ""; @@ -105,6 +120,8 @@ const hexToAscii = (hex: string) => { * * @param structObj The struct with account_address, module_name, and struct_name properties * @returns The MoveStructId + * @group Implementation + * @category Utils */ export const parseEncodedStruct = (structObj: { account_address: string; @@ -126,6 +143,8 @@ export const parseEncodedStruct = (structObj: { * * @param structObj The object to check * @returns Whether the object is an encoded struct type + * @group Implementation + * @category Utils */ export const isEncodedStruct = ( structObj: any, diff --git a/src/utils/memoize.ts b/src/utils/memoize.ts index 887142ac4..a0c8babd0 100644 --- a/src/utils/memoize.ts +++ b/src/utils/memoize.ts @@ -4,6 +4,8 @@ /** * The global cache Map shared across all functions. Must keep care to ensure that the * cache keys are unique across all functions. + * @group Implementation + * @category Utils */ const cache = new Map(); @@ -16,6 +18,8 @@ const cache = new Map(); * @param key The cache key used to store the result. * @param ttlMs The time-to-live in milliseconds for cached data. * @returns The cached or latest result. + * @group Implementation + * @category Utils */ export function memoizeAsync( func: (...args: any[]) => Promise, @@ -48,6 +52,8 @@ export function memoizeAsync( * @param func - The function whose result will be cached. * @param ttlMs - The time-to-live in milliseconds for cached data. * @returns A memoized version of the provided function that returns the cached result if available and within TTL. + * @group Implementation + * @category Utils */ export function memoize(func: (...args: any[]) => T, key: string, ttlMs?: number): (...args: any[]) => T { return (...args: any[]) => { diff --git a/src/utils/normalizeBundle.ts b/src/utils/normalizeBundle.ts index 36a83f074..7ec11bc6f 100644 --- a/src/utils/normalizeBundle.ts +++ b/src/utils/normalizeBundle.ts @@ -2,13 +2,18 @@ // SPDX-License-Identifier: Apache-2.0 import { Deserializer, Serializable } from "../bcs"; - +/** + * @group Implementation + * @category Utils + */ export type DeserializableClass = { /** * Deserializes a serialized object using the provided deserializer. * This function allows you to reconstruct an object from its serialized form. * * @param deserializer - An instance of the Deserializer used to read the serialized data. + * @group Implementation + * @category Utils */ deserialize(deserializer: Deserializer): T; }; @@ -19,6 +24,8 @@ export type DeserializableClass = { * * @param cls - The class of the object to normalize. * @param value - The instance to normalize. + * @group Implementation + * @category Utils */ export function normalizeBundle(cls: DeserializableClass, value: T) { const serializedBytes = value.bcsToBytes(); From 2a059b52871748bbce087c486d05701f4cbdc0c8 Mon Sep 17 00:00:00 2001 From: Jackson Date: Thu, 31 Oct 2024 16:03:19 -0400 Subject: [PATCH 2/2] Run pnpm fmt --- src/client/get.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/src/client/get.ts b/src/client/get.ts index 193e01123..e7f845456 100644 --- a/src/client/get.ts +++ b/src/client/get.ts @@ -155,7 +155,6 @@ export async function getAptosPepperService( return get({ ...options, type: AptosApiType.PEPPER }); } - /** * This function is a helper for paginating using a function wrapping an API * @group Implementation