Tutorial: Midnight Wallet SDK - Guía Completa para Desarrolladores

Índice

Introducción
Instalación
Conceptos Clave
Crear Instancias de Billetera
Gestión de Direcciones
Trabajar con Transacciones
Conectar con DApps
Ejemplos Prácticos

Introducción
Midnight Wallet SDK es un conjunto de herramientas que permite integrar funcionalidad de billetera en aplicaciones blockchain. El SDK proporciona abstracciones de alto nivel para gestionar operaciones comunes como:

Derivación de claves - Generar claves criptográficas a partir de una semilla
Balance de tokens - Obtener el saldo de tokens desde datos de la cadena
Gestión de monedas - Administrar monedas y datos para pruebas de conocimiento cero
Conexión con indexadores - Sincronizar estado con servidores indexadores
Creación de transacciones - Preparar y enviar transferencias de tokens

Paquetes Principales
PaqueteDescripción@midnight-ntwrk/wallet-apiInterfaces de alto nivel para billeteras@midnight-ntwrk/walletImplementación de wallet-api con herramientas adicionales@midnight-ntwrk/zswapConstrucción de bloques de Zswap@midnight-ntwrk/wallet-sdk-hdSoporte para billeteras jerárquico-determinísticas (HD)@midnight-ntwrk/wallet-sdk-address-formatSoporte para formato de dirección Bech32m

Instalación
Requisitos Previos

Node.js instalado
Yarn o npm como gestor de paquetes

Instalación del SDK
Usa Yarn para instalar el paquete:
bashyarn add @midnight-ntwrk/wallet/
Reemplaza con la versión requerida según la matriz de compatibilidad de versiones.
⚠️ Importante: A partir de la versión 4.0.0 hay cambios significativos. Consulta la matriz de compatibilidad para asegurar que usas la versión correcta.
Información Crítica sobre v4.0.0

Cambio importante: Las claves secretas ya no se incluyen en el estado serializado de la billetera
Restauración: Si restauras una billetera desde una instantánea, debes proporcionar la semilla original
Seguridad: Asegúrate de gestionar datos sensibles de forma segura

Conceptos Clave
Semilla de Billetera (Wallet Seed)
La semilla es un valor aleatorio (usualmente 256 bits) que se usa para derivar todas las claves criptográficas de tu billetera. Es esencial para:

Recuperar una billetera
Generar direcciones determinísticas
Restaurar estado desde instantáneas

Billeteras HD (Jerárquico-Determinísticas)
El SDK utiliza derivación BIP-32 siguiendo la ruta:
m / 44' / 2400' / account' / role / index
Donde:

account - Número de cuenta (recomendación BIP-44)
role - Tipo de rol (3 para Zswap)
index - Índice específico (recomendación BIP-44)

Ciclo de Vida de la Billetera

1. Crear instancia → 2. Iniciar sincronización → 3. Usar billetera → 4. Cerrar NetworkId (Identificador de Red) Define la red blockchain objetivo:

NetworkId.TestNet - Red de prueba
NetworkId.MainNet - Red principal
NetworkId.DevNet - Red de desarrollo

Crear Instancias de Billetera
Paso 1: Importar el Constructor
javascriptimport { WalletBuilder } from '@midnight-ntwrk/wallet';
import { NetworkId } from '@midnight-ntwrk/zswap';
Paso 2: Generar una Semilla
Para testing, puedes generar una semilla aleatoria:
javascriptimport { generateRandomSeed } from '@midnight-ntwrk/wallet-sdk-hd';

const semillaAleatoria = generateRandomSeed();
console.log('Semilla generada:', semillaAleatoria);
Para producción, usa derivación HD:
javascriptimport {
generateRandomSeed,
HDWallet,
Roles,
} from "@midnight-ntwrk/wallet-sdk-hd";

const semilla = generateRandomSeed();

function derivarSemillaDerivacion(semilla) {
const billetera = HDWallet.fromSeed(semilla);

if (billetera.type != "seedOk") {
throw new Error("Error inicializando HD Wallet");
}

const zswapKey = billetera.hdWallet
.selectAccount(0)
.selectRole(Roles.Zswap)
.deriveKeyAt(0);

if (zswapKey.type === "keyDerived") {
return zswapKey.key;
} else {
throw new Error("Error derivando clave");
}
}

const semillaFinal = derivarSemillaDerivacion(semilla);
console.log('Semilla derivada:', semillaFinal);
Paso 3: Construir la Instancia
Opción A: Desde una Semilla Específica
javascriptimport { WalletBuilder } from '@midnight-ntwrk/wallet';
import { NetworkId } from '@midnight-ntwrk/zswap';

const billetera = await WalletBuilder.build(
'https://indexer.testnet-02.midnight.network/api/v1/graphql', // URL del Indexador
'wss://indexer.testnet-02.midnight.network/api/v1/graphql/ws', // WebSocket del Indexador
'http://localhost:6300', // URL del Servidor de Pruebas
'https://rpc.testnet-02.midnight.network', // URL del Nodo
'0000000000000000000000000000000000000000000000000000000000000000', // Semilla
NetworkId.TestNet, // Red
'error' // Nivel de Log (opcional)
);
Opción B: Con Semilla Aleatoria (Testing)
javascriptimport { WalletBuilder } from '@midnight-ntwrk/wallet';
import { NetworkId } from '@midnight-ntwrk/zswap';
import { generateRandomSeed } from '@midnight-ntwrk/wallet-sdk-hd';

const semillaAleatoria = generateRandomSeed();

const billetera = await WalletBuilder.build(
'https://indexer.testnet-02.midnight.network/api/v1/graphql',
'wss://indexer.testnet-02.midnight.network/api/v1/graphql/ws',
'http://localhost:6300',
'https://rpc.testnet-02.midnight.network',
semillaAleatoria, // Semilla aleatoria
NetworkId.TestNet,
'error'
);
Paso 4: Iniciar la Sincronización
javascript// Inicia la sincronización con la cadena
billetera.start();

console.log('Billetera iniciada y sincronizando...');
Paso 5: Cerrar la Billetera
javascript// Cuando termines, cierra la billetera adecuadamente
await billetera.close();

console.log('Billetera cerrada y recursos liberados');

Instantáneas de Estado (State Snapshots)
Las instantáneas permiten guardar y restaurar el estado de una billetera rápidamente, ideal para extensiones de navegador o aplicaciones móviles.
Crear una Instantánea
javascriptconst estadoSerializado = await billetera.serialize();

console.log('Instantánea creada:', estadoSerializado);
Restaurar desde una Instantánea
⚠️ Importante: Debes proporcionar la semilla original para restaurar.
javascriptconst billetera_restaurada = await WalletBuilder.restore(
'https://indexer.testnet-02.midnight.network/api/v1/graphql',
'wss://indexer.testnet-02.midnight.network/api/v1/graphql/ws',
'http://localhost:6300',
'https://rpc.testnet-02.midnight.network',
'0000000000000000000000000000000000000000000000000000000000000000', // DEBES proporcionar la semilla
estadoSerializado,
'error'
);

billetera_restaurada.start();

Gestión de Direcciones
Formato Bech32m
Midnight utiliza direcciones en formato Bech32m con el prefijo personalizado mn_.
La estructura del prefijo es:
mn__
Ejemplos:

mn_shield-addr_test1... - Dirección de pago en TestNet
mn_shield-addr_test1... - Dirección escudada en TestNet (ESK para indexador)

Codificar una Dirección
javascriptimport {
ShieldedAddress,
ShieldedCoinPublicKey,
ShieldedEncryptionPublicKey,
MidnightBech32m,
} from "@midnight-ntwrk/wallet-sdk-address-format";
import { NetworkId } from "@midnight-ntwrk/zswap";
import { Buffer } from "buffer";

// Crear claves públicas
const claveCoinPublica = new ShieldedCoinPublicKey(
Buffer.from(
"064e092a80b33bee23404c46cfc48fec75a2356a9b01178dd6a62c29f5896f67",
"hex"
)
);

const claveEncriptacionPublica = new ShieldedEncryptionPublicKey(
Buffer.from(
"0300063c7753854aea18aa11f04d77b3c7eaa0918e4aa98d5eaf0704d8f4c2fc272899efbb8a71275f2a1aedd29f879021e0962b4730f9b47e1a",
"hex"
)
);

// Crear dirección
const direccion = new ShieldedAddress(claveCoinPublica, claveEncriptacionPublica);

// Codificar en Bech32m
const direccionCodificada = ShieldedAddress.codec
.encode(NetworkId.TestNet, direccion)
.asString();

console.log('Dirección codificada:', direccionCodificada);
// Salida: mn_shield-addr_test1qe8qj25qkva7ug6qf3rvl3y0a366ydt2nvq30rwk5ckznavfdansxqqx83m48p22agv25y0sf4mm83l25zgcuj4f34027pcymr6v9lp89zv7lwu2wyn472s6ahfflpusy8sfv268xrumgls62hqz4u
Decodificar una Dirección
javascriptconst direccionCodificada = "mn_shield-addr_test1qe8qj25qkva7ug6qf3rvl3y0a366ydt2nvq30rwk5ckznavfdansxqqx83m48p22agv25y0sf4mm83l25zgcuj4f34027pcymr6v9lp89zv7lwu2wyn472s6ahfflpusy8sfv268xrumgls62hqz4u";

// Parsear
const direccionParseada = MidnightBech32m.parse(direccionCodificada);

// Decodificar
const direccionDecodificada = ShieldedAddress.codec.decode(
NetworkId.TestNet,
direccionParseada
);

console.log('Clave pública de coin:', direccionDecodificada.coinPublicKeyString());
console.log('Clave pública de encriptación:', direccionDecodificada.encryptionPublicKeyString());

Trabajar con Transacciones
Ciclo de Vida de una Transacción

1. Preparar transacción sin prueba ↓
2. Calcular pruebas de conocimiento cero ↓
3. Enviar transacción comprobada Acceder al Estado de la Billetera El estado se proporciona a través de un observable de RxJS: javascriptimport { Observable } from 'rxjs';

// Suscribirse a cambios de estado
billetera.state().subscribe((estado) => {
console.log('Estado actual:', estado);
console.log('Saldo:', estado.coins);
console.log('Historial de transacciones:', estado.transactionHistory);
});
Paso 1: Preparar una Transferencia
javascriptimport { nativeToken } from '@midnight-ntwrk/zswap';

// ⚠️ IMPORTANTE: Asegúrate que la billetera haya sincronizado completamente
// antes de preparar una transacción. De lo contrario, podrías intentar gastar
// una moneda que ya fue gastada pero tu billetera aún no lo sabe.

const recetaTransferencia = await billetera.transferTransaction([
{
amount: 1n, // Cantidad en satoshis (BigInt)
type: nativeToken(), // Tipo de token (tDUST)
receiverAddress: 'mn_shield-addr_test1kj...' // Dirección del receptor
}
]);

console.log('Receta de transferencia preparada');
Paso 2: Balancear una Transacción Existente
Balancear una transacción significa ajustarla para cubrir las comisiones y equilibrar entradas/salidas:
javascriptconst transaccionBalanceada = await billetera.balanceTransaction(
transaccionExistente,
[] // newCoins (opcional) - para monedas nuevas creadas por DApps
);

console.log('Transacción balanceada');
Paso 3: Generar Pruebas de Conocimiento Cero
Este paso es computacionalmente intensivo y puede tomar varios segundos:
javascriptimport { TRANSACTION_TO_PROVE } from '@midnight-ntwrk/wallet-api';

// Crear la receta (wrapper) de la transacción
const receta = {
type: TRANSACTION_TO_PROVE,
transaction: recetaTransferencia
};

// Generar pruebas (⚠️ Esto es MUY lento - puede tomar decenas de segundos)
console.time('Generación de pruebas');
const transaccionComprobada = await billetera.proveTransaction(receta);
console.timeEnd('Generación de pruebas');

console.log('Pruebas generadas exitosamente');
Paso 4: Enviar la Transacción
javascript// La transacción debe estar:
// 1. Balanceada (entradas ≥ salidas + comisiones)
// 2. Comprobada (pruebas generadas)

const transaccionEnviada = await billetera.submitTransaction(
transaccionComprobada
);

console.log('Transacción enviada:', transaccionEnviada);
console.log('Hash de transacción:', transaccionEnviada.id);

Conectar con DApps
Las aplicaciones descentralizadas se conectan a la billetera a través del API de DApp Connector. La billetera se inyecta en el contexto del navegador, permitiendo que las DApps soliciten operaciones como:

Obtener dirección del usuario
Firmar transacciones
Enviar tokens
Ejecutar contratos inteligentes

Consulta:

DApp Connector Overview
Wallet Provider para más detalles técnicos

Ejemplos Prácticos
Ejemplo 1: Transferencia Básica de tDUST
Este ejemplo crea una billetera, sincroniza con la cadena y envía 1 tDUST a otra dirección:
javascriptimport { WalletBuilder } from '@midnight-ntwrk/wallet';
import { NetworkId, nativeToken } from '@midnight-ntwrk/zswap';

async function transferirTDUST() {
try {
// 1. Crear billetera
console.log('📱 Creando billetera...');
const billetera = await WalletBuilder.build(
'https://indexer.testnet-02.midnight.network/api/v1/graphql',
'wss://indexer.testnet-02.midnight.network/api/v1/graphql/ws',
'http://localhost:6300',
'https://rpc.testnet-02.midnight.network',
'0000000000000000000000000000000000000000000000000000000000000000',
NetworkId.TestNet
);

// 2. Iniciar sincronización
console.log('🔄 Iniciando sincronización...');
billetera.start();

// Esperar a que sincronice (en producción, implementa mejor lógica de espera)
await new Promise(resolve => setTimeout(resolve, 5000));

// 3. Preparar transferencia
console.log('💸 Preparando transferencia...');
const recetaTransferencia = await billetera.transferTransaction([
  {
    amount: 1n,
    type: nativeToken(),
    receiverAddress: 'mn_shield-addr_test1kjwksfp8x2tachehsfvufsdl35ljg5cxzdcysjdn6ntadspyxn3qxqrxypgjm055c2azrpuyn7un0ge2vm25vkfv38d24rj3ewcku5wmdc94gjr9'
  }
]);

// 4. Generar pruebas
console.log('⚙️ Generando pruebas de conocimiento cero (esto puede tomar un tiempo)...');
const transaccionComprobada = await billetera.proveTransaction(recetaTransferencia);

// 5. Enviar transacción
console.log('📤 Enviando transacción...');
const resultado = await billetera.submitTransaction(transaccionComprobada);

console.log('✅ ¡Transacción enviada exitosamente!');
console.log('ID de transacción:', resultado.id);

// 6. Cerrar billetera
await billetera.close();
console.log('🔐 Billetera cerrada');

} catch (error) {
console.error('❌ Error:', error.message);
}
}

// Ejecutar
transferirTDUST();
Ejemplo 2: Guardar y Restaurar Billetera
javascriptimport { WalletBuilder } from '@midnight-ntwrk/wallet';
import { NetworkId } from '@midnight-ntwrk/zswap';
import { generateRandomSeed } from '@midnight-ntwrk/wallet-sdk-hd';
import * as fs from 'fs';

async function guardarYRestaurarBilletera() {
const ruutaArchivo = './billetera_snapshot.json';
const semilla = generateRandomSeed();

try {
// 1. Crear billetera original
console.log('📱 Creando billetera original...');
const billetera = await WalletBuilder.build(
'https://indexer.testnet-02.midnight.network/api/v1/graphql',
'wss://indexer.testnet-02.midnight.network/api/v1/graphql/ws',
'http://localhost:6300',
'https://rpc.testnet-02.midnight.network',
semilla,
NetworkId.TestNet
);

billetera.start();

// Esperar sincronización
await new Promise(resolve => setTimeout(resolve, 3000));

// 2. Guardar instantánea
console.log('💾 Guardando instantánea...');
const estadoSerializado = await billetera.serialize();
fs.writeFileSync(ruutaArchivo, JSON.stringify({
  estado: estadoSerializado,
  semilla: Buffer.from(semilla).toString('hex')
}, null, 2));

await billetera.close();
console.log('✅ Instantánea guardada en:', ruutaArchivo);

// 3. Restaurar desde instantánea
console.log('📂 Leyendo instantánea...');
const datos = JSON.parse(fs.readFileSync(ruutaArchivo, 'utf-8'));

console.log('🔄 Restaurando billetera...');
const billetera_restaurada = await WalletBuilder.restore(
  'https://indexer.testnet-02.midnight.network/api/v1/graphql',
  'wss://indexer.testnet-02.midnight.network/api/v1/graphql/ws',
  'http://localhost:6300',
  'https://rpc.testnet-02.midnight.network',
  Buffer.from(datos.semilla, 'hex'),
  datos.estado
);

billetera_restaurada.start();
console.log('✅ Billetera restaurada exitosamente');

// Verificar estado
billetera_restaurada.state().subscribe((estado) => {
  console.log('Estado restaurado - Monedas:', estado.coins);
});

await billetera_restaurada.close();

} catch (error) {
console.error('❌ Error:', error.message);
}
}

guardarYRestaurarBilletera();
Ejemplo 3: Monitorear Estado en Tiempo Real
javascriptimport { WalletBuilder } from '@midnight-ntwrk/wallet';
import { NetworkId } from '@midnight-ntwrk/zswap';
import { debounceTime, distinctUntilChanged } from 'rxjs/operators';

async function monitorearBilletera() {
try {
const billetera = await WalletBuilder.build(
'https://indexer.testnet-02.midnight.network/api/v1/graphql',
'wss://indexer.testnet-02.midnight.network/api/v1/graphql/ws',
'http://localhost:6300',
'https://rpc.testnet-02.midnight.network',
'0000000000000000000000000000000000000000000000000000000000000000',
NetworkId.TestNet
);

billetera.start();

// Monitorear cambios de estado con debounce
billetera.state()
  .pipe(
    debounceTime(1000),                    // Esperar 1 segundo sin cambios
    distinctUntilChanged((a, b) =>         // Solo si realmente cambió
      JSON.stringify(a) === JSON.stringify(b)
    )
  )
  .subscribe((estado) => {
    console.log('\n📊 === ESTADO ACTUALIZADO ===');
    console.log('Monedas disponibles:', estado.coins.length);
    console.log('Saldo total:', estado.coins.reduce((sum, c) => sum + c.amount, 0n));
    console.log('Transacciones procesadas:', estado.transactionHistory.length);
    console.log('Última transacción:', 
      estado.transactionHistory[0]?.date || 'Ninguna');
  });

// Mantener proceso activo
console.log('👀 Monitoreando billetera (Ctrl+C para salir)...');

} catch (error) {
console.error('❌ Error:', error.message);
}
}

monitorearBilletera();

Buenas Prácticas y Recomendaciones

1. Sincronización Completa Antes de Transacciones javascript// ❌ INCORRECTO const receta = await billetera.transferTransaction([...]);

// ✅ CORRECTO
// Esperar a que la billetera esté sincronizada
await new Promise(resolve =>
billetera.state()
.pipe(filter(s => s.isSynced))
.subscribe(() => resolve())
);
const receta = await billetera.transferTransaction([...]);

1. Gestión Segura de Semillas javascript// ❌ INCORRECTO const semilla = "0000000000..."; // Hardcodeada

// ✅ CORRECTO
const semilla = process.env.WALLET_SEED; // Variables de entorno
// O
const semilla = await obtenerDelAlfiler(); // Sistema seguro de almacenamiento

1. Manejo de Errores Robusto javascripttry { const transaccion = await billetera.proveTransaction(receta); } catch (error) { if (error.message.includes('insufficient')) { console.error('Saldo insuficiente'); } else if (error.message.includes('timeout')) { console.error('Servidor de pruebas no disponible'); } else { console.error('Error desconocido:', error); } }
2. Cierre Adecuado de Recursos javascriptasync function operacionConBilletera() { const billetera = await WalletBuilder.build(...); try { billetera.start(); // Tu código aquí } finally { await billetera.close(); // Siempre cerrar } }
3. Timeouts en Operaciones Largas javascriptimport { timeout } from 'rxjs/operators';

const transaccionConTimeout = billetera.proveTransaction(receta)
.pipe(timeout(60000)); // 60 segundos máximo

Parámetros de Configuración
WalletBuilder.build() - Parámetros Obligatorios
ParámetroTipoDescripciónIndexer URLStringURL del API GraphQL del indexadorIndexer WebSocket URLStringURL WebSocket del indexadorProving Server URLStringURL del servidor de pruebasNode URLStringURL del nodo RPCSeedStringSemilla de 256 bits en hexNetwork IDNetworkIdTestNet, MainNet, etc.
Parámetros Opcionales
ParámetroTipoDefaultDescripciónLog LevelLogLevelwarnerror, warn, info, debugDiscard Transaction HistoryBooleanfalseDescartar historial de transacciones

Troubleshooting
Problema: "Error derivando clave"
Solución: Verifica que la semilla sea de 256 bits (64 caracteres hex)
Problema: Transacción rechazada por "double spend"
Solución: Asegúrate de que la billetera esté completamente sincronizada
antes de preparar la transacción
Problema: Servidor de pruebas no disponible
Solución: Verifica que el servidor de pruebas esté corriendo en localhost:6300
o usa URL correcta en la configuración
Problema: "secret keys are no longer included"
Solución: Proporciona la semilla original al restaurar desde instantánea

Recursos Adicionales

Documentación Oficial: https://docs.midnight.network
GitHub: https://github.com/midnight-ntwrk
API Reference: Consulta la documentación de @midnight-ntwrk/wallet
Ejemplos: Revisa los ejemplos incluidos en el repositorio

Conclusión
El Midnight Wallet SDK proporciona una forma robusta y segura de integrar funcionalidad de billetera en aplicaciones blockchain. Recuerda siempre:

✅ Gestiona las semillas de forma segura
✅ Sincroniza completamente antes de transacciones
✅ Cierra recursos adecuadamente
✅ Implementa manejo robusto de errores
✅ Prueba ampliamente antes de producción