Billeteras

Todo comienza con una billetera. Las billeteras son la forma en que se firman las transacciones, y sin una firma nada se escribe en la chain.

Las billeteras en ULedger son jerárquicas, así que se pueden crear billeteras hijas a partir de una padre, lo cual es útil cuando hace falta separar responsabilidades dentro de la misma organización. Una billetera por aplicación, una billetera por usuario, una billetera por departamento. La estructura se define libremente.

---

Crear una billetera

Se llama a POST /api/v1/wallets con la access key y el network tag. La billetera se genera, opcionalmente cifrada con una passphrase, y es almacenada 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);

Se debe guardar el mnemonic o la dirección de la billetera. Es la única forma de recuperar la billetera si se pierde.

:::note key_type es un número, no un nombre

Se debe enviar el valor numérico de la tabla siguiente. "key_type": "secp256k1", o incluso la cadena "0", se rechaza con 400 {"error":"invalid request body"}, que no indica qué campo falla. Esto aplica a POST /api/v1/wallets, /wallets/from-mnemonic y /wallets/from-key-hex. Un número desconocido, como 9, falla con 500 failed to create wallet.

:::

:::warning key_type debe coincidir con el blockchain en el que se registrará

Una billetera solo puede registrarse en una chain cuyo key type coincida con el suyo:

key_type	Algoritmo
0	secp256k1
1	mldsa87
2	ed25519
3	bls12377

Registrar una billetera en una chain con un key type distinto falla y no puede corregirse después: la billetera no puede existir en esa chain. Se debe verificar el keyType de la chain antes de crear la billetera:

curl "https://your-node-url/blockchains/{blockchainId}"

:::

Si la billetera se creó sin passphrase, se debe omitir passphrase por completo. Cada operación futura con esta billetera debe coincidir.

---

Cargar una billetera

Se recupera una billetera almacenada 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 una billetera se pueden asignar auth groups, conjuntos de permisos con nombre que controlan lo que diferentes roles pueden hacer con ella. Los nombres se definen libremente.

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 una billetera

Si es necesario restaurar una billetera, ya sea tras una pérdida de datos o para importar una generada en otro sistema, se puede recuperar desde una frase mnemónica.

Primero, se genera un mnemonic si aún no se tiene 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();
// Se recomienda guardarlo en un lugar seguro porque es la única forma de recuperar la billetera

Luego se restaura la billetera 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 se migran claves desde un sistema externo y ya se tiene un par de claves en hexadecimal, se usa POST /api/v1/wallets/from-key-hex, mientras que la Referencia de la API de Billeteras cubre los detalles.

---

Siguiente paso

Una billetera por sí sola no puede hacer nada en el blockchain hasta que esté registrada, y para hacerlo necesitamos crear nuestra primera transaction. Continuar en Transactions para registrar la billetera y comenzar a escribir datos.