Universal Private SDK

A professional SDK for privacy-preserving interactions and blockchain integration.

Note: This package is available on the public npm registry and supports standard installation methods.

📦 Installation

Option 1: Install from NPM Registry (Recommended)

This is the standard way to install the package. It ensures you get the latest updates and dependency resolution.

# using npm
npm install @st99005912/universal-private-sdk

# using yarn
yarn add @st99005912/universal-private-sdk

# using pnpm
pnpm add @st99005912/universal-private-sdk

View the package on npm: https://www.npmjs.com/package/@st99005912/universal-private-sdk

Option 2: Manual Installation via Tarball

If you need to install the package offline or strictly control the version artifact, you can use the .tgz file directly.

1. Download the release file: st99005912-universal-private-sdk-0.0.1.tgz
2. Run the installation command pointing to the file path:

npm install ./st99005912-universal-private-sdk-0.0.1.tgz

🚀 Getting Started

1. Initialize Engine

You must initialize the SDK before using any features.

Web Environment (React/Next.js):

import { initializeEngine, loadEngineProvider } from "@st99005912/universal-private-sdk";
import { createWebDatabase, createWebArtifactStore } from "@st99005912/universal-private-sdk/web";

const init = async () => {
  await initializeEngine({
    walletSource: "my-dapp",
    db: createWebDatabase("my-db"),
    artifactStore: createWebArtifactStore(),
    shouldDebug: true
  });

  // Connect to a network (e.g., Sepolia)
  await loadEngineProvider({
    name: "Sepolia",
    rpcUrl: "https://rpc.ankr.com/eth_sepolia",
    chainId: 11155111
  });
};

2. Create/Load Wallet

import { createRailgunWallet, loadWalletByID } from "@st99005912/universal-private-sdk";

// Create a new wallet
const createWallet = async (mnemonic: string, password: string) => {
  // Generate encryption key (store this safely)
  const encryptionKey = await pbkdf2(password, "salt", 100000); 
   
  const walletInfo = await createRailgunWallet(
    encryptionKey,
    mnemonic,
    { [NetworkName.Sepolia]: 0 } // Creation Block
  );
  return walletInfo.id;
};

3. Shield (Deposit to Privacy)

Transfer public tokens (ERC20) into a private balance.

import { erc20PopulateShieldTransaction } from "@st99005912/universal-private-sdk";

const shield = async (walletId: string, tokenAddress: string, amount: bigint, signer: JsonRpcSigner) => {
  const { transaction } = await erc20PopulateShieldTransaction(
    "Sepolia",
    walletId,
    [{ tokenAddress, amount, recipientAddress: "0zk..." }], // 0zk Address
    true // Sign with Public Wallet
  );

  // Send transaction
  const tx = await signer.sendTransaction(transaction);
  await tx.wait();
};

4. Private Transfer

Transfer funds within the privacy pool (0zk -> 0zk).

import { executeTransfer } from "@st99005912/universal-private-sdk";

const transfer = async (walletId: string, recipient: string, amount: bigint, token: string, key: string, signer: JsonRpcSigner) => {
  const tx = await executeTransfer(
    "Sepolia",
    walletId,
    recipient, // 0zk Address
    amount,
    token,
    key, // Encryption Key
    signer
  );
  console.log("Tx Hash:", tx.hash);
};

5. Cross-Chain Private Transfer

Transfer funds from a private balance on one chain to a public address on another chain.

import { executeCrossChainTransferFromEvm } from "@st99005912/universal-private-sdk";

const crossChain = async () => {
  const tx = await executeCrossChainTransferFromEvm(
    "Sepolia",             // Source chain
    "0xZetachainAdapt..",  // Zetachain Adapt contract address
    walletId,
    encryptionKey,
    1000000n,              // Total amount (including fees)
    997500n,               // Actual transfer amount (deducting 0.25% fee)
    "0xToken...",          // Token address
    "0xTargetZRC20...",    // Target chain ZRC20 address
    "0xReceiver...",       // Receiver address
    signer,
    "0xEVMAdapt..."        // EVM Adapt contract address
  );
   
  console.log("Cross-Chain Tx:", tx.hash);
};

🛠 Requirements

• Node.js: >= 16.0.0
• npm: >= 7.0.0

📄 License

This project is licensed under the MIT License.