feat(HYC-182): sdk ts docs

.github/workflows/docs-generator-trigger.yml

@@ -0,0 +1,49 @@
+name: Docs Generator trigger
+env:
+  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_DOCS_PROJECT_ID }}
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: "docs"
+  cancel-in-progress: true
+
+jobs:
+  trigger-generator:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18.12.1
+          cache: 'yarn'
+
+      - name: Install Vercel CLI
+        run: npm install --global vercel@canary
+
+      - name: Install Yarn Globally
+        run: npm install -g yarn
+
+      - name: Installing Dependencies
+        run: yarn
+
+      - name: Pull vercel setup
+        run: vercel pull --yes --token=${{ secrets.VERCEL_TOKEN }}
+
+      - name: Build Project Artifacts
+        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
+
+      - name: Deploy Project Artifacts to Vercel
+        run: >
+          vercel
+          deploy
+          --prebuilt
+          --prod
+          --token=${{ secrets.VERCEL_TOKEN }}

packages/sdk/.gitignore

@@ -26,3 +26,5 @@ temp
 verifier.wasm
 circuit.zkey
 env.json
+docs
+.vercel

packages/sdk/README.MD

@@ -0,0 +1,29 @@
+# Hideyour.cash
+
+Hideyour.cash is a compliant anonymous transactions tool, that utilizes ZK (Zero-knowledge proof) technology.
+
+The main feature is allowing the mixing of transactions using NEAR or any NEP-141 token only for well inteded users. The system integrates with data providors to block wallets suspicious of money laundering and smart contract hacking.
+
+This works by leveaging [hapi.one protocol] as a data partner which is responsible for allowlisting and denylisting accounts.
+
+## SDK
+
+This SDK is designed to assist developers when interacting with the main functions of the hideyour-cash protocol.
+
+### Installation
+
+Hideyour.cash SDK requires [Node.js] and [yarn].
+
+After installing all the tools, you can run the command:
+
+```sh
+yarn
+```
+And install all the dependencies
+
+### Build
+
+To compile SDK run the command:
+```sh
+yarn build
+```

packages/sdk/package.json

@@ -14,6 +14,7 @@
   },
   "scripts": {
     "build": "tsup",
+    "docs": "npx typedoc",
     "add_zk_assets": "yarn add_verifier_wasm && yarn add_circuit",
     "add_verifier_wasm": "cp ../circuits/out/withdraw_js/withdraw.wasm ./test/verifier.wasm",
     "add_circuit": "cp ../circuits/out/withdraw_0000.zkey ./test/circuit.zkey",
@@ -43,6 +44,7 @@
     "rollup-plugin-esbuild": "^5.0.0",
     "ts-jest": "^29.0.5",
     "ts-node": "^10.9.1",
+    "typedoc": "^0.23.28",
     "typescript": "^4.9.4",
     "yarn": "^1.22.19"
   },

packages/sdk/src/actions/compliance.ts

@@ -2,8 +2,17 @@ import { getTransaction } from "../helpers";
 import type { ConnectionType } from "../interfaces";
 import { sendTransactionsCallback } from "./connection";
 
+/**
+ * Send an account to allowlist
+ *
+ * This method sends a new accountId to be added to the Allowlist of the HYC Registry contract.
+ *
+ * @param contract The accountId of registry contract
+ * @param accountId The accountId to be send to allowlist
+ * @param connection the near connection that will to sign the transactions (Near Account or Wallet Selector)
+ * @returns {Promise<any>}
+ */
 export const sendAllowlist = async (
-  nodeUrl: string,
   contract: string,
   accountId: string,
   connection: ConnectionType

packages/sdk/src/actions/connection.ts

@@ -2,6 +2,15 @@ import { AttachedGas } from "../constants";
 import type { Transaction } from "../helpers";
 import type { ConnectionType } from "../interfaces";
 
+/**
+ * Send transactions callback
+ *
+ * This method is an abstraction that makes it possible to send transactions to Near Blockchain using a WalletSelector object or a Near Account.
+ *
+ * @param transactions the array of transactions to be send
+ * @param connection the near connection that will to sign the transactions (Near Account or Wallet Selector)
+ * @returns {Promise<any>}
+ */
 export const sendTransactionsCallback = async (
   connection: ConnectionType,
   transactions: Transaction[]

packages/sdk/src/actions/merkle-tree.ts

@@ -2,6 +2,19 @@ import { MerkleTreeService } from "../services";
 import type { MerkleTreeCacheInterface } from "../interfaces";
 import type MerkleTree from "fixed-merkle-tree";
 
+/**
+ * Prepare Merkle Tree
+ *
+ * This method is responsible for creating and starting a new merkle tree using the Merkle Tree service.
+ *
+ * @param contract The accountId of registry contract
+ * @param name The name of to be created merkle tree
+ * @param branchesQuery The graphql query to get all branches
+ * @param lastBranchesQuery The graphql query to get only the last branch
+ * @param graphqlUrl The graphql url
+ * @param cache The saved array of branches
+ * @returns {Promise<MerkleTree>}
+ */
 export const prepareMerkleTree = async (
   contract: string,
   name: string,

packages/sdk/src/actions/relayer.ts

@@ -1,4 +1,4 @@
-import axios from "axios";
+import axios, { AxiosResponse } from "axios";
 import { getTokenStorage } from "./ticket";
 import { getTransaction } from "../helpers";
 import { sendTransactionsCallback } from "./connection";
@@ -9,6 +9,16 @@ import type {
 } from "../interfaces";
 import { OneNear } from "../constants";
 
+/**
+ * Relayer Get Relayer Fee
+ *
+ * This method is responsible for sending a fee request to the relayer.
+ *
+ * @param relayer The data of relayer with the url to be requested fee
+ * @param accountId The near accountId to be calculate fee
+ * @param instanceId The instance accountId to be sended withdraw
+ * @returns {Promise<AxiosResponse>}
+ */
 export const getRelayerFee = async (
   relayer: RelayerDataInterface,
   accountId: string,
@@ -28,6 +38,15 @@ export const getRelayerFee = async (
   });
 };
 
+/**
+ * Relayer Send Withdraw
+ *
+ * This method is responsible for sending a withdraw request to the relayer.
+ *
+ * @param relayer The data of relayer with the url to be requested fee
+ * @param payload The generated withdraw payload to be sended to withdraw
+ * @returns {Promise<AxiosResponse>}
+ */
 export const sendWithdraw = async (
   relayer: RelayerDataInterface,
   payload: { publicArgs: PublicArgsInterface; token: string }
@@ -43,6 +62,19 @@ export const sendWithdraw = async (
   });
 };
 
+/**
+ * Relayer Send Contract Withdraw
+ *
+ * This method is responsible for sending a withdraw transaction to the blockchain. Without using a relayer.
+ *
+ * @param nodeUrl The Near RPC to send the transaction
+ * @param contract The instance accountId to be send on transaction
+ * @param signerId The signer accountId of the transaction
+ * @param receiverId The receiver accountId of ticket amount
+ * @param publicArgs The generated withdraw payload
+ * @param connection the near connection that will to sign the transactions (Near Account or Wallet Selector)
+ * @returns {Promise<AxiosResponse>}
+ */
 export const sendContractWithdraw = async (
   nodeUrl: string,
   contract: string,
@@ -67,6 +99,19 @@ export const sendContractWithdraw = async (
   return sendTransactionsCallback(connection, transactions);
 };
 
+/**
+ * Relayer check withdraw storages
+ *
+ * This method is responsible for verifying and calculating the storage of Relayer, Sender and Receiver on contract.
+ *
+ * @param nodeUrl The Near RPC to send the transaction
+ * @param contract The contract accountId to be send on transaction
+ * @param signerId The signer accountId of the transaction
+ * @param receiverId The receiver accountId of ticket amount
+ * @param relayerId The relayer accountId to be send the transaction
+ * @param connection the near connection that will to sign the transactions (Near Account or Wallet Selector)
+ * @returns {Promise<any[]>}
+ */
 export const checkWithdrawStorages = async (
   nodeUrl: string,
   contract: string,

packages/sdk/src/actions/snark-proof.ts

@@ -11,6 +11,17 @@ import type {
   WithdrawInputInterface,
 } from "../interfaces/snark-proof";
 
+/**
+ * Create snark proof
+ *
+ * This method is responsible for creating a new Snark Proof.
+ *
+ * @param payload The withdraw input to be send to plonk to calculate the proof
+ * @param verifierUrl The Url of verifier.wasm
+ * @param circuitUrl The Url of circuit.zkey
+ * @param logger The logger instance
+ * @returns {Promise<{ proof: any; publicSignals: string[] }>}
+ */
 export const createSnarkProof = async (
   payload: WithdrawInputInterface,
   verifierUrl = "./verifier.wasm",
@@ -43,6 +54,24 @@ export const createSnarkProof = async (
   }
 };
 
+/**
+ * SnarkProof - Prepare Withdraw
+ *
+ * This method is responsible for preparing a withdraw action, generating all account hashes, creating a withdraw input and generating a new proof.
+ *
+ * @param nodeUrl The Current Near RPC Url
+ * @param contract The instance accountId
+ * @param fee The relayer fee generated of relayer
+ * @param note The note to withdraw
+ * @param relayer The data of relayer to be create the proof
+ * @param recipient The receiver accountId of ticket amount
+ * @param logger The logger instance
+ * @param allowlistTree The allowlist merkle tree
+ * @param commitmentsTree the commitments merkle tree
+ * @param verifierUrl the url of verifier.wasm
+ * @param circuitUrl the url of circuit.zkey
+ * @returns {Promise<{ publicArgs: PublicArgsInterface }>}
+ */
 export const prepareWithdraw = async (
   nodeUrl: string,
   contract: string,
@@ -71,10 +100,7 @@ export const prepareWithdraw = async (
   const pathWL = allowlistTree.proof(commitment.account_hash);
 
   const input = await getWithdrawInput(
-    {
-      ...relayer,
-      hash: relayerHash,
-    },
+    relayerHash,
     fee,
     recipientHash,
     path,
@@ -97,6 +123,14 @@ export const prepareWithdraw = async (
   };
 };
 
+/**
+ * SnarkProof get commitment by ticket
+ *
+ * This method is responsible for generating a new commitment of a ticket.
+ *
+ * @param note The note to withdraw
+ * @returns {Promise<string>}
+ */
 export const getCommitmentByTicket = async (note: string): Promise<string> => {
   const { hash } = await mimcService.initMimc();
 
@@ -107,8 +141,22 @@ export const getCommitmentByTicket = async (note: string): Promise<string> => {
   return hash(secretsHash, parsedNote.account_hash);
 }
 
+/**
+ * SnarkProof get withdraw input
+ *
+ * This method is responsible for generating a withdraw input to create a new proof.
+ *
+ * @param hash The hash of relayer accountId
+ * @param fee The relayer fee
+ * @param recipientHash The receiver accountId of ticket amount
+ * @param path The commitments merkle tree proof
+ * @param pathAL The allowlist merkle tree proof
+ * @param commitment the parsed note
+ * @param single_hash The function to create a hash of nullifier of commitment
+ * @returns {Promise<WithdrawInputInterface>}
+ */
 export const getWithdrawInput = async (
-  { hash }: { hash: string },
+  hash: string,
   fee: string,
   recipientHash: string,
   path: any,
@@ -134,6 +182,17 @@ export const getWithdrawInput = async (
   };
 };
 
+/**
+ * SnarkProof get public args
+ *
+ * This method is responsible for returning a valid payload for a withdraw action.
+ *
+ * @param proof The proof generated by plonk
+ * @param relayer The data of relayer to be send to withdraw
+ * @param publicSignals The public signals generated by plonk
+ * @param receiver The receiver accountId of ticket amount
+ * @returns {Promise<PublicArgsInterface>}
+ */
 export const getPublicArgs = (
   proof: any,
   relayer: RelayerDataInterface,