From d0a9162f473735099b54ae9c475810cf9c104638 Mon Sep 17 00:00:00 2001 From: Greg Osuri Date: Tue, 10 Dec 2024 00:42:22 -0800 Subject: [PATCH] feat: Add JSDoc comments with examples to ValidationError and SdlValidationError classes - Enhanced the `ValidationError` class with detailed JSDoc comments, including usage examples for the `assert` method. - Updated the `SdlValidationError` class to include comprehensive JSDoc comments and examples, improving code documentation and usability. - Ensured consistency in documentation style across both error classes. Signed-off-by: Greg Osuri --- src/keplr/index.ts | 35 +++++++++++++++++++++++++++++++++-- src/network/index.ts | 22 ++++++++++++++++++++++ src/pbclient/pbclient.spec.ts | 3 +++ src/pbclient/pbclient.ts | 15 +++++++++++++++ src/rpc/index.ts | 19 +++++++++++++++++++ 5 files changed, 92 insertions(+), 2 deletions(-) diff --git a/src/keplr/index.ts b/src/keplr/index.ts index 6a91359..d821224 100644 --- a/src/keplr/index.ts +++ b/src/keplr/index.ts @@ -5,10 +5,19 @@ import { AminoTypes } from "@cosmjs/stargate"; import { Certificate } from "@akashnetwork/akash-api/akash/cert/v1beta2"; import { MsgCreateCertificate } from "@akashnetwork/akash-api/deprecated/akash/cert/v1beta1"; +/** + * Represents a blockchain chain. + * @typedef {Object} Chain + * @property {string} id - The unique identifier of the chain. + */ interface Chain { id: string; } +/** + * Returns the available blockchain chains. + * @returns {Object} An object containing mainnet and testnet chain configurations. + */ export function getChains() { return { mainnet: { @@ -20,25 +29,45 @@ export function getChains() { }; } +/** + * Retrieves the signer for a given blockchain chain. + * @param {Chain} chain - The blockchain chain for which to get the signer. + * @returns {Promise} A promise that resolves to the signer. + */ export function getSigner(chain: Chain) { return window.getOfflineSignerAuto(chain.id); } +/** + * Connects to a blockchain endpoint with a given signer. + * @param {Chain} chain - The blockchain chain to connect to. + * @param {OfflineSigner | OfflineDirectSigner} signer - The signer to use for the connection. + * @param {string} endPoint - The endpoint URL to connect to. + * @returns {Promise} A promise that resolves to the connected client. + */ export async function get(chain: Chain, signer: OfflineSigner | OfflineDirectSigner, endPoint: string) { + // Define custom Amino types for specific message types const customAminoTypes = new AminoTypes({ + // Specify the message type for creating a certificate "/akash.cert.v1beta2.MsgCreateCertificate": { + // Define the Amino type string for the message aminoType: "cert/cert-create-certificate", + // Function to convert the message to Amino format toAmino: ({ cert, pubkey }: MsgCreateCertificate) => { + // Encode the certificate and public key into a binary format const buf = Certificate.encode( Certificate.fromPartial({ cert, pubkey }) ).finish(); + // Convert the binary data to a base64 string const encoded = Buffer.from(buf); return encoded.toString("base64"); }, + // Function to convert the message from Amino format fromAmino: ({ cert, pubkey }: MsgCreateCertificate) => { + // Create a partial Certificate object from the Amino data return Certificate.fromPartial({ cert, pubkey @@ -47,10 +76,12 @@ export async function get(chain: Chain, signer: OfflineSigner | OfflineDirectSig } }); + // Create a registry that includes default types and Akash-specific types const myRegistry = new Registry([...defaultRegistryTypes, ...getAkashTypeRegistry()]); + // Connect to the blockchain endpoint using the provided signer and custom configurations return await SigningStargateClient.connectWithSigner(endPoint, signer, { - registry: myRegistry, - aminoTypes: customAminoTypes + registry: myRegistry, // Use the custom registry + aminoTypes: customAminoTypes // Use the custom Amino types }); } diff --git a/src/network/index.ts b/src/network/index.ts index 7a0b0fa..2a76f05 100644 --- a/src/network/index.ts +++ b/src/network/index.ts @@ -64,10 +64,22 @@ export async function getMetadata(network: NETWORK_TYPE): Promise res.json()); } +/** + * Retrieves endpoints for a specific network and type + * @param {NETWORK_TYPE} network - The network to get endpoints for + * @param {ENDPOINT_TYPE} type - The type of endpoint to retrieve + * @returns {Promise<{ address: string }[]>} A promise that resolves to an array of endpoint addresses + */ export function getEndpoints(network: NETWORK_TYPE, type: ENDPOINT_TYPE) { return getMetadata(network).then(meta => meta.apis[type]); } +/** + * Retrieves and sorts endpoints by their health status + * @param {NETWORK_TYPE} network - The network to get endpoints for + * @param {ENDPOINT_TYPE} type - The type of endpoint to retrieve + * @returns {Promise<{ address: string, responseTime: number | null }[]>} A promise that resolves to an array of endpoints sorted by response time + */ export function getEndpointsSorted(network: NETWORK_TYPE, type: ENDPOINT_TYPE) { return getEndpoints(network, type) .then(map(getEndpointHealthStatus(800))) @@ -76,10 +88,20 @@ export function getEndpointsSorted(network: NETWORK_TYPE, type: ENDPOINT_TYPE) { .then(sortBy(prop("responseTime"))); } +/** + * Checks if a node is responsive based on its response time + * @param {{ responseTime: number | null }} endpoint - The endpoint to check + * @returns {boolean} True if the node is responsive, false otherwise + */ function isNodeResponsive(endpoint: { responseTime: number | null }) { return endpoint.responseTime !== null; } +/** + * Returns a function that checks the health status of an endpoint + * @param {number} timeout - The timeout for the health check request + * @returns {function({ address: string }): Promise<{ address: string, responseTime: number | null }>} A function that returns a promise resolving to the endpoint's health status + */ function getEndpointHealthStatus(timeout: number) { return ({ address }: { address: string }) => { const startTime = performance.now(); diff --git a/src/pbclient/pbclient.spec.ts b/src/pbclient/pbclient.spec.ts index 7f0a4ef..d61ab01 100644 --- a/src/pbclient/pbclient.spec.ts +++ b/src/pbclient/pbclient.spec.ts @@ -5,6 +5,9 @@ import { Message } from "../stargate"; import { AminoMsg } from "@cosmjs/amino"; describe("createAminoMessage", () => { + /** + * Test to ensure createAminoMessage function creates an Amino message correctly. + */ it("creates an amino message", () => { const message = faker.helpers.arrayElement(Object.values(Message)); const messageBody: AminoMsg = { diff --git a/src/pbclient/pbclient.ts b/src/pbclient/pbclient.ts index f0648c8..869d047 100644 --- a/src/pbclient/pbclient.ts +++ b/src/pbclient/pbclient.ts @@ -12,6 +12,13 @@ const FEE = { gas: "100000" }; +/** + * Creates an Amino message object. + * + * @param {Message} message - The type of the message. + * @param {AminoMsg} messageBody - The body of the message. + * @returns {object} The Amino message object. + */ export function createAminoMessage(message: Message, messageBody: AminoMsg) { return { typeUrl: message, @@ -27,6 +34,14 @@ type MessageTypes = { }; }; +/** + * Creates a Stargate message object with a fee. + * + * @template T + * @param {T} message - The type of the message. + * @param {MessageTypes[T]} messageBody - The body of the message. + * @returns {object} The Stargate message object with a fee. + */ export function createStarGateMessage(message: T, messageBody: MessageTypes[T]) { return { message: { diff --git a/src/rpc/index.ts b/src/rpc/index.ts index 891da12..6a80edd 100644 --- a/src/rpc/index.ts +++ b/src/rpc/index.ts @@ -3,16 +3,35 @@ import { getAkashTypeRegistry } from "../stargate"; import { OfflineSigner, Registry } from "@cosmjs/proto-signing"; import { Tendermint34Client } from "@cosmjs/tendermint-rpc"; +/** + * Gets an RPC client for interacting with the Akash network + * @param {string} endpoint - The RPC endpoint URL to connect to + * @returns {Promise>} A protobuf RPC client instance + * @throws {Error} If connection to the endpoint fails + */ export async function getRpc(endpoint: string) { return getQueryClient(endpoint); } +/** + * Creates a query client for making read-only requests to the Akash network + * @param {string} endpoint - The RPC endpoint URL to connect to + * @returns {Promise>} A protobuf RPC client for queries + * @throws {Error} If connection to the endpoint fails + */ export async function getQueryClient(endpoint: string) { const tmClient = await Tendermint34Client.connect(endpoint); const queryClient = new QueryClient(tmClient); return createProtobufRpcClient(queryClient); } +/** + * Creates a message client for sending transactions to the Akash network + * @param {string} endpoint - The RPC endpoint URL to connect to + * @param {OfflineSigner} signer - The signer used to sign transactions + * @returns {Promise} A client for signing and sending transactions + * @throws {Error} If connection to the endpoint fails or if there are issues with the signer + */ export async function getMsgClient(endpoint: string, signer: OfflineSigner) { const msgRegistry = new Registry(getAkashTypeRegistry()); const options: SigningStargateClientOptions = {