@hinkal/common 0.2.18 → 0.2.19

package/API/scheduled-transactions-calls.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("../constants/server.constants.cjs"),n=require("../data-structures/http/HttpClient.cjs"),s=require("./getRelayerURL.cjs"),c=(e,t)=>n.httpClient.get(`${s.getRelayerURL(e)}${r.RELAYER_CONFIG.getScheduledTransactions(t)}`);exports.getScheduledTransactions=c;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("../constants/server.constants.cjs"),r=require("../data-structures/http/HttpClient.cjs"),n=require("./getServerURL.cjs"),s=e=>r.httpClient.get(`${n.RELAYER_URL}${t.RELAYER_CONFIG.getScheduledTransactions(e)}`);exports.getScheduledTransactions=s;

package/API/scheduled-transactions-calls.d.ts

@@ -2,5 +2,5 @@ import { ScheduledTransactionResponseItem } from '../types';
 interface ScheduledTransactionResponseInterface {
     transactions: ScheduledTransactionResponseItem[];
 }
-export declare const getScheduledTransactions: (chainId: number, hashedEthereumAddress: string) => Promise<ScheduledTransactionResponseInterface>;
+export declare const getScheduledTransactions: (hashedEthereumAddress: string) => Promise<ScheduledTransactionResponseInterface>;
 export {};

package/API/scheduled-transactions-calls.mjs

@@ -1,8 +1,8 @@
 import { RELAYER_CONFIG as r } from "../constants/server.constants.mjs";
-import { httpClient as o } from "../data-structures/http/HttpClient.mjs";
-import { getRelayerURL as n } from "./getRelayerURL.mjs";
-const c = (t, e) => o.get(
-  `${n(t)}${r.getScheduledTransactions(e)}`
+import { httpClient as e } from "../data-structures/http/HttpClient.mjs";
+import { RELAYER_URL as o } from "./getServerURL.mjs";
+const c = (t) => e.get(
+  `${o}${r.getScheduledTransactions(t)}`
 );
 export {
   c as getScheduledTransactions

package/API/simulate-batch-tx.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./getServerURL.cjs"),s=require("../constants/server.constants.cjs"),n=require("../data-structures/http/HttpClient.cjs");require("axios");const i=async(e,t)=>await n.httpClient.post(`${r.getServerURL(e)}${s.API_CONFIG.ROUTES.simulateBatchTx}`,{batchCalls:t});exports.simulateBatchTx=i;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./getServerURL.cjs"),s=require("../constants/server.constants.cjs"),n=require("../data-structures/http/HttpClient.cjs");require("axios");const i=async(e,t)=>await n.httpClient.post(`${r.SERVER_URL}${s.API_CONFIG.ROUTES.simulateBatchTx}`,{chainId:e,batchCalls:t});exports.simulateBatchTx=i;

package/API/simulate-batch-tx.d.ts

@@ -1,3 +1,3 @@
-import { TransactionSimulatorMinimalResult } from '../types/TransactionSimulator.types';
+import { TransactionSimulatorResult } from '../types/TransactionSimulator.types';
 import { WCTransactionParameters } from '../types';
-export declare const simulateBatchTx: (chainId: number, batchCalls: WCTransactionParameters[]) => Promise<TransactionSimulatorMinimalResult<string>>;
+export declare const simulateBatchTx: (chainId: number, batchCalls: WCTransactionParameters[]) => Promise<TransactionSimulatorResult<string>>;

package/API/simulate-batch-tx.mjs

@@ -1,11 +1,12 @@
-import { getServerURL as o } from "./getServerURL.mjs";
-import { API_CONFIG as e } from "../constants/server.constants.mjs";
-import { httpClient as s } from "../data-structures/http/HttpClient.mjs";
+import { SERVER_URL as r } from "./getServerURL.mjs";
+import { API_CONFIG as s } from "../constants/server.constants.mjs";
+import { httpClient as e } from "../data-structures/http/HttpClient.mjs";
 import "axios";
-const c = async (t, r) => await s.post(
-  `${o(t)}${e.ROUTES.simulateBatchTx}`,
+const c = async (t, o) => await e.post(
+  `${r}${s.ROUTES.simulateBatchTx}`,
   {
-    batchCalls: r
+    chainId: t,
+    batchCalls: o
   }
 );
 export {

package/API/solana-calls.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("../data-structures/http/HttpClient.cjs");require("axios");const r=require("../constants/server.constants.cjs"),n=require("./getServerURL.cjs"),i=async(e,t)=>s.httpClient.post(`${n.getServerURL(e)}${r.API_CONFIG.ROUTES.generateProoflessDepositLimitless}`,t),o=async(e,t)=>s.httpClient.post(`${n.getServerURL(e)}${r.API_CONFIG.ROUTES.generateMultiPaymentDepositLimitless}`,t),l=async(e,t)=>s.httpClient.post(`${n.getServerURL(e)}${r.API_CONFIG.ROUTES.generateAddAccessToken}`,t);exports.generateAddAccessToken=l;exports.generateMultiPaymentDepositLimitless=o;exports.generateProoflessDepositLimitless=i;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("../data-structures/http/HttpClient.cjs");require("axios");const s=require("../constants/server.constants.cjs"),n=require("./getServerURL.cjs"),r=async e=>t.httpClient.post(`${n.SERVER_URL}${s.API_CONFIG.ROUTES.generateProoflessDepositLimitless}`,e),i=async e=>t.httpClient.post(`${n.SERVER_URL}${s.API_CONFIG.ROUTES.generateMultiPaymentDepositLimitless}`,e),o=async e=>t.httpClient.post(`${n.SERVER_URL}${s.API_CONFIG.ROUTES.generateAddAccessToken}`,e);exports.generateAddAccessToken=o;exports.generateMultiPaymentDepositLimitless=i;exports.generateProoflessDepositLimitless=r;

package/API/solana-calls.d.ts

@@ -5,6 +5,7 @@ interface GenerateProoflessDepositLimitlessInput {
     mint: string;
     amount: string;
     stealthAddressStructure: AnchorStealthAddressStructure;
+    chainId: number;
 }
 interface GenerateMultiPaymentDepositLimitlessInput {
     payer: string;
@@ -12,23 +13,25 @@ interface GenerateMultiPaymentDepositLimitlessInput {
     mint: string;
     amounts: string[];
     stealthAddressStructure: AnchorStealthAddressStructure;
+    chainId: number;
 }
 interface GenerateProoflessDepositLimitlessOutput {
     serializedTransaction: string;
     blockhash: string;
     lastValidBlockHeight: number;
 }
-export declare const generateProoflessDepositLimitless: (chainId: number, input: GenerateProoflessDepositLimitlessInput) => Promise<GenerateProoflessDepositLimitlessOutput>;
-export declare const generateMultiPaymentDepositLimitless: (chainId: number, input: GenerateMultiPaymentDepositLimitlessInput) => Promise<GenerateProoflessDepositLimitlessOutput>;
+export declare const generateProoflessDepositLimitless: (input: GenerateProoflessDepositLimitlessInput) => Promise<GenerateProoflessDepositLimitlessOutput>;
+export declare const generateMultiPaymentDepositLimitless: (input: GenerateMultiPaymentDepositLimitlessInput) => Promise<GenerateProoflessDepositLimitlessOutput>;
 interface GenerateAddTokenPublicKeyInput {
     payer: string;
     accessKey: string;
     ethereumAddress: string;
+    chainId: number;
 }
 interface GenerateAddAccessTokenOutput {
     serializedTransaction: string;
     blockhash: string;
     lastValidBlockHeight: number;
 }
-export declare const generateAddAccessToken: (chainId: number, input: GenerateAddTokenPublicKeyInput) => Promise<GenerateAddAccessTokenOutput>;
+export declare const generateAddAccessToken: (input: GenerateAddTokenPublicKeyInput) => Promise<GenerateAddAccessTokenOutput>;
 export {};

package/API/solana-calls.mjs

@@ -1,19 +1,19 @@
-import { httpClient as s } from "../data-structures/http/HttpClient.mjs";
+import { httpClient as t } from "../data-structures/http/HttpClient.mjs";
 import "axios";
-import { API_CONFIG as o } from "../constants/server.constants.mjs";
-import { getServerURL as r } from "./getServerURL.mjs";
-const a = async (e, t) => s.post(
-  `${r(e)}${o.ROUTES.generateProoflessDepositLimitless}`,
-  t
-), c = async (e, t) => s.post(
-  `${r(e)}${o.ROUTES.generateMultiPaymentDepositLimitless}`,
-  t
-), l = async (e, t) => s.post(
-  `${r(e)}${o.ROUTES.generateAddAccessToken}`,
-  t
+import { API_CONFIG as s } from "../constants/server.constants.mjs";
+import { SERVER_URL as o } from "./getServerURL.mjs";
+const p = async (e) => t.post(
+  `${o}${s.ROUTES.generateProoflessDepositLimitless}`,
+  e
+), a = async (e) => t.post(
+  `${o}${s.ROUTES.generateMultiPaymentDepositLimitless}`,
+  e
+), c = async (e) => t.post(
+  `${o}${s.ROUTES.generateAddAccessToken}`,
+  e
 );
 export {
-  l as generateAddAccessToken,
-  c as generateMultiPaymentDepositLimitless,
-  a as generateProoflessDepositLimitless
+  c as generateAddAccessToken,
+  a as generateMultiPaymentDepositLimitless,
+  p as generateProoflessDepositLimitless
 };

package/API/token-calls.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("../constants/server.constants.cjs"),s=require("./getServerURL.cjs"),o=require("../data-structures/http/HttpClient.cjs");require("axios");const i=async(e,t,r=!1)=>await o.httpClient.post(`${s.getServerURL(e)}${n.API_CONFIG.ROUTES.getTokensInfo}`,{tokenAddresses:t,waitForOffsetUpdate:r});exports.tokensInfoCall=i;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("../constants/server.constants.cjs"),s=require("./getServerURL.cjs"),o=require("../data-structures/http/HttpClient.cjs");require("axios");const i=async(e,t,n=!1)=>await o.httpClient.post(`${s.SERVER_URL}${r.API_CONFIG.ROUTES.getTokensInfo}`,{chainId:e,tokenAddresses:t,waitForOffsetUpdate:n});exports.tokensInfoCall=i;

package/API/token-calls.mjs

@@ -1,12 +1,13 @@
-import { API_CONFIG as r } from "../constants/server.constants.mjs";
-import { getServerURL as n } from "./getServerURL.mjs";
+import { API_CONFIG as e } from "../constants/server.constants.mjs";
+import { SERVER_URL as n } from "./getServerURL.mjs";
 import { httpClient as s } from "../data-structures/http/HttpClient.mjs";
 import "axios";
-const l = async (o, t, e = !1) => await s.post(
-  `${n(o)}${r.ROUTES.getTokensInfo}`,
+const l = async (o, t, r = !1) => await s.post(
+  `${n}${e.ROUTES.getTokensInfo}`,
   {
+    chainId: o,
     tokenAddresses: t,
-    waitForOffsetUpdate: e
+    waitForOffsetUpdate: r
   }
 );
 export {

package/API/unspent-utxos-calls.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("../constants/server.constants.cjs"),r=require("./getRelayerURL.cjs"),o=require("../data-structures/http/HttpClient.cjs"),a=e=>{const t=e.getConstructableParams();return{...t,amount:t.amount.toString(),randomization:t.randomization?.toString()}},U=(e,t)=>o.httpClient.post(`${r.getRelayerURL(e)}${s.RELAYER_CONFIG.storeUnspentUtxos}`,{hashedEthereumAddress:t.hashedEthereumAddress,chainId:t.chainId,utxos:t.utxos.map(n=>a(n))}),i=(e,t)=>o.httpClient.get(`${r.getRelayerURL(e)}${s.RELAYER_CONFIG.getUnspentUtxos(t)}`),p=(e,t,n)=>o.httpClient.delete(`${r.getRelayerURL(e)}${s.RELAYER_CONFIG.deleteUnspentUtxos}`,{data:{hashedEthereumAddress:t,nullifiers:n}});exports.deleteUnspentUtxos=p;exports.getUnspentUtxos=i;exports.storeUnspentUtxos=U;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("../constants/server.constants.cjs"),s=require("./getServerURL.cjs"),r=require("../data-structures/http/HttpClient.cjs"),U=t=>{const e=t.getConstructableParams();return{...e,amount:e.amount.toString(),randomization:e.randomization?.toString()}},a=t=>r.httpClient.post(`${s.RELAYER_URL}${n.RELAYER_CONFIG.storeUnspentUtxos}`,{hashedEthereumAddress:t.hashedEthereumAddress,chainId:t.chainId,utxos:t.utxos.map(e=>U(e))}),i=(t,e)=>r.httpClient.get(`${s.RELAYER_URL}${n.RELAYER_CONFIG.getUnspentUtxos(t,e)}`),p=(t,e,o)=>r.httpClient.delete(`${s.RELAYER_URL}${n.RELAYER_CONFIG.deleteUnspentUtxos}`,{data:{hashedEthereumAddress:e,nullifiers:o,chainId:t}});exports.deleteUnspentUtxos=p;exports.getUnspentUtxos=i;exports.storeUnspentUtxos=a;

package/API/unspent-utxos-calls.d.ts

@@ -8,7 +8,7 @@ interface StoreUnspentUtxosResponse {
     status: string;
     message: string;
 }
-export declare const storeUnspentUtxos: (chainId: number, body: StoreUnspentUtxosRequestBody) => Promise<StoreUnspentUtxosResponse>;
+export declare const storeUnspentUtxos: (body: StoreUnspentUtxosRequestBody) => Promise<StoreUnspentUtxosResponse>;
 interface UnspentUtxo {
     id: string;
     utxo: IUtxoConstructor<string>;

package/API/unspent-utxos-calls.mjs

@@ -1,25 +1,22 @@
-import { RELAYER_CONFIG as o } from "../constants/server.constants.mjs";
-import { getRelayerURL as s } from "./getRelayerURL.mjs";
-import { httpClient as r } from "../data-structures/http/HttpClient.mjs";
-const a = (e) => {
-  const t = e.getConstructableParams();
+import { RELAYER_CONFIG as n } from "../constants/server.constants.mjs";
+import { RELAYER_URL as o } from "./getServerURL.mjs";
+import { httpClient as s } from "../data-structures/http/HttpClient.mjs";
+const a = (t) => {
+  const e = t.getConstructableParams();
   return {
-    ...t,
-    amount: t.amount.toString(),
-    randomization: t.randomization?.toString()
+    ...e,
+    amount: e.amount.toString(),
+    randomization: e.randomization?.toString()
   };
-}, U = (e, t) => r.post(`${s(e)}${o.storeUnspentUtxos}`, {
+}, U = (t) => s.post(`${o}${n.storeUnspentUtxos}`, {
   hashedEthereumAddress: t.hashedEthereumAddress,
   chainId: t.chainId,
-  utxos: t.utxos.map((n) => a(n))
-}), d = (e, t) => r.get(
-  `${s(e)}${o.getUnspentUtxos(t)}`
-), u = (e, t, n) => r.delete(
-  `${s(e)}${o.deleteUnspentUtxos}`,
-  {
-    data: { hashedEthereumAddress: t, nullifiers: n }
-  }
-);
+  utxos: t.utxos.map((e) => a(e))
+}), d = (t, e) => s.get(
+  `${o}${n.getUnspentUtxos(t, e)}`
+), u = (t, e, r) => s.delete(`${o}${n.deleteUnspentUtxos}`, {
+  data: { hashedEthereumAddress: e, nullifiers: r, chainId: t }
+});
 export {
   u as deleteUnspentUtxos,
   d as getUnspentUtxos,

package/README.md

@@ -5,11 +5,10 @@ Hinkal is a privacy middleware and smart-contract SDK for public blockchains tha
 The SDK allows wallets, dApps, and payment platforms to integrate protocol-level privacy on Ethereum, Solana, Polygon, Base, Arbitrum, and Optimis. It hides transaction history, wallet relationships, and asset flows on-chain while preserving public-chain finality and compliance.
 
 With Hinkal SDK, developers can:
-  •  Enable private sends between public wallets
-  •  Perform confidential payouts and settlements
-  •  Route transactions through Hinkal’s privacy contracts without exposing sender, recipient, or amounts
-  •  Maintain non-custodial control with optional compliance visibility via viewing keys   
-
+• Enable private sends between public wallets
+• Perform confidential payouts and settlements
+• Route transactions through Hinkal’s privacy contracts without exposing sender, recipient, or amounts
+• Maintain non-custodial control with optional compliance visibility via viewing keys
 
 ## Installation
 
@@ -25,18 +24,24 @@ Or, yarn:
 yarn add @hinkal/common
 ```
 
-### Usage
+## Usage
+
+### Initialization
 
-#### Initialization
+To begin using Hinkal in your application, you'll need to initialize the SDK with your preferred Web3 connection library. Hinkal supports multiple popular libraries out of the box, allowing seamless integration with your existing wallet connection setup.
+
+Initializing the SDK creates a `Hinkal` object that encapsulates:
+- The user's shielded balances
+- Actions the user can perform, such as shielding (depositing), transfers, and swapping
+- Cryptographic keys for privacy-preserving operations
 
-To get started with Hinkal, initialize it based on the Web3 connection library you’re using:
 
 **ethers.js:**
 
 ```typescript
 import { prepareEthersHinkal } from '@hinkal/common/providers/prepareEthersHinkal';
 // signer: ethers.Signer
-const hinkal = await prepareEthersHinkal(signer);
+const hinkal = await prepareEthersHinkal(signer, hinkalConfig);
 ```
 
 **wagmi:**
@@ -44,128 +49,292 @@ const hinkal = await prepareEthersHinkal(signer);
 ```typescript
 import { prepareWagmiHinkal } from '@hinkal/common/providers/prepareWagmiHinkal';
 // connector: wagmi.Connector
-// config: wagmi.Config
-const hinkal = await prepareWagmiHinkal(connector, config);
+// wagmiConfig: wagmi.Config
+const hinkal = await prepareWagmiHinkal(connector, wagmiConfig, hinkalConfig);
+```
+The `hinkalConfig` is defined as follows:
+```typescript
+type HinkalConfig = {
+  /**
+   * Path to the cache file used for storing temporary data.
+   * It should be a valid file path string.
+   */
+  cacheFilePath?: string;
+  /**
+   * Indicator to use caching on a file level.
+   * Node only.
+   */
+  useFileCache?: boolean;
+  disableCaching?: boolean;
+  serializedCache?: Record<string, string>;
+  /**
+   * Indicator controlling wether the proof should be constructed remotely in secure enclave.
+   */
+  generateProofRemotely?: boolean;
+  disableMerkleTreeUpdates?: boolean;
+};
 ```
 
-#### Shielded balance
+### Shielded balance
 
-Once the Hinkal object is initialized, shielded balances become accessible and can be calculated as needed:
+Shielded balances are encrypted token holdings stored within the Hinkal protocol. Unlike regular blockchain balances that are publicly visible, shielded balances are hidden from external observers, providing privacy for your assets. After initializing the Hinkal object, you can access and calculate your shielded balances:
 
 ```typescript
-const balances = await hinkal.getBalances();
+const balances: Promise<Map<string, TokenBalance>>  = await hinkal.getBalances();
 ```
 
-#### Depositing funds to the shielded balance
+This returns a map from token address to balance for all tokens held by the user, including ERC20 and ERC721 tokens.
+
+
+### Shielding: depositing funds to the shielded balance
+
+Shielding is the process of moving your tokens from a public blockchain address into a private, encrypted balance. Once shielded, your tokens are no longer visible on-chain to external observers. This provides privacy for your holdings and subsequent transactions. 
 
 A user can deposit funds to their shielded address using:
 
 ```typescript
-function deposit(erc20addresses: string[], amountChanges: bigint[]): Promise<TransactionObject>;
+function deposit(erc20Tokens: ERC20Token[], amountChanges: bigint[]): Promise<ethers.providers.TransactionResponse>;
+```
+
+where:
+- `erc20Tokens` is an array of tokens to deposit
+- `amountChanges` represents the corresponding token amounts for the deposit
+
+The `ERC20Token` type is defined as follows:
+
+```typescript
+type ERC20Token = {
+  chainId: number;
+  erc20TokenAddress: string;
+  name: string;
+  symbol: string;
+  decimals: number;
+};
+```
+
+### Private Send to Public Address: withdrawing funds from the shielded balance
+
+Private Send to Public Address allows you to send tokens from your private, shielded balance directly to any public blockchain address. The sender's identity is not exposed during this transaction. The recipient receives the funds at their public address, where the tokens become visible on-chain. This is useful when you need to interact with public DeFi protocols, send funds to exchanges, or transfer to any public wallet while maintaining privacy for your shielded balance.
+
+A user can withdraw funds from their shielded address to a public address using:
+
+```typescript
+function withdraw(
+  erc20Tokens: ERC20Token[],
+  deltaAmounts: bigint[],
+  recipientAddress: string,
+  isRelayerOff: boolean,
+): Promise<RelayerTransaction>;
+```
+
+where:
+- `recipientAddress` is the public address that will receive the withdrawn funds
+- `isRelayerOff` determines whether to use a relayer for the transaction (when `false`, a relayer handles gas fees; when `true`, the user pays gas directly)
+- `RelayerTransaction` type represents the transaction response from the relayer service.
+
+### Private Send to Private Address: transfering funds from shielded balance
+
+Private Send to Private Address enables fully confidential transfers between shielded balances. Both the sender and recipient remain anonymous, and the transaction amount is hidden from external observers. This is the most private way to transfer tokens, as neither party's identity nor the transaction details are exposed on-chain.
+
+A user can transfer tokens from their shielded balance to another shielded address using:
+
+```typescript
+function transfer(
+  erc20Tokens: ERC20Token[],
+  deltaAmounts: bigint[],
+  privateRecipientAddress: string,
+): Promise<RelayerTransaction>;
+```
+where:
+- `privateRecipientAddress` is the recipient's private address, formatted as a comma-separated string with five components:
+- `randomization` - a random value for privacy
+- `stealthAddress` - the recipient's stealth address (hex format starting with `0x`)
+- `encryptionKey` - the recipient's encryption key (hex format starting with `0x`, 66 characters)
+- `H0` - the first hash component of elliptic curve point for stealth address derivation
+- `H1` - the second hash component of elliptic curve point for stealth address derivation
+
+### Private Send from Public to Public addresses
+
+Private Send from Public to Public addresses enables you to transfer tokens between two public addresses while using Hinkal's privacy infrastructure. The tokens are first shielded from the sender's public address, then unshielded to the recipient's public address either immediately or after some interval. This ensures there is no traceable connection between the sender and recipient on-chain, providing transaction privacy even when both parties use public addresses.
+
+A user can perform a private transfer between public addresses using:
+
+```typescript
+function depositAndWithdraw(
+  erc20Token: ERC20Token,
+  ecipientAmounts: bigint[],
+  recipientAddresses: string[],
+  txCompletionTime?: number,
+): Promise<RelayerTransaction>;
 ```
 
-where erc20Addresses is an array of token addresses, and amountChanges represents the token amounts for the deposit.
+where:
+- `erc20Token` is the token to transfer (only single token transfers are supported for this method)
+- `recipientAmounts` is an array of amounts to send to each recipient (in the token's smallest unit)
+- `recipientAddresses` is an array of public addresses that will receive the funds
+- `txCompletionTime` (optional) specifies a delay in milliseconds before the withdrawal completes
+
 
-#### Interacting with smart contracts privately
+### Swapping tokens from the shielded balance
 
-After a user’s shielded balance is updated, they can perform any smart contract interaction privately using:
+Swapping allows you to exchange tokens directly from your shielded balance without revealing your identity. The swap is executed through integrated DEX protocols (Uniswap, 1Inch, Odos) while keeping your transaction private. Your tokens are withdrawn from your shielded balance, swapped through the specified protocol, and the resulting tokens are deposited back into your shielded balance—all in a single private transaction.
+
+A user can swap tokens directly from their shielded balance using:
+
+```typescript
+function swap(
+  erc20Tokens: ERC20Token[],
+  deltaAmounts: bigint[],
+  externalActionId: ExternalActionId,
+  swapData: string,
+): Promise<RelayerTransaction>;
+```
+
+where:
+- `externalActionId` identifies the external swap protocol to use. Possible values include:
+  - `ExternalActionId.Uniswap` - for Uniswap swaps
+  - `ExternalActionId.OneInch` - for 1Inch swaps
+  - `ExternalActionId.Odos` - for Odos swaps
+- `swapData` contains the encoded swap parameters specific to the chosen protocol
+
+**Getting swap calldata:**
+
+To obtain the swap calldata using the Hinkal SDK, you can use the built-in swap data generation utilities.
+
+To get swap data for 1Inch, you can use the `getOneInchPrice` function. This function fetches a quote from the 1Inch aggregator and returns both the expected output amount and the encoded swap data that can be passed to the `swap` function:
+
+
+**1Inch:**
+```typescript
+function getOneInchPrice(
+  chainId: number,
+  inSwapToken: ERC20Token,
+  outSwapToken: ERC20Token,
+  inSwapAmount: string,
+  slippagePercentage?: number,
+): Promise<{
+    outSwapAmountValue: bigint;
+    oneInchDataValue: string;
+}>
+```
+Similar functions are available for other supported swap protocols:
+- **Uniswap:** `getUniswapPrice`
+- **Odos:** `getOdosPrice`
+- **LiFi:** `getLifiPrice`
+
+### Interacting with smart contracts privately
+
+The SDK lets you interact with any smart contract on the blockchain while keeping your identity private. When you initiate a private wallet action, your funds are first unshielded from your Hinkal shielded balance to an intermediary called an Emporium contract. The Emporium then executes your desired actions on-chain (such as swaps, staking, or other DeFi interactions) without exposing who initiated them. After the operations complete, the resulting tokens are automatically shielded back into your Hinkal shielded balance. This means you can use DeFi protocols, NFT marketplaces, or any other smart contract while maintaining full anonymity.
 
 ```typescript
 function actionPrivateWallet(
+  chainId:number,
   erc20Addresses: string[],
-  amountChanges: bigint[],
+  deltaAmounts: bigint[],
   onChainCreation: boolean[],
   ops: string[],
-): Promise<TransactionObject>;
+): Promise<RelayerTransaction>;
 ```
 
-where onChainCreation indicates the amounts of tokens that are uncertain before the transaction is executed on-chain. The ops array contains encoded user operations.
+Parameters:
+- `chainId` - the blockchain network identifier
+- `onChainCreation` - array of booleans indicating the direction of token changes: `true` for positive changes (tokens received), `false` for negative changes (tokens spent)
+- `ops` - array of encoded user operations to execute (see User operations below)
+
+User operations (`ops`) are encoded instructions that tell the Emporium contract what actions to perform. Each operation specifies a target contract, the function to call, and any necessary parameters. For example, to stake ETH with Lido, you would create an operation that calls Lido's `submit` function with the appropriate value.
 
-##### User operations
+To generate user operations, a user will need the `emporiumOp` function.
 
-To generate user operations (`ops`) you will need the `emporiumOp` function.
 ```typescript
-import {emporiumOp} from "@hinkal/common";
+function emporiumOp(
+  contract: ethers.Contract | string;
+  func?: string;
+  args?: any[];
+  callDataString?: string;
+  invokeWallet?: boolean;
+  value?: bigint;
+): Promise<RelayerTransaction>;
 ```
 
 The function accepts the following arguments:
-  1. `endpoint` *(required)* - target address or contract instance (with address). The contract instance will be used to properly encode the call function, if any, in the custom operation.
-  2. `func` *(optional)* - the name of the function to be called on the target address.
-  3. `args` *(optional)* - arguments of the function to be called on the target address.
-  4. `invokeWallet` *(optional)* - bool flag that determines the type of transaction. There are two types: stateful and stateless interaction. The default is false (stateless).
-  5. `value` *(optional)* - the amount of native currency to transfer to the target address.
+1. `contract` _(required)_ - target address or contract instance (with address). The contract instance will be used to properly encode the call function, if any, in the custom operation.
+2. `func` _(optional)_ - the name of the function to be called on the target address.
+3. `args` _(optional)_ - arguments of the function to be called on the target address.
+4. `callDataString` _(optional)_ - pre-encoded calldata string. If provided, `func` and `args` should not be used.
+5. `invokeWallet` _(optional)_ - boolean flag that determines the type of interaction (see the stateless/stateful interactions below).
+6. `value` _(optional)_ - the value field to the user operation call.
 
-The `emporiumOp` function will generate data for subsequent calls, supporting both stateful interaction (with state preservation) and stateless interaction (without state preservation). This is determined by the `invokeWallet` flag.
 
-To execute on a smart contract, the user operation will be received in the following format:
+When the Emporium contract executes a user operation, it receives the data in this format:
+
 ```solidity
 (address endpoint, bool invokeWallet, uint256 value, bytes data)
 ```
 
-This will make it possible to make that kind of call:
+This enables the Emporium contract to execute generic calls using user operations:
+
 ```solidity
 (bool success, bytes memory err) = endpoint.call{value: value}(data);
 ```
 
-##### Stateless and stateful
-
-The best way to demonstrate how this works is with an example.
+User operations can be categorized into two types based on whether the target protocol needs to track the caller account's history:
 
-**Stateless interaction**
+**Stateless interactions** are operations where the resulting token amount changes depend only on the calldata provided. Two different accounts executing the same calldata should receive the same result, regardless of their transaction history. Examples include token swaps, liquidity provision, and simple staking operations.
 
-Let's say we need to exchange USDC for ETH using DEX. 
+For example, consider exchanging USDC for ETH using a DEX. To perform a swap, the DEX does not need to know historical data about the caller (e.g., when and what swaps have been performed from his account in the past). It only needs to know how much token to swap and the exchange rate.
 
 ```typescript
 const operations = [
-  emporiumOp(usdcContractInstance, 'approve', [swapRouterAddress, amountIn]),
-  emporiumOp(swapRouterContractInstance, 'exactInputSingle', [swapSingleParams]),
-  emporiumOp(wethContractInstance, 'withdraw', [amountOut]),
+  emporiumOp({ contract: usdcContractInstance, func: 'approve', args: [swapRouterAddress, amountIn] }),
+  emporiumOp({ contract: swapRouterContractInstance, func: 'exactInputSingle', args: [swapSingleParams] }),
+  emporiumOp({ contract: wethContractInstance, func: 'withdraw', args: [amountOut] }),
 ];
 ```
+In this example:
+- First operation approves the swap router to spend USDC tokens
+- Second operation executes the swap from USDC to WETH
+- Third operation unwraps WETH to ETH
 
-To perform a DEX swap, DEX does not need to know historical data about the calling party (e.g. when and what swaps have been performed from this account in the past). It only needs the current token balance for the exchange.
 
-In this case it will be **stateless interaction**, so there is no need to change the default value of the `invokeWallet` flag.
+**Stateful interactions** are operations where the target protocol needs to track the account's history for future calculations, such as staking rewards, voting power, or checkpoints.  In these cases, set `invokeWallet: true` to ensure the operation is executed from a persistent wallet address that the protocol can track.
 
-**Stateful interaction**
+Consider a scenario where you have already staked Curve LP tokens and want to claim your rewards. The gauge contract needs to track your staking history to calculate accumulated rewards, so it must recognize the same wallet address across multiple interactions.
 
-Another example is when the protocol with which an account interacts needs to know what actions this account has done before, for example, to gain rewards. In this case, some account state will be required.
-
-Let's imagine that you already have Curve LP tokens and need to make a stake.
-
-```solidity
+```typescript
 const operations = [
-  emporiumOp(lpTokenInstance, 'approve', [gaugeAddressInstance, amount]), // without flag, because is's stateless interaction
-  emporiumOp(gaugeAddressInstance, 'deposit', [amount, invokeWalletAddress], true), // with flag, because it's stateful interaction
+  emporiumOp({ contract: lpTokenInstance, func: 'approve', args: [gaugeAddressInstance, amount], invokeWallet: true }), 
+  emporiumOp({ contract: gaugeAddressInstance, func: 'deposit', args: [amount, invokeWalletAddress], invokeWallet: true }), 
 ];
 ```
+In this example:
+- First operation approves the gauge contract to spend LP tokens, executed from the persistent wallet
+- Second operation deposits LP tokens into the gauge, with the wallet address as the recipient for reward tracking
 
-As you can see, in this case `approve` is a stateless interaction, but `deposit` is a stateful interaction, because under the hood Curve will record this address and timestamp in order to calculate the checkpoint correctly in the future.
+## Access Tokens
 
-### Access Tokens
+Access tokens are required credentials that allow users to interact with Hinkal's privacy smart contracts. Think of them as a "passport" that proves you've completed the necessary compliance verification.
 
-Before interacting with Hinkal smart contracts, users need to mint an access token after passing compliance checks.
+Before you can deposit funds, make transfers, or perform any private transactions through Hinkal, you must have a valid access token associated with your wallet. This is a one-time requirement—once you have an access token, you can use Hinkal's features without needing to verify again.
 
-To check whether a user already has an access token, use the checkAccessToken function:
+To check whether a user already has an access token on a specific chain, use the `checkAccessToken` function:
 
 ```typescript
 function checkAccessToken(): Promise<boolean>;
 ```
 
-If the user does not have an access token, they must use one of the compliance providers to pass the check. To view the available providers:
+If the user does not have an access token, they need to complete a compliance verification through one of Hinkal's supported compliance providers. This is a one-time process that verifies the user meets regulatory requirements before they can use the privacy features.
 
+To get a list of all available compliance providers that can be used for verification:
 ```typescript
 function getSupportedPassportLinks(): string[];
 ```
 
-After passing the compliance check, the user can mint an access token using:
+After passing the compliance check with one of the supported providers, the access token will be automatically minted during the user's first transaction with Hinkal. This token is stored on-chain and grants the user permission to interact with Hinkal's privacy contracts. 
 
-```typescript
-const { signatureData } = await hinkal.getAPI().getAccessTokenSignature(chainId, ethereumAddress, accessKey);
-await mintAccessToken(this, signatureData);
-```
+## References
+
+Wallet: [Hinkal Wallet](https://chromewebstore.google.com/detail/hinkal-wallet/khfjgapjfcdoffmklchibpepboholpbe)
 
-### References
+Application: [Private Send](https://send.hinkal.io) 
 
-Application: [Hinkal](https://app.hinkal.pro)
-Docs: [Hinkal Documentation](https://hinkal-team.gitbook.io/hinkal)
+Docs: [Hinkal Documentation](https://hinkal-team.gitbook.io/hinkal)