డెవలపర్ డాక్స్

IQLabs SDK కోసం ప్రధాన భావనలు మరియు ఫంక్షన్లు

ఈ డాక్యుమెంట్ ప్రగతిలో ఉంది; ఇంకా మెరుగుపరచబడుతుంది.

ప్రధాన భావనలు

IQLabs SDK ను ఉపయోగించే ముందు తెలుసుకోవాల్సిన ప్రధాన భావనలు ఇవే.

---

డేటా స్టోరేజ్ (Code In)

ఇది ఏదైనా డేటా (ఫైళ్లు, టెక్స్ట్, JSON) ను ఆన్-చెయిన్‌లో నిల్వ చేసే విధానం.

ఇది ఎలా నిల్వ అవుతుంది?

డేటా పరిమాణంపై ఆధారపడి, SDK ఉత్తమ విధానాన్ని ఎంచుకుంటుంది:

• చిన్న డేటా (< 900 bytes): వెంటనే నిల్వ, అత్యంత వేగంగా
• మధ్య డేటా (< 8.5 KB): అనేక ట్రాన్సాక్షన్‌లుగా విభజిస్తుంది
• పెద్ద డేటా (>= 8.5 KB): వేగం కోసం సమాంతరంగా అప్‌లోడ్ చేస్తుంది

సంబంధిత ప్రధాన ఫంక్షన్లు

• codeIn(): డేటాను అప్‌లోడ్ చేసి ట్రాన్సాక్షన్ ID పొందండి
• readCodeIn(): ట్రాన్సాక్షన్ ID తో డేటాను తిరిగి చదవండి

---

యూజర్ స్టేట్ PDA

ఒక యూజర్‌కు సంబంధించిన ఆన్-చెయిన్ ప్రొఫైల్ అకౌంట్.

ఏవి నిల్వ అవుతాయి?

• ప్రొఫైల్ సమాచారం (పేరు, ప్రొఫైల్ ఫోటో, బయో మొదలైనవి)
• అప్‌లోడ్ చేసిన ఫైళ్ల సంఖ్య
• ఫ్రెండ్ రిక్వెస్ట్ రికార్డులు

ఫ్రెండ్ రిక్వెస్ట్‌లు PDA లో విలువలుగా నిల్వ కావు; అవి ట్రాన్సాక్షన్‌లుగా పంపబడతాయి.

ఇది ఎప్పుడు సృష్టించబడుతుంది?

మీరు మొదటిసారి codeIn() ను కాల్ చేసినప్పుడు ఇది ఆటోమేటిక్‌గా సృష్టించబడుతుంది. అదనపు సెటప్ అవసరం లేదు, అయితే మొదటి యూజర్‌కు రెండుసార్లు సైన్ చేయాల్సి రావచ్చు.

---

కనెక్షన్ PDA

రెండు యూజర్ల మధ్య సంబంధాలను (ఫ్రెండ్స్, మెసేజెస్ మొదలైనవి) నిర్వహించే ఆన్-చెయిన్ అకౌంట్.

దీనికి ఏ స్థితులు ఉంటాయి?

• pending: ఫ్రెండ్ రిక్వెస్ట్ పంపబడింది కానీ ఇంకా అంగీకరించబడలేదు
• approved: రిక్వెస్ట్ అంగీకరించబడింది, యూజర్లు కనెక్ట్ అయ్యారు
• blocked: ఒక పక్షం మరో పక్షాన్ని బ్లాక్ చేసింది

బ్లాక్ చేసిన కనెక్షన్‌ను బ్లాక్ చేసిన వ్యక్తి మాత్రమే అన్‌బ్లాక్ చేయగలడు.

సంబంధిత ప్రధాన ఫంక్షన్లు

• requestConnection(): ఫ్రెండ్ రిక్వెస్ట్ పంపండి (pending ను సృష్టిస్తుంది)
• manageConnection(): రిక్వెస్ట్‌ను అంగీకరించండి/తిరస్కరించండి/బ్లాక్/అన్‌బ్లాక్ చేయండి
• readConnection(): ప్రస్తుత సంబంధ స్థితిని తనిఖీ చేయండి
• writeConnectionRow(): కనెక్ట్ అయిన ఫ్రెండ్‌తో సందేశాలు/డేటా మార్పిడి చేయండి
• fetchUserConnections(): అన్ని కనెక్షన్లు పొందండి (పంపిన & స్వీకరించిన రిక్వెస్ట్‌లు)

---

డేటాబేస్ టేబుళ్లు

JSON డేటాను డేటాబేస్‌లా టేబుళ్లలో నిల్వ చేయండి.

టేబుళ్లు ఎలా సృష్టించబడతాయి?

ప్రత్యేక “create table” ఫంక్షన్ లేదు. writeRow() ద్వారా మొదటి రైటు టేబుల్‌ను ఆటోమేటిక్‌గా సృష్టిస్తుంది.

ఒక టేబుల్ dbRootId మరియు tableSeed (టేబుల్ పేరు) కలయికతో ప్రత్యేకంగా గుర్తించబడుతుంది.

సంబంధిత ప్రధాన ఫంక్షన్లు

• writeRow(): కొత్త రోను జోడించండి (లేకపోతే టేబుల్‌ను సృష్టిస్తుంది)
• readTableRows(): టేబుల్ రోలను చదవండి
• getTablelistFromRoot(): డేటాబేస్‌లోని అన్ని టేబుళ్లను జాబితా చేయండి
• fetchInventoryTransactions(): అప్‌లోడ్ చేసిన ఫైళ్లను జాబితా చేయండి

---

ఫంక్షన్ వివరాలు

డేటా స్టోరేజ్ మరియు రిట్రీవల్

codeIn()

పారామీటర్లు	connection: Solana RPC కనెక్షన్ signer: సైనింగ్ వాలెట్ data: అప్‌లోడ్ చేయాల్సిన డేటా (ఒకే స్ట్రింగ్ లేదా అర్రే) mode: కాంట్రాక్ట్ మోడ్ (డీఫాల్ట్: ‘anchor’)
రిటర్న్	ట్రాన్సాక్షన్ సిగ్నేచర్ (string)

import { codeIn } from 'iqlabs-sdk';

// ఒకే ఫైల్‌ను అప్‌లోడ్ చేయండి
const signature = await codeIn(connection, signer, 'Hello, blockchain!');

// అనేక ఫైళ్లను అప్‌లోడ్ చేయండి
const multiSig = await codeIn(connection, signer, ['file1.txt', 'file2.txt', 'file3.txt']);

---

readCodeIn()

పారామీటర్లు	txSignature: ట్రాన్సాక్షన్ సిగ్నేచర్ connection: (ఐచ్చికం) Solana RPC కనెక్షన్
రిటర్న్	నిల్వ చేసిన డేటా (string)

import { readCodeIn } from 'iqlabs-sdk';

const data = await readCodeIn('5Xg7...', connection);
console.log(data); // 'Hello, blockchain!'

---

కనెక్షన్ నిర్వహణ

requestConnection()

పారామీటర్లు	connection: Solana RPC కనెక్షన్ signer: సైనింగ్ వాలెట్ dbRootId: డేటాబేస్ ID partyA, partyB: కనెక్ట్ చేయాల్సిన ఇద్దరు యూజర్లు tableName: కనెక్షన్ టేబుల్ పేరు columns: కాలమ్ లిస్ట్ idCol: ID కాలమ్ extKeys: ఎక్స్‌టెన్షన్ కీలు
రిటర్న్	ట్రాన్సాక్షన్ సిగ్నేచర్ (string)

import { requestConnection } from 'iqlabs-sdk';

// ఫ్రెండ్ రిక్వెస్ట్ పంపండి
await requestConnection(
  connection, signer, 'my-db',
  myWalletAddress, friendWalletAddress,
  'dm_table', ['message', 'timestamp'], 'message_id', []
);

---

manageConnection()

పారామీటర్లు	builder: InstructionBuilder accounts: { db_root, connection_table, signer } args: { db_root_id, connection_seed, new_status }
రిటర్న్	TransactionInstruction

import { contract } from 'iqlabs-sdk';

// ఫ్రెండ్ రిక్వెస్ట్‌ను అంగీకరించండి
const approveIx = contract.manageConnectionInstruction(
  builder,
  { db_root, connection_table, signer: myPubkey },
  { db_root_id, connection_seed, new_status: contract.CONNECTION_STATUS_APPROVED }
);

// యూజర్‌ను బ్లాక్ చేయండి
const blockIx = contract.manageConnectionInstruction(
  builder,
  { db_root, connection_table, signer: myPubkey },
  { db_root_id, connection_seed, new_status: contract.CONNECTION_STATUS_BLOCKED }
);

---

readConnection()

పారామీటర్లు	dbRootId: డేటాబేస్ ID walletA, walletB: పరిశీలించాల్సిన రెండు వాలెట్లు
రిటర్న్	{ status: 'pending' | 'approved' | 'blocked', requester, blocker }

import { readConnection } from 'iqlabs-sdk';

const { status, requester, blocker } = await readConnection('my-db', walletA, walletB);
console.log(status); // 'pending' | 'approved' | 'blocked'

---

writeConnectionRow()

పారామీటర్లు	connection: Solana RPC కనెక్షన్ signer: సైనింగ్ వాలెట్ dbRootId: డేటాబేస్ ID connectionSeed: కనెక్షన్ సీడ్ rowJson: JSON డేటా
రిటర్న్	ట్రాన్సాక్షన్ సిగ్నేచర్ (string)

import { writeConnectionRow } from 'iqlabs-sdk';

await writeConnectionRow(
  connection, signer, 'my-db', connectionSeed,
  JSON.stringify({ message_id: '123', message: 'Hello friend!', timestamp: Date.now() })
);

---

fetchUserConnections()

UserState PDA ట్రాన్సాక్షన్ హిస్టరీని విశ్లేషించి యూజర్ యొక్క అన్ని కనెక్షన్లు (ఫ్రెండ్ రిక్వెస్ట్‌లు)ను పొందుతుంది. ప్రతి కనెక్షన్‌లో అది ఏ యాప్‌కు చెందినదో సూచించే dbRootId ఉంటుంది.

పారామీటర్లు	userPubkey: యూజర్ పబ్లిక్ కీ (string లేదా PublicKey) options: ఐచ్చిక సెట్టింగ్స్
ఆప్షన్లు	limit: తీసుకోవాల్సిన గరిష్ఠ ట్రాన్సాక్షన్ల సంఖ్య before: పేజినేషన్ కోసం సిగ్నేచర్ speed: రేట్ లిమిట్ ప్రొఫైల్ (‘light’, ‘medium’, ‘heavy’, ‘extreme’) mode: కాంట్రాక్ట్ మోడ్ (ఐచ్చికం)
రిటర్న్	dbRootId, partyA, partyB, status, requester, blocker, timestamp తో కూడిన కనెక్షన్ ఆబ్జెక్టుల అర్రే

import { fetchUserConnections } from 'iqlabs-sdk/reader';

// అన్ని కనెక్షన్లు పొందండి (అన్ని యాప్‌లు!)
const connections = await fetchUserConnections(myPubkey, {
  speed: 'light',  // 6 RPS (డీఫాల్ట్)
  limit: 100
});

// యాప్ ఆధారంగా ఫిల్టర్
const solchatConnections = connections.filter(c => c.dbRootId === 'solchat');
const zoConnections = connections.filter(c => c.dbRootId === 'zo-trading');

// స్థితి ఆధారంగా ఫిల్టర్
const pendingRequests = connections.filter(c => c.status === 'pending');
const friends = connections.filter(c => c.status === 'approved');
const blocked = connections.filter(c => c.status === 'blocked');

// కనెక్షన్ వివరాలు పరిశీలించండి
connections.forEach(conn => {
  console.log(`App: ${conn.dbRootId}, ${conn.partyA} <-> ${conn.partyB}, status: ${conn.status}`);
});

---

టేబుల్ నిర్వహణ

writeRow()

పారామీటర్లు	connection: Solana RPC కనెక్షన్ signer: సైనింగ్ వాలెట్ dbRootId: డేటాబేస్ ID tableSeed: టేబుల్ పేరు rowJson: JSON రో డేటా
రిటర్న్	ట్రాన్సాక్షన్ సిగ్నేచర్ (string)

import { writeRow } from 'iqlabs-sdk';

// మొదటి రోను రాసి టేబుల్ సృష్టించండి
await writeRow(connection, signer, 'my-db', 'users', JSON.stringify({
  id: 1, name: 'Alice', email: '[e-mail]'
}));

// అదే టేబుల్‌లో మరో రో జోడించండి
await writeRow(connection, signer, 'my-db', 'users', JSON.stringify({
  id: 2, name: 'Bob', email: '[e-mail]'
}));

---

readTableRows()

పారామీటర్లు	accountInfo: టేబుల్ అకౌంట్ సమాచారం
రిటర్న్	రో అర్రే (Row[])

import { readTableRows, contract } from 'iqlabs-sdk';

const dbRootPda = contract.pda.getDbRootPda('my-db');
const tablePda = contract.pda.getTablePda(dbRootPda, 'users');
const accountInfo = await connection.getAccountInfo(tablePda);
const rows = readTableRows(accountInfo);

console.log(`Total rows: ${rows.length}`);

---

getTablelistFromRoot()

పారామీటర్లు	dbRootId: డేటాబేస్ ID
రిటర్న్	టేబుల్ పేర్ల అర్రే (string[])

import { getTablelistFromRoot } from 'iqlabs-sdk';

const tables = await getTablelistFromRoot('my-db');
console.log('Table list:', tables);

---

fetchInventoryTransactions()

పారామీటర్లు	userPubkey: యూజర్ పబ్లిక్ కీ limit: గరిష్ఠం (ఐచ్చికం)
రిటర్న్	ట్రాన్సాక్షన్ అర్రే

import { fetchInventoryTransactions } from 'iqlabs-sdk';

const myFiles = await fetchInventoryTransactions(myPubkey, 20);
myFiles.forEach(tx => {
  let metadata: { data?: unknown } | null = null;
  try {
    metadata = JSON.parse(tx.metadata);
  } catch {
    metadata = null;
  }

  if (metadata && metadata.data !== undefined) {
    const inlineData = typeof metadata.data === 'string'
      ? metadata.data
      : JSON.stringify(metadata.data);
    console.log(`Inline data: ${inlineData}`);
  } else {
    console.log(`Signature: ${tx.signature}`);
  }
});

---

ఎన్‌విరాన్‌మెంట్ సెట్టింగ్స్

setRpcUrl()

పారామీటర్లు	url: Solana RPC URL
రిటర్న్	ఏమీ లేదు (void)

import { setRpcUrl } from 'iqlabs-sdk';

setRpcUrl('https://your-rpc.example.com');

---

అడ్వాన్స్‌డ్ ఫంక్షన్లు

ఇవి లో-లెవల్ SDK ఫంక్షన్లు. సాధారణ వినియోగానికి అవసరం లేదు, కానీ కస్టమ్ ఫీచర్లు తయారు చేయడంలో లేదా డీబగ్గింగ్‌లో సహాయపడతాయి.

రైటర్ ఫంక్షన్లు

manageRowData()

టేబుళ్లలో రో డేటాను నిర్వహించడానికి లో-లెవల్ ఫంక్షన్.

మాడ్యూల్	writer
యూజ్ కేస్	కస్టమ్ రో నిర్వహణ, బ్యాచ్ ఆపరేషన్లు

import { manageRowData } from 'iqlabs-sdk/writer';

await manageRowData(connection, signer, {
  dbRootId: 'my-db',
  tableSeed: 'users',
  operation: 'update',
  rowData: JSON.stringify({ id: 1, name: 'Updated Name' })
});

---

రీడర్ ఫంక్షన్లు

readUserState()

ఒక యూజర్ యొక్క UserState PDA ను చదుతుంది.

మాడ్యూల్	reader
యూజ్ కేస్	ప్రొఫైల్ డేటా పొందడం, అప్‌లోడ్ కౌంట్‌లను చెక్ చేయడం

import { readUserState } from 'iqlabs-sdk/reader';

const userState = await readUserState(userPubkey);
console.log('Profile:', userState.profile);
console.log('Upload count:', userState.fileCount);

---

readInventoryMetadata()

యూజర్ ఇన్వెంటరీ (అప్‌లోడ్ చేసిన ఫైళ్లు)కి సంబంధించిన మెటాడేటాను చదుతుంది.

మాడ్యూల్	reader
యూజ్ కేస్	మెటాడేటాతో ఫైళ్లను జాబితా చేయడం, ఫైల్ నిర్వహణ

import { readInventoryMetadata } from 'iqlabs-sdk/reader';

const metadata = await readInventoryMetadata(userPubkey);
metadata.forEach(item => {
  console.log(`File: ${item.name}, Size: ${item.size}, Signature: ${item.signature}`);
});

---

fetchAccountTransactions()

ఒక నిర్దిష్ట అకౌంట్‌కి సంబంధించిన అన్ని ట్రాన్సాక్షన్‌లను తీసుకొస్తుంది.

మాడ్యూల్	reader
యూజ్ కేస్	ట్రాన్సాక్షన్ హిస్టరీ, అకౌంట్ విశ్లేషణ, డీబగ్గింగ్

import { fetchAccountTransactions } from 'iqlabs-sdk/reader';

const transactions = await fetchAccountTransactions(accountPubkey, {
  limit: 50,
  before: lastSignature
});

transactions.forEach(tx => {
  console.log(`Signature: ${tx.signature}, Block: ${tx.slot}`);
});

---

getSessionPdaList()

సెషన్ PDAs జాబితాను పొందుతుంది.

మాడ్యూల్	reader
యూజ్ కేస్	సెషన్ నిర్వహణ, సక్రియ సెషన్‌ల ట్రాకింగ్

import { getSessionPdaList } from 'iqlabs-sdk/reader';

const sessions = await getSessionPdaList(userPubkey);
sessions.forEach(session => {
  console.log(`Session PDA: ${session.pda}, Active: ${session.isActive}`);
});

---

యుటిలిటీ ఫంక్షన్లు

deriveDmSeed()

రెండు యూజర్ల మధ్య డైరెక్ట్ మెసేజింగ్ (DM) కోసం నిర్ణీత సీడ్ను ఉత్పత్తి చేస్తుంది.

మాడ్యూల్	utils / reader
యూజ్ కేస్	స్థిరమైన కనెక్షన్ IDలను సృష్టించడం, DM ఛానల్ సెటప్

import { deriveDmSeed } from 'iqlabs-sdk/utils';

const seed1 = deriveDmSeed(walletA, walletB);
const seed2 = deriveDmSeed(walletB, walletA);
console.log(seed1 === seed2); // true

---

toSeedBytes()

స్ట్రింగ్ సీడ్ను PDA డెరివేషన్‌కి అవసరమైన బైట్ ఫార్మాట్‌కు మార్చుతుంది.

మాడ్యూల్	utils
యూజ్ కేస్	కస్టమ్ PDA డెరివేషన్, లో-లెవల్ సీడ్ మానిప్యులేషన్

import { toSeedBytes } from 'iqlabs-sdk/utils';

const seedString = 'my-custom-seed';
const seedBytes = toSeedBytes(seedString);

const [pda, bump] = PublicKey.findProgramAddressSync(
  [seedBytes, otherSeed],
  programId
);