Documentação para desenvolvedores

Conceitos e funções principais para o SDK da IQLabs

Este documento está em andamento e será refinado.

Conceitos principais

Estes são os conceitos principais que você precisa conhecer antes de usar o SDK da IQLabs.

---

Armazenamento de dados (Code In)

É assim que você armazena qualquer dado (arquivos, texto, JSON) on-chain.

Como é armazenado?

Dependendo do tamanho dos dados, o SDK escolhe o método ideal:

• Dados pequenos (< 900 bytes): armazenar imediatamente, mais rápido
• Dados médios (< 8.5 KB): dividir em várias transações
• Dados grandes (>= 8.5 KB): enviar em paralelo para mais velocidade

Funções principais relacionadas

• codeIn(): enviar dados e obter um ID de transação
• readCodeIn(): ler dados a partir de um ID de transação

---

PDA de estado do usuário

Uma conta de perfil on-chain para um usuário.

O que é armazenado?

• Informações de perfil (nome, foto de perfil, bio, etc.)
• Número de arquivos enviados
• Registros de solicitações de amizade

Solicitações de amizade não são armazenadas como valores no PDA; elas são enviadas como transações.

Quando é criado?

É criado automaticamente na primeira vez que você chama codeIn(). Nenhuma configuração extra é necessária, mas o primeiro usuário pode precisar assinar duas vezes.

---

PDA de conexão

Uma conta on-chain que gerencia relacionamentos entre dois usuários (amigos, mensagens, etc.).

Quais estados pode ter?

• pending: uma solicitação de amizade foi enviada, mas ainda não foi aceita
• approved: a solicitação foi aceita e os usuários estão conectados
• blocked: um lado bloqueou o outro

Uma conexão bloqueada só pode ser desbloqueada por quem bloqueou.

Funções principais relacionadas

• requestConnection(): enviar uma solicitação de amizade (cria pending)
• manageConnection(): aprovar/rejeitar/bloquear/desbloquear uma solicitação
• readConnection(): verificar o status atual do relacionamento
• writeConnectionRow(): trocar mensagens/dados com um amigo conectado
• fetchUserConnections(): buscar todas as conexões (solicitações enviadas e recebidas)

---

Tabelas de banco de dados

Armazene dados JSON em tabelas como um banco de dados.

Como as tabelas são criadas?

Não existe uma função dedicada de “criar tabela”. A primeira gravação via writeRow() cria a tabela automaticamente.

Uma tabela é identificada de forma única pela combinação de dbRootId e tableSeed (nome da tabela).

Funções principais relacionadas

• writeRow(): adicionar uma nova linha (cria a tabela se não existir)
• readTableRows(): ler linhas de uma tabela
• getTablelistFromRoot(): listar todas as tabelas de um banco de dados
• fetchInventoryTransactions(): listar arquivos enviados

---

Detalhes das funções

Armazenamento e recuperação de dados

codeIn()

Parâmetros	connection: conexão RPC Solana signer: carteira assinante data: dados para envio (string única ou array) mode: modo de contrato (padrão: ‘anchor’)
Retorna	Assinatura da transação (string)

import { codeIn } from 'iqlabs-sdk';

// Enviar um único arquivo
const signature = await codeIn(connection, signer, 'Hello, blockchain!');

// Enviar vários arquivos
const multiSig = await codeIn(connection, signer, ['file1.txt', 'file2.txt', 'file3.txt']);

---

readCodeIn()

Parâmetros	txSignature: assinatura da transação connection: (opcional) conexão RPC Solana
Retorna	Dados armazenados (string)

import { readCodeIn } from 'iqlabs-sdk';

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

---

Gerenciamento de conexões

requestConnection()

Parâmetros	connection: conexão RPC Solana signer: carteira assinante dbRootId: ID do banco de dados partyA, partyB: os dois usuários a conectar tableName: nome da tabela de conexão columns: lista de colunas idCol: coluna de ID extKeys: chaves de extensão
Retorna	Assinatura da transação (string)

import { requestConnection } from 'iqlabs-sdk';

// Enviar uma solicitação de amizade
await requestConnection(
  connection, signer, 'my-db',
  myWalletAddress, friendWalletAddress,
  'dm_table', ['message', 'timestamp'], 'message_id', []
);

---

manageConnection()

Parâmetros	builder: InstructionBuilder accounts: { db_root, connection_table, signer } args: { db_root_id, connection_seed, new_status }
Retorna	TransactionInstruction

import { contract } from 'iqlabs-sdk';

// Aprovar uma solicitação de amizade
const approveIx = contract.manageConnectionInstruction(
  builder,
  { db_root, connection_table, signer: myPubkey },
  { db_root_id, connection_seed, new_status: contract.CONNECTION_STATUS_APPROVED }
);

// Bloquear um usuário
const blockIx = contract.manageConnectionInstruction(
  builder,
  { db_root, connection_table, signer: myPubkey },
  { db_root_id, connection_seed, new_status: contract.CONNECTION_STATUS_BLOCKED }
);

---

readConnection()

Parâmetros	dbRootId: ID do banco de dados walletA, walletB: as duas carteiras a verificar
Retorna	{ 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()

Parâmetros	connection: conexão RPC Solana signer: carteira assinante dbRootId: ID do banco de dados connectionSeed: semente de conexão rowJson: dados JSON
Retorna	Assinatura da transação (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()

Busca todas as conexões (solicitações de amizade) de um usuário analisando o histórico de transações do PDA UserState. Cada conexão inclui seu dbRootId, identificando a qual app a conexão pertence.

Parâmetros	userPubkey: chave pública do usuário (string ou PublicKey) options: opções opcionais
Opções	limit: número máximo de transações para buscar before: assinatura para paginar a partir de speed: perfil de limite de taxa (‘light’, ‘medium’, ‘heavy’, ‘extreme’) mode: modo de contrato (opcional)
Retorna	Array de objetos de conexão com dbRootId, partyA, partyB, status, requester, blocker, timestamp

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

// Buscar todas as conexões (em todos os apps!)
const connections = await fetchUserConnections(myPubkey, {
  speed: 'light',  // 6 RPS (padrão)
  limit: 100
});

// Filtrar por app
const solchatConnections = connections.filter(c => c.dbRootId === 'solchat');
const zoConnections = connections.filter(c => c.dbRootId === 'zo-trading');

// Filtrar por status
const pendingRequests = connections.filter(c => c.status === 'pending');
const friends = connections.filter(c => c.status === 'approved');
const blocked = connections.filter(c => c.status === 'blocked');

// Verificar detalhes da conexão
connections.forEach(conn => {
  console.log(`App: ${conn.dbRootId}, ${conn.partyA} <-> ${conn.partyB}, status: ${conn.status}`);
});

---

Gerenciamento de tabelas

writeRow()

Parâmetros	connection: conexão RPC Solana signer: carteira assinante dbRootId: ID do banco de dados tableSeed: nome da tabela rowJson: dados JSON da linha
Retorna	Assinatura da transação (string)

import { writeRow } from 'iqlabs-sdk';

// Escrever a primeira linha para criar a tabela
await writeRow(connection, signer, 'my-db', 'users', JSON.stringify({
  id: 1, name: 'Alice', email: '[e-mail]'
}));

// Adicionar outra linha à mesma tabela
await writeRow(connection, signer, 'my-db', 'users', JSON.stringify({
  id: 2, name: 'Bob', email: '[e-mail]'
}));

---

readTableRows()

Parâmetros	accountInfo: informações da conta da tabela
Retorna	Array de linhas (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()

Parâmetros	dbRootId: ID do banco de dados
Retorna	Array de nomes de tabela (string[])

import { getTablelistFromRoot } from 'iqlabs-sdk';

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

---

fetchInventoryTransactions()

Parâmetros	userPubkey: chave pública do usuário limit: máximo (opcional)
Retorna	Array de transações

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

---

Configurações de ambiente

setRpcUrl()

Parâmetros	url: URL de RPC Solana
Retorna	Nenhum (void)

import { setRpcUrl } from 'iqlabs-sdk';

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

---

Funções avançadas

Estas são funções de baixo nível do SDK. Não são necessárias para uso típico, mas são úteis ao criar recursos personalizados ou depurar.

Funções de escrita

manageRowData()

Função de baixo nível para gerenciar dados de linhas em tabelas.

Módulo	writer
Caso de uso	Gerenciamento personalizado de linhas, operações em lote

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

---

Funções de leitura

readUserState()

Lê o PDA UserState de um usuário.

Módulo	reader
Caso de uso	Buscar dados de perfil, conferir contagens de upload

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

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

---

readInventoryMetadata()

Lê os metadados associados ao inventário do usuário (arquivos enviados).

Módulo	reader
Caso de uso	Listar arquivos do usuário com metadados, gerenciamento de arquivos

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

Busca todas as transações de uma conta específica.

Módulo	reader
Caso de uso	Histórico de transações, análise de conta, depuração

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

Recupera uma lista de PDAs de sessão.

Módulo	reader
Caso de uso	Gerenciamento de sessões, acompanhamento de sessões ativas

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

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

---

Funções utilitárias

deriveDmSeed()

Deriva uma semente determinística para mensagens diretas (DM) entre dois usuários.

Módulo	utils / reader
Caso de uso	Criar identificadores de conexão consistentes, configuração de canal DM

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

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

---

toSeedBytes()

Converte uma semente de string para o formato de bytes necessário para derivação de PDA.

Módulo	utils
Caso de uso	Derivação personalizada de PDA, manipulação de sementes de baixo nível

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

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

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