@tari-project/tarijs 0.4.1 → 0.4.2

package/.github/workflows/ci.yml

@@ -22,4 +22,5 @@ jobs:
         with:
           auto-install: true
       - run: pnpm install
-      - run: moon :build
+      - run: moon :build
+      - run: moon :test

package/.github/workflows/documentation-deploy.yml

@@ -0,0 +1,44 @@
+name: Deploy documentation to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: 'moonrepo/setup-toolchain@v0'
+        with:
+          auto-install: true
+      - run: pnpm install
+      - run: moon tari-docs:build
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docusaurus/tari-docs/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/.github/workflows/documentation-test-deploy.yml

@@ -0,0 +1,20 @@
+name: Test documentation deployment
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test-deploy:
+    name: Test documentation deployment
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: 'moonrepo/setup-toolchain@v0'
+        with:
+          auto-install: true
+      - run: pnpm install
+      - run: moon tari-docs:build

package/.moon/workspace.yml

@@ -14,6 +14,7 @@ $schema: 'https://moonrepo.dev/schemas/workspace.json'
 projects:
   - 'apps/*'
   - 'packages/*'
+  - 'docusaurus/*'
 
 
 

package/README.md

@@ -45,3 +45,22 @@ moon tarijs:build
 ```
 The distribution files will be under the `example/dist` folder. 
 
+## Documentation
+
+This monorepo includes a documentation site located in the `docusaurus` folder.  It's built using [Docusaurus](https://docusaurus.io/) and generates a static website.
+
+### Modifying the Documentation
+
+To start the documentation site:
+
+```bash
+$ moon tari-docs:start
+```
+
+This will open the documentation site in your browser at `http://localhost:3000/tari.js/`
+
+You can now update the documentation by editing files in the `docusaurus/tari-docs/docs/` folder. Changes will be reflected automatically.
+
+### Publishing documentation
+
+The documentation is hosted on GitHub Pages and served from the `/docs` folder of the `gh-pages` branch. The `documentation-deploy.yml` workflow defines the deployment process.

package/docusaurus/tari-docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

package/docusaurus/tari-docs/docs/index.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 1
+slug: /
+---
+
+# Overview
+
+This is the documentation of `tari.js` library, which enables interaction with Tari L2 (Ootle) wallet using TypeScript or JavaScript.
+
+At its core, `TariProvider` is an abstract interface implemented by multiple concrete providers. To access a wallet, you need to create an instance of one of these providers:
+
+* [Tari WalletConnect provider](./providers/wallet-connect.md)
+* [Tari Universe provider](./providers/tari-universe.md)
+* [Tari Wallet Daemon provider](./providers/wallet-daemon.md)
+* Tari Metamask provider
+

package/docusaurus/tari-docs/docs/installation.md

@@ -0,0 +1,27 @@
+---
+sidebar_position: 2
+title: Installation
+---
+
+# Installation
+
+`tari.js` consists of a set of [packages](https://github.com/tari-project/tari.js/tree/main/packages).
+
+Usually, you will need to install the base package and at least one package that implements a concrete provider.
+
+## Install base package
+
+```bash npm2yarn
+npm install @tari-project/tarijs
+```
+
+## Install a provider
+
+For this documentation, we will use the `Wallet Daemon Provider`, which allows direct connection to the wallet if you are hosting it locally.
+However, you are free to install any other available provider.
+
+```bash npm2yarn
+npm install @tari-project/wallet-daemon-provider
+```
+
+We will review all providers on their dedicated pages.

package/docusaurus/tari-docs/docs/providers/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Providers",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "List of all available providers."
+  }
+}

package/docusaurus/tari-docs/docs/providers/tari-universe.md

@@ -0,0 +1,27 @@
+---
+sidebar_position: 2
+---
+
+# Tari Universe provider
+
+This provider is designed for building Tari Universe apps.
+
+## Install required dependencies
+
+```bash npm2yarn
+npm install @tari-project/tari-universe-provider @tari-project/tari-permissions
+```
+
+## Establish the connection
+
+```js
+import { TariPermissions } from "@tari-project/tari-permissions";
+import { TariUniverseProvider } from "@tari-project/tari-universe-provider";
+
+const permissions = new TariPermissions().addPermission("Admin");
+const optionalPermissions = new TariPermissions();
+const provider = new TariUniverseProvider({
+  permissions,
+  optionalPermissions,
+});
+```

package/docusaurus/tari-docs/docs/providers/wallet-connect.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 1
+---
+
+
+# WalletConnect provider
+
+[WalletConnect](https://walletconnect.network/) is an open-source protocol that lets users connect their cryptocurrency wallets to decentralized applications (dApps) in a secure way. It uses QR codes or deep linking to establish a connection between the wallet and the dApp, allowing users to interact with dApps without exposing their private keys.
+
+## Install required dependencies
+
+```bash npm2yarn
+npm install @tari-project/wallet-connect-provider
+```
+
+`WalletConnect` provider is browser only. This means it requires user interaction.
+
+Establishing connection requires multiple steps.
+
+## Obtain WalletConnect Project ID
+
+Obtain a WalletConnect Project ID by registering your project on the WalletConnect Cloud. This ID is then used to connect your dApp to the WalletConnect infrastructure, facilitating communication between the dApp and user wallets.
+
+## Request a connection and display wallet connect dialog
+
+```js
+import { WalletConnectTariProvider } from "@tari-project/wallet-connect-provider";
+
+const projectId = "1825b9dd9c17b5a33063ae91cbc48a6e";
+const provider = new WalletConnectTariProvider(projectId);
+await provider.connect();
+```
+
+You should see `WalletConnect` dialog:
+
+![WalletConnect](/img/tari/wallet-connect-1.png)
+
+## Copy connection link to clipboard
+
+Click the copy link icon in the top right corner.
+
+## Authorize the connection in your wallet
+
+Authorize the connection by clicking `Connect with WalletConnect` button in your wallet.
+
+![WalletConnect](/img/tari/wallet-connect-2.png)
+
+![WalletConnect](/img/tari/wallet-connect-3.png)
+
+## Success!
+
+Go back to your web application, and the connection should now be established.

package/docusaurus/tari-docs/docs/providers/wallet-daemon.md

@@ -0,0 +1,37 @@
+---
+sidebar_position: 3
+---
+
+# Wallet daemon provider
+
+This is the only provider that works in both Node.js and browser environments. It enables a direct connection to a wallet via JSON-RPC.
+
+## Install required dependencies
+
+```bash npm2yarn
+npm install @tari-project/wallet-daemon-provider @tari-project/tari-permissions
+```
+
+## Establish and test the connection
+
+```js
+import { TariPermissions } from "@tari-project/tari-permissions";
+import { WalletDaemonTariProvider } from "@tari-project/wallet-daemon-provider";
+
+const permissions = new TariPermissions().addPermission("Admin");
+const serverUrl = "http://127.0.0.1:12010/json_rpc";
+const provider = await WalletDaemonTariProvider.buildFetchProvider({
+  permissions,
+  serverUrl,
+});
+
+// Test connection
+const account = await provider.getAccount();
+console.log(`Account address: ${account.address}`);
+```
+
+If the connection is successful, it should output an account address similar to the following:
+
+```txt
+Account id: component_24b679b98056c7ca7e3d9f9266fec928c7f29d35e7aec546ed69f532aff40710
+```

package/docusaurus/tari-docs/docs/wallet/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Interaction with the wallet",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Features of TariProvider."
+  }
+}

package/docusaurus/tari-docs/docs/wallet/default-account.md

@@ -0,0 +1,51 @@
+---
+sidebar_position: 1
+---
+
+# Account
+
+The provider is linked to an account in your wallet.
+
+```js
+const account = await provider.getAccount();
+```
+
+This call returns the account details:
+
+```json
+{
+  "account_id": 1,
+  "address": "component_24b679b98056c7ca7e3d9f9266fec928c7f29d35e7aec546ed69f532aff40710",
+  "public_key": "a6534c991a5c034b2f81af809b9577fe6b5425f810de292c0a4d4d43793a8f50",
+  "resources": [
+    {
+      "type": "Confidential",
+      "resource_address": "resource_0101010101010101010101010101010101010101010101010101010101010101",
+      "balance": 999999643,
+      "vault_id": "vault_24b679b98056c7ca7e3d9f9266fec928c7f29d35bf23f7b434c7e61c4d0b7057",
+      "token_symbol": "XTR"
+    },
+    {
+      "type": "Fungible",
+      "resource_address": "resource_217d58767480fbaa48693e11de34baf7fd727e33ee7627f0c4e5b78def378e57",
+      "balance": 990,
+      "vault_id": "vault_24b679b98056c7ca7e3d9f9266fec928c7f29d35ba5d265d0bfc518baa4de2fa",
+      "token_symbol": "token-a"
+    },
+    {
+      "type": "Fungible",
+      "resource_address": "resource_9cdad1188895b080885a64abb71a66a4a4cb1d81d1a55f018a0472b91ee2b47b",
+      "balance": 990,
+      "vault_id": "vault_24b679b98056c7ca7e3d9f9266fec928c7f29d352289e045361315cf27335067",
+      "token_symbol": "token-b"
+    },
+    {
+      "type": "Fungible",
+      "resource_address": "resource_c3df71792220ec8f3d3896991d49e100096020f8e26bce2cd16ba5c27831f988",
+      "balance": 20,
+      "vault_id": "vault_24b679b98056c7ca7e3d9f9266fec928c7f29d35f2bfd6b4ca0aa2ba2fcc4769",
+      "token_symbol": "LP"
+    }
+  ]
+}
+```

package/docusaurus/tari-docs/docs/wallet/get-substate.md

@@ -0,0 +1,110 @@
+---
+sidebar_position: 4
+---
+
+# Get substate
+
+It is possible to get substate details by substate address:
+
+```js
+const substateAddress = "component_9cdad1188895b080885a64abb71a66a4a4cb1d8117679d85c8b35a4ec5d02243";
+const substate = await provider.getSubstate(substateAddress);
+```
+
+```json
+{
+  "value": {
+    "substate": {
+      "Component": {
+        "access_rules": {
+          "default": "AllowAll",
+          "method_access": {}
+        },
+        "body": {
+          "state": {
+            "Map": [
+              [
+                {
+                  "Text": "vault"
+                },
+                {
+                  "Tag": [
+                    132,
+                    {
+                      "Bytes": [
+                        156,
+                        218,
+                        209,
+                        24,
+                        136,
+                        149,
+                        176,
+                        128,
+                        136,
+                        90,
+                        100,
+                        171,
+                        183,
+                        26,
+                        102,
+                        164,
+                        164,
+                        203,
+                        29,
+                        129,
+                        22,
+                        248,
+                        9,
+                        1,
+                        100,
+                        31,
+                        71,
+                        132,
+                        87,
+                        88,
+                        252,
+                        4
+                      ]
+                    }
+                  ]
+                }
+              ]
+            ]
+          }
+        },
+        "entity_id": [
+          156,
+          218,
+          209,
+          24,
+          136,
+          149,
+          176,
+          128,
+          136,
+          90,
+          100,
+          171,
+          183,
+          26,
+          102,
+          164,
+          164,
+          203,
+          29,
+          129
+        ],
+        "module_name": "TestFaucet",
+        "owner_key": "a6534c991a5c034b2f81af809b9577fe6b5425f810de292c0a4d4d43793a8f50",
+        "owner_rule": "OwnedBySigner",
+        "template_address": "20a814546424dae7496451a170325ddaed52d118e4fcf46c1abd32b3d6ee8163"
+      }
+    },
+    "version": 0
+  },
+  "address": {
+    "substate_id": "component_9cdad1188895b080885a64abb71a66a4a4cb1d8117679d85c8b35a4ec5d02243",
+    "version": 0
+  }
+}
+```

package/docusaurus/tari-docs/docs/wallet/list-substates.md

@@ -0,0 +1,69 @@
+---
+sidebar_position: 3
+---
+
+# List substates
+
+In the Tari network, substates are discrete units of state within the Tari Digital Assets Network. Each substate encapsulates a specific piece of data—such as ownership records, smart contract states, or asset balances.  
+Substates follow a create-spend lifecycle, meaning they are created, referenced, and eventually consumed or modified according to network rules.
+
+You can query substates using the `listSubstates` method of a `TariProvider`.
+
+```ts
+listSubstates(
+  filter_by_template: string | null,
+  filter_by_type: SubstateType | null,
+  limit: number | null,
+  offset: number | null
+): Promise<ListSubstatesResponse>;
+```
+
+
+## List by template
+
+```js
+const accountTemplate = "0000000000000000000000000000000000000000000000000000000000000000";
+const accountSubstates = await provider.listSubstates(accountTemplate, null, 1, 0);
+```
+
+The result could be similar to:
+
+```json
+{
+  "substates": [
+    {
+      "substate_id": "component_24b679b98056c7ca7e3d9f9266fec928c7f29d35e7aec546ed69f532aff40710",
+      "module_name": "Account",
+      "version": 3,
+      "template_address": "0000000000000000000000000000000000000000000000000000000000000000"
+    }
+  ]
+}
+```
+
+## List by substate type
+
+```js
+const accountSubstatesByType = await provider.listSubstates(null, "Component", 2, 0);
+```
+
+Output:
+
+```json
+{
+  "substates": [
+    {
+      "substate_id": "component_24b679b98056c7ca7e3d9f9266fec928c7f29d35e7aec546ed69f532aff40710",
+      "module_name": "Account",
+      "version": 3,
+      "template_address": "0000000000000000000000000000000000000000000000000000000000000000"
+    },
+    {
+      "substate_id": "component_1120a9ce46a820a955580cd7d07ee6b93a2ce16ee1671e4dcefd72dfbd33a168",
+      "module_name": "TariswapIndex",
+      "version": 1,
+      "template_address": "60041a6b62a9aa5dbbcc99d8be3ac59765f619c522fd387906dd30c9a9a78d3f"
+    }
+  ]
+}
+```

package/docusaurus/tari-docs/docs/wallet/submit-transaction/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Submit transaction",
+  "position": 5,
+  "link": {
+    "type": "doc",
+    "id": "transactions-index"
+  }
+}

package/docusaurus/tari-docs/docs/wallet/submit-transaction/build-execute-request.md

@@ -0,0 +1,38 @@
+---
+sidebar_position: 2
+---
+
+# Build and execute a request
+
+## Build a transaction
+
+After constructing an instance of the *Transaction Builder*, you can build a transaction as follows:
+
+```js
+const transaction = builder.build();
+```
+
+## Build a transaction request
+
+The transaction request has additional parameters. Therefore, you build it using `buildTransactionRequest`:
+
+```js
+const isDryRun = false;
+const inputRefs = undefined; // Obsolete
+const network = Network.LocalNet;
+const requiredSubstates = []; // Soon to be retired. Use `builder.withInputs()` instead.
+const submitTransactionRequest = buildTransactionRequest(
+  transaction,
+  account.account_id,
+  requiredSubstates,
+  inputRefs,
+  isDryRun,
+  network
+);
+```
+
+## Execute a transaction
+
+```js
+const txResult = await submitAndWaitForTransaction(provider, submitTransactionRequest);
+```

package/docusaurus/tari-docs/docs/wallet/submit-transaction/index.md

@@ -0,0 +1,14 @@
+---
+id: transactions-index
+title: Submit Transaction
+description: A detailed explanation of submitting transactions.
+---
+
+# Submit transaction
+
+The provider exposes the `submitTransaction` and `getTransactionResult` methods. The first submits the transaction, while the second polls the current status of the transaction using its ID. These methods are low-level, so it is recommended to use the transaction builder and other helpers instead.
+
+```ts
+submitTransaction(req: SubmitTransactionRequest): Promise<SubmitTransactionResponse>;
+getTransactionResult(transactionId: string): Promise<TransactionResult>;
+```

package/docusaurus/tari-docs/docs/wallet/submit-transaction/transaction-builder/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Transaction Builder",
+  "position": 1,
+  "link": {
+    "type": "doc",
+    "id": "transaction-builder-index"
+  }
+}

package/docusaurus/tari-docs/docs/wallet/submit-transaction/transaction-builder/call-function.md

@@ -0,0 +1,17 @@
+---
+sidebar_position: 5
+---
+
+# CallFunction
+
+`callFunction` can be used to create instances of components or call other *static* methods.
+
+```js
+builder = builder.callFunction(
+  {
+    templateAddress,
+    functionName: "new",
+  },
+  [1, 2, 3]
+);
+```

package/docusaurus/tari-docs/docs/wallet/submit-transaction/transaction-builder/call-method.md

@@ -0,0 +1,17 @@
+---
+sidebar_position: 5
+---
+
+# CallMethod
+
+`callMethod` calls a method on an instance of a template—in other words, on a component.
+
+```js
+const amount = 10;
+const tokenResource = "resource_217d58767480fbaa48693e11de34baf7fd727e33ee7627f0c4e5b78def378e57";
+  
+builder = builder.callMethod({
+    componentAddress: account.address,
+    methodName: "withdraw",
+}, [tokenResource, amount.toString()]);
+```