@tari-project/tarijs 0.4.0 → 0.4.2

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,36 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[TITLE]"
+labels: 'bug-report'
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS & Version: [e.g. iOS 10.2.1]
+ - Browser & Version [e.g. chrome v71.0.12345]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser & Version [e.g. stock browser v0.1.2]
+
+**Additional context**
+Add any other context about the problem here.

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+Description
+---
+
+Motivation and Context
+---
+
+How Has This Been Tested?
+---
+
+What process can a PR reviewer use to test or verify this change?
+---
+
+<!-- Checklist -->
+<!-- 1. Is the title of your PR in the form that would make nice release notes? The title, excluding the conventional commit
+tag, will be included exactly as is in the CHANGELOG, so please think about it carefully. -->
+
+
+Breaking Changes
+---
+
+- [x] None
+- [ ] Requires data directory on base node to be deleted
+- [ ] Requires hard fork
+- [ ] Other - Please specify
+
+<!-- Does this include a breaking change? If so, include this line as a footer -->
+<!-- BREAKING CHANGE: Description what the user should do, e.g. delete a database, resync the chain -->

package/.github/dependabot.yml

@@ -0,0 +1,8 @@
+---
+version: 2
+updates:
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

package/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+---
+name: CI
+
+'on':
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+
+concurrency:
+  # https://docs.github.com/en/actions/examples/using-concurrency-expressions-and-a-test-matrix
+  group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/v') || github.ref != 'refs/heads/main' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: 'moonrepo/setup-toolchain@v0'
+        with:
+          auto-install: true
+      - run: pnpm install
+      - 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/.github/workflows/npm_publish.yml

@@ -0,0 +1,26 @@
+---
+# Publishing the package to the npm registry when the version number changes
+# See https://github.com/marketplace/actions/npm-publish for more information
+name: Publish Package to npmjs
+
+on:
+  push:
+    branches: main
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: 'moonrepo/setup-toolchain@v0'
+        with:
+          auto-install: true
+      - run: pnpm install --frozen-lockfile
+      - run: moon :build
+      - name: Publish
+        run: |
+          pnpm config set git-checks false
+          pnpm config set //registry.npmjs.org/:_authToken ${{ secrets.NPM_TOKEN }}
+          pnpm publish --access public --no-git-checks -r
+        env:
+          NPM_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/pr_signed_commits_check.yml

@@ -0,0 +1,19 @@
+---
+# Checks if the comments are signed or not
+name: PR - Signed commits check
+
+'on':
+  pull_request_target
+
+permissions: {}
+
+jobs:
+  check-signed-commits:
+    name: Check signed commits in PR
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Check signed commits in PR
+        uses: 1Password/check-signed-commits-action@v1

package/.github/workflows/pr_title.yml

@@ -0,0 +1,30 @@
+---
+# Checks that PR titles conform to Conventional Commits
+# See https://www.conventionalcommits.org/en/v1.0.0/ for more information
+name: PR
+
+'on':
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - edited
+      - synchronize
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check-title:
+    runs-on: ubuntu-latest
+    steps:
+      - name: install
+        run: |
+          npm install -g @commitlint/cli @commitlint/config-conventional
+          echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
+      - name: lint
+        run: |
+          echo "$PR_TITLE" | commitlint
+        env:
+          PR_TITLE: ${{github.event.pull_request.title}}

package/.moon/toolchain.yml

@@ -0,0 +1,6 @@
+# Enable Node.js and override default settings
+language: 'typescript'
+node:
+  packageManager: 'pnpm'
+typescript:
+   syncProjectReferences: true

package/.moon/workspace.yml

@@ -0,0 +1,33 @@
+# https://moonrepo.dev/docs/config/workspace
+$schema: 'https://moonrepo.dev/schemas/workspace.json'
+
+# Require a specific version of moon while running commands, otherwise fail.
+# versionConstraint: '>=1.0.0'
+
+# Extend and inherit an external configuration file. Must be a valid HTTPS URL or file system path.
+# extends: './shared/workspace.yml'
+
+# REQUIRED: A map of all projects found within the workspace, or a list or file system globs.
+# When using a map, each entry requires a unique project ID as the map key, and a file system
+# path to the project folder as the map value. File paths are relative from the workspace root,
+# and cannot reference projects located outside the workspace boundary.
+projects:
+  - 'apps/*'
+  - 'packages/*'
+  - 'docusaurus/*'
+
+
+
+# Configures the version control system to utilize within the workspace. A VCS
+# is required for determining touched (added, modified, etc) files, calculating file hashes,
+# computing affected files, and much more.
+vcs:
+  # The client to use when managing the repository.
+  # Accepts "git". Defaults to "git".
+  manager: 'git'
+
+  # The default branch (master/main/trunk) in the repository for comparing the
+  # local branch against. For git, this is is typically "master" or "main",
+  # and must include the remote prefix (before /).
+  defaultBranch: 'main'
+

package/.prettierrc

@@ -0,0 +1,12 @@
+{
+  "printWidth": 120,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "arrowParens": "always",
+  "endOfLine": "auto"
+}

package/.prototools

@@ -0,0 +1,9 @@
+moon = "1.31.0"
+node = "22.13.1"
+pnpm = "9.15.3"
+
+[plugins]
+moon = "https://raw.githubusercontent.com/moonrepo/moon/master/proto-plugin.toml"
+
+[settings]
+auto-install = true

package/CODEOWNERS

@@ -0,0 +1,3 @@
+# CI/CD-related files require a review by the devops team
+.github/**/* @tari-project/devops
+CODEOWNERS @tari-project/devops

package/README.md

@@ -0,0 +1,66 @@
+# tari.js
+
+This project provides a unified TypeScript library to connect and send requests to a Tari wallet. It's intended for web application developers that want to interact with a Tari wallet (connect, get substates, submit transactions, etc.).
+
+Tari wallets supported:
+* Tari Wallet Daemon
+* MetaMask through the [tari-snap](https://github.com/tari-project/tari-snap)
+
+An example site (under the `example` folder) contains a web project that allows the user to connect to any type of Tari wallet and perform common actions.
+
+Please read the [TODO](TODO.md) file for upcoming features.
+
+## Library building
+
+You must have the [tari-dan](https://github.com/tari-project/tari-dan) repo cloned at the same folder level as this repo.
+
+To build the library:
+First you must install [proto](https://moonrepo.dev/proto) to manage node and pnpm versions 
+```shell
+proto use
+pnpm install
+moon tarijs:build
+```
+
+The bundled files for deployment or publication will be located under the `dist` folder.
+
+## Running the example site
+
+To run the example site you will need to:
+* Compile the library following the previous section.
+* Have access to a Tari Wallet Daemon and to the Tari MetaMask Snap.
+* Copy the `example/.env.example` file to `example/.env` and edit the correct environment variable values.
+
+To run in development mode, in the packages/tarijs folder:
+```shell
+cd example
+moon tarijs:build
+pnpm run dev
+```
+
+For building and distribution,  in the packages/tarijs folder
+```shell
+cd example
+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/TODO.md

@@ -0,0 +1,12 @@
+# TODO
+
+- In the wallet provider interface:
+  - Full TypeScript class definitions for transaction requests (instructions, etc.).
+  - Common return types for both types of wallets.
+  - Implement `getSubstate` method for the Tari Wallet Daemon provider.
+  - Add account balance to `getAccountData` method for the Tari Wallet Daemon provider.
+- For the example site:
+  - The button should indicate when a connection was established.
+  - The `TariConnect` button could be made into a reusable React component, ready to be imported by any web.
+- Typescript-bindings
+  - [Types refactor and cleanup](https://github.com/tari-project/tari.js/issues/29)

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"
+    }
+  ]
+}
+```