Ciclo de vida de una wallet

6.1 Alta#

El alta es una sola llamada atómica: la wallet, el fragmento del servidor y el sobre de recuperación se registran juntos o no se registra nada.

import { createWallet } from "nyx_wallet";

const wallet = await createWallet(config, {
  name: "Cuenta principal",
  blockchain: "polygon",
  network: "mainnet",   // por defecto "testnet", a propósito
  deployment,
});

console.log(wallet.walletId, wallet.address);

Lo que ocurre por dentro, en este orden: se verifica la fuente de aleatoriedad, se genera la llave, se reparte en tres fragmentos, se sella el sobre de recuperación, y solo entonces se registra todo en una única petición.

El orden importa. Si el autenticador no entrega la llave de recuperación —el caso típico es una passkey que vive en otro dispositivo y se usa por el flujo del QR—, la operación aborta antes de tocar la red y antes de escribir nada en local. No queda nada que limpiar y no puede nacer una wallet sin recuperación.

Persiste en tu dominio solo la referencia pública:

walletId · address · saltNonce · chainId · versión de integración

Nunca material de llave, fragmentos, aserciones reutilizables ni la llave de recuperación.

El usuario no ve nada de esto. Crear la wallet no exige biometría; solo firmar y exportar la exigen.

6.2 Reapertura en el mismo dispositivo#

import { openWallet } from "nyx_wallet";

const wallet = await openWallet(config, walletId, { deployment, saltNonce });

El deployment debe ser el mismo que se usó al crear la wallet.

6.3 Mover fondos#

const operation = await wallet.sendFunds({
  to: "0x…",
  value: "1000000000000000",  // wei
  nonce: accountNonce,         // del EntryPoint, ver aviso
});

console.log(operation.userOpHash, operation.sponsored);

Aquí es donde el usuario ve Face ID o su huella.

El nonce no tiene valor por defecto. El SDK no trae un proveedor con el que consultarlo, y asumir 0 sería correcto exactamente una vez —la primera— y silenciosamente incorrecto siempre después. Consúltalo al EntryPoint con el proveedor de tu aplicación.

6.4 Seguir una operación#

El navegador nunca recibe la URL del bundler. Consulta el recibo a través de Nyx:

import { getUserOperationReceipt } from "nyx_wallet";

const receipt = await getUserOperationReceipt({
  apiBaseUrl: config.apiBaseUrl,
  accessToken: session.accessToken,
  userOpHash: operation.userOpHash,
});

null significa que el bundler todavía no la ha incluido, no que la haya rechazado.

6.5 Recuperación en un dispositivo nuevo#

Cuando el almacén del dispositivo está vacío —perdió el teléfono, cambió de navegador, borró datos— no se usa openWallet, se usa recuperación:

import { recoverWalletWithPasskey, createDeviceStore } from "nyx_wallet";

// La recuperación toma su propia configuración, más acotada que la de la wallet:
// no necesita almacén de dispositivo ni credencial biométrica, porque todavía
// no hay wallet abierta en este dispositivo.
const result = await recoverWalletWithPasskey(
  {
    apiBaseUrl: "https://<tu-entorno-nyx>/api",
    accessToken: session.accessToken,
    keyProvider: createPasskeyRecoveryKeyProvider(),
    deployment,          // el MISMO que se usó al crear la wallet
    saltNonce,
  },
  walletId,
);

if (result.status === "needs-guardians") {
  // Estado esperado de producto, no un error: llevar al flujo de guardianes.
  return startGuardianRecovery(walletId, result.detail);
}

// Guarda el fragmento del dispositivo nuevo antes de continuar.
const deviceStore = createDeviceStore({ userId: session.userId });
await deviceStore.write(result.material.walletId, result.material.device);

La recuperación reconstruye la llave en el cliente, genera tres fragmentos nuevos y actualiza el fragmento de Nyx y el sobre. El juego anterior queda matemáticamente revocado: el fragmento anterior no combina con el nuevo juego. Esto no revoca una llave completa que un atacante ya hubiera reconstruido. La dirección de la cuenta no cambia.

needs-guardians se devuelve exactamente en dos condiciones: no hay PRF utilizable en esta plataforma, o la passkey de este dispositivo no puede abrir el sobre. Los errores de red, autenticación o integridad no se convierten en un falso flujo de recuperación social.

6.6 Exportar la llave#

const privateKey = await wallet.exportPrivateKey();

Ocurre entera en el dispositivo y exige biometría. No hay ningún endpoint que devuelva esto.

La exportación no es opcional de quitar: es la definición de autocustodia. Lo que sí decide tu aplicación es dónde se muestra y con cuánta fricción alrededor.

6.7 Cerrar#

wallet.close();

Invalida el manejador y suelta las referencias en memoria al terminar la sesión.