chore: release v1.20.0

CHANGELOG.md

@@ -1,13 +1,6 @@
 ## [1.19.2](https://github.com/ardriveapp/turbo-sdk/compare/v1.19.1...v1.19.2) (2024-10-21)
 
 
-### Bug Fixes
-
-* still use relative path for manifest when folderPath inputs with `./` PE-6975 ([23007f7](https://github.com/ardriveapp/turbo-sdk/commit/23007f7115b7699b91110da41581b8023ed6a232))
-
-## [1.19.2-alpha.1](https://github.com/ardriveapp/turbo-sdk/compare/v1.19.1...v1.19.2-alpha.1) (2024-10-17)
-
-
 ### Bug Fixes
 
 * still use relative path for manifest when folderPath inputs with `./` PE-6975 ([23007f7](https://github.com/ardriveapp/turbo-sdk/commit/23007f7115b7699b91110da41581b8023ed6a232))

README.md

@@ -65,6 +65,9 @@ Welcome to the `@ardrive/turbo-sdk`! This SDK provides functionality for interac
       - [Polygon (POL / MATIC) Crypto Top Up](#polygon-pol--matic-crypto-top-up)
       - [Solana (SOL) Crypto Top Up](#solana-sol-crypto-top-up)
       - [KYVE Crypto Top Up](#kyve-crypto-top-up)
+    - [`shareCredits({ approvedAddress, approvedWincAmount, expiresBySeconds })`](#sharecredits-approvedaddress-approvedwincamount-expiresbyseconds-)
+    - [`revokeCredits({ approvedAddress })`](#revokecredits-approvedaddress-)
+    - [`getCreditShareApprovals({ userAddress })`](#getcreditshareapprovals-useraddress-)
 - [CLI](#cli)
   - [Install CLI](#install-cli)
   - [CLI Usage](#cli-usage)
@@ -76,6 +79,10 @@ Welcome to the `@ardrive/turbo-sdk`! This SDK provides functionality for interac
       - [`upload-folder`](#upload-folder)
       - [`upload-file`](#upload-file)
       - [`price`](#price)
+      - [`share-credits`](#share-credits)
+      - [`revoke-credits`](#revoke-credits)
+      - [`list-shares`](#list-shares)
+- [Turbo Credit Sharing](#turbo-credit-sharing)
 - [Developers](#developers)
   - [Requirements](#requirements)
   - [Setup & Build](#setup--build)
@@ -677,6 +684,39 @@ const { winc, status, id, ...fundResult } = await turbo.topUpWithTokens({
 });
 ```
 
+#### `shareCredits({ approvedAddress, approvedWincAmount, expiresBySeconds })`
+
+Shares credits from the connected wallet to the provided native address and approved winc amount. This action will create a signed data item for the approval
+
+```typescript
+const { approvalDataItemId, approvedWincAmount } = await turbo.shareCredits({
+  approvedAddress: '2cor...VUa',
+  approvedWincAmount: 0.08315565032,
+  expiresBySeconds: 3600,
+});
+```
+
+#### `revokeCredits({ approvedAddress })`
+
+Revokes all credits shared from the connected wallet to the provided native address.
+
+```typescript
+const revokedApprovals = await turbo.revokeCredits({
+  approvedAddress: '2cor...VUa',
+});
+```
+
+#### `getCreditShareApprovals({ userAddress })`
+
+Returns all given or received credit share approvals for the connected wallet or the provided native address.
+
+```typescript
+const { givenApprovals, receivedApprovals } =
+  await turbo.getCreditShareApprovals({
+    userAddress: '2cor...VUa',
+  });
+```
+
 ## CLI
 
 ### Install CLI
@@ -723,6 +763,8 @@ npx turbo --help
 
 #### Options
 
+Global options:
+
 - `-V, --version` - output the version number
 - `-h, --help` - display help for command
 - `--dev` - Enable development endpoints (default: false)
@@ -731,10 +773,18 @@ npx turbo --help
 - `--payment-url <url>` - Set a custom payment service URL
 - `-t, --token <token>` - Token type for the command or connected wallet (default: "arweave")
 
+Wallet options:
+
 - `-w, --wallet-file <filePath>` - Wallet file to use with the action. Formats accepted: JWK.json, KYVE, ETH, or POL 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
 
+Upload options:
+
+- `--paid-by <paidBy...>` - A list of native addresses to pay for the upload.
+- `--ignore-approvals` - When no paid by is provided, the CLI will look for and use any received credit share approvals to pay for the upload. This flag will ignore any approvals and only use the connected wallet's balance for upload payment. Default: false
+- `--use-signer-balance-first` - Use the connected wallet's balance before using any credit share approvals for the upload. Default: false
+
 #### Commands
 
 ##### `balance`
@@ -820,7 +870,7 @@ Command Options:
 e.g:
 
 ```shell
-turbo upload-file --file-path '../path/to/my/file.txt' --token ethereum --wallet-file ../path/to/eth/private/key.txt
+turbo upload-file --file-path '../path/to/my/file.txt' --token ethereum --wallet-file ../path/to/eth/private/key.txt --paid-by '0x...first-payer-address' '0x...second-payer-address' '0x...third-payer-address' 'etc...'
 ```
 
 ##### `price`
@@ -846,6 +896,78 @@ turbo price --value 1024 --type bytes
 turbo price --value 1.1 --type arweave
 ```
 
+##### `share-credits`
+
+Shares credits from the connected wallet to the provided native address and approved winc amount.
+
+Command Options:
+
+- `-a, --address <nativeAddress>` - Native address to that will receive the Credits
+- `-v, --value <value>` - Value of winc to share to the target address
+- `-e, --expires-by-seconds <seconds>` - Expiry time in seconds for the credit share approval
+
+e.g:
+
+```shell
+turbo share-credits --address 2cor...VUa --value 0.083155650320 --wallet-file ../path/to/my/wallet --expires-by-seconds 3600
+```
+
+##### `revoke-credits`
+
+Revoke all credits shared from the connected wallet to the provided native address.
+
+Command Options:
+
+- `-a, --address <nativeAddress>` - Native address to revoke credit share approvals for
+
+e.g:
+
+```shell
+turbo revoke-credits --wallet-file ../path/to/my/wallet
+```
+
+##### `list-shares`
+
+List all given and received credit share approvals from the connected wallet or the provided native address.
+
+Command Options:
+
+- `-a, --address <nativeAddress>` - Native address to list credit share approvals for
+
+e.g:
+
+```shell
+turbo list-shares --address 2cor...VUa --wallet-file ../path/to/my/wallet
+```
+
+## Turbo Credit Sharing
+
+Users can share their purchased Credits with other users' wallets by creating Credit Share Approvals. These approvals are created by uploading a signed data item with tags indicating the recipient's wallet address, the amount of Credits to share, and an optional amount of seconds that the approval will expire in. The recipient can then use the shared Credits to pay for their own uploads to Turbo.
+
+Shared Credits cannot be re-shared by the recipient to other recipients. Only the original owner of the Credits can share or revoke Credit Share Approvals. Credits that are shared to other wallets may not be used by the original owner of the Credits for sharing or uploading unless the Credit Share Approval is revoked or expired.
+
+Approvals can be revoked at any time by similarly uploading a signed data item with tags indicating the recipient's wallet address. This will remove all approvals and prevent the recipient from using the shared Credits. All unused Credits from expired or revoked approvals are returned to the original owner of the Credits.
+
+To use the shared Credits, recipient users must provide the wallet address of the user who shared the Credits with them in the `x-paid-by` HTTP header when uploading data. This tells Turbo services to look for and use Credit Share Approvals to pay for the upload before using the signer's balance.
+
+For user convenience, during upload the Turbo CLI will use any available Credit Share Approvals found for the connected wallet before using the signing wallet's balance. To instead ignore all Credit shares and only use the signer's balance, use the `--ignore-approvals` flag. To use the signer's balance first before using Credit shares, use the `--use-signer-balance-first` flag. In contrast, the Turbo SDK layer does not provide this functionality and will only use approvals when `paidBy` is provided.
+
+The Turbo SDK provides the following methods to manage Credit Share Approvals:
+
+- `shareCredits`: Creates a Credit Share Approval for the specified wallet address and amount of Credits.
+- `revokeCredits`: Revokes all Credit Share Approvals for the specified wallet address.
+- `listShares`: Lists all Credit Share Approvals for the specified wallet address or connected wallet.
+- `dataItemOpts: { ...opts, paidBy: string[] }`: Upload methods now accept 'paidBy', an array of wallet addresses that have provided credit share approvals to the user from which to pay, in the order provided and as necessary, for the upload.
+
+The Turbo CLI provides the following commands to manage Credit Share Approvals:
+
+- `share-credits`: Creates a Credit Share Approval for the specified wallet address and amount of Credits.
+- `revoke-credits`: Revokes all Credit Share Approvals for the specified wallet address.
+- `list-shares`: Lists all Credit Share Approvals for the specified wallet address or connected wallet.
+- `paidBy: --paid-by <paidBy...>`: Upload commands now accept '--paid-by', an array of wallet addresses that have provided credit share approvals to the user from which to pay, in the order provided and as necessary, for the upload.
+- `--ignore-approvals`: Ignore all Credit Share Approvals and only use the signer's balance.
+- `--use-signer-balance-first`: Use the signer's balance first before using Credit Share Approvals.
+
 ## Developers
 
 ### Requirements

docker-compose.yml

@@ -1,5 +1,3 @@
-version: '3.0'
-
 services:
   arlocal:
     image: textury/arlocal:v1.1.66

examples/vite/.gitignore

@@ -0,0 +1,23 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

examples/vite/README.md

@@ -0,0 +1,54 @@
+# Typescript React Example - Vite
+
+This example shows how to use the `@ardrive/turbo-sdk` within a Typescript/React project using [Vite].
+
+## Getting Started
+
+1. Install the dependencies:
+
+```bash
+yarn
+```
+
+2. Start the development server:
+
+```bash
+yarn start
+```
+
+3. Open your browser and navigate to `http://localhost:3000`. You should see:
+
+![screenshot](./public/screenshot.png)
+
+## Polyfills
+
+The `@ar.io/sdk` uses some modern browser features that may not be available in all browsers. To ensure compatibility, you may need to include some polyfills. This example uses the [vite-plugin-node-polyfills] plugin to include the necessary polyfills.
+
+The [tsconfig.json](./tsconfig.json) includes the following compiler options:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "Bundler", // or nodenext are recommended to use named exports (e.g. @ardrive/turbo-sdk/web)
+    "lib": ["es2015", "dom"]
+  }
+}
+```
+
+The [vite.config.js](./vite.config.js) file includes the following polyfills required for the `@ardrive/turbo-sdk`:
+
+```javascript
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+import { nodePolyfills } from 'vite-plugin-node-polyfills';
+
+export default defineConfig({
+  build: {},
+  base: '/',
+  plugins: [react(), nodePolyfills()],
+});
+```
+
+If you are using a bundler other than Vite, you may need to include the necessary polyfills in a similar way.
+
+[vite-plugin-node-polyfills]: https://www.npmjs.com/package/vite-plugin-node-polyfills

examples/vite/index.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="theme-color" content="#000000" />
+    <meta
+      name="description"
+      content="Web site created using create-react-app"
+    />
+    <title>React App</title>
+  </head>
+  <body>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>

examples/vite/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "react-typescript-vite",
+  "version": "0.1.0",
+  "private": true,
+  "dependencies": {
+    "@ardrive/turbo-sdk": "^1.19.2",
+    "arweave": "^1.15.5",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^5.17.0",
+    "@testing-library/react": "^13.4.0",
+    "@testing-library/user-event": "^13.5.0",
+    "@types/jest": "^27.5.2",
+    "@types/node": "^16.18.96",
+    "@types/react": "^18.3.1",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.2.1",
+    "starknet": "^6.11.0",
+    "typescript": "^5.3.3",
+    "vite": "^5.2.14",
+    "vite-plugin-html": "^3.2.2",
+    "vite-plugin-node-polyfills": "^0.22.0"
+  },
+  "scripts": {
+    "start": "vite --config vite.config.js",
+    "build": "vite build --config vite.config.js",
+    "postinstall": "yarn link @ardrive/turbo-sdk"
+  }
+}

examples/vite/src/App.css

@@ -0,0 +1,11 @@
+.App {
+  text-align: center;
+  background-color: #f0f0f0;
+}
+
+.markdown {
+  text-align: left;
+  margin: auto;
+  padding: 50px;
+  color: white;
+}

examples/vite/src/App.test.tsx

@@ -0,0 +1,9 @@
+import { render, screen } from '@testing-library/react';
+
+import App from './App';
+
+test('renders learn react link', () => {
+  render(<App />);
+  const linkElement = screen.getByText(/learn react/i);
+  expect(linkElement).toBeInTheDocument();
+});