Session keys only work with CHIPI wallets. This hook requires the owner’s
encryptKey (PIN) to sign the registration transaction.Usage
const {
addSessionKeyToContract,
addSessionKeyToContractAsync,
data,
isLoading,
error,
isSuccess,
reset
} = useAddSessionKeyToContract();
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
params.encryptKey | string | Yes | Owner’s PIN to decrypt wallet private key for signing |
params.wallet | WalletData | Yes | Wallet object with publicKey, encryptedPrivateKey, walletType |
params.sessionConfig | SessionConfig | Yes | Session configuration (see below) |
bearerToken | string | Yes | Authentication token from your auth provider |
SessionConfig Structure
{
sessionPublicKey: string; // From useCreateSessionKey().data.publicKey
validUntil: number; // Unix timestamp (seconds)
maxCalls: number; // Maximum transactions allowed
allowedEntrypoints: string[]; // Whitelisted function selectors (empty = all allowed)
}
Return Value
| Property | Type | Description |
|---|---|---|
addSessionKeyToContract | function | Trigger registration (fire-and-forget) |
addSessionKeyToContractAsync | function | Trigger registration (returns Promise with tx hash) |
data | string | Transaction hash of registration |
isLoading | boolean | Whether registration is in progress |
isError | boolean | Whether an error occurred |
error | Error | null | Error details if any |
isSuccess | boolean | Whether registration succeeded |
reset | function | Reset mutation state |
Example Implementation
import {
useAddSessionKeyToContract,
useCreateSessionKey,
useGetWallet
} from "@chipi-stack/chipi-react";
export function RegisterSession() {
const { createSessionKeyAsync } = useCreateSessionKey();
const { addSessionKeyToContractAsync, isLoading, error } = useAddSessionKeyToContract();
const { data: wallet } = useGetWallet({
params: { externalUserId: "user-123" },
getBearerToken
});
const [pin, setPin] = useState('');
const handleRegisterSession = async () => {
const bearerToken = await getBearerToken();
// Step 1: Create session key
const session = await createSessionKeyAsync({
encryptKey: pin,
durationSeconds: 3600,
});
// Step 2: Register on contract
const txHash = await addSessionKeyToContractAsync({
params: {
encryptKey: pin,
wallet: {
publicKey: wallet.publicKey,
encryptedPrivateKey: wallet.encryptedPrivateKey,
walletType: "CHIPI",
},
sessionConfig: {
sessionPublicKey: session.publicKey,
validUntil: session.validUntil,
maxCalls: 100, // Allow 100 transactions
allowedEntrypoints: [], // Empty = all functions allowed
},
},
bearerToken,
});
// Store session for later use
localStorage.setItem('chipiSession', JSON.stringify(session));
console.log('Session registered:', txHash);
};
return (
<div className="p-6 bg-white rounded-lg shadow">
<h2 className="text-xl font-semibold mb-4">Register Session Key</h2>
<input
type="password"
value={pin}
onChange={(e) => setPin(e.target.value)}
placeholder="Enter your PIN"
className="w-full p-2 border rounded mb-4"
/>
<button
onClick={handleRegisterSession}
disabled={isLoading || !pin || !wallet}
className="w-full bg-blue-600 text-white py-2 rounded hover:bg-blue-700 disabled:bg-gray-400"
>
{isLoading ? 'Registering...' : 'Register Session'}
</button>
{error && (
<div className="mt-4 p-3 bg-red-50 text-red-700 rounded">
Error: {error.message}
</div>
)}
</div>
);
}
Restricting Session Permissions
For enhanced security, whitelist specific function selectors:const txHash = await addSessionKeyToContractAsync({
params: {
encryptKey: pin,
wallet: walletData,
sessionConfig: {
sessionPublicKey: session.publicKey,
validUntil: session.validUntil,
maxCalls: 10, // Only 10 calls allowed
allowedEntrypoints: [
"0x83afd3f4caedc6eebf44246fe54e38c95e3179a5ec9ea81740eca5b482d12e", // transfer
"0x219209e083275171774dab1df80982e9df2096516f06319c5c6d71ae0a8480c", // approve
],
},
},
bearerToken,
});
Limiting
allowedEntrypoints restricts what functions the session can call. This is recommended for production to minimize attack surface.Error Handling
Common errors:| Error | Cause | Solution |
|---|---|---|
Session keys require CHIPI wallet type | Wallet is READY type | Create a new wallet with walletType: "CHIPI" |
Invalid encryptKey | Wrong PIN entered | Verify the PIN matches the one used during wallet creation |
Session already exists | Session already registered | Use useGetSessionData to check status |
Registration requires a blockchain transaction. The transaction is gas-sponsored but may take 10-30 seconds to confirm.