@n1xyz/nord-ts 0.0.1 → 0.0.5

package/README.md

@@ -1,110 +1,193 @@
 # nord-ts
 
-This package provides an interface to interact with the Nord exchange. Functionality includes generating Action messages, signing with `Ed25119` and sending payloads. There are also various util functions and interfaces provided.
+This package provides an interface to interact with the Nord exchange. The core components are `Nord` and `NordUser` classes which enable market data access, trading operations, and account management.
 
 ## Installation
 
-### npm
-
 ```bash
+# npm
 npm install nord-ts
-```
-
-### yarn
 
-```bash
+# yarn
 yarn add nord-ts
 ```
 
-## Features
+## Key Components
+
+### Nord
+
+The `Nord` class is the main entry point for interacting with the Nord exchange:
 
-- create a new client with a new user and a new session ( `createClient` )
-- generate Action messages ( `deposit` | `withdraw` | `placeOrder` | `cancelOrderById` )
-- Cryptographic support for `Ed25119` key types.
-- Message signing and transmission capabilities.
-- Data serialization and deserialization for protobuf.
+- Provides market data access (orderbooks, trades, etc.)
+- Manages WebSocket connections for real-time updates
+- Offers utility methods for timestamp and nonce generation
 
-## Usage
+### NordUser
 
-### Basic Examples
+The `NordUser` class represents a user account on the Nord exchange:
 
-#### Client
+- Handles authentication and session management
+- Provides trading functionality (place/cancel orders)
+- Manages deposits and withdrawals
+- Tracks user balances, positions, and orders
+
+## Usage Examples
+
+### Initializing Nord
 
 ```typescript
-import { Nord, types } from "nord-ts";
+import { Nord } from "nord-ts";
 
-const c = await Nord.createClient({
-  url: 'http://localhost:3000',
-  privateKey: /* secp256k1 sec1 compressed secret key */,
+// Create a Nord instance
+const nord = new Nord({
+  webServerUrl: 'https://api.nord.exchange',
+  solanaProgramId: 'your_solana_program_id',
+  solanaUrl: 'https://api.mainnet-beta.solana.com',
 });
 
-const tokenId = 0;
-try {
-    await c.deposit(tokenId, 10000000);
-} catch (e) {
-    console.log(`couldn't do deposit, reason: ${e}`)
-}
+// Initialize and fetch market data
+await nord.fetchNordInfo();
+```
+
+### Creating a User from Private Key
+
+```typescript
+import { Nord, NordUser } from "nord-ts";
+import { Connection } from "@solana/web3.js";
+
+// Create Nord instance
+const nord = new Nord({
+  webServerUrl: 'https://api.nord.exchange',
+  solanaProgramId: 'your_solana_program_id',
+  solanaUrl: 'https://api.mainnet-beta.solana.com',
+});
+
+// Optional Solana connection
+const connection = new Connection('https://api.mainnet-beta.solana.com');
+
+// Create user from private key
+const user = NordUser.fromPrivateKey(
+  nord,
+  'your_private_key', // Can be string or Uint8Array
+  connection // Optional
+);
+
+// Fetch user account information
+await user.updateAccountId();
+await user.fetchInfo();
+```
+
+### Trading Operations
+
+```typescript
+import { Nord, NordUser, Side, FillMode } from "nord-ts";
+
+// Assuming nord and user are already initialized
 
+// Place a limit order
 try {
-    await c.withdraw(tokenId, 100);
-} catch (e) {
-    console.log(`couldn't do withdraw, reason: ${e}`)
+  const orderId = await user.placeOrder({
+    marketId: 0, // BTC/USDC market
+    side: Side.Bid, // Buy
+    fillMode: FillMode.Limit,
+    isReduceOnly: false,
+    size: 0.1, // 0.1 BTC
+    price: 50000, // $50,000 per BTC
+  });
+  
+  console.log(`Order placed with ID: ${orderId}`);
+  
+  // Cancel the order
+  await user.cancelOrder(orderId);
+} catch (error) {
+  console.error(`Trading error: ${error}`);
 }
+```
+
+### Deposits and Withdrawals
+
+```typescript
+import { Nord, NordUser } from "nord-ts";
+
+// Assuming nord and user are already initialized
 
-const marketId = 0;
-const size = 1;
-const price = 1;
-const isReduceOnly = false;
-let orderID: number = 0;
+// Withdraw tokens
 try {
-    orderId = await c.placeOrder(
-        marketId,
-        Side.Ask,
-        FillMode.Limit,
-        isReduceOnly,
-        size,
-        price
-    );
-} catch (e) {
-    console.log(`couldn't do placeOrder, reason: ${e}`)
+  const tokenId = 0; // USDC
+  const amount = 100; // 100 USDC
+  
+  await user.withdraw(tokenId, amount);
+  console.log(`Successfully withdrew ${amount} of token ID ${tokenId}`);
+} catch (error) {
+  console.error(`Withdrawal error: ${error}`);
 }
 
+// For Solana SPL tokens
 try {
-    await c.cancelOrder(
-        marketId,
-        orderId
-    );
-} catch (e) {
-    console.log(`couldn't do cancelOrder, reason: ${e}`)
+  const tokenId = 1; // SOL
+  const amount = 1; // 1 SOL
+  
+  const txId = await user.depositSpl(amount, tokenId);
+  console.log(`Deposit transaction ID: ${txId}`);
+} catch (error) {
+  console.error(`Deposit error: ${error}`);
 }
 ```
 
-#### Subscriber
+### Market Data
 
 ```typescript
-import { Subscriber } from "./nord";
+import { Nord } from "nord-ts";
+
+// Assuming nord is already initialized
 
-const STREAM_URL =
-  "ws://localhost:3000/ws/trades@BTCUSDC&deltas@BTCUSDC&user@0";
+// Get orderbook for a market
+const orderbook = await nord.getOrderbook({ marketId: 0 });
+console.log('Bids:', orderbook.bids);
+console.log('Asks:', orderbook.asks);
 
-const s = new Subscriber({
-  streamURL: STREAM_URL,
-  maxBufferLen: 100,
+// Get recent trades
+const trades = await nord.getTrades({ marketId: 0, limit: 10 });
+console.log('Recent trades:', trades.trades);
+
+// Subscribe to real-time orderbook updates
+const orderbookSub = nord.subscribeOrderbook('BTC/USDC');
+orderbookSub.on('update', (data) => {
+  console.log('Orderbook update:', data);
 });
-s.subsribe();
 ```
 
-## Development
+### Account Information
 
-### Install dependencies
 
-```bash
-yarn
+```typescript
+import { Nord, NordUser } from "nord-ts";
+
+// Assuming nord and user are already initialized
+
+// Get account information
+const accountInfo = await user.fetchInfo();
+
+// Access user balances
+console.log('Balances:', user.balances);
+
+// Access user positions
+console.log('Positions:', user.positions);
+
+// Access user orders
+console.log('Orders:', user.orders);
 ```
 
-### Generate proto files
+## Development
 
-````bash
+```bash
+# Install dependencies
+yarn
+
+# Build the package
 yarn build
 ```
-````
+
+## Documentation
+
+For more detailed documentation, please refer to the source code and inline comments in the `Nord` and `NordUser` classes.

package/dist/bridge/client.d.ts

@@ -0,0 +1,150 @@
+import * as anchor from "@coral-xyz/anchor";
+import { AnchorProvider } from "@coral-xyz/anchor";
+import { Connection, Keypair, PublicKey } from "@solana/web3.js";
+import { BlockFacts, DepositSplParams, PdaSeedType, SolanaBridgeConfig, WithdrawalParams } from "./types";
+/**
+ * Solana Bridge Client for interacting with the bridge program
+ */
+export declare class SolanaBridgeClient {
+    /** Anchor program instance */
+    program: any;
+    /** Solana connection */
+    connection: Connection;
+    /** Program ID */
+    programId: PublicKey;
+    /** Configuration */
+    config: SolanaBridgeConfig;
+    /** Anchor provider */
+    provider: AnchorProvider;
+    /**
+     * Create a new Solana Bridge Client
+     *
+     * @param config Bridge configuration
+     * @param wallet Anchor wallet for signing transactions
+     */
+    constructor(config: SolanaBridgeConfig, wallet: anchor.Wallet);
+    /**
+     * Derive a PDA (Program Derived Address) for the given seeds
+     *
+     * @param type PDA seed type
+     * @param seeds Additional seeds
+     * @returns [PDA, bump]
+     */
+    findPda(type: PdaSeedType, ...seeds: (Buffer | PublicKey | string | number)[]): Promise<[PublicKey, number]>;
+    /**
+     * Find the contract storage PDA
+     *
+     * @returns [PDA, bump]
+     */
+    findContractStoragePda(): Promise<[PublicKey, number]>;
+    /**
+     * Find the asset whitelisted PDA for a token mint
+     *
+     * @param mint Token mint address
+     * @returns [PDA, bump]
+     */
+    findAssetWhitelistedPda(mint: PublicKey): Promise<[PublicKey, number]>;
+    /**
+     * Find the deposit storage PDA for a deposit index
+     *
+     * @param depositIndex Deposit index
+     * @returns [PDA, bump]
+     */
+    findDepositStoragePda(depositIndex: number): Promise<[PublicKey, number]>;
+    /**
+     * Find the block storage PDA for a block ID
+     *
+     * @param blockId Block ID
+     * @returns [PDA, bump]
+     */
+    findBlockStoragePda(blockId: number): Promise<[PublicKey, number]>;
+    /**
+     * Find the withdrawal nullifier PDA
+     *
+     * @param blockId Block ID
+     * @param leafIndex Leaf index
+     * @returns [PDA, bump]
+     */
+    findWithdrawalNullifierPda(blockId: number, leafIndex: number): Promise<[PublicKey, number]>;
+    /**
+     * Find the authority PDA
+     *
+     * @returns [PDA, bump]
+     */
+    findAuthorityPda(): Promise<[PublicKey, number]>;
+    /**
+     * Helper method to sign and send a transaction
+     *
+     * @param transaction Transaction to sign and send
+     * @param signers Additional signers (beyond the provider's wallet)
+     * @returns Transaction signature
+     */
+    private signAndSendTransaction;
+    /**
+     * Deposit SPL tokens to the bridge
+     *
+     * @param params Deposit parameters
+     * @param signer Signer keypair
+     * @returns Transaction signature
+     */
+    depositSpl(params: DepositSplParams): Promise<string>;
+    /**
+     * Withdraw tokens from the bridge
+     *
+     * @param params Withdrawal parameters
+     * @param signer Signer keypair
+     * @returns Transaction signature
+     */
+    withdraw(params: WithdrawalParams, signer: Keypair): Promise<string>;
+    /**
+     * Whitelist an asset (token) for use with the bridge
+     *
+     * @param mint Token mint address
+     * @param signer Operator keypair
+     * @returns Transaction signature
+     */
+    whitelistAsset(mint: PublicKey, signer: Keypair): Promise<string>;
+    /**
+     * Propose a new block
+     *
+     * @param facts Block facts
+     * @param signer Operator keypair
+     * @returns Transaction signature
+     */
+    proposeBlock(facts: BlockFacts, signer: Keypair): Promise<string>;
+    /**
+     * Finalize a block
+     *
+     * @param blockId Block ID
+     * @param stateUpdateId State update ID
+     * @param signer Payer keypair
+     * @returns Transaction signature
+     */
+    finalizeBlock(blockId: number, stateUpdateId: number, signer: Keypair): Promise<string>;
+    /**
+     * Finalize a DA fact
+     *
+     * @param fact DA fact (32-byte array)
+     * @param signer Payer keypair
+     * @returns Transaction signature
+     */
+    finalizeDaFact(fact: Buffer, signer: Keypair): Promise<string>;
+    /**
+     * Initialize the bridge contract
+     *
+     * @param operator Operator public key
+     * @param initialAppStateCommitment Initial app state commitment (32-byte array)
+     * @param signer Payer keypair
+     * @returns Transaction signature
+     */
+    initialize(operator: PublicKey, initialAppStateCommitment: Buffer, signer: Keypair): Promise<string>;
+    /**
+     * Create an associated token account if it doesn't exist
+     *
+     * @param mint Token mint
+     * @param owner Account owner
+     * @param payer Transaction payer
+     * @returns Associated token account address
+     */
+    createTokenAccountIfNeeded(mint: PublicKey, owner: PublicKey, payer: Keypair): Promise<PublicKey>;
+}