Entwicklerdokumentation

Dieses Dokument ist in Arbeit und wird weiter verfeinert.

Kernkonzepte

Dies sind die wichtigsten Konzepte, die du kennen solltest, bevor du das IQLabs SDK verwendest.

Datenspeicherung (Code In)

So speicherst du beliebige Daten (Dateien, Text, JSON) on-chain.

Wie wird es gespeichert?

Abhängig von der Datengröße wählt das SDK die optimale Methode:

Kleine Daten (< 900 Bytes): sofort speichern, am schnellsten
Mittlere Daten (< 8.5 KB): in mehrere Transaktionen aufteilen
Große Daten (>= 8.5 KB): parallel hochladen für mehr Geschwindigkeit

Wichtige zugehörige Funktionen

codeIn(): Daten hochladen und eine Transaktions-ID erhalten
readCodeIn(): Daten anhand einer Transaktions-ID auslesen

Benutzerstatus-PDA

Ein On-Chain-Profilkonto für einen Nutzer.

Was wird gespeichert?

Profilinformationen (Name, Profilbild, Bio usw.)
Anzahl hochgeladener Dateien
Einträge zu Freundschaftsanfragen

Freundschaftsanfragen werden nicht als Werte im PDA gespeichert; sie werden als Transaktionen gesendet.

Wann wird es erstellt?

Es wird automatisch erstellt, wenn du codeIn() zum ersten Mal aufrufst. Es ist keine zusätzliche Einrichtung erforderlich, aber der erste Nutzer muss möglicherweise zweimal signieren.

Verbindungs-PDA

Ein On-Chain-Konto, das Beziehungen zwischen zwei Nutzern verwaltet (Freunde, Nachrichten usw.).

Welche Zustände kann es haben?

pending: Eine Freundschaftsanfrage wurde gesendet, aber noch nicht akzeptiert
approved: Die Anfrage wurde akzeptiert und die Nutzer sind verbunden
blocked: Eine Seite hat die andere blockiert

Eine blockierte Verbindung kann nur von der blockierenden Person aufgehoben werden.

Wichtige zugehörige Funktionen

requestConnection(): Freundschaftsanfrage senden (erstellt pending)
manageConnection(): Anfrage annehmen/ablehnen/blockieren/entsperren
readConnection(): aktuellen Beziehungsstatus prüfen
writeConnectionRow(): Nachrichten/Daten mit einem verbundenen Freund austauschen
fetchUserConnections(): alle Verbindungen abrufen (gesendete & empfangene Anfragen)

Datenbanktabellen

JSON-Daten in Tabellen wie in einer Datenbank speichern.

Wie werden Tabellen erstellt?

Es gibt keine spezielle “create table”-Funktion. Der erste Schreibvorgang über writeRow() erstellt die Tabelle automatisch.

Eine Tabelle wird eindeutig durch die Kombination aus dbRootId und tableSeed (Tabellenname) identifiziert.

Wichtige zugehörige Funktionen

writeRow(): eine neue Zeile hinzufügen (erstellt die Tabelle, falls sie fehlt)
readTableRows(): Zeilen aus einer Tabelle lesen
getTablelistFromRoot(): alle Tabellen in einer Datenbank auflisten
fetchInventoryTransactions(): hochgeladene Dateien auflisten

Funktionsdetails

Datenspeicherung und -abruf

`codeIn()`

Parameter	`connection`: Solana-RPC-Verbindung `signer`: signierende Wallet `data`: hochzuladende Daten (einzelner String oder Array) `mode`: Vertragsmodus (Standard: ‘anchor’)
Rückgabe	Transaktionssignatur (string)

import { codeIn } from 'iqlabs-sdk';

// Eine einzelne Datei hochladen
const signature = await codeIn(connection, signer, 'Hello, blockchain!');

// Mehrere Dateien hochladen
const multiSig = await codeIn(connection, signer, ['file1.txt', 'file2.txt', 'file3.txt']);

`readCodeIn()`

Parameter	`txSignature`: Transaktionssignatur `connection`: (optional) Solana-RPC-Verbindung
Rückgabe	Gespeicherte Daten (string)

import { readCodeIn } from 'iqlabs-sdk';

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

Verbindungsverwaltung

`requestConnection()`

Parameter	`connection`: Solana-RPC-Verbindung `signer`: signierende Wallet `dbRootId`: Datenbank-ID `partyA`, `partyB`: die zwei zu verbindenden Nutzer `tableName`: Name der Verbindungstabelle `columns`: Spaltenliste `idCol`: ID-Spalte `extKeys`: Erweiterungsschlüssel
Rückgabe	Transaktionssignatur (string)

import { requestConnection } from 'iqlabs-sdk';

// Eine Freundschaftsanfrage senden
await requestConnection(
  connection, signer, 'my-db',
  myWalletAddress, friendWalletAddress,
  'dm_table', ['message', 'timestamp'], 'message_id', []
);

`manageConnection()`

Parameter	`builder`: InstructionBuilder `accounts`: `{ db_root, connection_table, signer }` `args`: `{ db_root_id, connection_seed, new_status }`
Rückgabe	TransactionInstruction

import { contract } from 'iqlabs-sdk';

// Eine Freundschaftsanfrage genehmigen
const approveIx = contract.manageConnectionInstruction(
  builder,
  { db_root, connection_table, signer: myPubkey },
  { db_root_id, connection_seed, new_status: contract.CONNECTION_STATUS_APPROVED }
);

// Einen Nutzer blockieren
const blockIx = contract.manageConnectionInstruction(
  builder,
  { db_root, connection_table, signer: myPubkey },
  { db_root_id, connection_seed, new_status: contract.CONNECTION_STATUS_BLOCKED }
);

`readConnection()`

Parameter	`dbRootId`: Datenbank-ID `walletA`, `walletB`: die beiden zu prüfenden Wallets
Rückgabe	`{ 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()`

Parameter	`connection`: Solana-RPC-Verbindung `signer`: signierende Wallet `dbRootId`: Datenbank-ID `connectionSeed`: Verbindungssamen `rowJson`: JSON-Daten
Rückgabe	Transaktionssignatur (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()`

Ruft alle Verbindungen (Freundschaftsanfragen) eines Nutzers ab, indem der Transaktionsverlauf des UserState-PDA analysiert wird. Jede Verbindung enthält ihre dbRootId, die angibt, zu welcher App die Verbindung gehört.

Parameter	`userPubkey`: öffentlicher Schlüssel des Nutzers (string oder PublicKey) `options`: optionale Einstellungen
Optionen	`limit`: maximale Anzahl an Transaktionen `before`: Signatur, ab der paginiert wird `speed`: Rate-Limit-Profil (‘light’, ‘medium’, ‘heavy’, ‘extreme’) `mode`: Vertragsmodus (optional)
Rückgabe	Array von Verbindungsobjekten mit dbRootId, partyA, partyB, status, requester, blocker, timestamp

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

// Alle Verbindungen abrufen (über alle Apps!)
const connections = await fetchUserConnections(myPubkey, {
  speed: 'light',  // 6 RPS (Standard)
  limit: 100
});

// Nach App filtern
const solchatConnections = connections.filter(c => c.dbRootId === 'solchat');
const zoConnections = connections.filter(c => c.dbRootId === 'zo-trading');

// Nach Status filtern
const pendingRequests = connections.filter(c => c.status === 'pending');
const friends = connections.filter(c => c.status === 'approved');
const blocked = connections.filter(c => c.status === 'blocked');

// Verbindungsdetails prüfen
connections.forEach(conn => {
  console.log(`App: ${conn.dbRootId}, ${conn.partyA} <-> ${conn.partyB}, status: ${conn.status}`);
});

Tabellenverwaltung

`writeRow()`

Parameter	`connection`: Solana-RPC-Verbindung `signer`: signierende Wallet `dbRootId`: Datenbank-ID `tableSeed`: Tabellenname `rowJson`: JSON-Zeilen-Daten
Rückgabe	Transaktionssignatur (string)

import { writeRow } from 'iqlabs-sdk';

// Erste Zeile schreiben, um die Tabelle zu erstellen
await writeRow(connection, signer, 'my-db', 'users', JSON.stringify({
  id: 1, name: 'Alice', email: 'alice@example.com'
}));

// Weitere Zeile in dieselbe Tabelle hinzufügen
await writeRow(connection, signer, 'my-db', 'users', JSON.stringify({
  id: 2, name: 'Bob', email: 'bob@example.com'
}));

`readTableRows()`

Parameter	`accountInfo`: Kontoinformationen der Tabelle
Rückgabe	Zeilen-Array (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()`

Parameter	`dbRootId`: Datenbank-ID
Rückgabe	Tabellenname-Array (string[])

import { getTablelistFromRoot } from 'iqlabs-sdk';

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

`fetchInventoryTransactions()`

Parameter	`userPubkey`: öffentlicher Schlüssel des Nutzers `limit`: Maximum (optional)
Rückgabe	Transaktions-Array

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}`);
  }
});

Umgebungseinstellungen

`setRpcUrl()`

Parameter	`url`: Solana-RPC-URL
Rückgabe	Keine (void)

import { setRpcUrl } from 'iqlabs-sdk';

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

Erweiterte Funktionen

Dies sind Low-Level-SDK-Funktionen. Für den typischen Gebrauch nicht nötig, aber hilfreich beim Erstellen eigener Features oder beim Debugging.

Writer-Funktionen

`manageRowData()`

Low-Level-Funktion zur Verwaltung von Zeilendaten in Tabellen.

Modul	`writer`
Anwendungsfall	Benutzerdefinierte Zeilenverwaltung, Batch-Operationen

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' })
});

Reader-Funktionen

`readUserState()`

Liest den UserState-PDA eines Nutzers.

Modul	`reader`
Anwendungsfall	Profildaten abrufen, Upload-Zählung prüfen

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

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

`readInventoryMetadata()`

Liest Metadaten, die mit dem Inventar des Nutzers (hochgeladene Dateien) verbunden sind.

Modul	`reader`
Anwendungsfall	Nutzerdateien mit Metadaten auflisten, Dateiverwaltung

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()`

Ruft alle Transaktionen für ein bestimmtes Konto ab.

Modul	`reader`
Anwendungsfall	Transaktionsverlauf, Kontoanalyse, Debugging

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()`

Ruft eine Liste von Session-PDAs ab.

Modul	`reader`
Anwendungsfall	Sitzungsverwaltung, Nachverfolgung aktiver Sitzungen

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

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

Hilfsfunktionen

`deriveDmSeed()`

Leitet einen deterministischen Seed für Direktnachrichten (DM) zwischen zwei Nutzern ab.

Modul	`utils` / `reader`
Anwendungsfall	Konsistente Verbindungs-IDs erstellen, DM-Kanal einrichten

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

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

`toSeedBytes()`

Konvertiert einen String-Seed in das Byte-Format, das für die PDA-Ableitung erforderlich ist.

Modul	`utils`
Anwendungsfall	Benutzerdefinierte PDA-Ableitung, Low-Level-Seed-Manipulation

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

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

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

Page

​Kernkonzepte

​Datenspeicherung (Code In)

​Wie wird es gespeichert?

​Wichtige zugehörige Funktionen

​Benutzerstatus-PDA

​Was wird gespeichert?

​Wann wird es erstellt?

​Verbindungs-PDA

​Welche Zustände kann es haben?

​Wichtige zugehörige Funktionen

​Datenbanktabellen

​Wie werden Tabellen erstellt?

​Wichtige zugehörige Funktionen

​Funktionsdetails

​Datenspeicherung und -abruf

​codeIn()

​readCodeIn()

​Verbindungsverwaltung

​requestConnection()

​manageConnection()

​readConnection()

​writeConnectionRow()

​fetchUserConnections()

​Tabellenverwaltung

​writeRow()

​readTableRows()

​getTablelistFromRoot()

​fetchInventoryTransactions()

​Umgebungseinstellungen

​setRpcUrl()

​Erweiterte Funktionen

​Writer-Funktionen

​manageRowData()

​Reader-Funktionen

​readUserState()

​readInventoryMetadata()

​fetchAccountTransactions()

​getSessionPdaList()

​Hilfsfunktionen

​deriveDmSeed()

​toSeedBytes()

Kernkonzepte

Datenspeicherung (Code In)

Wie wird es gespeichert?

Wichtige zugehörige Funktionen

Benutzerstatus-PDA

Was wird gespeichert?

Wann wird es erstellt?

Verbindungs-PDA

Welche Zustände kann es haben?

Wichtige zugehörige Funktionen

Datenbanktabellen

Wie werden Tabellen erstellt?

Wichtige zugehörige Funktionen

Funktionsdetails

Datenspeicherung und -abruf

`codeIn()`

`readCodeIn()`

Verbindungsverwaltung

`requestConnection()`

`manageConnection()`

`readConnection()`

`writeConnectionRow()`

`fetchUserConnections()`

Tabellenverwaltung

`writeRow()`

`readTableRows()`

`getTablelistFromRoot()`

`fetchInventoryTransactions()`

Umgebungseinstellungen

`setRpcUrl()`

Erweiterte Funktionen

Writer-Funktionen

`manageRowData()`

Reader-Funktionen

`readUserState()`

`readInventoryMetadata()`

`fetchAccountTransactions()`

`getSessionPdaList()`

Hilfsfunktionen

`deriveDmSeed()`

`toSeedBytes()`