algosdk 1.24.0 → 1.24.1

package/src/client/kmd.ts

@@ -0,0 +1,423 @@
+import ServiceClient from './v2/serviceClient';
+import * as txn from '../transaction';
+import { CustomTokenHeader, KMDTokenHeader } from './urlTokenBaseHTTPClient';
+
+export default class Kmd extends ServiceClient {
+  constructor(
+    token: string | KMDTokenHeader | CustomTokenHeader,
+    baseServer = 'http://127.0.0.1',
+    port: string | number = 7833,
+    headers = {}
+  ) {
+    super('X-KMD-API-Token', token, baseServer, port, headers);
+  }
+
+  /**
+   * version returns a VersionResponse containing a list of kmd API versions supported by this running kmd instance.
+   */
+  async versions() {
+    const res = await this.c.get('/versions');
+    return res.body;
+  }
+
+  /**
+   * listWallets returns a ListWalletsResponse containing the list of wallets known to kmd. Using a wallet ID
+   * returned from this endpoint, you can initialize a wallet handle with client.InitWalletHandle
+   */
+  async listWallets() {
+    const res = await this.c.get('/v1/wallets');
+    return res.body;
+  }
+
+  /**
+   * createWallet creates a wallet with the specified name, password, driver,
+   * and master derivation key. If the master derivation key is blank, one is
+   * generated internally to kmd. CreateWallet returns a CreateWalletResponse
+   * containing information about the new wallet.
+   * @param walletName
+   * @param walletPassword
+   * @param walletDriverName
+   * @param walletMDK
+   */
+  async createWallet(
+    walletName: string,
+    walletPassword: string,
+    walletMDK: Uint8Array = new Uint8Array(),
+    walletDriverName = 'sqlite'
+  ) {
+    const req = {
+      wallet_name: walletName,
+      wallet_driver_name: walletDriverName,
+      wallet_password: walletPassword,
+      master_derivation_key: Buffer.from(walletMDK).toString('base64'),
+    };
+    const res = await this.c.post('/v1/wallet', req);
+    return res.body;
+  }
+
+  /**
+   * initWalletHandle accepts a wallet ID and a wallet password, and returns an
+   * initWalletHandleResponse containing a wallet handle token. This wallet
+   * handle token can be used for subsequent operations on this wallet, like key
+   * generation, transaction signing, etc.. WalletHandleTokens expire after a
+   * configurable number of seconds, and must be renewed periodically with
+   * RenewWalletHandle. It is good practice to call ReleaseWalletHandle when
+   * you're done interacting with this wallet.
+   * @param walletID
+   * @param walletPassword
+   */
+  async initWalletHandle(walletID: string, walletPassword: string) {
+    const req = {
+      wallet_id: walletID,
+      wallet_password: walletPassword,
+    };
+    const res = await this.c.post('/v1/wallet/init', req);
+    return res.body;
+  }
+
+  /**
+   * releaseWalletHandle invalidates the passed wallet handle token, making
+   * it unusuable for subsequent wallet operations.
+   * @param walletHandle
+   */
+  async releaseWalletHandle(walletHandle: string) {
+    const req = {
+      wallet_handle_token: walletHandle,
+    };
+    const res = await this.c.post('/v1/wallet/release', req);
+    return res.body;
+  }
+
+  /**
+   * renewWalletHandle accepts a wallet handle and attempts to renew it, moving
+   * the expiration time to some number of seconds in the future. It returns a
+   * RenewWalletHandleResponse containing the walletHandle and the number of
+   * seconds until expiration
+   * @param walletHandle
+   */
+  async renewWalletHandle(walletHandle: string) {
+    const req = {
+      wallet_handle_token: walletHandle,
+    };
+    const res = await this.c.post('/v1/wallet/renew', req);
+    return res.body;
+  }
+
+  /**
+   * renameWallet accepts a wallet ID, wallet password, and a new wallet name,
+   * and renames the underlying wallet.
+   * @param walletID
+   * @param walletPassword
+   * @param newWalletName
+   */
+  async renameWallet(
+    walletID: string,
+    walletPassword: string,
+    newWalletName: string
+  ) {
+    const req = {
+      wallet_id: walletID,
+      wallet_password: walletPassword,
+      wallet_name: newWalletName,
+    };
+    const res = await this.c.post('/v1/wallet/rename', req);
+    return res.body;
+  }
+
+  /**
+   * getWallet accepts a wallet handle and returns high level information about
+   * this wallet in a GetWalletResponse.
+   * @param walletHandle
+   */
+  async getWallet(walletHandle: string) {
+    const req = {
+      wallet_handle_token: walletHandle,
+    };
+    const res = await this.c.post('/v1/wallet/info', req);
+    return res.body;
+  }
+
+  /**
+   * exportMasterDerivationKey accepts a wallet handle and a wallet password, and
+   * returns an ExportMasterDerivationKeyResponse containing the master
+   * derivation key. This key can be used as an argument to CreateWallet in
+   * order to recover the keys generated by this wallet. The master derivation
+   * key can be encoded as a sequence of words using the mnemonic library, and
+   * @param walletHandle
+   * @param walletPassword
+   */
+  async exportMasterDerivationKey(
+    walletHandle: string,
+    walletPassword: string
+  ) {
+    const req = {
+      wallet_handle_token: walletHandle,
+      wallet_password: walletPassword,
+    };
+    const res = await this.c.post('/v1/master-key/export', req);
+    return {
+      master_derivation_key: Buffer.from(
+        res.body.master_derivation_key,
+        'base64'
+      ),
+    };
+  }
+
+  /**
+   * importKey accepts a wallet handle and an ed25519 private key, and imports
+   * the key into the wallet. It returns an ImportKeyResponse containing the
+   * address corresponding to this private key.
+   * @param walletHandle
+   * @param secretKey
+   */
+  async importKey(walletHandle: string, secretKey: Uint8Array) {
+    const req = {
+      wallet_handle_token: walletHandle,
+      private_key: Buffer.from(secretKey).toString('base64'),
+    };
+    const res = await this.c.post('/v1/key/import', req);
+    return res.body;
+  }
+
+  /**
+   * exportKey accepts a wallet handle, wallet password, and address, and returns
+   * an ExportKeyResponse containing the ed25519 private key corresponding to the
+   * address stored in the wallet.
+   * @param walletHandle
+   * @param walletPassword
+   * @param addr
+   */
+  async exportKey(walletHandle: string, walletPassword: string, addr: string) {
+    const req = {
+      wallet_handle_token: walletHandle,
+      address: addr,
+      wallet_password: walletPassword,
+    };
+    const res = await this.c.post('/v1/key/export', req);
+    return { private_key: Buffer.from(res.body.private_key, 'base64') };
+  }
+
+  /**
+   * generateKey accepts a wallet handle, and then generates the next key in the
+   * wallet using its internal master derivation key. Two wallets with the same
+   * master derivation key will generate the same sequence of keys.
+   * @param walletHandle
+   */
+  async generateKey(walletHandle: string) {
+    const req = {
+      wallet_handle_token: walletHandle,
+      display_mnemonic: false,
+    };
+    const res = await this.c.post('/v1/key', req);
+    return res.body;
+  }
+
+  /**
+   * deleteKey accepts a wallet handle, wallet password, and address, and deletes
+   * the information about this address from the wallet (including address and
+   * secret key). If DeleteKey is called on a key generated using GenerateKey,
+   * the same key will not be generated again. However, if a wallet is recovered
+   * using the master derivation key, a key generated in this way can be
+   * recovered.
+   * @param walletHandle
+   * @param walletPassword
+   * @param addr
+   */
+  async deleteKey(walletHandle: string, walletPassword: string, addr: string) {
+    const req = {
+      wallet_handle_token: walletHandle,
+      address: addr,
+      wallet_password: walletPassword,
+    };
+    const res = await this.c.delete('/v1/key', req);
+    return res.body;
+  }
+
+  /**
+   * ListKeys accepts a wallet handle and returns a ListKeysResponse containing
+   * all of the addresses for which this wallet contains secret keys.
+   * @param walletHandle
+   */
+  async listKeys(walletHandle: string) {
+    const req = {
+      wallet_handle_token: walletHandle,
+    };
+    const res = await this.c.post('/v1/key/list', req);
+    return res.body;
+  }
+
+  /**
+   * signTransaction accepts a wallet handle, wallet password, and a transaction,
+   * and returns and SignTransactionResponse containing an encoded, signed
+   * transaction. The transaction is signed using the key corresponding to the
+   * Sender field.
+   * @param walletHandle
+   * @param walletPassword
+   * @param transaction
+   */
+  async signTransaction(
+    walletHandle: string,
+    walletPassword: string,
+    transaction: txn.TransactionLike
+  ) {
+    const tx = txn.instantiateTxnIfNeeded(transaction);
+
+    const req = {
+      wallet_handle_token: walletHandle,
+      wallet_password: walletPassword,
+      transaction: Buffer.from(tx.toByte()).toString('base64'),
+    };
+    const res = await this.c.post('/v1/transaction/sign', req);
+
+    if (res.status === 200) {
+      return Buffer.from(res.body.signed_transaction, 'base64');
+    }
+    return res.body;
+  }
+
+  /**
+   * signTransactionWithSpecificPublicKey accepts a wallet handle, wallet password, a transaction, and a public key,
+   * and returns and SignTransactionResponse containing an encoded, signed
+   * transaction. The transaction is signed using the key corresponding to the
+   * publicKey arg.
+   * @param walletHandle
+   * @param walletPassword
+   * @param transaction
+   * @param publicKey - sign the txn with the key corresponding to publicKey (used for working with a rekeyed addr)
+   */
+  async signTransactionWithSpecificPublicKey(
+    walletHandle: string,
+    walletPassword: string,
+    transaction: txn.TransactionLike,
+    publicKey: Uint8Array | string
+  ) {
+    const tx = txn.instantiateTxnIfNeeded(transaction);
+
+    const req = {
+      wallet_handle_token: walletHandle,
+      wallet_password: walletPassword,
+      transaction: Buffer.from(tx.toByte()).toString('base64'),
+      public_key: Buffer.from(publicKey).toString('base64'),
+    };
+    const res = await this.c.post('/v1/transaction/sign', req);
+
+    if (res.status === 200) {
+      return Buffer.from(res.body.signed_transaction, 'base64');
+    }
+    return res.body;
+  }
+
+  /**
+   * listMultisig accepts a wallet handle and returns a ListMultisigResponse
+   * containing the multisig addresses whose preimages are stored in this wallet.
+   * A preimage is the information needed to reconstruct this multisig address,
+   * including multisig version information, threshold information, and a list
+   * of public keys.
+   * @param walletHandle
+   */
+  async listMultisig(walletHandle: string) {
+    const req = {
+      wallet_handle_token: walletHandle,
+    };
+    const res = await this.c.post('/v1/multisig/list', req);
+    return res.body;
+  }
+
+  /**
+   * importMultisig accepts a wallet handle and the information required to
+   * generate a multisig address. It derives this address, and stores all of the
+   * information within the wallet. It returns a ImportMultisigResponse with the
+   * derived address.
+   * @param walletHandle
+   * @param version
+   * @param threshold
+   * @param pks
+   */
+  async importMultisig(
+    walletHandle: string,
+    version: number,
+    threshold: number,
+    pks: string[]
+  ) {
+    const req = {
+      wallet_handle_token: walletHandle,
+      multisig_version: version,
+      threshold,
+      pks,
+    };
+    const res = await this.c.post('/v1/multisig/import', req);
+    return res.body;
+  }
+
+  /**
+   * exportMultisig accepts a wallet handle, wallet password, and multisig
+   * address, and returns an ExportMultisigResponse containing the stored
+   * multisig preimage. The preimage contains all of the information necessary
+   * to derive the multisig address, including version, threshold, and a list of
+   * public keys.
+   * @param walletHandle
+   * @param walletPassword
+   * @param addr
+   */
+  async exportMultisig(walletHandle: string, addr: string) {
+    const req = {
+      wallet_handle_token: walletHandle,
+      address: addr,
+    };
+    const res = await this.c.post('/v1/multisig/export', req);
+    return res.body;
+  }
+
+  /**
+   * signMultisigTransaction accepts a wallet handle, wallet password,
+   * transaction, public key (*not* an address), and an optional partial
+   * MultisigSig. It looks up the secret key corresponding to the public key, and
+   * returns a SignMultisigTransactionResponse containing a MultisigSig with a
+   * signature by the secret key included.
+   * @param walletHandle
+   * @param pw
+   * @param tx
+   * @param pk
+   * @param partial
+   */
+  async signMultisigTransaction(
+    walletHandle: string,
+    pw: string,
+    transaction: txn.TransactionLike,
+    pk: Uint8Array | string,
+    partial: string
+  ) {
+    const tx = txn.instantiateTxnIfNeeded(transaction);
+    const req = {
+      wallet_handle_token: walletHandle,
+      transaction: Buffer.from(tx.toByte()).toString('base64'),
+      public_key: Buffer.from(pk).toString('base64'),
+      partial_multisig: partial,
+      wallet_password: pw,
+    };
+    const res = await this.c.post('/v1/multisig/sign', req);
+    return res.body;
+  }
+
+  /**
+   * deleteMultisig accepts a wallet handle, wallet password, and multisig
+   * address, and deletes the information about this multisig address from the
+   * wallet (including address and secret key).
+   * @param walletHandle
+   * @param walletPassword
+   * @param addr
+   */
+  async deleteMultisig(
+    walletHandle: string,
+    walletPassword: string,
+    addr: string
+  ) {
+    const req = {
+      wallet_handle_token: walletHandle,
+      address: addr,
+      wallet_password: walletPassword,
+    };
+    const res = await this.c.delete('/v1/multisig', req);
+    return res.body;
+  }
+}

package/src/client/urlTokenBaseHTTPClient.ts

@@ -0,0 +1,217 @@
+import { fetch, Response, Headers } from 'cross-fetch';
+import {
+  BaseHTTPClient,
+  BaseHTTPClientResponse,
+  BaseHTTPClientError,
+  Query,
+} from './baseHTTPClient';
+
+export interface AlgodTokenHeader {
+  'X-Algo-API-Token': string;
+}
+
+export interface IndexerTokenHeader {
+  'X-Indexer-API-Token': string;
+}
+
+export interface KMDTokenHeader {
+  'X-KMD-API-Token': string;
+}
+
+export interface CustomTokenHeader {
+  [headerName: string]: string;
+}
+
+class URLTokenBaseHTTPError extends Error implements BaseHTTPClientError {
+  constructor(message: string, public response: BaseHTTPClientResponse) {
+    super(message);
+    this.name = 'URLTokenBaseHTTPError';
+    this.response = response;
+  }
+}
+
+export type TokenHeader =
+  | AlgodTokenHeader
+  | IndexerTokenHeader
+  | KMDTokenHeader
+  | CustomTokenHeader;
+
+/**
+ * Implementation of BaseHTTPClient that uses a URL and a token
+ * and make the REST queries using fetch.
+ * This is the default implementation of BaseHTTPClient.
+ */
+export class URLTokenBaseHTTPClient implements BaseHTTPClient {
+  private readonly baseURL: URL;
+  private readonly tokenHeader: TokenHeader;
+
+  constructor(
+    tokenHeader: TokenHeader,
+    baseServer: string,
+    port?: string | number,
+    private defaultHeaders: Record<string, any> = {}
+  ) {
+    // Append a trailing slash so we can use relative paths. Without the trailing
+    // slash, the last path segment will be replaced by the relative path. See
+    // usage in `addressWithPath`.
+    const fixedBaseServer = baseServer.endsWith('/')
+      ? baseServer
+      : `${baseServer}/`;
+    const baseServerURL = new URL(fixedBaseServer);
+    if (typeof port !== 'undefined') {
+      baseServerURL.port = port.toString();
+    }
+
+    if (baseServerURL.protocol.length === 0) {
+      throw new Error('Invalid base server URL, protocol must be defined.');
+    }
+
+    this.baseURL = baseServerURL;
+    this.tokenHeader = tokenHeader;
+  }
+
+  /**
+   * Compute the URL for a path relative to the instance's address
+   * @param relativePath - A path string
+   * @param query - An optional key-value object of query parameters to add to the URL. If the
+   *   relativePath already has query parameters on it, the additional parameters defined here will
+   *   be added to the URL without modifying those (unless a key collision occurs).
+   * @returns A URL string
+   */
+  private getURL(relativePath: string, query?: Query<string>): string {
+    let fixedRelativePath: string;
+    if (relativePath.startsWith('./')) {
+      fixedRelativePath = relativePath;
+    } else if (relativePath.startsWith('/')) {
+      fixedRelativePath = `.${relativePath}`;
+    } else {
+      fixedRelativePath = `./${relativePath}`;
+    }
+    const address = new URL(fixedRelativePath, this.baseURL);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        address.searchParams.set(key, value);
+      }
+    }
+    return address.toString();
+  }
+
+  private static formatFetchResponseHeaders(
+    headers: Headers
+  ): Record<string, string> {
+    const headersObj: Record<string, string> = {};
+    headers.forEach((key, value) => {
+      headersObj[key] = value;
+    });
+    return headersObj;
+  }
+
+  private static async checkHttpError(res: Response) {
+    if (res.ok) {
+      return;
+    }
+
+    let body: Uint8Array | null = null;
+    let bodyErrorMessage: string | null = null;
+
+    try {
+      body = new Uint8Array(await res.arrayBuffer());
+      const decoded: Record<string, any> = JSON.parse(
+        Buffer.from(body).toString()
+      );
+      if (decoded.message) {
+        bodyErrorMessage = decoded.message;
+      }
+    } catch (_) {
+      // ignore any error that happened while we are parsing the error response
+    }
+
+    let message = `Network request error. Received status ${res.status} (${res.statusText})`;
+    if (bodyErrorMessage) {
+      message += `: ${bodyErrorMessage}`;
+    }
+
+    throw new URLTokenBaseHTTPError(message, {
+      body,
+      status: res.status,
+      headers: URLTokenBaseHTTPClient.formatFetchResponseHeaders(res.headers),
+    });
+  }
+
+  private static async formatFetchResponse(
+    res: Response
+  ): Promise<BaseHTTPClientResponse> {
+    await this.checkHttpError(res);
+    return {
+      body: new Uint8Array(await res.arrayBuffer()),
+      status: res.status,
+      headers: URLTokenBaseHTTPClient.formatFetchResponseHeaders(res.headers),
+    };
+  }
+
+  async get(
+    relativePath: string,
+    query?: Query<string>,
+    requestHeaders: Record<string, string> = {}
+  ): Promise<BaseHTTPClientResponse> {
+    // Expand headers for use in fetch
+    const headers = {
+      ...this.tokenHeader,
+      ...this.defaultHeaders,
+      ...requestHeaders,
+    };
+
+    const res = await fetch(this.getURL(relativePath, query), {
+      mode: 'cors',
+      headers,
+    });
+
+    return URLTokenBaseHTTPClient.formatFetchResponse(res);
+  }
+
+  async post(
+    relativePath: string,
+    data: Uint8Array,
+    query?: Query<string>,
+    requestHeaders: Record<string, string> = {}
+  ): Promise<BaseHTTPClientResponse> {
+    // Expand headers for use in fetch
+    const headers = {
+      ...this.tokenHeader,
+      ...this.defaultHeaders,
+      ...requestHeaders,
+    };
+
+    const res = await fetch(this.getURL(relativePath, query), {
+      method: 'POST',
+      mode: 'cors',
+      body: data,
+      headers,
+    });
+
+    return URLTokenBaseHTTPClient.formatFetchResponse(res);
+  }
+
+  async delete(
+    relativePath: string,
+    data: Uint8Array,
+    query?: Query<string>,
+    requestHeaders: Record<string, string> = {}
+  ): Promise<BaseHTTPClientResponse> {
+    // Expand headers for use in fetch
+    const headers = {
+      ...this.tokenHeader,
+      ...this.defaultHeaders,
+      ...requestHeaders,
+    };
+
+    const res = await fetch(this.getURL(relativePath, query), {
+      method: 'DELETE',
+      mode: 'cors',
+      body: data,
+      headers,
+    });
+
+    return URLTokenBaseHTTPClient.formatFetchResponse(res);
+  }
+}

package/src/client/v2/algod/accountApplicationInformation.ts

@@ -0,0 +1,20 @@
+import JSONRequest from '../jsonrequest';
+import HTTPClient from '../../client';
+import IntDecoding from '../../../types/intDecoding';
+
+export default class AccountApplicationInformation extends JSONRequest {
+  constructor(
+    c: HTTPClient,
+    intDecoding: IntDecoding,
+    private account: string,
+    private applicationID: number
+  ) {
+    super(c, intDecoding);
+    this.account = account;
+    this.applicationID = applicationID;
+  }
+
+  path() {
+    return `/v2/accounts/${this.account}/applications/${this.applicationID}`;
+  }
+}

package/src/client/v2/algod/accountAssetInformation.ts

@@ -0,0 +1,20 @@
+import JSONRequest from '../jsonrequest';
+import HTTPClient from '../../client';
+import IntDecoding from '../../../types/intDecoding';
+
+export default class AccountAssetInformation extends JSONRequest {
+  constructor(
+    c: HTTPClient,
+    intDecoding: IntDecoding,
+    private account: string,
+    private assetID: number
+  ) {
+    super(c, intDecoding);
+    this.account = account;
+    this.assetID = assetID;
+  }
+
+  path() {
+    return `/v2/accounts/${this.account}/assets/${this.assetID}`;
+  }
+}