Merge pull request #284 from ardriveapp/dev

PE-1558: Release ArDrive CLI v1.15.0

README.md

@@ -123,11 +123,12 @@ ardrive upload-file --wallet-file /path/to/my/wallet.json --parent-folder-id "f0
         10. [Understanding Bundled Transactions](#bundles)
         11. [Uploading a Non-Bundled Transaction](#no-bundle)
         12. [Fetching the Metadata of a File Entity](#fetching-the-metadata-of-a-file-entity)
-        13. [Moving Files](#moving-files)
-        14. [Uploading Manifests](#uploading-manifests)
-        15. [Hosting a Webpage with Manifest](#hosting-a-webpage-with-manifest)
-        16. [Uploading With a Custom Content Type](#custom-content-type)
-        17. [Uploading a Custom Manifest](#custom-manifest)
+        13. [Retrying a Failed File Data Transaction (Public Unbundled Files Only)](#retry-tx)
+        14. [Moving Files](#moving-files)
+        15. [Uploading Manifests](#uploading-manifests)
+        16. [Hosting a Webpage with Manifest](#hosting-a-webpage-with-manifest)
+        17. [Uploading With a Custom Content Type](#custom-content-type)
+        18. [Uploading a Custom Manifest](#custom-manifest)
     7. [Other Utility Operations](#other-utility-operations)
         1. [Monitoring Transactions](#monitoring-transactions)
         2. [Dealing With Network Congestion](#dealing-with-network-congestion)
@@ -962,6 +963,25 @@ Example output:
 }
 ```
 
+### Retrying a Failed File Data Transaction (Public Unbundled Files Only)<a id="retry-tx"></a>
+
+Arweave data upload transactions are split into two phases: transaction posting and chunks uploading. Once the transaction post phase has been completed, you've effectively "paid" the network for storage of the data chunks that you'll send in the next stage.
+
+If your system encounters an error while posting the transaction, you can retry posting the transaction for as long as your tx_anchor is valid ([learn more about tx_anchors here][tx_anchors]). You may retry and/or resume posting chunks at any time after your transaction has posted. The ArDrive CLI allows you to take advantage of this Arweave protocol capability.
+
+Using the CLI, when the transaction post has succeeded but the chunk upload step fails, the data transaction's ID could be lost. There are a few options to recover this ID. If the failed transaction is the most recent one sent from a wallet, the transaction ID can be recovered with the `ardrive last-tx -w /path/to/wallet` command AFTER the transaction's headers have been mined (It can take 5-10 minutes for the tx-id to become available with the last-tx approach). Other options for finding the partially uploaded transaction's ID include:
+
+-   Using an Arweave gateway GQL http endpoint to search for transactions that belong to the wallet. See this [Arweave GQL Guide][gql-guide] for more info.
+-   Browse the recent transactions associated with the wallet via a block explorer tool like [ViewBlock][viewblock].
+
+In order to re-seed the chunks for an unbundled ArFS data transaction, a user must have the data transaction ID, the original file data, and either a destination folder ID or a valid file ID for the file. Supply that information to the `retry-tx` command like so:
+
+```shell
+ardrive retry-tx --tx-id { Data Transaction ID } --parent-folder-id { Destination Folder ID }  --local-path /path/to/file  --wallet-file /path/to/wallet
+```
+
+**Note: Retry feature is currently only available for PUBLIC unbundled file transactions. It is also perfectly safe to mistakenly re-seed the chunks of a healthy transaction, the transaction will remain stable and the wallet balance will not be affected.**
+
 ### Moving Files<a id="moving-files"></a>
 
 Files can be moved from one folder to another within the same drive. Moving a file is simply the process of uploading a new file metadata revision with an updated File ID <> Parent Folder ID relationship. The following command will move a file from its current location in a public drive to a new parent folder in that drive:
@@ -1306,6 +1326,8 @@ create-manifest
 move-file
 move-folder
 
+retry-tx
+
 
 Read ArFS
 ===========
@@ -1373,3 +1395,6 @@ ardrive <command> --help
 [example-manifest-webpage]: https://arweave.net/qozq9YIUPEHfZhoTp9DkBpJuA_KNULBnfLiMroj5pZI
 [arlocal]: https://github.com/textury/arlocal
 [mozilla-mime-types]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types
+[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

package.json

@@ -1,14 +1,14 @@
 {
 	"name": "ardrive-cli",
-	"version": "1.14.0",
+	"version": "1.15.0",
 	"description": "The ArDrive Command Line Interface (CLI is a Node.js application for terminal-based ArDrive workflows. It also offers utility operations for securely interacting with Arweave wallets and inspecting various Arweave blockchain conditions.",
 	"main": "./lib/index.js",
 	"bin": {
 		"ardrive": "./lib/index.js"
 	},
 	"types": "./lib/index.d.ts",
 	"dependencies": {
-		"ardrive-core-js": "1.13.0",
+		"ardrive-core-js": "1.14.0",
 		"arweave": "1.10.18",
 		"axios": "^0.21.1",
 		"commander": "^8.2.0",

src/commands/index.ts

@@ -26,6 +26,7 @@ import './move_folder';
 import './rename_drive';
 import './rename_file';
 import './rename_folder';
+import './retry_tx';
 import './send_ar';
 import './send_tx';
 import './tx_status';

src/commands/retry_tx.ts

@@ -0,0 +1,90 @@
+import { CLICommand, ParametersHelper } from '../CLICommand';
+import {
+	BoostParameter,
+	ConflictResolutionParams,
+	DestinationFileNameParameter,
+	DryRunParameter,
+	ParentFolderIdParameter,
+	LocalPathParameter,
+	GatewayParameter,
+	CustomContentTypeParameter,
+	TransactionIdParameter,
+	FileIdParameter,
+	WalletTypeParameters
+} from '../parameter_declarations';
+import { SUCCESS_EXIT_CODE } from '../CLICommand/error_codes';
+import { CLIAction } from '../CLICommand/action';
+import { wrapFileOrFolder, EID, TxID } from 'ardrive-core-js';
+import { cliArDriveFactory } from '..';
+import { getArweaveFromURL } from '../utils/get_arweave_for_url';
+
+new CLICommand({
+	name: 'retry-tx',
+	parameters: [
+		LocalPathParameter,
+		{ name: ParentFolderIdParameter, required: false },
+		{ name: FileIdParameter, required: false },
+		DestinationFileNameParameter,
+		BoostParameter,
+		DryRunParameter,
+		...ConflictResolutionParams,
+		CustomContentTypeParameter,
+		GatewayParameter,
+		{
+			name: TransactionIdParameter,
+			description: '(PUBLIC UNBUNDLED FILES ONLY) The transaction ID of the data transaction to retry'
+		},
+		...WalletTypeParameters
+	],
+	action: new CLIAction(async function action(options) {
+		const parameters = new ParametersHelper(options);
+
+		const conflictResolution = parameters.getFileNameConflictResolution();
+		const customContentType = parameters.getParameterValue(CustomContentTypeParameter);
+		const localFilePath = parameters.getRequiredParameterValue<string>(LocalPathParameter);
+
+		const dataTxId = parameters.getRequiredParameterValue(TransactionIdParameter, TxID);
+		const wrappedFile = wrapFileOrFolder(localFilePath, customContentType);
+
+		if (wrappedFile.entityType !== 'file') {
+			throw Error('Retrying folder uploads is not yet supported!');
+		}
+
+		const wallet = await parameters.getRequiredWallet();
+		const arweave = getArweaveFromURL(parameters.getGateway());
+
+		const arDrive = cliArDriveFactory({
+			wallet,
+			feeMultiple: parameters.getOptionalBoostSetting(),
+			dryRun: parameters.isDryRun(),
+			arweave
+		});
+
+		const destinationFolderId = parameters.getParameterValue(ParentFolderIdParameter, EID);
+		const fileId = parameters.getParameterValue(FileIdParameter, EID);
+
+		const results = await (async () => {
+			if (fileId) {
+				return arDrive.retryPublicArFSFileUploadByFileId({
+					wrappedFile,
+					dataTxId,
+					fileId
+				});
+			}
+
+			if (destinationFolderId) {
+				return arDrive.retryPublicArFSFileUploadByDestFolderId({
+					wrappedFile,
+					dataTxId,
+					destinationFolderId,
+					conflictResolution
+				});
+			}
+
+			throw Error('Must provide a file ID or destination folder ID in order to retry and ArFS file transaction');
+		})();
+
+		console.log(JSON.stringify(results, null, 4));
+		return SUCCESS_EXIT_CODE;
+	})
+});

yarn.lock

@@ -1538,7 +1538,7 @@ __metadata:
     "@types/source-map-support": ^0
     "@typescript-eslint/eslint-plugin": ^4.18.0
     "@typescript-eslint/parser": ^4.18.0
-    ardrive-core-js: 1.13.0
+    ardrive-core-js: 1.14.0
     arweave: 1.10.18
     axios: ^0.21.1
     chai: ^4.3.4
@@ -1564,9 +1564,9 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"ardrive-core-js@npm:1.13.0":
-  version: 1.13.0
-  resolution: "ardrive-core-js@npm:1.13.0"
+"ardrive-core-js@npm:1.14.0":
+  version: 1.14.0
+  resolution: "ardrive-core-js@npm:1.14.0"
   dependencies:
     "@alexsasharegan/simple-cache": ^3.3.3
     arbundles: ^0.5.5
@@ -1584,7 +1584,7 @@ __metadata:
     smartweave: ^0.4.45
     utf8: ^3.0.0
     uuid: ^8.3.2
-  checksum: d363267352a24aa2f4ca494dff76facf63722457bad2366b5f90ad7c32d87a8d32a9e502c2923b4c456c911b900157db9bd42ad653c50f1ba34160daff2dc214
+  checksum: 46c4485354e58b7b5b24c98ca2e8f5e9be57f7cc2acc5a30622a2d31d9b2bdd7e6e89b48bb955d065bf1b37824f3b779eaaef948b4d8739d69a10247d1fa5709
   languageName: node
   linkType: hard