@sip-protocol/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RECTOR Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# @sip-protocol/react
+
+React hooks for [Shielded Intents Protocol](https://sip-protocol.org).
+
+## Installation
+
+```bash
+npm install @sip-protocol/react @sip-protocol/sdk
+# or
+pnpm add @sip-protocol/react @sip-protocol/sdk
+```
+
+## Quick Start
+
+Wrap your app with `SIPProvider`:
+
+```tsx
+import { SIPProvider } from '@sip-protocol/react'
+
+function App() {
+  return (
+    <SIPProvider config={{ network: 'testnet' }}>
+      <YourApp />
+    </SIPProvider>
+  )
+}
+```
+
+Use hooks in your components:
+
+```tsx
+import { useSIP } from '@sip-protocol/react'
+
+function MyComponent() {
+  const sip = useSIP()
+
+  const handleCreateIntent = async () => {
+    const intent = await sip.createShieldedIntent({
+      from: { chain: 'ethereum', token: 'ETH', amount: '1.0' },
+      to: { chain: 'solana', token: 'SOL' },
+      privacyLevel: 'shielded'
+    })
+  }
+
+  return <button onClick={handleCreateIntent}>Create Private Swap</button>
+}
+```
+
+## Available Hooks
+
+### `useSIP()`
+
+Access the SIP client instance directly.
+
+```tsx
+const sip = useSIP()
+```
+
+### `useStealthAddress()` (stub)
+
+Generate and manage stealth addresses. Full implementation coming soon.
+
+```tsx
+const { generate, parse, isValid } = useStealthAddress()
+```
+
+### `usePrivateSwap()` (stub)
+
+Execute private swaps with shielded intents. Full implementation coming soon.
+
+```tsx
+const { execute, status, error } = usePrivateSwap()
+```
+
+### `useViewingKey()` (stub)
+
+Generate and manage viewing keys for compliance. Full implementation coming soon.
+
+```tsx
+const { generate, decrypt, share } = useViewingKey()
+```
+
+## Configuration
+
+The `SIPProvider` accepts the same configuration as the core SDK:
+
+```tsx
+<SIPProvider
+  config={{
+    network: 'mainnet',
+    mode: 'production',
+    defaultPrivacy: PrivacyLevel.SHIELDED,
+    proofProvider: new MockProofProvider(),
+    intentsAdapter: {
+      jwtToken: process.env.NEAR_INTENTS_JWT
+    }
+  }}
+>
+  <App />
+</SIPProvider>
+```
+
+See [@sip-protocol/sdk](https://github.com/sip-protocol/sip-protocol/tree/main/packages/sdk) for full configuration options.
+
+## Development Status
+
+This package is under active development:
+
+- [x] Provider setup
+- [x] `useSIP()` hook
+- [ ] `useStealthAddress()` implementation
+- [ ] `usePrivateSwap()` implementation
+- [ ] `useViewingKey()` implementation
+- [ ] Additional utility hooks
+
+## Documentation
+
+- [Full Documentation](https://docs.sip-protocol.org)
+- [SDK Reference](https://docs.sip-protocol.org/sdk)
+- [Examples](https://github.com/sip-protocol/sip-protocol/tree/main/examples)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,404 @@
+import React, { ReactNode } from 'react';
+import * as _sip_protocol_sdk from '@sip-protocol/sdk';
+import { SIPConfig, SIP } from '@sip-protocol/sdk';
+import { ChainId, Quote, PrivacyLevel, ViewingKey, EncryptedTransaction } from '@sip-protocol/types';
+
+interface SIPProviderProps {
+    config: SIPConfig;
+    children: ReactNode;
+}
+/**
+ * SIPProvider wraps your app and provides SIP client instance via context
+ *
+ * @example
+ * ```tsx
+ * import { SIPProvider } from '@sip-protocol/react'
+ *
+ * function App() {
+ *   return (
+ *     <SIPProvider config={{ nearIntents: { apiUrl: '...' } }}>
+ *       <YourApp />
+ *     </SIPProvider>
+ *   )
+ * }
+ * ```
+ */
+declare function SIPProvider({ config, children }: SIPProviderProps): React.JSX.Element;
+
+/**
+ * Return type for useSIP hook
+ */
+interface UseSIPReturn {
+    /** SIP client instance (null if not initialized or no provider) */
+    client: SIP | null;
+    /** Whether the client is ready to use */
+    isReady: boolean;
+    /** Error during initialization (if any) */
+    error: Error | null;
+    /** Manually initialize the SIP client (only for standalone usage) */
+    initialize: (config: SIPConfig) => Promise<void>;
+}
+/**
+ * useSIP - Main hook for accessing SIP client
+ *
+ * Provides access to the SIP client instance from SIPProvider, along with
+ * initialization state and error handling. Can also be used standalone without
+ * a provider by calling `initialize()`.
+ *
+ * **Usage with SIPProvider (recommended):**
+ * ```tsx
+ * import { SIPProvider, useSIP } from '@sip-protocol/react'
+ *
+ * function App() {
+ *   return (
+ *     <SIPProvider config={{ network: 'testnet' }}>
+ *       <MyComponent />
+ *     </SIPProvider>
+ *   )
+ * }
+ *
+ * function MyComponent() {
+ *   const { client, isReady } = useSIP()
+ *
+ *   if (!isReady || !client) {
+ *     return <div>Loading...</div>
+ *   }
+ *
+ *   // Use client.createIntent(), client.getQuotes(), etc.
+ * }
+ * ```
+ *
+ * **Standalone usage (without provider):**
+ * ```tsx
+ * function MyComponent() {
+ *   const { client, isReady, initialize, error } = useSIP()
+ *
+ *   useEffect(() => {
+ *     initialize({ network: 'testnet' }).catch(console.error)
+ *   }, [])
+ *
+ *   if (error) {
+ *     return <div>Error: {error.message}</div>
+ *   }
+ *
+ *   if (!isReady || !client) {
+ *     return <div>Initializing...</div>
+ *   }
+ *
+ *   return <div>Ready!</div>
+ * }
+ * ```
+ *
+ * @returns Object with client, isReady, error, and initialize function
+ *
+ * @example Basic usage with provider
+ * ```tsx
+ * import { useSIP } from '@sip-protocol/react'
+ *
+ * function MyComponent() {
+ *   const { client, isReady } = useSIP()
+ *
+ *   if (!isReady || !client) {
+ *     return <div>Loading...</div>
+ *   }
+ *
+ *   // Use client methods
+ *   const handleCreateIntent = async () => {
+ *     const intent = await client.createIntent({ ... })
+ *   }
+ * }
+ * ```
+ *
+ * @example With error handling
+ * ```tsx
+ * function MyComponent() {
+ *   const { client, isReady, error } = useSIP()
+ *
+ *   if (error) {
+ *     return <div>Failed to initialize: {error.message}</div>
+ *   }
+ *
+ *   if (!isReady || !client) {
+ *     return <div>Initializing SIP client...</div>
+ *   }
+ *
+ *   return <div>Ready to use SIP!</div>
+ * }
+ * ```
+ *
+ * @example Standalone initialization
+ * ```tsx
+ * function MyComponent() {
+ *   const { client, isReady, initialize } = useSIP()
+ *
+ *   const handleInit = async () => {
+ *     try {
+ *       await initialize({
+ *         network: 'mainnet',
+ *         mode: 'production',
+ *         intentsAdapter: { jwtToken: 'xxx' }
+ *       })
+ *     } catch (err) {
+ *       console.error('Init failed:', err)
+ *     }
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleInit} disabled={isReady}>
+ *       {isReady ? 'Initialized' : 'Initialize SIP'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+declare function useSIP(): UseSIPReturn;
+
+/**
+ * useStealthAddress - Generate and manage stealth addresses
+ *
+ * @remarks
+ * This hook handles stealth address generation for privacy-preserving transactions.
+ * It automatically generates a meta-address on mount and allows regeneration of
+ * one-time stealth addresses from that meta-address.
+ *
+ * Features:
+ * - Auto-generates meta-address for the specified chain
+ * - Generates one-time stealth addresses
+ * - Supports both secp256k1 (EVM) and ed25519 (Solana/NEAR) chains
+ * - Copy-to-clipboard functionality
+ * - Loading state management
+ *
+ * @param chain - Target blockchain (determines curve type and address format)
+ *
+ * @example
+ * ```tsx
+ * import { useStealthAddress } from '@sip-protocol/react'
+ *
+ * function ReceivePayment() {
+ *   const {
+ *     metaAddress,
+ *     stealthAddress,
+ *     isGenerating,
+ *     regenerate,
+ *     copyToClipboard,
+ *   } = useStealthAddress('ethereum')
+ *
+ *   return (
+ *     <div>
+ *       <p>Share this: {metaAddress}</p>
+ *       <p>One-time address: {stealthAddress}</p>
+ *       <button onClick={regenerate}>Generate New</button>
+ *       <button onClick={copyToClipboard}>Copy</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useStealthAddress(chain: ChainId): {
+    metaAddress: string | null;
+    stealthAddress: string | null;
+    isGenerating: boolean;
+    regenerate: () => void;
+    copyToClipboard: () => Promise<void>;
+};
+
+/**
+ * Status of the swap lifecycle
+ */
+type SwapStatus = 'idle' | 'fetching_quote' | 'pending' | 'confirming' | 'completed' | 'failed';
+/**
+ * Parameters for fetching a quote
+ */
+interface QuoteParams {
+    /** Input chain */
+    inputChain: string;
+    /** Output chain */
+    outputChain: string;
+    /** Input token symbol */
+    inputToken: string;
+    /** Output token symbol */
+    outputToken: string;
+    /** Input amount (as string, in smallest unit) */
+    inputAmount: string;
+    /** Privacy level (optional) */
+    privacyLevel?: PrivacyLevel;
+    /** Maximum acceptable slippage (0-1, e.g. 0.01 = 1%) */
+    maxSlippage?: number;
+}
+/**
+ * Parameters for executing a swap
+ */
+interface SwapParams {
+    /** Input asset details */
+    input: {
+        chain: string;
+        token: string;
+        amount: bigint;
+    };
+    /** Output asset details */
+    output: {
+        chain: string;
+        token: string;
+        minAmount: bigint;
+    };
+    /** Privacy level */
+    privacyLevel: PrivacyLevel;
+    /** Maximum acceptable slippage (0-1, e.g. 0.01 = 1%) */
+    maxSlippage?: number;
+}
+/**
+ * Result of a swap execution
+ */
+interface SwapResult {
+    /** Transaction hash (if available) */
+    txHash?: string;
+    /** Status of the swap */
+    status: string;
+    /** Output amount received */
+    outputAmount?: bigint;
+    /** Intent ID */
+    intentId: string;
+}
+/**
+ * usePrivateSwap - Execute private swaps with shielded intents
+ *
+ * @remarks
+ * Hook for managing the complete lifecycle of a private swap:
+ * - Fetch quotes from solvers
+ * - Execute swaps with privacy
+ * - Track swap status through completion
+ * - Handle errors gracefully
+ *
+ * @example
+ * ```tsx
+ * import { usePrivateSwap } from '@sip-protocol/react'
+ * import { PrivacyLevel } from '@sip-protocol/types'
+ *
+ * function MyComponent() {
+ *   const { quote, fetchQuote, swap, status, isLoading, error, reset } = usePrivateSwap()
+ *
+ *   // Fetch a quote
+ *   const handleGetQuote = async () => {
+ *     await fetchQuote({
+ *       inputChain: 'solana',
+ *       outputChain: 'ethereum',
+ *       inputToken: 'SOL',
+ *       outputToken: 'ETH',
+ *       inputAmount: '1000000000', // 1 SOL
+ *     })
+ *   }
+ *
+ *   // Execute the swap
+ *   const handleSwap = async () => {
+ *     const result = await swap({
+ *       input: { chain: 'solana', token: 'SOL', amount: 1000000000n },
+ *       output: { chain: 'ethereum', token: 'ETH', minAmount: 0n },
+ *       privacyLevel: PrivacyLevel.SHIELDED,
+ *       maxSlippage: 0.01,
+ *     })
+ *   }
+ * }
+ * ```
+ */
+declare function usePrivateSwap(): {
+    quote: Quote | null;
+    fetchQuote: (params: QuoteParams) => Promise<void>;
+    swap: (params: SwapParams) => Promise<SwapResult>;
+    status: SwapStatus;
+    isLoading: boolean;
+    error: Error | null;
+    reset: () => void;
+};
+
+/**
+ * Auditor share entry
+ */
+interface AuditorShare {
+    auditorId: string;
+    viewingKeyHash: string;
+    sharedAt: number;
+}
+/**
+ * useViewingKey - Generate and manage viewing keys for compliance
+ *
+ * @remarks
+ * Hook for managing viewing keys that enable selective disclosure of transaction
+ * details to auditors or regulators while maintaining on-chain privacy.
+ *
+ * Features:
+ * - Generate cryptographically random viewing keys
+ * - Decrypt encrypted transaction data
+ * - Share viewing keys with auditors (tracked in state)
+ * - Hierarchical key derivation via path parameter
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useViewingKey } from '@sip-protocol/react'
+ *
+ * function CompliancePanel() {
+ *   const { viewingKey, generate, decrypt, share } = useViewingKey()
+ *
+ *   const handleGenerateKey = () => {
+ *     const key = generate('m/0/audit')
+ *     console.log('Generated viewing key:', key.hash)
+ *   }
+ *
+ *   const handleDecrypt = async (encrypted: EncryptedTransaction) => {
+ *     try {
+ *       const data = await decrypt(encrypted)
+ *       console.log('Decrypted amount:', data.amount)
+ *     } catch (e) {
+ *       console.error('Decryption failed - wrong key')
+ *     }
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleGenerateKey}>Generate Key</button>
+ *       {viewingKey && <p>Key hash: {viewingKey.hash}</p>}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example Sharing with auditors
+ * ```tsx
+ * function AuditManager() {
+ *   const { viewingKey, generate, share, sharedWith } = useViewingKey()
+ *
+ *   useEffect(() => {
+ *     generate('m/0/compliance')
+ *   }, [])
+ *
+ *   const handleShareWithAuditor = async () => {
+ *     await share('auditor-123')
+ *     console.log('Shared with:', sharedWith)
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleShareWithAuditor}>Share with Auditor</button>
+ *       <ul>
+ *         {sharedWith.map(audit => (
+ *           <li key={audit.auditorId}>{audit.auditorId}</li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useViewingKey(): {
+    /** Current viewing key (null if not generated) */
+    viewingKey: ViewingKey | null;
+    /** List of auditors who have been given access */
+    sharedWith: AuditorShare[];
+    /** Generate a new viewing key */
+    generate: (path?: string) => ViewingKey;
+    /** Decrypt encrypted transaction data */
+    decrypt: (encrypted: EncryptedTransaction) => Promise<_sip_protocol_sdk.TransactionData>;
+    /** Share viewing key with an auditor */
+    share: (auditorId: string) => Promise<void>;
+};
+
+export { SIPProvider, type SIPProviderProps, usePrivateSwap, useSIP, useStealthAddress, useViewingKey };