@defield/sdk

SDK oficial para integrar DeField Protocol — escrow on-chain con yield automático, pagos por etapas (milestones), reputación portable (soulbound NFT) y arbitraje descentralizado con slashing.

Funciona con cualquier PublicClient / WalletClient de viem, compatible con wagmi, ethers.js adapters o llamadas directas.

Instalación

npm install @defield/sdk viem
# o
yarn add @defield/sdk viem

Quickstart

import { createPublicClient, createWalletClient, http, parseUnits } from "viem";
import { baseSepolia } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";
import { DeFieldClient, getScoreLevel, formatUSDC } from "@defield/sdk";

// — Clientes viem
const publicClient = createPublicClient({
  chain: baseSepolia,
  transport: http(),
});

const account = privateKeyToAccount("0x...");
const walletClient = createWalletClient({
  account,
  chain: baseSepolia,
  transport: http(),
});

// — DeFieldClient
const defield = new DeFieldClient({ publicClient, walletClient, chainId: 84532 });

Escrow — Pagos simples

// Crear un escrow (buyer firma)
const txHash = await defield.createEscrow({
  seller:   "0xSELLER...",
  amount:   parseUnits("100", 6),   // 100 USDC
  deadline: BigInt(Math.floor(Date.now() / 1000) + 7 * 24 * 3600), // 7 días
});

// Liberar pago cuando el trabajo esté hecho
await defield.releasePayment(42n);

// Leer datos de un escrow
const escrow = await defield.getEscrow(42n);
console.log(escrow.buyer, escrow.status);

Milestone Escrow — Pagos por etapas

// Crear un escrow con 3 etapas (1 depósito, N sub-escrows)
const txHash = await defield.createMilestoneEscrow({
  seller:    "0xSELLER...",
  amounts:   [parseUnits("500", 6), parseUnits("300", 6), parseUnits("200", 6)],
  deadlines: [deadline1, deadline2, deadline3],
});

// Liberar una etapa individual
await defield.releaseMilestone(projectId, 0n); // libera etapa 0

// Leer datos del proyecto
const project = await defield.getMilestoneProject(projectId);
console.log(project.escrowIds);       // IDs de cada sub-escrow
console.log(project.milestonesReleased); // cuántas liberadas

// Total de proyectos creados
const total = await defield.projectCount();

Cada etapa genera yield de forma independiente y se puede disputar por separado.

Reputación — Soulbound NFT Badges

// Score agregado 0-100
const score = await defield.getScore("0xUSER...");
const level = getScoreLevel(score);
console.log(`${score}/100 — ${level.label}`); // "72/100 — Expert"

// Stats del Seller Badge
const seller = await defield.getSellerStats("0xUSER...");
console.log(`${seller.completed}/${seller.total} deals, ${formatUSDC(seller.volumeUSDC)} USDC`);

// Stats del Buyer Badge
const buyer = await defield.getBuyerStats("0xUSER...");

// Reputación completa (seller + buyer + score máximo)
const rep = await defield.getReputation("0xUSER...");

// Con Judge Badge incluido
const full = await defield.getFullReputation("0xUSER...");
if (full.judge) {
  console.log(`Judge score: ${full.judge.score}, cases: ${full.judge.casesHandled}`);
}

// Token ID de cada badge (0 = no mintado)
const sellerToken = await defield.getSellerToken("0xUSER...");
const buyerToken  = await defield.getBuyerToken("0xUSER...");
const judgeToken  = await defield.getJudgeToken("0xUSER...");

// SVG on-chain del badge (data URI, sin IPFS)
const svg = await defield.getTokenURI(sellerToken);

Disputas — Arbitraje descentralizado

// Abrir disputa (buyer)
await defield.openDispute(escrowId);

// Enviar pruebas (hash keccak256)
await defield.submitEvidence(disputeId, "0xEVIDENCE_HASH...");

// Asignar jurado (después del período de evidencia)
await defield.assignJury(disputeId);

// Jurado: commit de voto (commit-reveal)
const commitHash = keccak256(encodePacked(["uint8", "bytes32"], [vote, salt]));
await defield.commitVote(disputeId, commitHash);

// Jurado: revelar voto
await defield.revealVote(disputeId, vote, salt);

// Resolver la disputa (conteo de votos)
await defield.tallyVotes(disputeId);

// Leer datos de una disputa
const dispute = await defield.getDispute(disputeId);
console.log(dispute.status, dispute.buyerVotes, dispute.sellerVotes);

// Ver jurado asignado
const jury = await defield.getJury(disputeId);

// Parámetros del protocolo
const fee   = await defield.getDisputeFee();   // fee en USDC
const stake = await defield.getMinStake();      // stake mínimo para ser árbitro
const total = await defield.disputeCount();     // total de disputas

Árbitros

// Registrarse como árbitro (requiere approve de minStake primero)
await defield.registerArbitrator();

// Retirar stake + yield acumulado
await defield.withdrawStake();

// Consultar datos de un árbitro
const arb = await defield.getArbitrator("0xARB...");
console.log(arb.stake, arb.casesHandled, arb.active);

// Listar todos los árbitros registrados
const all = await defield.getArbitrators();

Helpers

import { getScoreLevel, formatUSDC } from "@defield/sdk";

// Nivel de score
getScoreLevel(72);
// → { min: 55, max: 79, label: "Expert", color: "#37e6c1" }

// Formatear USDC (bigint 6 decimals → string)
formatUSDC(15_500_000n); // → "15.50"

API Reference completa

DeFieldClient — Lectura

| Método | Retorno | Descripción | |--------|---------|-------------| | getScore(user) | number | Score agregado 0–100 | | getSellerStats(user) | RoleStats | Stats del Seller Badge | | getBuyerStats(user) | RoleStats | Stats del Buyer Badge | | getReputation(user) | ReputationSummary | Seller + Buyer + score máximo | | getFullReputation(user) | FullReputationSummary | Incluye Judge Badge | | getSellerToken(user) | bigint | Token ID del Seller Badge (0 = sin badge) | | getBuyerToken(user) | bigint | Token ID del Buyer Badge | | getJudgeToken(user) | bigint | Token ID del Judge Badge | | getJudgeStats(user) | JudgeStats | Stats del Judge Badge | | getTokenURI(tokenId) | string | SVG on-chain del badge (data URI) | | getEscrow(escrowId) | EscrowInfo | Datos completos de un escrow | | getMilestoneProject(id) | MilestoneProjectInfo | Datos de un proyecto por etapas | | projectCount() | bigint | Total de proyectos milestone creados | | getDispute(disputeId) | DisputeInfo | Datos de una disputa | | getJury(disputeId) | Address[] | Panel del jurado asignado | | getArbitrator(arb) | ArbitratorInfo | Datos de un árbitro | | getArbitrators() | ArbitratorInfo[] | Todos los árbitros registrados | | disputeCount() | bigint | Total de disputas | | getDisputeFee() | bigint | Fee de disputa (USDC) | | getMinStake() | bigint | Stake mínimo para árbitros (USDC) |

DeFieldClient — Escritura

| Método | Descripción | |--------|-------------| | createEscrow({seller, amount, deadline}) | Aprueba USDC y crea escrow | | releasePayment(escrowId) | Buyer libera el pago | | openDispute(escrowId) | Buyer abre disputa | | createMilestoneEscrow({seller, amounts, deadlines}) | Crea proyecto con N etapas | | releaseMilestone(projectId, milestoneIndex) | Libera una etapa | | submitEvidence(disputeId, evidenceHash) | Enviar hash de pruebas | | assignJury(disputeId) | Asignar jurado | | commitVote(disputeId, commitHash) | Jurado: commit de voto | | revealVote(disputeId, vote, salt) | Jurado: revelar voto | | tallyVotes(disputeId) | Contar votos y resolver | | registerArbitrator() | Registrarse como árbitro | | withdrawStake() | Retirar stake + yield |

Propiedad

| Propiedad | Descripción | |-----------|-------------| | contracts | Devuelve las direcciones de todos los contratos para el chain configurado |

Tipos exportados

import type {
  EscrowInfo,
  MilestoneProjectInfo,
  RoleStats,
  ReputationSummary,
  FullReputationSummary,
  DisputeInfo,
  ArbitratorInfo,
  JudgeStats,
  ScoreLevel,
} from "@defield/sdk";

import { EscrowStatus, DisputeStatus, Vote } from "@defield/sdk";

// EscrowStatus: Active | Released | Refunded | Disputed
// DisputeStatus: Open | CommitPhase | RevealPhase | ResolvedBuyer | ResolvedSeller | ResolvedSplit | Escalated
// Vote: None | Buyer | Seller | Split

Direcciones de contratos

import { ADDRESSES } from "@defield/sdk";

ADDRESSES[84532].EscrowContract     // 0xC28e74cfB4044C00dD2CB257922A3112E2eeA7bA
ADDRESSES[84532].ReputationContract // 0x77a1fcdF80d9AAed2BA7d3e22fcA66631D99Cbf6
ADDRESSES[84532].YieldRouter        // 0xBc08C9131f6F9225C68B03217DeF669Bb056C44d
ADDRESSES[84532].DisputeContract    // 0x376Db275ddB79D6Da306e6aD566d086763b3Bf22
ADDRESSES[84532].YieldPaymaster     // 0xDE5c4e556069b89B90B1C070887Ce56A798f6F2a
ADDRESSES[84532].USDC               // 0x036CbD53842c5426634e7929541eC2318f3dCF7e

Contratos desplegados — Base Sepolia

| Contrato | Dirección | Verificado | |----------|-----------|------------| | EscrowContract | 0xC28e74cfB4044C00dD2CB257922A3112E2eeA7bA | Basescan | | ReputationContract | 0x77a1fcdF80d9AAed2BA7d3e22fcA66631D99Cbf6 | Basescan | | YieldRouter | 0xBc08C9131f6F9225C68B03217DeF669Bb056C44d | Basescan | | DisputeContract | 0x376Db275ddB79D6Da306e6aD566d086763b3Bf22 | Basescan | | YieldPaymaster | 0xDE5c4e556069b89B90B1C070887Ce56A798f6F2a | Basescan |

ABIs

El SDK exporta los ABIs completos de todos los contratos para uso directo con viem o ethers.js:

import { ESCROW_ABI, REPUTATION_ABI, DISPUTE_ABI, JUDGE_ABI, ERC20_ABI } from "@defield/sdk";

Licencia

MIT