Merge pull request #5 from Bobinstein/turbo

feat(Turbo): Added ability to use Turbo for uploading data

README.md

@@ -24,7 +24,7 @@ Import the SDK:
 import AtomicToolkit from 'atomic-toolkit';
 ```
 
-## Initialize with Arweave Wallet or Irys SDK
+## Initialize with Arweave Wallet, Irys SDK, or Turbo SDK
 
 Using Arweave Wallet
 
@@ -50,6 +50,55 @@ await irys.ready();
 const toolkit = new AtomicToolkit({ irys });
 ```
 
+Using Turbo Through Irys:
+
+```ts
+import Irys from '@irys/sdk';
+
+const irys = new Irys({
+    url: 'https://up.arweave.net',
+    token: 'matic',
+    key: 'your-private-key',
+});
+
+await irys.ready();
+
+const toolkit = new AtomicToolkit({ irys });
+```
+
+Using Turbo:
+
+```ts
+const { TurboFactory } = require('@ardrive/turbo-sdk');
+const AtomicToolkit = require('atomic-toolkit').default;
+const fs = require('fs');
+
+const jwk = JSON.parse(fs.readFileSync('./KeyFile.json'));
+const turbo = TurboFactory.authenticated({ privateKey: jwk });
+
+const toolkit = new AtomicToolkit({ turbo });
+```
+
+Using Turbo in the web:
+
+```ts
+import { ArconnectSigner } from 'arbundles/web';
+import { TurboFactory } from '@ardrive/turbo-sdk/web';
+import { AtomicToolkitWeb } from 'atomic-toolkit';
+
+async function connectToolkit() {
+    await window.arweaveWallet.connect([
+        'ACCESS_PUBLIC_KEY',
+        'SIGNATURE',
+        'ACCESS_ADDRESS',
+        'SIGN_TRANSACTION',
+    ]);
+    const arConnectSigner = new ArconnectSigner(window.arweaveWallet);
+    const turbo = await TurboFactory.authenticated({ signer: arConnectSigner });
+    const toolkit = new AtomicToolkitWeb({ turbo });
+}
+```
+
 ## Documentation
 
 For a complete overview of available functions and usage examples, please refer to the official documentation: [https://atomictoolkit.mintlify.app](https://atomictoolkit.mintlify.app/introduction)

apps/docs/guides/collection/create-collection.mdx

@@ -39,18 +39,29 @@ For details on the options see the [Create Collection Options](/types-reference/
 
 ### Return Value
 
-The function returns a promise that resolves to `UploadResponse` or `Transaction` depending on whether Irys is used or not.
+The function returns a promise that resolves to `UploadResponse`, `Transaction`, or `TurboUploadDataItemResponse` depending on whether Irys or Turbo are used or not.
 
--   `UploadResonse` - Returned when Irys is used. It contains feilds such as:
+-   `UploadResponse` - Returned when Irys is used. It contains fields such as:
     -   **id: `string`** - The transaction ID of the collection.
     -   **signature: `string`** - The signature used while creating the collection.
     -   **timestamp: `number`** - The timestamp of the transaction.
--   `Transaction` - Returned when Arweave is used. It contains feilds such as:
+-   `Transaction` - Returned when Arweave is used. It contains fields such as:
     -   **id: `string`** - The transaction ID of the collection.
     -   **owner: `string`** - The owner of the collection.
     -   **tags: `Tag[]`** - The tags of the collection.
     -   **data: `Uint8Array`** - The data of the collection.
     -   **signature: `string`** - The signature used while creating the collection.
+-   `TurboUploadDataItemResponse` - Returned when Turbo is used. It contains fields such as: 
+    -   **id: `string`** - The transaction ID of the collection,
+    -   **timestamp: `number`** - The timestamp of the transaction,
+    -   **winc: `string`** - The amount of Turbo Credits, in Winston Credits, spent on the upload,
+    -   **version: `string`** - The version number of the upload receipt returned,
+    -   **deadlineHeight: `number`** - The latest block height in which the uploaded data will be settled on Arweave,
+    -   **dataCaches: `array`** - A list of nodes where the data was cached while upload to Arweave is pending,
+    -   **fastFinalityIndexes: `array`** - A list of nodes where data is made available while waiting for it to settle on Arweave,
+    -   **public: `string`** - The public key of the wallet used for upload,
+    -   **signature: `string`** - The signature used while creating the collection,
+    -   **owner: `string`** - The owner of the collection.
 
 ### Example Usage
 
@@ -123,18 +134,30 @@ For details on the options see the [Create Collection Options](/types-reference/
 
 ### Return Value
 
-The function returns a function called `mutateAsync` which when called returns a promise that will resolve to `UploadResponse` or `Transaction` depending on whether Irys is used or not.
+The function returns a function called `mutateAsync` which when called returns a promise that will resolve to `UploadResponse`, `Transaction`, or `TurboUploadDataItemResponse` depending on whether Irys or Turbo are used or not.
 
--   `UploadResonse` - Returned when Irys is used. It contains feilds such as:
+-   `UploadResponse` - Returned when Irys is used. It contains fields such as:
     -   **id: `string`** - The transaction ID of the collection.
     -   **signature: `string`** - The signature used while creating the collection.
     -   **timestamp: `number`** - The timestamp of the transaction.
--   `Transaction` - Returned when Arweave is used. It contains feilds such as:
+-   `Transaction` - Returned when Arweave is used. It contains fields such as:
     -   **id: `string`** - The transaction ID of the collection.
     -   **owner: `string`** - The owner of the collection.
     -   **tags: `Tag[]`** - The tags of the collection.
     -   **data: `Uint8Array`** - The data of the collection.
     -   **signature: `string`** - The signature used while creating the collection.
+-   `TurboUploadDataItemResponse` - Returned when Turbo is used. It contains fields such as: 
+    -   **id: `string`** - The transaction ID of the collection,
+    -   **timestamp: `number`** - The timestamp of the transaction,
+    -   **winc: `string`** - The amount of Turbo Credits, in Winston Credits, spent on the upload,
+    -   **version: `string`** - The version number of the upload receipt returned,
+    -   **deadlineHeight: `number`** - The latest block height in which the uploaded data will be settled on Arweave,
+    -   **dataCaches: `array`** - A list of nodes where the data was cached while upload to Arweave is pending,
+    -   **fastFinalityIndexes: `array`** - A list of nodes where data is made available while waiting for it to settle on Arweave,
+    -   **public: `string`** - The public key of the wallet used for upload,
+    -   **signature: `string`** - The signature used while creating the collection,
+    -   **owner: `string`** - The owner of the collection.
+
 
 <Note>
     You don't need to include the _banner_ and _thumbnail_ feilds in the

apps/docs/guides/utilities/get-upload-cost.mdx

@@ -68,3 +68,22 @@ const costWithIrys = await toolkit.utils.getUploadCost(10 ** 9); // 1 GB
     }
 }
 ```
+
+```json
+// With Turbo
+{
+  token: 'turbo',
+  cost: { 
+    atomic: '164313830', 
+    formatted: '0.00016431383' 
+  },
+  balance: { 
+    atomic: '517190608', 
+    formatted: '0.000517190608' 
+  },
+  additional: { 
+    atomic: '0', 
+    formatted: '0' 
+  }
+}
+```

apps/docs/guides/utilities/upload-data.mdx

@@ -23,18 +23,29 @@ The function takes in a object containing the following parameters:
 
 ## Return Value
 
-The function returns a promise that resolves to `UploadResponse` or `Transaction` depending on whether Irys is used or not.
+The function returns a promise that resolves to `UploadResponse`, `Transaction`, or `TurboUploadDataItemResponse` depending on whether Irys or Turbo are used or not.
 
--   `UploadResonse` - Returned when Irys is used. It contains feilds such as:
+-   `UploadResponse` - Returned when Irys is used. It contains fields such as:
     -   **id: `string`** - The transaction ID of the collection.
     -   **signature: `string`** - The signature used while creating the collection.
     -   **timestamp: `number`** - The timestamp of the transaction.
--   `Transaction` - Returned when Arweave is used. It contains feilds such as:
+-   `Transaction` - Returned when Arweave is used. It contains fields such as:
     -   **id: `string`** - The transaction ID of the collection.
     -   **owner: `string`** - The owner of the collection.
     -   **tags: `Tag[]`** - The tags of the collection.
     -   **data: `Uint8Array`** - The data of the collection.
     -   **signature: `string`** - The signature used while creating the collection.
+-   `TurboUploadDataItemResponse` - Returned when Turbo is used. It contains fields such as: 
+    -   **id: `string`** - The transaction ID of the collection,
+    -   **timestamp: `number`** - The timestamp of the transaction,
+    -   **winc: `string`** - The amount of Turbo Credits, in Winston Credits, spent on the upload,
+    -   **version: `string`** - The version number of the upload receipt returned,
+    -   **deadlineHeight: `number`** - The latest block height in which the uploaded data will be settled on Arweave,
+    -   **dataCaches: `array`** - A list of nodes where the data was cached while upload to Arweave is pending,
+    -   **fastFinalityIndexes: `array`** - A list of nodes where data is made available while waiting for it to settle on Arweave,
+    -   **public: `string`** - The public key of the wallet used for upload,
+    -   **signature: `string`** - The signature used while creating the collection,
+    -   **owner: `string`** - The owner of the collection.
 
 ## Example
 

apps/docs/usage/browser.mdx

@@ -9,6 +9,7 @@ This section walks through the steps to use Atomic Toolkit in a browser applicat
 
 1. Using Injected Arweave Wallet
 2. Using WebIrys
+3. Using Turbo
 
 ## Using Injected Arweave Wallet
 
@@ -150,3 +151,32 @@ const webIrys = await getWebIrys();
 
 const toolkit = new AtomicToolkitWeb({ warp: warp, irys: webIrys });
 ```
+
+## Using Turbo
+
+This uses an authenticated Turbo instance for uploading data using Turbo credits.
+
+```ts
+import { ArconnectSigner } from 'arbundles/web';
+import { TurboFactory } from '@ardrive/turbo-sdk/web';
+import { AtomicToolkitWeb } from 'atomic-toolkit';
+
+async function connectToolkit() {
+    await window.arweaveWallet.connect([
+        'ACCESS_PUBLIC_KEY',
+        'SIGNATURE',
+        'ACCESS_ADDRESS',
+        'SIGN_TRANSACTION',
+    ]);
+    const arConnectSigner = new ArconnectSigner(window.arweaveWallet);
+    const turbo = await TurboFactory.authenticated({ signer: arConnectSigner });
+    const toolkit = new AtomicToolkitWeb({ turbo });
+}
+```
+
+### Input Parameters
+
+The following params are available and they must be passed in as an object:
+
+-   **warp (optional)**: `Warp`: A Warp Instance to use with Deploy Plugin. If not provided, the default Warp instance for Mainnet will be used.
+-   **turbo**: `TurboAuthenticatedClient`: An authenticated Turbo Instance to use for uploading data.

apps/docs/usage/server-side.mdx

@@ -165,3 +165,23 @@ const toolkit = new AtomicToolkit({
     warp,
 });
 ```
+
+## Using Turbo SDK
+
+```ts
+import { TurboFactory } from '@ardrive/turbo-sdk';
+import AtomicToolkit from 'atomic-toolkit';
+import fs from 'fs';
+
+const jwk = JSON.parse(fs.readFileSync('./KeyFile.json'));
+
+const turbo = TurboFactory.authenticated({ privateKey: jwk });
+const toolkit = new AtomicToolkit({ turbo });
+```
+
+### Input Parameters
+
+The following params are available for this function and they must be passed in as an object:
+
+-   **warp (optional)**: `Warp`: A Warp Instance to use with Deploy Plugin. If not provided, the default Warp instance for Mainnet will be used.
+-   **turbo**: An authenticated Turbo instance to use for uploading with Turbo.

packages/atomic-toolkit/package.json

@@ -54,6 +54,7 @@
         "access": "public"
     },
     "dependencies": {
+        "@ardrive/turbo-sdk": "^1.3.0",
         "@irys/sdk": "^0.1.1",
         "arbundles": "^0.10.0",
         "arweave": "^1.14.4",

packages/atomic-toolkit/src/base.ts

@@ -8,22 +8,25 @@ import { getConfig } from './lib/config';
 // Types
 import * as Types from './types';
 import { JWKInterface } from 'arweave/node/lib/wallet';
+import { TurboAuthenticatedClientInterface } from '@ardrive/turbo-sdk';
 
 class AtomicToolkitBase {
     protected warp: Warp;
     protected arweaveInstance: Arweave;
     protected irys: WebIrys | Irys | null | undefined;
     protected key: JWKInterface | 'use_wallet' | null;
+    protected turbo: TurboAuthenticatedClientInterface | null | undefined;
 
     constructor(
         opts: Types.AtomicToolkitNodeOpts | Types.AtomicToolkitWebOpts,
     ) {
-        const { warp, arweave, irys, key } = getConfig(opts);
+        const { warp, arweave, irys, key, turbo } = getConfig(opts);
 
         this.warp = warp;
         this.arweaveInstance = arweave;
         this.irys = irys;
         this.key = key;
+        this.turbo = turbo;
     }
 }
 

packages/atomic-toolkit/src/lib/collection/index.ts

@@ -23,6 +23,7 @@ import type { Tag } from 'arbundles';
 import * as Types from '../../types';
 import Transaction from 'arweave/node/lib/transaction';
 import { UploadResponse } from '@irys/sdk/build/cjs/common/types';
+import { TurboUploadDataItemResponse } from '@ardrive/turbo-sdk';
 
 class Collection extends ModuleBase {
     protected assets: AtomicAssets;
@@ -38,7 +39,7 @@ class Collection extends ModuleBase {
 
     public async createCollectionWithAssetIds(
         opts: Types.CreateCollectionWithAssetIdsOpts,
-    ): Promise<UploadResponse | Transaction> {
+    ): Promise<UploadResponse | Transaction | TurboUploadDataItemResponse> {
         const data = {
             type: 'Collection',
             items: opts.assetIds,

packages/atomic-toolkit/src/lib/config.ts

@@ -3,6 +3,7 @@ import { Warp, WarpFactory } from 'warp-contracts';
 import { DeployPlugin } from 'warp-contracts-plugin-deploy';
 import Irys, { WebIrys } from '@irys/sdk';
 import { JWKInterface } from 'arbundles';
+import { TurboAuthenticatedClientInterface, TurboFactory} from '@ardrive/turbo-sdk';
 
 import * as Types from '../types';
 
@@ -24,6 +25,7 @@ export const getConfig = (
     let baseArweave: Arweave;
     let baseIrys: WebIrys | Irys | null | undefined;
     let baseKey: JWKInterface | 'use_wallet' | null;
+    let baseTurbo: TurboAuthenticatedClientInterface | null;
     const { warp, ...props } = opts;
 
     if (warp) {
@@ -42,19 +44,28 @@ export const getConfig = (
         baseIrys = irys;
         baseArweave = defaultArweave;
         baseKey = null;
+        baseTurbo = null;
+    } else if (typeof props === 'object' && 'turbo' in props) {
+        const { turbo } = props as Types.AtomicToolkitWithTurbo;
+        baseTurbo = turbo ?? null;
+        baseArweave = defaultArweave;
+        baseKey = null;
+        baseIrys = null;
     } else {
         const { arweave, key } = props as
             | Types.AtomicToolkitWithArweave
             | Types.AtomicToolkitWebWithArweave;
         baseArweave = arweave ?? defaultArweave;
         baseKey = key ?? 'use_wallet';
         baseIrys = null;
+        baseTurbo = null;
     }
 
     return {
         warp: baseWarp,
         arweave: baseArweave,
         irys: baseIrys,
         key: baseKey,
+        turbo: baseTurbo,
     };
 };

packages/atomic-toolkit/src/lib/index.ts

@@ -2,6 +2,7 @@ import Arweave from 'arweave';
 import { Warp } from 'warp-contracts';
 import { JWKInterface } from 'arbundles';
 import Irys, { WebIrys } from '@irys/sdk';
+import { TurboAuthenticatedClientInterface, TurboUnauthenticatedClientInterface } from '@ardrive/turbo-sdk';
 
 import * as Types from '../types';
 
@@ -10,12 +11,14 @@ class ModuleBase {
     protected arweave: Arweave;
     protected irys: WebIrys | Irys | null;
     protected key: JWKInterface | 'use_wallet' | null;
+    protected turbo: TurboAuthenticatedClientInterface | null
 
     constructor(opts: Types.ModuleOpts) {
         this.warp = opts.warp;
         this.arweave = opts.arweave;
         this.irys = opts.irys;
         this.key = opts.key;
+        this.turbo = opts.turbo
     }
 }