Merge pull request #138 from ardriveapp/kyve-docs

docs: CLI and KYVE

README.md

@@ -31,6 +31,8 @@ Welcome to the `@ardrive/turbo-sdk`! This SDK provides functionality for interac
       - [Ethereum Private Key](#ethereum-private-key)
       - [HexSolanaSigner](#hexsolanasigner)
       - [Solana Secret Key](#solana-secret-key)
+      - [KYVE Private Key](#kyve-private-key)
+      - [KYVE Mnemonic](#kyve-mnemonic)
   - [TurboUnauthenticatedClient](#turbounauthenticatedclient)
     - [`getSupportedCurrencies()`](#getsupportedcurrencies)
     - [`getSupportedCountries()`](#getsupportedcountries)
@@ -40,9 +42,10 @@ Welcome to the `@ardrive/turbo-sdk`! This SDK provides functionality for interac
     - [`getUploadCosts({ bytes })`](#getuploadcosts-bytes-)
     - [`uploadSignedDataItem({ dataItemStreamFactory, dataItemSizeFactory, signal })`](#uploadsigneddataitem-dataitemstreamfactory-dataitemsizefactory-signal-)
     - [`createCheckoutSession({ amount, owner })`](#createcheckoutsession-amount-owner-)
-      - [Arweave (AR)](#arweave-ar)
-      - [Ethereum (ETH)](#ethereum-eth)
-      - [Solana (SOL)](#solana-sol)
+      - [Arweave (AR) Fiat Top Up](#arweave-ar-fiat-top-up)
+      - [Ethereum (ETH) Fiat Top Up](#ethereum-eth-fiat-top-up)
+      - [Solana (SOL) Fiat Top Up](#solana-sol-fiat-top-up)
+      - [KYVE Fiat Top Up](#kyve-fiat-top-up)
     - [`submitFundTransaction({ txId })`](#submitfundtransaction-txid-)
   - [TurboAuthenticatedClient](#turboauthenticatedclient)
     - [`getBalance()`](#getbalance)
@@ -53,8 +56,16 @@ Welcome to the `@ardrive/turbo-sdk`! This SDK provides functionality for interac
       - [NodeJS Upload Folder](#nodejs-upload-folder)
       - [Browser Upload Folder](#browser-upload-folder)
     - [`topUpWithTokens({ tokenAmount, feeMultiplier })`](#topupwithtokens-tokenamount-feemultiplier-)
-      - [Ethereum (ETH)](#ethereum-eth-1)
-      - [Solana (SOL)](#solana-sol-1)
+      - [Arweave (AR) Crypto Top Up](#arweave-ar-crypto-top-up)
+      - [Ethereum (ETH) Crypto Top Up](#ethereum-eth-crypto-top-up)
+      - [Solana (SOL) Crypto Top Up](#solana-sol-crypto-top-up)
+      - [KYVE Crypto Top Up](#kyve-crypto-top-up)
+- [CLI](#cli)
+  - [Install CLI](#install-cli)
+  - [CLI Usage](#cli-usage)
+    - [Options](#options)
+    - [Commands](#commands)
+      - [`crypto-fund`](#crypto-fund)
 - [Developers](#developers)
   - [Requirements](#requirements)
   - [Setup & Build](#setup--build)
@@ -268,6 +279,26 @@ const turbo = TurboFactory.authenticated({
 });
 ```
 
+##### KYVE Private Key
+
+```typescript
+const turbo = TurboFactory.authenticated({
+  privateKey: kyveHexadecimalPrivateKey,
+  token: 'kyve',
+});
+```
+
+##### KYVE Mnemonic
+
+```typescript
+import { privateKeyFromKyveMnemonic } from '@ardrive/turbo-sdk';
+
+const turbo = TurboFactory.authenticated({
+  privateKey: privateKeyFromKyveMnemonic(mnemonic),
+  token: 'kyve',
+});
+```
+
 ### TurboUnauthenticatedClient
 
 #### `getSupportedCurrencies()`
@@ -341,7 +372,7 @@ const uploadResponse = await turbo.uploadSignedDataItem({
 
 Creates a Stripe checkout session for a Turbo Top Up with the provided amount, currency, owner. The returned URL can be opened in the browser, all payments are processed by Stripe. To leverage promo codes, see [TurboAuthenticatedClient].
 
-##### Arweave (AR)
+##### Arweave (AR) Fiat Top Up
 
 ```typescript
 const { url, winc, paymentAmount, quotedPaymentAmount, adjustments } =
@@ -364,7 +395,7 @@ if (process.platform === 'darwin') {
 }
 ```
 
-##### Ethereum (ETH)
+##### Ethereum (ETH) Fiat Top Up
 
 ```ts
 const turbo = TurboFactory.unauthenticated({ token: 'ethereum' });
@@ -375,7 +406,7 @@ const { url, winc, paymentAmount } = await turbo.createCheckoutSession({
 });
 ```
 
-##### Solana (SOL)
+##### Solana (SOL) Fiat Top Up
 
 ```ts
 const turbo = TurboFactory.unauthenticated({ token: 'solana' });
@@ -386,6 +417,17 @@ const { url, winc, paymentAmount } = await turbo.createCheckoutSession({
 });
 ```
 
+##### KYVE Fiat Top Up
+
+```ts
+const turbo = TurboFactory.unauthenticated({ token: 'kyve' });
+
+const { url, winc, paymentAmount } = await turbo.createCheckoutSession({
+  amount: USD(10.0), // $10.00 USD
+  owner: publicKyveAddress,
+});
+```
+
 #### `submitFundTransaction({ txId })`
 
 Submits the transaction ID of a funding transaction to Turbo Payment Service for top up processing. The `txId` is the transaction ID of the transaction to be submitted.
@@ -536,6 +578,8 @@ Tops up the connected wallet with Credits by submitting a payment transaction fo
 - The `tokenAmount` is the amount of tokens in the token type's smallest unit value (e.g: Winston for arweave token type) to fund the wallet with.
 - The `feeMultiplier` (optional) is the multiplier to apply to the reward for the transaction to modify its chances of being mined. Credits will be added to the wallet balance after the transaction is confirmed on the given blockchain. Defaults to 1.0, meaning no multiplier.
 
+##### Arweave (AR) Crypto Top Up
+
 ```typescript
 const turbo = TurboFactory.authenticated({ signer, token: 'arweave' });
 
@@ -545,7 +589,7 @@ const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
 });
 ```
 
-##### Ethereum (ETH)
+##### Ethereum (ETH) Crypto Top Up
 
 ```ts
 const turbo = TurboFactory.authenticated({ signer, token: 'ethereum' });
@@ -555,7 +599,7 @@ const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
 });
 ```
 
-##### Solana (SOL)
+##### Solana (SOL) Crypto Top Up
 
 ```ts
 const turbo = TurboFactory.authenticated({ signer, token: 'solana' });
@@ -565,6 +609,88 @@ const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
 });
 ```
 
+##### KYVE Crypto Top Up
+
+```ts
+const turbo = TurboFactory.authenticated({ signer, token: 'kyve' });
+
+const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
+  tokenAmount: KYVEToTokenAmount(0.00001), // 0.00001 KYVE
+});
+```
+
+## CLI
+
+### Install CLI
+
+Global installation:
+
+```shell
+npm install -g @ardrive/turbo-sdk
+```
+
+or
+
+```shell
+yarn global add @ardrive/turbo-sdk
+```
+
+or install locally as a dev dependency:
+
+```shell
+npm install --save-dev @ardrive/turbo-sdk
+```
+
+or
+
+```shell
+yarn add -D @ardrive/turbo-sdk
+```
+
+### CLI Usage
+
+```shell
+turbo --help
+```
+
+or from local installation:
+
+```shell
+yarn turbo --help
+```
+
+```shell
+npx turbo --help
+```
+
+#### Options
+
+- `-V, --version` - output the version number
+- `-h, --help` - display help for command
+- `--dev` - Enable development endpoints (default: false)
+- `-g, --gateway <url>` - Set a custom crypto gateway URL
+- `-t, --token <token>` - Token type for the command or connected wallet (default: "arweave")
+
+- `-w, --wallet-file <filePath>` - Wallet file to use with the action. Formats accepted: JWK.json, KYVE or ETH private key as a string, or SOL Secret Key as a Uint8Array
+- `-m, --mnemonic <phrase>` - Mnemonic to use with the action (KYVE only)
+- `-p, --private-key <key>` - Private key to use with the action
+
+#### Commands
+
+##### `crypto-fund`
+
+Fund a wallet with Turbo Credits by submitting a payment transaction for the crypto amount to the Turbo wallet and then submitting that transaction id to Turbo Payment Service for top up processing.
+
+Command Options:
+
+- `-v, --value <value>` - Amount of tokens in the token type's smallest unit value to fund the wallet with
+
+e.g:
+
+```shell
+turbo crypto-fund --value 0.0001 --token kyve --private-key 'b27...45c'
+```
+
 ## Developers
 
 ### Requirements

bundle.mjs

@@ -20,6 +20,7 @@ const bundle = () => {
         },
       }),
     ],
+    external: ['commander'],
     tsconfig: './tsconfig.web.json',
     outfile: './bundles/web.bundle.min.js',
   })

src/cli/cli.ts

@@ -62,7 +62,7 @@ applyOptions(
 
 applyOptions(
   program.command('crypto-fund').description('Top up a wallet with crypto'),
-  [...walletOptions, optionMap.token, optionMap.value],
+  [...walletOptions, optionMap.value],
 ).action(async (_commandOptions, command: Command) => {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const options: any = command.optsWithGlobals();
@@ -88,7 +88,7 @@ applyOptions(
 });
 
 if (
-  process.argv[1].includes('.bin/turbo') || // Running from global .bin
+  process.argv[1].includes('bin/turbo') || // Running from global .bin
   process.argv[1].includes('cli/cli') // Running from source
 ) {
   program.parse(process.argv);

src/cli/utils.ts

@@ -101,6 +101,7 @@ export const globalOptions = [
   optionMap.gateway,
   optionMap.debug,
   optionMap.quiet,
+  optionMap.token,
 ];
 
 export function applyOptions(
@@ -149,6 +150,7 @@ export async function privateKeyFromOptions(
     if (token === 'kyve') {
       return privateKeyFromKyveMnemonic(mnemonic);
     } else {
+      // TODO: Implement other token types mnemonic to wallet
       throw new Error(
         'mnemonic provided but this token type mnemonic to wallet is not supported',
       );
@@ -160,8 +162,10 @@ export async function privateKeyFromOptions(
   } else if (privateKey !== undefined) {
     return privateKey;
   }
+  // TODO: Get TURBO_WALLET_FILE, TURBO_MNEMONIC, TURBO_PRIVATE_KEY or similar from ENV variables
+  // TODO: Add prompts for selecting wallet type and secure input
 
-  throw new Error('mnemonic or wallet file required');
+  throw new Error('mnemonic or wallet file or private key is required');
 }
 
 const tokenToDevGatewayMap: Record<TokenType, string> = {