Track Arkiv Network¶

Track del hackathon · 28–29 mayo · Premio USD 1.500

Modalidad 100% remota

Todo el equipo puede competir desde cualquier lugar. No hace falta estar en el Saluzzi.

Documentación oficial del track¶

Reglas, guía para builders, rúbrica, FAQ y recursos del desafío Arkiv × Puna Tech:

Arkiv × Puna Tech Hackathon (GitHub)

Formulario de entrega: forms.arkiv.network/punatech26

arkiv.network · Documentación SDK

Consigna del track¶

Datos verificables + IA. Apps que lean o escriban datos confiables, búsqueda, acceso o monetización de datos, prototipos Web3 + IA con caso de uso claro.

Construí un prototipo donde importe que un dato no se pueda editar a escondidas y donde Arkiv sea parte central del flujo (no un checkbox al final).

¿Qué es Arkiv?¶

Arkiv es una capa de datos universal para Ethereum: una “base de datos” consultable, con datos anclados on-chain, con vencimiento opcional y atributos indexables.

En lugar de guardar todo en un servidor que vos controlás (y que nadie puede auditar), publicás entidades en la red. Cualquiera puede:

Leer el contenido y metadatos
Verificar quién lo creó y cuándo
Consultar por atributos (como una DB)

Analogía rápida¶

Mundo tradicional	Con Arkiv
Base PostgreSQL en tu VPS	Entidades en la red Braga
`UPDATE` silencioso en una fila	Historial verificable on-chain
API REST propia	SDK + JSON-RPC `arkiv_query`
“Confiá en nosotros”	“Verificá en el explorer”

¿Para qué sirve?¶

Certificados y credenciales verificables (curso, inspección, entrega)
Registros de auditoría (quién cambió qué y cuándo)
Datos abiertos con garantías (datasets con prueba de integridad)
Trazabilidad (origen → estado actual de un activo o evento)
Apps + IA que leen/escriben datos confiables (resúmenes, búsqueda, clasificación)

Conceptos que tenés que conocer¶

Concepto	Qué es
Entity (entidad)	Unidad de dato: `payload` + `contentType` + `attributes` + expiración
Payload	Contenido (texto, JSON, binario)
Attributes	Metadatos indexables (`key` / `value`) para consultas
Entity key	Identificador único de la entidad
PublicClient	Cliente solo lectura — seguro en frontend
WalletClient	Cliente lectura/escritura — necesita clave privada
Braga	Red de prueba (testnet) actual de Arkiv

Red de prueba: Braga¶

Usá solo Braga durante el hackathon.

Parámetro	Valor
Network ID	`60138453102`
HTTP RPC	`https://braga.hoodi.arkiv.network/rpc`
WebSocket	`wss://braga.hoodi.arkiv.network/rpc/ws`
Gas token	GLM (pedilo en el faucet)
Faucet	braga.hoodi.arkiv.network/faucet
Block explorer	explorer.braga.hoodi.arkiv.network
Entity explorer	data.arkiv.network

Kaolin deprecada

Si encontrás docs viejas de Kaolin: migrá a Braga. Guía de migración.

Instalación¶

Requisitos¶

Node.js 18+
Cuenta Ethereum (clave privada) con GLM en Braga
Editor + GitHub

Paso 1 · Proyecto¶

mkdir puna-tech-arkiv && cd puna-tech-arkiv
npm init -y
npm pkg set type=module
npm install @arkiv-network/sdk dotenv typescript tsx

Paso 2 · Variables de entorno¶

Creá .env:

PRIVATE_KEY=0xTU_CLAVE_PRIVADA_AQUI

Agregá a .gitignore:

.env
node_modules/

Paso 3 · Faucet¶

Entrá al faucet de Braga
Pegá la dirección pública de tu wallet
Esperá GLM para pagar gas al crear entidades

Tutorial 1 · Hello World (crear y leer)¶

Archivo hello.ts:

import { createWalletClient, createPublicClient, http } from "@arkiv-network/sdk";
import { stringToPayload } from "@arkiv-network/sdk/utils";
import { braga } from "@arkiv-network/sdk/chains";
import { privateKeyToAccount } from "@arkiv-network/sdk/accounts";
import { config } from "dotenv";

config();

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);

const walletClient = createWalletClient({
  chain: braga,
  transport: http(),
  account,
});

const publicClient = createPublicClient({
  chain: braga,
  transport: http(),
});

// 1. Crear entidad
const { entityKey, txHash } = await walletClient.createEntity({
  payload: stringToPayload("Hello, Puna Tech 2026!"),
  contentType: "text/plain",
  attributes: [
    { key: "event", value: "puna-tech" },
    { key: "track", value: "arkiv" },
  ],
  expiresIn: 86400, // segundos — 24 h
});

console.log("✅ Entidad creada");
console.log("   Key:", entityKey);
console.log("   Tx: ", txHash);

// 2. Leer entidad
const entity = await publicClient.getEntity(entityKey);
console.log("📄 Contenido:", entity.toText());

npx tsx hello.ts

Qué deberías ver: entityKey, hash de transacción y el texto Hello, Puna Tech 2026!.
Buscá el txHash en el explorer.

Tutorial 2 · Guardar JSON estructurado¶

Para apps reales, el payload suele ser JSON:

import { jsonToPayload } from "@arkiv-network/sdk/utils";

const reporte = {
  tipo: "inspeccion",
  barrio: "Centro",
  fecha: "2026-05-28",
  ok: true,
};

const { entityKey } = await walletClient.createEntity({
  payload: jsonToPayload(reporte),
  contentType: "application/json",
  attributes: [
    { key: "tipo", value: "inspeccion" },
    { key: "barrio", value: "Centro" },
    { key: "status", value: "active" },
  ],
  expiresIn: 604800, // 7 días
});

const entity = await publicClient.getEntity(entityKey);
const data = entity.toJSON(); // objeto parseado
console.log(data);

Idea de proyecto: cada reporte ciudadano = una entidad con atributos consultables.

Tutorial 3 · Consultar entidades (query)¶

Podés consultar sin wallet, vía PublicClient o JSON-RPC.

Con SDK (conceptual)¶

Usá publicClient para getEntity(key) cuando conocés la key.

Con JSON-RPC `arkiv_query`¶

curl https://braga.hoodi.arkiv.network/rpc \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"arkiv_query",
    "params":[
      "track = \"arkiv\" && status = \"active\"",
      {"resultsPerPage":"0xa"}
    ]
  }'

Operadores útiles: &&, ||, =, !=, >, <, ~ (glob).
Atributos especiales: $owner, $creator, $key, $all.

→ Documentación completa de queries

Tutorial 4 · Frontend de solo lectura¶

En React/Next, nunca expongas PRIVATE_KEY. Patrón:

// lib/arkiv-read.ts — solo PublicClient
import { createPublicClient, http } from "@arkiv-network/sdk";
import { braga } from "@arkiv-network/sdk/chains";

export const arkivRead = createPublicClient({
  chain: braga,
  transport: http(),
});

// En un componente:
// const entity = await arkivRead.getEntity(entityKeyFromProps);
// setTexto(entity.toText());

Las escrituras van en:

Script Node que corre en tu máquina durante el hackathon, o
API route en Vercel con PRIVATE_KEY en variables de entorno

flowchart LR
  Browser -->|GET /api/reportes| API[Vercel API route]
  API -->|WalletClient.createEntity| Braga[(Braga)]
  Browser -->|PublicClient.getEntity| Braga

Tutorial 5 · Actualizar y borrar (opcional)¶

Si tu MVP necesita corregir datos:

// Actualizar (solo owner)
await walletClient.updateEntity({
  entityKey,
  payload: stringToPayload("Contenido corregido"),
  contentType: "text/plain",
});

// Borrar
await walletClient.deleteEntity({ entityKey });

Para el hackathon muchos equipos alcanzan con solo create + read + query.

Casos de uso para el track¶

Idea	Flujo Arkiv
Inspección municipal	`createEntity` con JSON + atributos `barrio`, `tipo`
Certificado de taller	Entidad con `contentType: application/json` + link en QR
Dataset + IA	Guardar resumen IA como entidad; UI consulta por `$owner`
Trazabilidad	Cadena de entidades referenciando `parentKey` en attributes

Qué evalúa el jurado¶

Criterio	Detalle
Problema	¿Por qué on-chain y no un Google Sheet?
Integración	¿createEntity / getEntity / query visibles en la demo?
Claridad	¿Se entiende payload vs attributes en el pitch?
IA	¿Sumó valor o es decoración?
Demo	¿Funciona en 2 min?

Plan sugerido · 48 h¶

Hora	Objetivo
Jue 9–12	Tutorial 1 + 2 funcionando
Jue 12–18	UI que lista/crea entidades
Vie 9–15	Query + 1 feature IA
Vie 15–18	Pitch + Loom backup

Errores frecuentes¶

Error	Solución
`insufficient funds`	Faucet GLM en Braga
`invalid private key`	Clave con prefijo `0x`, 64 hex
Entidad no aparece	Esperá confirmación; revisá tx en explorer
Query vacía	Verificá nombres de attributes en create vs query

Links oficiales¶

Arkiv × Puna Tech Hackathon (GitHub) — reglas, guía builders, rúbrica, FAQ
Formulario de entrega
Instalación SDK
Querying data
Litepaper (PDF)
Guía completa /hackathon · Reglas

Mentores¶

Pedí ayuda en el venue con: error exacto del SDK, diseño de entidades, o demo que no confirma on-chain.