Merge pull request #332 from ardriveapp/PE-1489_data_item_experimental

PE-4278: Optionally Send Data Items to Turbo

README.md

@@ -93,6 +93,7 @@ ardrive upload-file --wallet-file /path/to/my/wallet.json --parent-folder-id "f0
     3. [Wallet Operations](#wallet-operations)
     4. [Working With Entities](#working-with-entities)
         1. [Dry Run](#dry-run)
+        2. [Uploading to Turbo (BETA)](#upload-to-turbo)
     5. [Working With Drives](#working-with-drives)
         1. [Understanding Drive Hierarchies](#understanding-drive-hierarchies)
             1. [Fetching Drive Info](#drive-info)
@@ -393,6 +394,16 @@ ardrive <my-command> <other-options> --dry-run
 
 This can be very useful for gathering price estimations or to confirm that you've copy-pasted your entity IDs correctly before committing to an upload.
 
+### Uploading to Turbo (BETA) <a id="upload-to-turbo"></a>
+
+Users can optionally choose to send each ArFS entities created to [ArDrive Turbo][ardrive-turbo] using the `--turbo` flag. Instead of using AR from an Arweave wallet, you can use Turbo Credits or take advantage of free/discounted upload promotions.
+
+```shell
+ardrive <my-command> <other-options> --turbo
+```
+
+This flag will skip any balance check on the CLI side. Turbo will check a user's balance and accept/reject a data item at the time of upload. The `--turbo` flag by default will send your files to `upload.ardrive.io` to be bundled. To change the Turbo destination, users can use the `--turbo-url` flag.
+
 ## Working With Drives
 
 ### Understanding Drive Hierarchies
@@ -1571,3 +1582,4 @@ ardrive <command> --help
 [viewblock]: https://viewblock.io/arweave/
 [tx_anchors]: https://docs.arweave.org/developers/server/http-api#field-definitions
 [gql-guide]: https://gql-guide.vercel.app/#owners
+[ardrive-turbo]: https://ardrive.io/turbo/

package.json

@@ -8,7 +8,7 @@
 	},
 	"types": "./lib/index.d.ts",
 	"dependencies": {
-		"ardrive-core-js": "2.0.0-alpha-0",
+		"ardrive-core-js": "2.0.0",
 		"arweave": "1.11.4",
 		"axios": "^0.21.1",
 		"bn.js": "^5.2.1",
@@ -18,7 +18,7 @@
 		"prompts": "^2.4.0"
 	},
 	"engines": {
-		"node": ">=18.17.0"
+		"node": ">=18"
 	},
 	"devDependencies": {
 		"@istanbuljs/nyc-config-typescript": "^1.0.1",

src/CLICommand/parameters_helper.ts

@@ -18,7 +18,8 @@ import {
 	MetaDataFileParameter,
 	MetaDataGqlTagsParameter,
 	MetadataJsonParameter,
-	DataGqlTagsParameter
+	DataGqlTagsParameter,
+	TurboUrlParameter
 } from '../parameter_declarations';
 import { cliWalletDao } from '..';
 import passwordPrompt from 'prompts';
@@ -46,12 +47,14 @@ import {
 } from 'ardrive-core-js';
 import { JWKInterface } from 'arweave/node/lib/wallet';
 import { deriveIpfsCid } from '../utils/ipfs_utils';
+import { turboProdUrl } from 'ardrive-core-js/lib/utils/constants';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type ParameterOptions = any;
 
 const DEFAULT_GATEWAY = 'https://arweave.net:443';
 const ARWEAVE_GATEWAY_ENV_VAR = 'ARWEAVE_GATEWAY';
+const TURBO_URL_ENV_VAR = 'TURBO_URL';
 
 interface GetDriveKeyParams {
 	driveId: DriveID;
@@ -437,6 +440,42 @@ export class ParametersHelper {
 		return userProvidedURL;
 	}
 
+	/**
+	 * Gathers a valid turbo URL from user provided turbo parameter,
+	 * an environment variable, or returns the default arweave turbo
+	 *
+	 * @throws on user provided turbos that are incompatible with URL class constructor
+	 * @throws when hostName cannot be derived from a user provided turbo
+	 */
+	public getTurbo(): URL {
+		const userProvidedURL = (() => {
+			// Use optional --turbo-url supplied parameter as first choice
+			const turboFromParam = this.getParameterValue(TurboUrlParameter);
+			if (turboFromParam) {
+				return new URL(turboFromParam);
+			}
+
+			// Then check for an ENV provided turbo
+			const envTurbo = process.env[TURBO_URL_ENV_VAR];
+			if (envTurbo) {
+				return new URL(envTurbo);
+			}
+
+			return undefined;
+		})();
+
+		if (!userProvidedURL) {
+			// Return default CLI turbo if no turbo url can be derived from the user
+			return new URL(turboProdUrl);
+		}
+
+		if (userProvidedURL.hostname === '') {
+			// Ensure a valid host name was provided to be used in Arweave.init()
+			throw new TypeError(`Host name could not be determined from provided URL: ${userProvidedURL.href}`);
+		}
+		return userProvidedURL;
+	}
+
 	public isDryRun(): boolean {
 		const dryRun = this.getParameterValue(DryRunParameter);
 		return !!dryRun;

src/commands/create_drive.ts

@@ -1,11 +1,13 @@
 import { CLICommand, ParametersHelper } from '../CLICommand';
 import {
 	BoostParameter,
+	TurboUrlParameter,
 	DriveCreationPrivacyParameters,
 	DriveNameParameter,
 	DryRunParameter,
 	GatewayParameter,
-	ShouldBundleParameter
+	ShouldBundleParameter,
+	ShouldTurboParameter
 } from '../parameter_declarations';
 import { cliArDriveFactory } from '..';
 import { SUCCESS_EXIT_CODE } from '../CLICommand/error_codes';
@@ -21,22 +23,27 @@ new CLICommand({
 		...DriveCreationPrivacyParameters,
 		ShouldBundleParameter,
 		BoostParameter,
-		GatewayParameter
+		GatewayParameter,
+		ShouldTurboParameter,
+		TurboUrlParameter
 	],
 	action: new CLIAction(async function action(options) {
 		const parameters = new ParametersHelper(options);
 		const wallet: Wallet = await parameters.getRequiredWallet();
 		const dryRun = parameters.isDryRun();
 		const driveName = parameters.getRequiredParameterValue(DriveNameParameter);
 		const shouldBundle = !!parameters.getParameterValue(ShouldBundleParameter);
+		const useTurbo = !!parameters.getParameterValue(ShouldTurboParameter);
 		const arweave = getArweaveFromURL(parameters.getGateway());
+		const turboUrl = parameters.getTurbo();
 
 		const ardrive = cliArDriveFactory({
 			wallet: wallet,
 			feeMultiple: parameters.getOptionalBoostSetting(),
 			dryRun,
 			shouldBundle,
-			arweave
+			arweave,
+			turboSettings: useTurbo ? { turboUrl } : undefined
 		});
 
 		const createDriveResult = await (async function () {

src/commands/create_folder.ts

@@ -5,7 +5,9 @@ import {
 	DryRunParameter,
 	ParentFolderIdParameter,
 	DrivePrivacyParameters,
-	GatewayParameter
+	GatewayParameter,
+	ShouldTurboParameter,
+	TurboUrlParameter
 } from '../parameter_declarations';
 import { cliArDriveFactory } from '..';
 import { SUCCESS_EXIT_CODE } from '../CLICommand/error_codes';
@@ -21,19 +23,24 @@ new CLICommand({
 		BoostParameter,
 		DryRunParameter,
 		...DrivePrivacyParameters,
-		GatewayParameter
+		GatewayParameter,
+		ShouldTurboParameter,
+		TurboUrlParameter
 	],
 	action: new CLIAction(async function action(options) {
 		const parameters = new ParametersHelper(options);
 		const wallet: Wallet = await parameters.getRequiredWallet();
 		const dryRun = parameters.isDryRun();
 		const arweave = getArweaveFromURL(parameters.getGateway());
+		const useTurbo = !!parameters.getParameterValue(ShouldTurboParameter);
+		const turboUrl = parameters.getTurbo();
 
 		const ardrive = cliArDriveFactory({
 			wallet,
 			feeMultiple: parameters.getOptionalBoostSetting(),
 			dryRun,
-			arweave
+			arweave,
+			turboSettings: useTurbo ? { turboUrl } : undefined
 		});
 
 		const parentFolderId = parameters.getRequiredParameterValue(ParentFolderIdParameter, EID);

src/commands/create_manifest.ts

@@ -12,7 +12,9 @@ import {
 	WalletFileParameter,
 	DestinationManifestNameParameter,
 	ConflictResolutionParams,
-	GatewayParameter
+	GatewayParameter,
+	ShouldTurboParameter,
+	TurboUrlParameter
 } from '../parameter_declarations';
 import { fileUploadConflictPrompts } from '../prompts';
 import { getArweaveFromURL } from '../utils/get_arweave_for_url';
@@ -28,19 +30,24 @@ new CLICommand({
 		SeedPhraseParameter,
 		...ConflictResolutionParams,
 		...TreeDepthParams,
-		GatewayParameter
+		GatewayParameter,
+		ShouldTurboParameter,
+		TurboUrlParameter
 	],
 	action: new CLIAction(async function action(options) {
 		const parameters = new ParametersHelper(options, cliWalletDao);
 
 		const wallet = await parameters.getRequiredWallet();
 		const arweave = getArweaveFromURL(parameters.getGateway());
+		const useTurbo = !!parameters.getParameterValue(ShouldTurboParameter);
+		const turboUrl = parameters.getTurbo();
 
 		const arDrive = cliArDriveFactory({
 			wallet: wallet,
 			feeMultiple: parameters.getOptionalBoostSetting(),
 			dryRun: parameters.isDryRun(),
-			arweave
+			arweave,
+			turboSettings: useTurbo ? { turboUrl } : undefined
 		});
 
 		const folderId = parameters.getRequiredParameterValue(FolderIdParameter, EID);

src/commands/move_file.ts

@@ -5,7 +5,9 @@ import {
 	FileIdParameter,
 	ParentFolderIdParameter,
 	DrivePrivacyParameters,
-	GatewayParameter
+	GatewayParameter,
+	ShouldTurboParameter,
+	TurboUrlParameter
 } from '../parameter_declarations';
 import { cliArDriveFactory } from '..';
 import { SUCCESS_EXIT_CODE } from '../CLICommand/error_codes';
@@ -20,6 +22,8 @@ new CLICommand({
 		ParentFolderIdParameter,
 		BoostParameter,
 		DryRunParameter,
+		ShouldTurboParameter,
+		TurboUrlParameter,
 		...DrivePrivacyParameters,
 		GatewayParameter
 	],
@@ -30,12 +34,15 @@ new CLICommand({
 		const dryRun = parameters.isDryRun();
 		const fileId = parameters.getRequiredParameterValue(FileIdParameter, EID);
 		const newParentFolderId = parameters.getRequiredParameterValue(ParentFolderIdParameter, EID);
+		const shouldUseTurbo = !!parameters.getParameterValue(ShouldTurboParameter);
+		const turboUrl = parameters.getTurbo();
 
 		const wallet: Wallet = await parameters.getRequiredWallet();
 		const ardrive = cliArDriveFactory({
 			wallet: wallet,
 			feeMultiple: parameters.getOptionalBoostSetting(),
 			dryRun,
+			turboSettings: shouldUseTurbo ? { turboUrl } : undefined,
 			arweave
 		});