Warn that only devnet has a faucet

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to the Aptos TypeScript SDK will be captured in this file. T
 
 # Unreleased
 
+- We now throw an error earlier when you try to use the faucet with testnet or mainnet, rather than letting the call happen and then fail later.
+
 # 1.33.1 (2024-11-28)
 
 - Add `gasProfile` function to `Move` class to allow for gas profiling of Aptos Move functions

src/api/aptosConfig.ts

@@ -177,6 +177,14 @@ export class AptosConfig {
         return NetworkToNodeAPI[this.network];
       case AptosApiType.FAUCET:
         if (this.faucet !== undefined) return this.faucet;
+        if (this.network === Network.TESTNET) {
+          throw new Error(
+            "There is no way to programmatically mint testnet APT, you must use the minting site at https://aptos.dev/network/faucet",
+          );
+        }
+        if (this.network === Network.MAINNET) {
+          throw new Error("There is no mainnet faucet");
+        }
         if (this.network === Network.CUSTOM) throw new Error("Please provide a custom faucet url");
         return NetworkToFaucetAPI[this.network];
       case AptosApiType.INDEXER:

src/api/faucet.ts

@@ -16,6 +16,9 @@ export class Faucet {
   /**
    * Initializes a new instance of the Aptos client with the specified configuration.
    *
+   * Note that only devnet has a publicly accessible faucet. For testnet, you must use
+   * the minting page at https://aptos.dev/network/faucet.
+   *
    * @param config - The configuration settings for the Aptos client.
    *
    * @example
@@ -24,7 +27,7 @@ export class Faucet {
    *
    * async function runExample() {
    *     // Create a configuration for the Aptos client
-   *     const config = new AptosConfig({ network: Network.TESTNET }); // specify your own network if needed
+   *     const config = new AptosConfig({ network: Network.DEVNET }); // specify your own network if needed
    *
    *     // Initialize the Aptos client with the configuration
    *     const aptos = new Aptos(config);
@@ -40,6 +43,9 @@ export class Faucet {
   /**
    * This function creates an account if it does not exist and mints the specified amount of coins into that account.
    *
+   * Note that only devnet has a publicly accessible faucet. For testnet, you must use
+   * the minting page at https://aptos.dev/network/faucet.
+   *
    * @param args - The arguments for funding the account.
    * @param args.accountAddress - The address of the account to fund.
    * @param args.amount - The amount of tokens to fund the account with.
@@ -50,7 +56,7 @@ export class Faucet {
    * ```typescript
    * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
    *
-   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const config = new AptosConfig({ network: Network.DEVNET });
    * const aptos = new Aptos(config);
    *
    * async function runExample() {

src/api/transaction.ts

@@ -66,7 +66,7 @@ import { SimpleTransaction } from "../transactions/instances/simpleTransaction";
  *   );
  *
  *   // Set up the client
- *   const config = new AptosConfig({ network: Network.TESTNET });
+ *   const config = new AptosConfig({ network: Network.DEVNET });
  *   const aptos = new Aptos(config);
  *
  *   // Generate two account credentials

src/cli/localNode.ts

@@ -7,8 +7,8 @@ import { platform } from "os";
 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.
+ * Represents a local node for running a localnet environment.
+ * This class provides methods to start, stop, and check the status of the localnet process.
  * It manages the lifecycle of the node process and ensures that it is operational before executing tests.
  * @group Implementation
  * @category CLI
@@ -59,7 +59,7 @@ export class LocalNode {
   }
 
   /**
-   * Runs a local testnet and waits for the process to be up.
+   * Runs a localnet and waits for the process to be up.
    * If the local node process is already running, it returns without starting the process.
    *
    * @returns {Promise<void>} A promise that resolves when the process is up.
@@ -76,11 +76,11 @@ export class LocalNode {
   }
 
   /**
-   * Starts the local testnet by running the Aptos node with the specified command-line arguments.
+   * Starts the localnet by running the Aptos node with the specified command-line arguments.
    *
    * @returns {void}
    *
-   * @throws {Error} If there is an issue starting the local testnet.
+   * @throws {Error} If there is an issue starting the localnet.
    * @group Implementation
    * @category CLI
    */
@@ -115,7 +115,7 @@ export class LocalNode {
   }
 
   /**
-   * Waits for the local testnet process to be operational within a specified maximum wait time.
+   * Waits for the localnet process to be operational within a specified maximum wait time.
    * This function continuously checks if the process is up and will throw an error if it fails to start.
    *
    * @returns Promise<boolean> - Resolves to true if the process is up, otherwise throws an error.
@@ -145,9 +145,9 @@ export class LocalNode {
   }
 
   /**
-   * Checks if the local testnet is up by querying the readiness endpoint.
+   * Checks if the localnet is up by querying the readiness endpoint.
    *
-   * @returns Promise<boolean> - A promise that resolves to true if the testnet is up, otherwise false.
+   * @returns Promise<boolean> - A promise that resolves to true if the localnet is up, otherwise false.
    * @group Implementation
    * @category CLI
    */

src/client/post.ts

@@ -178,6 +178,9 @@ export async function postAptosIndexer<Req extends {}, Res extends {}>(
  * Sends a request to the Aptos faucet to obtain test tokens.
  * This function modifies the provided configuration to ensure that the API_KEY is not included in the request.
  *
+ * Note that only devnet has a publicly accessible faucet. For testnet, you must use
+ * the minting page at https://aptos.dev/network/faucet.
+ *
  * @param options - The options for the request.
  * @param options.aptosConfig - The configuration settings for the Aptos client.
  * @param options.aptosConfig.clientConfig - The client-specific configuration settings.

src/internal/faucet.ts

@@ -20,6 +20,9 @@ import { waitForTransaction } from "./transaction";
  * Funds an account with a specified amount of tokens from the Aptos faucet.
  * This function is useful for quickly providing a new or existing account with tokens to facilitate transactions.
  *
+ * Note that only devnet has a publicly accessible faucet. For testnet, you must use
+ * the minting page at https://aptos.dev/network/faucet.
+ *
  * @param args - The arguments for funding the account.
  * @param args.aptosConfig - The configuration settings for connecting to the Aptos network.
  * @param args.accountAddress - The address of the account to be funded.

src/internal/staking.ts

@@ -5,7 +5,7 @@
  * This file contains the underlying implementations for exposed API surface in
  * 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.
+ * staking namespace and without having a dependency cycle error.
  * @group Implementation
  */
 

src/utils/apiEndpoints.ts

@@ -28,8 +28,6 @@ export const NetworkToNodeAPI: Record<string, string> = {
  * @category Network
  */
 export const NetworkToFaucetAPI: Record<string, string> = {
-  mainnet: "https://faucet.mainnet.aptoslabs.com",
-  testnet: "https://faucet.testnet.aptoslabs.com",
   devnet: "https://faucet.devnet.aptoslabs.com",
   local: "http://127.0.0.1:8081",
 };

tests/unit/aptosConfig.test.ts

@@ -30,7 +30,7 @@ describe("aptos config", () => {
     const aptosConfig = new AptosConfig(settings);
     expect(aptosConfig.network).toEqual("testnet");
     expect(aptosConfig.getRequestUrl(AptosApiType.FULLNODE)).toBe(NetworkToNodeAPI[Network.TESTNET]);
-    expect(aptosConfig.getRequestUrl(AptosApiType.FAUCET)).toBe(NetworkToFaucetAPI[Network.TESTNET]);
+    expect(() => aptosConfig.getRequestUrl(AptosApiType.FAUCET)).toThrow();
     expect(aptosConfig.getRequestUrl(AptosApiType.INDEXER)).toBe(NetworkToIndexerAPI[Network.TESTNET]);
   });
 
@@ -41,7 +41,7 @@ describe("aptos config", () => {
     const aptosConfig = new AptosConfig(settings);
     expect(aptosConfig.network).toEqual("mainnet");
     expect(aptosConfig.getRequestUrl(AptosApiType.FULLNODE)).toBe(NetworkToNodeAPI[Network.MAINNET]);
-    expect(aptosConfig.getRequestUrl(AptosApiType.FAUCET)).toBe(NetworkToFaucetAPI[Network.MAINNET]);
+    expect(() => aptosConfig.getRequestUrl(AptosApiType.FAUCET)).toThrow();
     expect(aptosConfig.getRequestUrl(AptosApiType.INDEXER)).toBe(NetworkToIndexerAPI[Network.MAINNET]);
   });