@hinkal/common 0.2.38 → 0.2.39

package/README.md

@@ -80,9 +80,95 @@ type HinkalConfig = {
    * Indicator controlling wether the proof should be constructed remotely in secure enclave. Defaults to true.
    */
   generateProofRemotely?: boolean;
+
+  /** Disables automatic merkle tree updates. Defaults to false. */
+  disableMerkleTreeUpdates?: boolean;
+
+  /** Override which Tron chain this Hinkal instance targets. */
+  tronChainOverride?: number;
 };
 ```
 
+### Identity persistence
+
+When a user connects their wallet, they sign a fixed login message to authenticate with Hinkal. That signature defines their Hinkal identity. Their shielded balances, transaction ability, and all private operations depend on it.
+
+Most wallets return the same signature every time for the same message. Some do not. Smart contract wallets, certain hardware wallets, and other non-deterministic signers may produce a different signature on each login, even for the same address and message.
+
+When that happens, a returning user appears as a new account. Funds deposited in an earlier session remain tied to the original identity and are not accessible from the new one.
+
+Use `storeAndGetInitialSignature` to keep identity stable across sessions. It stores the user's first login signature server-side and returns that same signature on every later login. The user still signs each session to prove wallet ownership, but the SDK always initializes with the original signature.
+
+```typescript
+function storeAndGetInitialSignature(
+  authSignature: string,
+  isSolanaLedger?: boolean,
+  txMessageForSolanaLedger?: string,
+): Promise<string>;
+```
+
+Parameters:
+
+- `authSignature` — signature from the current login session
+- `isSolanaLedger` — set to `true` for a Solana Ledger wallet. Defaults to `false`
+- `txMessageForSolanaLedger` — base64-encoded transaction message used for Solana Ledger authentication. Required when `isSolanaLedger` is `true`
+
+Typical flow:
+
+```typescript
+const authSignature = await hinkal.signHinkalMessage();
+const initialSignature = await hinkal.storeAndGetInitialSignature(authSignature);
+hinkal.initUserKeysWithSignature(initialSignature);
+```
+
+Call this once per session, after wallet connection and before fetching balances or submitting transactions.
+
+**Security**
+
+The stored signature is protected at every stage. Before leaving the client, the signature is encrypted with hybrid encryption. The payload is encrypted with a symmetric key, and that key is encrypted with the enclave's public key.
+
+Inside the secure enclave, Google Cloud KMS decrypts the symmetric key. Only then is the signature decrypted. The plaintext signature never leaves the enclave unprotected.
+
+At rest, only the encrypted signature and encrypted key are stored in the database. A caller cannot retrieve a stored signature by wallet address alone. Each request must include any valid signature that proves wallet ownership.
+
+Requests that fail this check are rejected. The first signature stored for a given address is never replaced. Later logins only use a fresh signature to authenticate retrieval of the original.
+
+You should use this function in any wallet-connected application where users may reconnect across sessions, especially when supporting smart contract wallets. It is not necessary if your wallet produces deterministic signatures for the same login message on every session — in that case, calling `initUserKeys` or `initUserKeysWithSignature` with the fresh signature is sufficient. It is also not needed if you persist the signature yourself, or if you use seed-phrase-based login through `initUserKeysFromSeedPhrases`.
+
+**Solana Ledger wallets**
+
+For standard EVM and Solana wallets, authentication uses a plain message signature. Call `signHinkalMessage` and pass the result to `storeAndGetInitialSignature` without extra parameters.
+
+Solana Ledger wallets cannot reliably sign arbitrary UTF-8 messages. For those wallets, Hinkal uses a deterministic empty Solana transaction instead. The transaction uses a fixed blockhash and block height, so signing it always returns the same result.
+
+Use `signSolanaLedgerMessage` to get both the signature and the transaction message, then pass them to `storeAndGetInitialSignature`:
+
+```typescript
+const isSolanaLedger = hinkal.getProviderAdapter().isSolanaLedger?.() ?? false;
+let authSignature: string;
+let txMessageForSolanaLedger: string | undefined;
+
+if (isSolanaLedger) {
+  const ledgerAuth = await hinkal.signSolanaLedgerMessage();
+  authSignature = ledgerAuth.signature;
+  txMessageForSolanaLedger = ledgerAuth.txMessageForSolanaLedger;
+} else {
+  authSignature = await hinkal.signHinkalMessage();
+}
+
+const initialSignature = await hinkal.storeAndGetInitialSignature(
+  authSignature,
+  isSolanaLedger,
+  txMessageForSolanaLedger,
+);
+
+hinkal.initUserKeysWithSignature(initialSignature);
+```
+
+On return visits, the user must sign the same deterministic transaction again to authenticate. The enclave verifies the fresh signature against `txMessageForSolanaLedger`, not against a plain login message.
+
+If your application caches the transaction message locally between sessions, pass the cached value as `txMessageForSolanaLedger` so the enclave can verify the correct payload.
+
 ### Shielded balance
 
 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:
@@ -188,9 +274,93 @@ 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
+- `txCompletionTime` (optional) is a Unix timestamp in seconds by which all scheduled withdrawals must complete
 - `preEstimateGas` If true (default), the gas needed for the operation will be estimated before executing the deposit. This can help avoid failed transactions due to "out of gas" error.
 
+### Private Send from Public to Public addresses (extended)
+
+Private Send from Public to Public addresses (extended) follows the same flow as `depositAndWithdraw`. Tokens are shielded from the sender's public address, then withdrawn to one or more recipient public addresses on a relayer schedule. In addition to the deposit transaction hash, it returns a `scheduleId` that you can use to check the status of each scheduled withdrawal.
+
+A user can perform an extended private transfer between public addresses using:
+
+```typescript
+function depositAndWithdrawExtended(
+  erc20Token: ERC20Token,
+  recipientAmounts: bigint[],
+  recipientAddresses: string[],
+  txCompletionTime?: number,
+  preEstimateGas?: boolean,
+): Promise<DepositAndSendExtendedResult>;
+```
+
+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) is a Unix timestamp in seconds by which all scheduled withdrawals must complete
+- `preEstimateGas` If true (default), the gas needed for the operation will be estimated before executing the deposit. This can help avoid failed transactions due to "out of gas" error.
+
+The function returns:
+
+```typescript
+type DepositAndSendExtendedResult = {
+  depositTxHash: string;
+  scheduleId: string;
+};
+```
+
+where:
+
+- `depositTxHash` is the on-chain hash of the deposit transaction
+- `scheduleId` is the relayer schedule identifier used to fetch withdrawal status
+
+### Checking scheduled send status
+
+After calling `depositAndWithdrawExtended`, a user can fetch the current status of the scheduled withdrawals using the returned `scheduleId`:
+
+```typescript
+function checkSendTransactionStatus(scheduleId: string): Promise<ScheduledTransactionByIdResponse>;
+```
+
+where:
+
+- `scheduleId` is the schedule identifier returned from an extended deposit-and-send call
+
+The function returns:
+
+```typescript
+type ScheduledTransactionByIdResponse = {
+  scheduleId: string;
+  chainId: number;
+  transactions: ScheduledTransactionItemStatus[];
+};
+
+type ScheduledTransactionItemStatus = {
+  status: ScheduledTransactionStatus;
+  scheduledTime: string;
+  txHash: string | null;
+};
+```
+
+where:
+
+- `scheduleId` is the schedule identifier
+- `chainId` is the chain on which the scheduled transactions are executed
+- `transactions` is the list of scheduled withdrawals, one entry per recipient
+  - `status` indicates the current state of a scheduled withdrawal
+  - `scheduledTime` is the planned execution time in ISO 8601 format
+  - `txHash` is the on-chain transaction hash once the withdrawal is sent on-chain, or `null` before submission
+
+Possible values for `ScheduledTransactionStatus` are:
+
+- `pending` — the withdrawal is scheduled and waiting for its execution time
+- `processing` — the relayer is currently submitting the withdrawal transaction on-chain
+- `waiting_for_relayer` — the relayer is busy; the withdrawal is queued to start
+- `sent_on_chain` — the withdrawal was submitted on-chain and `txHash` is available
+- `completed` — the withdrawal was confirmed on-chain
+- `failed` — the withdrawal transaction failed
+
 ### Swapping tokens from the shielded balance
 
 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.
@@ -342,15 +512,19 @@ In this example:
 
 Hinkal SDK is available on the following blockchain networks:
 
-| Chain    | Chain ID | Status  |
-| -------- | -------- | ------- |
-| Ethereum | 1        | ✅ Live |
-| Polygon  | 137      | ✅ Live |
-| Base     | 8453     | ✅ Live |
-| Arbitrum | 42161    | ✅ Live |
-| Optimism | 10       | ✅ Live |
-| Solana   | -        | ✅ Live |
-| Tron     | -        | ✅ Live |
+| Chain           | Chain ID   | Status  |
+| --------------- | ---------- | ------- |
+| Ethereum        | 1          | ✅ Live |
+| Arbitrum        | 42161      | ✅ Live |
+| Optimism        | 10         | ✅ Live |
+| Polygon         | 137        | ✅ Live |
+| Base            | 8453       | ✅ Live |
+| Solana          | 501        | ✅ Live |
+| Tron            | 728126428  | ✅ Live |
+| Tempo           | 4217       | ✅ Live |
+| Arc Testnet     | 5042002    | ✅ Live |
+| Sepolia Testnet | 11155111   | ✅ Live |
+| Tron Nile       | 3448148188 | ✅ Live |
 
 Each chain supports the full suite of Hinkal privacy features including shielding, transfers, and confidential interactions with DeFi protocols.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hinkal/common",
-  "version": "0.2.38",
+  "version": "0.2.39",
   "homepage": "hinkal.io",
   "author": {
     "name": "Hinkal Protocol"

package/webworker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hinkal/common",
-  "version": "0.2.38",
+  "version": "0.2.39",
   "homepage": "hinkal.io",
   "author": {
     "name": "Hinkal Protocol"

package/webworker/viteWorkerURL.constant.cjs

@@ -14,8 +14,8 @@
   var e = /* @__PURE__ */ ((r) => (r.ZKProof = "ZKProof", r.SnarkJS = "SnarkJS", r.UTXO = "UTXO", r))(e || {});
 
   const n = async () => ({
-    [e.ZKProof]: await getWorkerURL(domain + '/0.2.38/' + 'zkProofWorkerLauncher.js'),
-    [e.SnarkJS]: await getWorkerURL(domain + '/0.2.38/' + 'snarkjsWorkerLauncher.js'),
-    [e.UTXO]: await getWorkerURL(domain + '/0.2.38/' + 'utxoWorkerLauncher.js'),
+    [e.ZKProof]: await getWorkerURL(domain + '/0.2.39/' + 'zkProofWorkerLauncher.js'),
+    [e.SnarkJS]: await getWorkerURL(domain + '/0.2.39/' + 'snarkjsWorkerLauncher.js'),
+    [e.UTXO]: await getWorkerURL(domain + '/0.2.39/' + 'utxoWorkerLauncher.js'),
   });
   exports.getWorkerViteURL = n;

package/webworker/viteWorkerURL.constant.mjs

@@ -14,8 +14,8 @@
   var e = /* @__PURE__ */ ((r) => (r.ZKProof = "ZKProof", r.SnarkJS = "SnarkJS", r.UTXO = "UTXO", r))(e || {});
 
   const n = async () => ({
-    [e.ZKProof]: await getWorkerURL(domain + '/0.2.38/' + 'zkProofWorkerLauncher.js'),
-    [e.SnarkJS]: await getWorkerURL(domain + '/0.2.38/' + 'snarkjsWorkerLauncher.js'),
-    [e.UTXO]: await getWorkerURL(domain + '/0.2.38/' + 'utxoWorkerLauncher.js'),
+    [e.ZKProof]: await getWorkerURL(domain + '/0.2.39/' + 'zkProofWorkerLauncher.js'),
+    [e.SnarkJS]: await getWorkerURL(domain + '/0.2.39/' + 'snarkjsWorkerLauncher.js'),
+    [e.UTXO]: await getWorkerURL(domain + '/0.2.39/' + 'utxoWorkerLauncher.js'),
   });
   export { n as getWorkerViteURL };