Skip to main content

Querying

🚧 Under Construction 🚧
This SDK is still in an experimental phase. We advise you use the SDK with localnet.

You can use IkaClient to query the Ika protocol state and objects. This guide covers all available query methods.

Client Initialization​

Before making any queries, ensure your client is properly initialized:

// Initialize the client (recommended for better performance)
await ikaClient.initialize();

// Or let the client auto-initialize on first query
// The client will automatically initialize itself when needed

Basic Object Queries​

Get dWallet​

Retrieve a single dWallet by its ID:

try {
	const dWallet = await ikaClient.getdWallet(dWalletID);
	console.log('dWallet state:', dWallet.state.$kind);
} catch (error) {
	if (error instanceof ObjectNotFoundError) {
		console.error('dWallet not found:', dWalletID);
	} else if (error instanceof NetworkError) {
		console.error('Network error:', error.message);
	}
}

Get Multiple dWallets​

Efficiently retrieve multiple dWallets in a single batch request:

const dWalletIDs = ['0x123...', '0x456...', '0x789...'];
const dWallets = await ikaClient.getMultipledWallets(dWalletIDs);

// Process each dWallet
dWallets.forEach((dWallet, index) => {
	console.log(`dWallet ${dWalletIDs[index]}: ${dWallet.state.$kind}`);
});

Get dWallet Capabilities​

Query dWallet capabilities owned by an address with pagination support:

let cursor: string | null | undefined = undefined;
const allCaps: dWalletCap[] = [];

do {
	const {
		dWalletCaps,
		cursor: nextCursor,
		hasNextPage,
	} = await ikaClient.getOwneddWalletCaps(
		address,
		cursor,
		50, // limit per page
	);

	allCaps.push(...dWalletCaps);
	cursor = nextCursor;

	if (!hasNextPage) break;
} while (cursor);

console.log(`Found ${allCaps.length} dWallet capabilities`);

Get Presign​

Retrieve a presign session object:

const presign = await ikaClient.getPresign(presignID);
console.log('Presign state:', presign.state.$kind);

Get Encrypted User Secret Key Share​

Query an encrypted user secret key share:

const encryptedUserSecretKeyShare = await ikaClient.getEncryptedUserSecretKeyShare(
	encryptedUserSecretKeyShareID,
);

Get Partial User Signature​

Retrieve a partial user signature object:

const partialUserSignature = await ikaClient.getPartialUserSignature(partialUserSignatureID);

State-Based Queries​

Polling for State Changes​

Query objects in specific states with customizable polling behavior:

// Wait for dWallet to become active with custom timeout and interval
try {
	const dWallet = await ikaClient.getdWalletInParticularState(dWalletID, dWalletState.ACTIVE, {
		timeout: 60000, // 60 seconds
		interval: 2000, // poll every 2 seconds
	});
	console.log('dWallet is now active!');
} catch (error) {
	console.error('Timeout waiting for dWallet to become active');
}

Presign State Polling​

const presign = await ikaClient.getPresignInParticularState(presignID, PresignState.ACTIVE, {
	timeout: 30000,
	interval: 1000,
});

Encrypted User Secret Key Share State Polling​

const encryptedShare = await ikaClient.getEncryptedUserSecretKeyShareInParticularState(
	encryptedUserSecretKeyShareID,
	EncryptedUserSecretKeyShareState.ACTIVE,
	{ timeout: 45000, interval: 1500 },
);

Partial User Signature State Polling​

const partialSignature = await ikaClient.getPartialUserSignatureInParticularState(
	partialUserSignatureID,
	PartialUserSignatureState.ACTIVE,
);

Encryption Key Queries​

Get Active Encryption Key​

Retrieve the active encryption key for a specific address:

const encryptionKey = await ikaClient.getActiveEncryptionKey(address);
console.log('Encryption key ID:', encryptionKey.id.id);

Get All Network Encryption Keys​

Retrieve all available network encryption keys:

const allKeys = await ikaClient.getAllNetworkEncryptionKeys();
console.log(`Found ${allKeys.length} encryption keys`);

allKeys.forEach((key) => {
	console.log(`Key ${key.id}: epoch ${key.epoch}`);
});

Get Latest Network Encryption Key​

Get the most recent encryption key:

const latestKey = await ikaClient.getLatestNetworkEncryptionKey();
console.log('Latest encryption key:', latestKey.id);

Get Specific Network Encryption Key​

Retrieve a specific encryption key by ID:

try {
	const encryptionKey = await ikaClient.getNetworkEncryptionKey(encryptionKeyID);
	console.log('Encryption key epoch:', encryptionKey.epoch);
} catch (error) {
	if (error instanceof ObjectNotFoundError) {
		console.error('Encryption key not found:', encryptionKeyID);
	}
}

Get dWallet's Network Encryption Key​

Automatically detect which encryption key a dWallet uses:

const dwalletEncryptionKey = await ikaClient.getdWalletNetworkEncryptionKey(dWalletID);
console.log('dWallet uses encryption key:', dwalletEncryptionKey.id);

Protocol Parameters and Configuration​

Get Protocol Public Parameters​

Retrieve cryptographic parameters for the network:

// Get parameters for a specific dWallet
const dWallet = await ikaClient.getdWallet(dWalletID);
const parameters = await ikaClient.getProtocolPublicParameters(dWallet);

// Or get parameters using client's configured encryption key
const defaultParameters = await ikaClient.getProtocolPublicParameters();

Get Current Epoch​

Retrieve the current network epoch:

const epoch = await ikaClient.getEpoch();
console.log('Current epoch:', epoch);

Configure Encryption Key Options​

Manage client encryption key settings:

// Get current options
const currentOptions = ikaClient.getEncryptionKeyOptions();

// Set specific encryption key
ikaClient.setEncryptionKeyID(specificEncryptionKeyID);

// Set comprehensive options
ikaClient.setEncryptionKeyOptions({
	encryptionKeyID: specificEncryptionKeyID,
	autoDetect: false,
});

Cache Management​

Check Cached Parameters​

Check if protocol parameters are cached for an encryption key:

const isCached = ikaClient.isProtocolPublicParametersCached(encryptionKeyID);
if (isCached) {
	const cachedParams = ikaClient.getCachedProtocolPublicParameters(encryptionKeyID);
}

Cache Invalidation​

Manage client cache for optimal performance:

// Invalidate all caches
ikaClient.invalidateCache();

// Invalidate only object cache
ikaClient.invalidateObjectCache();

// Invalidate only encryption key cache
ikaClient.invalidateEncryptionKeyCache();

// Invalidate specific protocol parameters
ikaClient.invalidateProtocolPublicParametersCache(encryptionKeyID);

// Invalidate all protocol parameters
ikaClient.invalidateProtocolPublicParametersCache();