privy-starknet-provider 1.0.0

package/README.md

@@ -0,0 +1,250 @@
+# privy-starknet-provider
+
+Starknet wallet provider for React Native apps using Privy authentication and AVNU paymaster for gasless transactions.
+
+## Features
+
+- Privy Authentication - Seamless embedded wallet creation with email/social login
+- Deterministic Key Derivation - Same user always gets the same Starknet address
+- Gasless Transactions - AVNU paymaster integration for sponsored transactions
+- Multi-Token Support - ETH and STRK balance tracking
+- React Native Ready - Built specifically for Expo/React Native with proper polyfills
+- 
+## Installation
+
+```bash
+npm install @keep-starknet-strange/privy-starknet-provider
+```
+
+### Peer Dependencies
+
+Install these required peer dependencies:
+
+```bash
+npm install react react-native expo @privy-io/expo expo-crypto
+```
+
+### Required Polyfills
+
+Add these imports to your app's entry point (e.g., `index.js`):
+
+```javascript
+import 'fast-text-encoding';
+import 'react-native-get-random-values';
+import '@ethersproject/shims';
+```
+
+Install polyfill dependencies:
+
+```bash
+npm install fast-text-encoding react-native-get-random-values @ethersproject/shims readable-stream
+```
+
+### Metro Configuration
+
+Create or update `metro.config.js` in your project root:
+
+```javascript
+const { getDefaultConfig } = require('expo/metro-config');
+const path = require('path');
+
+const config = getDefaultConfig(__dirname);
+
+config.resolver.unstable_conditionNames = ['browser', 'require', 'react-native'];
+
+const projectRoot = __dirname;
+const libraryRoot = path.resolve(projectRoot, '..'); // Adjust if needed
+
+// Watch library directory if using local development
+config.watchFolders = [libraryRoot];
+
+// Only use your app's node_modules to avoid duplicate React
+config.resolver.nodeModulesPaths = [
+  path.resolve(projectRoot, 'node_modules'),
+];
+
+// Block parent node_modules if in monorepo
+config.resolver.blockList = [
+  new RegExp(`${libraryRoot.replace(/\//g, '\\/')}/node_modules/.*`),
+];
+
+// Configure polyfills
+config.resolver.extraNodeModules = {
+  crypto: require.resolve('expo-crypto'),
+  stream: require.resolve('readable-stream'),
+  'react': path.resolve(projectRoot, 'node_modules/react'),
+  'react-native': path.resolve(projectRoot, 'node_modules/react-native'),
+};
+
+module.exports = config;
+```
+
+## Usage
+
+### 1. Wrap Your App
+
+```tsx
+import { PrivyProvider } from '@privy-io/expo';
+import { StarknetProvider } from '@keep-starknet-strange/privy-starknet-provider';
+
+export default function App() {
+  return (
+    <PrivyProvider appId="your-privy-app-id" clientId="your-privy-client-id">
+      <StarknetProvider
+        config={{
+          rpcUrl: 'https://starknet-sepolia.g.alchemy.com/v2/YOUR_KEY',
+          contractAddress: '0x...', // Optional
+          avnuApiKey: 'your-avnu-api-key', // Required for gasless transactions
+        }}
+      >
+        <YourApp />
+      </StarknetProvider>
+    </PrivyProvider>
+  );
+}
+```
+
+### 2. Use the Hook
+
+```tsx
+import { useStarknet } from '@keep-starknet-strange/privy-starknet-provider';
+
+function MyComponent() {
+  const {
+    address,
+    balance,
+    isDeployed,
+    txPending,
+    executeGaslessTransaction,
+  } = useStarknet();
+
+  // Execute gasless transaction
+  const handleTransaction = async () => {
+    const result = await executeGaslessTransaction([
+      {
+        contractAddress: '0x...',
+        entrypoint: 'increment',
+        calldata: [],
+      },
+    ]);
+
+    if (result.success) {
+      console.log('Transaction successful!', result.transactionHash);
+    }
+  };
+
+  return (
+    <View>
+      <Text>Address: {address}</Text>
+      <Text>ETH Balance: {balance?.eth}</Text>
+      <Text>STRK Balance: {balance?.strk}</Text>
+      <Text>Deployed: {isDeployed ? 'Yes' : 'No'}</Text>
+
+      <Button
+        onPress={handleTransaction}
+        disabled={txPending}
+        title="Execute Transaction"
+      />
+    </View>
+  );
+}
+```
+
+## API Reference
+
+### StarknetProvider
+
+Context provider that wraps your app.
+
+**Props:**
+
+- `config` - Configuration object
+  - `rpcUrl` (required) - Starknet RPC endpoint URL
+  - `contractAddress` (optional) - Your smart contract address
+  - `avnuApiKey` (required) - AVNU API key for gasless transactions
+
+### useStarknet()
+
+Hook to access Starknet wallet functionality.
+
+**Returns:**
+
+- `account` - Starknet account instance
+- `provider` - Starknet RPC provider
+- `address` - Account address (0x...)
+- `privateKey` - Private key for signing
+- `balance` - Balance info `{ eth: string, strk: string }`
+- `isDeployed` - Whether account is deployed on-chain
+- `isInitializing` - Whether initialization is in progress
+- `txPending` - Whether a transaction is pending
+- `error` - Current error message
+- `initialize()` - Initialize Starknet account
+- `refreshBalance()` - Refresh balance information
+- `deployAccount()` - Deploy account on-chain (optional, can be done via gasless transaction)
+- `executeGaslessTransaction(calls)` - Execute gasless transaction via AVNU paymaster
+- `clearError()` - Clear error state
+
+## Configuration
+
+### Get API Keys
+
+1. **Privy App ID & Client ID** - Create an app at https://dashboard.privy.io
+2. **AVNU API Key** - Request at https://docs.avnu.fi
+3. **Alchemy RPC** - Get key at https://alchemy.com (or use any Starknet RPC)
+
+### Environment Variables
+
+```bash
+EXPO_PUBLIC_PRIVY_APP_ID=your_privy_app_id
+EXPO_PUBLIC_PRIVY_CLIENT_ID=your_privy_client_id
+EXPO_PUBLIC_AVNU_API_KEY=your_avnu_api_key
+EXPO_PUBLIC_STARKNET_RPC_URL=https://starknet-sepolia.g.alchemy.com/v2/YOUR_KEY
+EXPO_PUBLIC_CONTRACT_ADDRESS=0x...
+```
+
+## Example
+
+See the `example` directory for a complete working demo.
+
+To run the example:
+
+```bash
+cd example
+npm install
+npx expo start
+```
+
+## Account Model
+
+This package uses ArgentX account contracts on Starknet Sepolia testnet:
+
+- Deterministic address derivation from Privy user ID
+- Same user always gets same Starknet address
+- Account can be deployed automatically via gasless transactions
+- Uses STRK as gas token when deployed
+
+## Gasless Transactions
+
+Gasless transactions are powered by AVNU paymaster:
+
+- Works for both deployed and undeployed accounts
+- Undeployed accounts can deploy and execute in one gasless transaction
+- Deployed accounts use STRK as gas token (sponsored by AVNU)
+- Requires valid AVNU API key
+- Works on Starknet Sepolia testnet
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR on GitHub.
+
+## Credits
+
+Built with:
+
+- Privy - Embedded wallet infrastructure
+- Starknet.js - Starknet JavaScript library
+- AVNU - Gasless transaction paymaster

package/dist/StarknetProvider.d.ts

@@ -0,0 +1,10 @@
+import React, { ReactNode } from 'react';
+import type { StarknetContext as StarknetContext0, StarknetProviderConfig } from './types';
+export declare const StarknetContext: React.Context<StarknetContext0 | null>;
+interface StarknetProviderProps {
+    children: ReactNode;
+    config: StarknetProviderConfig;
+}
+export declare function StarknetProvider({ children, config }: StarknetProviderProps): React.JSX.Element;
+export {};
+//# sourceMappingURL=StarknetProvider.d.ts.map

package/dist/StarknetProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StarknetProvider.d.ts","sourceRoot":"","sources":["../src/StarknetProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAsC,SAAS,EAAE,MAAM,OAAO,CAAC;AAG7E,OAAO,KAAK,EACV,eAAe,IAAI,gBAAgB,EACnC,sBAAsB,EAGvB,MAAM,SAAS,CAAC;AAWjB,eAAO,MAAM,eAAe,wCAA+C,CAAC;AAE5E,UAAU,qBAAqB;IAC7B,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,EAAE,sBAAsB,CAAC;CAChC;AAED,wBAAgB,gBAAgB,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,qBAAqB,qBA+Q3E"}

package/dist/StarknetProvider.js

@@ -0,0 +1,273 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StarknetContext = void 0;
+exports.StarknetProvider = StarknetProvider;
+const react_1 = __importStar(require("react"));
+const expo_1 = require("@privy-io/expo");
+const starknet_1 = require("starknet");
+const utils_1 = require("./utils");
+exports.StarknetContext = (0, react_1.createContext)(null);
+function StarknetProvider({ children, config }) {
+    const { user } = (0, expo_1.usePrivy)();
+    const [account, setAccount] = (0, react_1.useState)(null);
+    const [provider, setProvider] = (0, react_1.useState)(null);
+    const [address, setAddress] = (0, react_1.useState)(null);
+    const [privateKey, setPrivateKey] = (0, react_1.useState)(null);
+    const [balance, setBalance] = (0, react_1.useState)(null);
+    const [isDeployed, setIsDeployed] = (0, react_1.useState)(false);
+    const [isInitializing, setIsInitializing] = (0, react_1.useState)(false);
+    const [txPending, setTxPending] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    // Initialize Starknet account when Privy user is logged in
+    (0, react_1.useEffect)(() => {
+        if (user) {
+            initialize();
+        }
+        else {
+            // Reset state when user logs out
+            setAccount(null);
+            setProvider(null);
+            setAddress(null);
+            setPrivateKey(null);
+            setBalance(null);
+            setIsDeployed(false);
+            setError(null);
+        }
+    }, [user]);
+    // Auto-refresh balance every 10 seconds when account exists
+    (0, react_1.useEffect)(() => {
+        if (account && provider) {
+            const interval = setInterval(() => {
+                refreshBalance();
+            }, 10000);
+            return () => clearInterval(interval);
+        }
+    }, [account, provider]);
+    const initialize = async () => {
+        if (!user || !config.rpcUrl) {
+            setError('Missing user or RPC URL');
+            return;
+        }
+        setIsInitializing(true);
+        setError(null);
+        try {
+            // Create Starknet provider
+            const starknetProvider = (0, utils_1.createStarknetProvider)(config.rpcUrl);
+            // Derive deterministic private key from Privy user ID
+            const userSeed = user.id;
+            const derivedPrivateKey = await (0, utils_1.derivePrivateKey)(userSeed);
+            // Create Starknet account
+            const starknetAccount = (0, utils_1.createStarknetAccount)(derivedPrivateKey, starknetProvider);
+            // Set state
+            setProvider(starknetProvider);
+            setAccount(starknetAccount);
+            setAddress(starknetAccount.address);
+            setPrivateKey(derivedPrivateKey);
+            // Fetch initial balance and deployment status
+            const balances = await (0, utils_1.fetchBalances)(starknetProvider, starknetAccount.address);
+            setBalance(balances);
+            const deploymentStatus = await (0, utils_1.checkAccountDeployment)(starknetProvider, starknetAccount.address);
+            setIsDeployed(deploymentStatus.isDeployed);
+        }
+        catch (err) {
+            console.error('Failed to initialize Starknet account:', err);
+            setError(err.message || 'Failed to initialize Starknet account');
+        }
+        finally {
+            setIsInitializing(false);
+        }
+    };
+    const refreshBalance = async () => {
+        if (!provider || !address)
+            return;
+        try {
+            const balances = await (0, utils_1.fetchBalances)(provider, address);
+            setBalance(balances);
+        }
+        catch (err) {
+            console.error('Failed to refresh balance:', err);
+        }
+    };
+    const deployAccount = async () => {
+        if (!account || !provider || !privateKey) {
+            return { transactionHash: '', success: false, error: 'Account not initialized' };
+        }
+        setTxPending(true);
+        setError(null);
+        try {
+            console.log('🚀 Deploying Starknet account...');
+            const starkKeyPub = starknet_1.ec.starkCurve.getStarkKey(privateKey);
+            const constructorCalldata = starknet_1.CallData.compile({
+                owner: starkKeyPub,
+                guardian: '0x0',
+            });
+            const { transaction_hash } = await account.deployAccount({
+                classHash: utils_1.ARGENTX_CLASS_HASH,
+                constructorCalldata,
+                addressSalt: starkKeyPub,
+                contractAddress: account.address,
+            });
+            console.log('📡 Waiting for deployment confirmation...');
+            await provider.waitForTransaction(transaction_hash);
+            console.log('✅ Account deployed successfully!');
+            setIsDeployed(true);
+            // Refresh balance after deployment
+            await refreshBalance();
+            return { transactionHash: transaction_hash, success: true };
+        }
+        catch (err) {
+            const errorMsg = err.message || 'Failed to deploy account';
+            console.error('Deployment failed:', errorMsg);
+            setError(errorMsg);
+            return { transactionHash: '', success: false, error: errorMsg };
+        }
+        finally {
+            setTxPending(false);
+        }
+    };
+    const executeGaslessTransaction = async (calls) => {
+        if (!account || !provider || !privateKey) {
+            return {
+                transactionHash: '',
+                success: false,
+                error: 'Account not initialized',
+            };
+        }
+        if (!config.avnuApiKey) {
+            return {
+                transactionHash: '',
+                success: false,
+                error: 'AVNU API key is required. Please add EXPO_PUBLIC_AVNU_API_KEY to your .env file.',
+            };
+        }
+        setTxPending(true);
+        setError(null);
+        try {
+            console.log('🚀 Executing gasless transaction with AVNU Paymaster...');
+            console.log('Account address:', account.address);
+            // Check if account is deployed
+            const deploymentStatus = await (0, utils_1.checkAccountDeployment)(provider, account.address);
+            console.log('Account deployed:', deploymentStatus.isDeployed);
+            // Create account with paymaster configured
+            const paymasterOptions = {
+                nodeUrl: 'https://sepolia.paymaster.avnu.fi',
+                headers: {
+                    'x-paymaster-api-key': config.avnuApiKey,
+                },
+            };
+            // Create new account instance with paymaster
+            const paymasterAccount = new starknet_1.Account({
+                provider,
+                address: account.address,
+                signer: privateKey,
+                paymaster: paymasterOptions,
+            });
+            // Prepare paymaster details
+            // Use 'sponsored' mode so paymaster pays for all gas fees
+            const paymasterDetails = {
+                feeMode: { mode: 'sponsored' },
+            };
+            if (!deploymentStatus.isDeployed) {
+                const deploymentData = (0, utils_1.generateDeploymentData)(privateKey);
+                paymasterDetails.deploymentData = {
+                    address: account.address,
+                    class_hash: deploymentData.class_hash,
+                    salt: deploymentData.salt,
+                    unique: deploymentData.unique,
+                    calldata: deploymentData.calldata,
+                    version: 1,
+                };
+                console.log('Including deployment data for undeployed account (sponsored mode)');
+            }
+            console.log('Estimating fees with paymaster...');
+            const estimatedFees = await paymasterAccount.estimatePaymasterTransactionFee(calls, paymasterDetails);
+            console.log('Estimated fees:', estimatedFees);
+            console.log('Executing transaction...');
+            const result = await paymasterAccount.executePaymasterTransaction(calls, paymasterDetails, estimatedFees.suggested_max_fee_in_gas_token);
+            console.log('📡 Waiting for transaction confirmation...');
+            await provider.waitForTransaction(result.transaction_hash);
+            console.log('✅ Gasless transaction confirmed!');
+            // Update deployment status if account wasn't deployed
+            if (!deploymentStatus.isDeployed) {
+                setIsDeployed(true);
+            }
+            // Refresh balance after transaction
+            await refreshBalance();
+            return { transactionHash: result.transaction_hash, success: true };
+        }
+        catch (err) {
+            console.error('Paymaster error:', err);
+            console.error('Error message:', err.message);
+            let errorMsg = err.message || 'Gasless transaction failed';
+            // Provide helpful error messages
+            if (errorMsg.includes('401')) {
+                errorMsg = 'AVNU API key is invalid or expired. Get a new key at https://docs.avnu.fi';
+            }
+            else if (errorMsg.includes('403')) {
+                errorMsg = 'AVNU API key does not have permission for paymaster transactions';
+            }
+            else if (errorMsg.includes('429')) {
+                errorMsg = 'AVNU rate limit exceeded. Please try again later.';
+            }
+            console.error('Gasless transaction error:', errorMsg);
+            setError(errorMsg);
+            return { transactionHash: '', success: false, error: errorMsg };
+        }
+        finally {
+            setTxPending(false);
+        }
+    };
+    const clearError = () => {
+        setError(null);
+    };
+    const contextValue = {
+        account,
+        provider,
+        address,
+        privateKey,
+        balance,
+        isDeployed,
+        isInitializing,
+        txPending,
+        error,
+        initialize,
+        refreshBalance,
+        deployAccount,
+        executeGaslessTransaction,
+        clearError,
+    };
+    return <exports.StarknetContext.Provider value={contextValue}>{children}</exports.StarknetContext.Provider>;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { StarknetProvider } from './StarknetProvider';
+export { useStarknet } from './useStarknet';
+export type { StarknetProviderConfig, BalanceInfo, DeploymentStatus, TransactionResult, StarknetContextState, StarknetContextActions, StarknetContext, } from './types';
+export { derivePrivateKey, createStarknetAccount, createStarknetProvider, fetchBalances, checkAccountDeployment, generateDeploymentData, ETH_TOKEN_ADDRESS, STRK_TOKEN_ADDRESS, ARGENTX_CLASS_HASH, } from './utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,YAAY,EACV,sBAAsB,EACtB,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,GAChB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,aAAa,EACb,sBAAsB,EACtB,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ARGENTX_CLASS_HASH = exports.STRK_TOKEN_ADDRESS = exports.ETH_TOKEN_ADDRESS = exports.generateDeploymentData = exports.checkAccountDeployment = exports.fetchBalances = exports.createStarknetProvider = exports.createStarknetAccount = exports.derivePrivateKey = exports.useStarknet = exports.StarknetProvider = void 0;
+// Main exports
+var StarknetProvider_1 = require("./StarknetProvider");
+Object.defineProperty(exports, "StarknetProvider", { enumerable: true, get: function () { return StarknetProvider_1.StarknetProvider; } });
+var useStarknet_1 = require("./useStarknet");
+Object.defineProperty(exports, "useStarknet", { enumerable: true, get: function () { return useStarknet_1.useStarknet; } });
+// Utility exports
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "derivePrivateKey", { enumerable: true, get: function () { return utils_1.derivePrivateKey; } });
+Object.defineProperty(exports, "createStarknetAccount", { enumerable: true, get: function () { return utils_1.createStarknetAccount; } });
+Object.defineProperty(exports, "createStarknetProvider", { enumerable: true, get: function () { return utils_1.createStarknetProvider; } });
+Object.defineProperty(exports, "fetchBalances", { enumerable: true, get: function () { return utils_1.fetchBalances; } });
+Object.defineProperty(exports, "checkAccountDeployment", { enumerable: true, get: function () { return utils_1.checkAccountDeployment; } });
+Object.defineProperty(exports, "generateDeploymentData", { enumerable: true, get: function () { return utils_1.generateDeploymentData; } });
+Object.defineProperty(exports, "ETH_TOKEN_ADDRESS", { enumerable: true, get: function () { return utils_1.ETH_TOKEN_ADDRESS; } });
+Object.defineProperty(exports, "STRK_TOKEN_ADDRESS", { enumerable: true, get: function () { return utils_1.STRK_TOKEN_ADDRESS; } });
+Object.defineProperty(exports, "ARGENTX_CLASS_HASH", { enumerable: true, get: function () { return utils_1.ARGENTX_CLASS_HASH; } });

package/dist/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "privy-starknet-provider",
+  "version": "1.0.0",
+  "description": "Starknet wallet provider for React Native apps using Privy authentication and AVNU paymaster",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "example": "cd example && npm start",
+    "example:ios": "cd example && npx expo run:ios --device",
+    "example:android": "cd example && npx expo run:android --device"
+  },
+  "keywords": [
+    "starknet",
+    "privy",
+    "wallet",
+    "react-native",
+    "expo",
+    "avnu",
+    "paymaster",
+    "gasless",
+    "blockchain",
+    "web3"
+  ],
+  "author": "Keep Starknet Strange",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/keep-starknet-strange/privy.git"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.70.0",
+    "expo": ">=49.0.0",
+    "@privy-io/expo": ">=0.63.0",
+    "expo-crypto": ">=13.0.0"
+  },
+  "dependencies": {
+    "starknet": "^9.2.1",
+    "@noble/curves": "^1.9.1",
+    "@noble/hashes": "^1.8.0"
+  },
+  "devDependencies": {
+    "@types/react": "~19.1.0",
+    "typescript": "~5.9.2"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}