Wallets

Todo comienza con un wallet. Los wallets son la forma en que firmas transacciones, y sin una firma nada se escribe en la chain.

Los wallets en ULedger son jerárquicos — puedes crear wallets hijo a partir de un padre, lo cual es útil cuando necesitas separar responsabilidades dentro de la misma organización. Un wallet por aplicación, un wallet por usuario, un wallet por departamento. La estructura es tuya para decidir.

---

Crear un wallet

Llama a POST /api/v1/wallets con tu access key y el network tag. El wallet se genera, opcionalmente cifrado con una passphrase, y es almacenado por el TMS.

const res = await fetch('https://your-tms-url/api/v1/wallets', {
  method: 'POST',
  headers: {
    'X-AccessKey': 'your-entity-access-key',
    'X-Tag': 'mainnet',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entropy: 256,
    key_type: 0,        // 0 = secp256k1
    output: 1,          // 1 = address + mnemonic
    passphrase: 'my-secure-passphrase',
    save_to_storage: true,
  }),
});

const wallet = await res.json();
console.log('Address:', wallet.address);
console.log('Mnemonic:', wallet.mnemonic);

Guarda el mnemonic o la dirección del wallet. Es la única forma de recuperar el wallet si lo pierdes.

Si creaste el wallet sin passphrase, omite passphrase por completo. Cada operación futura con este wallet debe coincidir.

---

Cargar un wallet

Recupera un wallet almacenado en cualquier momento por dirección:

const res = await fetch('https://your-tms-url/api/v1/wallets/load-by-address', {
  method: 'POST',
  headers: {
    'X-AccessKey': 'your-entity-access-key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    address: 'your-wallet-address',
    output: 2,                           // 2 = full wallet JSON
    passphrase: 'my-secure-passphrase',  // omit if created without one
  }),
});

const data = await res.json();
console.log('Wallet:', data.wallet.address);

---

Grupos de auth

Al crear un wallet puedes asignar auth groups — conjuntos de permisos con nombre que controlan lo que diferentes roles pueden hacer con él. Los nombres son tuyos para definir.

body: JSON.stringify({
  entropy: 256,
  key_type: 0,
  output: 1,
  passphrase: 'my-secure-passphrase',
  save_to_storage: true,
  auth_groups: {
    admin:  { create: true,  read: true,  update: true,  delete: true  },
    writer: { create: true,  read: true,  update: false, delete: false },
    reader: { create: false, read: true,  update: false, delete: false },
  },
}),

---

Recuperar un wallet

Si necesitas restaurar un wallet — ya sea tras una pérdida de acceso o para importar uno de otro sistema — puedes recuperarlo desde una frase mnemónica.

Primero, genera un mnemonic si aún no tienes uno:

const res = await fetch('https://your-tms-url/api/v1/wallets/generate-mnemonic-from-entropy', {
  method: 'POST',
  headers: {
    'X-AccessKey': 'your-entity-access-key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ entropy: 256 }),
});

const { mnemonic } = await res.json();
// Guárdalo en un lugar seguro — es la única forma de recuperar el wallet

Luego restaura el wallet desde ese mnemonic en cualquier momento:

const res = await fetch('https://your-tms-url/api/v1/wallets/from-mnemonic', {
  method: 'POST',
  headers: {
    'X-AccessKey': 'your-entity-access-key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    mnemonic: 'word1 word2 word3 ... word24',
    key_type: 0,
    passphrase: 'my-secure-passphrase',
    save_to_storage: true,
    output: 1,
  }),
});

const wallet = await res.json();
console.log('Dirección recuperada:', wallet.address);

Si estás migrando claves desde un sistema externo y ya tienes un par de claves en hexadecimal, usa POST /api/v1/wallets/from-key-hex — consulta la Referencia de Wallets para más detalles.

---

Siguiente paso

Un wallet por sí solo no puede hacer nada en el blockchain hasta que esté registrado, y para hacerlo necesitamos crear nuestra primera transaction. Ve a Transactions para registrar tu wallet y comenzar a escribir datos.