Referencia de Tipos de Transaction

Todos los cambios de estado en ULedger se realizan mediante transactions firmadas. Este documento cataloga cada tipo de transaction, sus campos requeridos, quién puede enviarla y qué hace.

Todas las transactions comparten un envelope común:

{
    "type": "<TRANSACTION_TYPE>",
    "sender": "<wallet-address>",
    "blockchainId": "<chain-id>",
    "signature": "<hex-signature-of-payload>",
    "payload": { ... }
}

Transactions de Billetera

`TX_CREATE_WALLET`

Crea una nueva billetera on-chain.

Campo	Tipo	Descripción
`publicKey`	string	Clave pública comprimida en hexadecimal de la nueva billetera.
`keyType`	string	Algoritmo de clave: `secp256k1`, `ed25519`, `mldsa87`, `bls12377`.
`authGroups`	map	`{ "admin": {...}, "wallet": {...} }` con booleanos CRUD.
`capabilities`	array	Capabilities iniciales opcionales (deben ser ⊆ las capabilities del padre).

Quién puede enviarla: Cualquier billetera registrada con wallet.Create == true en sus auth groups. La billetera que la envía se convierte en el Parent de la nueva billetera.

Reglas de procesamiento:

Derivar la dirección de la nueva billetera como SHA256(lowercase(publicKey)).
Validar que el padre exista y tenga el permiso CanCreateWallets().
Validar la herencia de capabilities (capabilities del hijo ⊆ capabilities del padre).
Crear la billetera y establecer Parent = sender.
Agregar la dirección de la nueva billetera al array SatelliteWallets del remitente.

`ALTER_WALLET`

Modifica una billetera existente: habilitar/deshabilitar, actualizar auth groups, actualizar capabilities.

Campo	Tipo	Descripción
`walletAddress`	string	Dirección de la billetera a modificar.
`enabled`	bool	Habilitar o deshabilitar la billetera.
`authGroups`	map	Auth groups de reemplazo (opcional).
`capabilities`	array	Capabilities de reemplazo (opcional).

Quién puede enviarla: El padre de la billetera, o cualquier billetera con autoridad admin sobre la billetera.

Reglas de procesamiento para deshabilitar: Cascada BFS: todas las billeteras en SatelliteWallets (de forma recursiva) también se deshabilitan. Esto es atómico.

Reglas de procesamiento para capabilities: El reemplazo debe ser un subconjunto de las capabilities de la billetera padre.

Transactions de Entity

`CREATE_ENTITY`

Crea una nueva entity organizacional.

Campo	Tipo	Descripción
`name`	string	3–64 caracteres, minúsculas, alfanumérico + guion.
`entityType`	string	`ORGANIZATION`, `DEPARTMENT`, `PERSONAL`, `SERVICE`, `DEVICE`, `AGENT`.
`parent`	string	Dirección de la entity padre (vacía para la raíz).
`metadata`	map	Metadatos clave-valor opcionales.

Quién puede enviarla: Para la entity raíz: una billetera raíz (wallet.Parent == ""). Para una entity hija: una billetera con ManageChildren == true en la entity padre.

Reglas de procesamiento:

El padre debe existir, estar habilitado y admitir el tipo de hijo solicitado.
Una billetera raíz que crea una entity raíz no debe tener ya una afiliación wallet.Entity.
El remitente se convierte en el propietario de la entity; se vincula automáticamente con el rol admin y con todos los permisos.
Se establece el backlink wallet.Entity en la billetera creadora.

`ALTER_ENTITY`

Actualiza los metadatos o el estado de habilitación de la entity.

Campo	Tipo	Descripción
`entityAddress`	string	Entity a modificar.
`metadata`	map	Metadatos de reemplazo o combinados.
`enabled`	bool	Habilitar o deshabilitar la entity.

Quién puede enviarla: Billetera con ManageMetadata == true (para metadatos) o el propietario de la entity (para habilitar/deshabilitar).

`TRANSFER_ENTITY`

Cambia el propietario de la entity a una nueva billetera.

Campo	Tipo	Descripción
`entityAddress`	string	Entity a transferir.
`newOwnerAddress`	string	Dirección de la billetera del nuevo propietario.

Quién puede enviarla: Cualquier billetera con TransferOwnership == true en la entity.

Reglas de procesamiento: Se elimina el backlink wallet.Entity del propietario anterior; se establece el del nuevo propietario.

`LINK_WALLET_TO_ENTITY`

Vincula una billetera a una entity con un rol y un conjunto de permisos.

Campo	Tipo	Descripción
`entityAddress`	string	Entity a la que se vincula.
`walletAddress`	string	Billetera a vincular.
`role`	string	`"admin"` o `"member"` (se almacena, no se consulta para la autorización).
`permissions`	object	Bits de `EntityPermission`.

Quién puede enviarla: Billetera con ManageWallets == true en la entity.

Reglas de procesamiento: Si role == "admin", se establece el backlink wallet.Entity en la billetera vinculada.

`UNLINK_WALLET_FROM_ENTITY`

Elimina una billetera de la lista de miembros de una entity.

Campo	Tipo	Descripción
`entityAddress`	string	Entity de la que se desvincula.
`walletAddress`	string	Billetera a eliminar.

Quién puede enviarla: Billetera con ManageWallets == true en la entity.

`SET_ENTITY_ACCESS_LIST`

Modifica la lista negra o la lista de confianza de la entity.

Campo	Tipo	Descripción
`entityAddress`	string	Entity cuya lista de acceso se modifica.
`operation`	string	`ADD_BLACKLIST`, `REMOVE_BLACKLIST`, `ADD_TRUSTED`, `REMOVE_TRUSTED`.
`targetAddress`	string	Dirección de billetera a agregar o eliminar.

Quién puede enviarla: Billetera con ManageAccessList == true en la entity.

Transactions de Recuperación de Entity

`CONFIGURE_ENTITY_RECOVERY`

Establece la configuración de billeteras de recuperación para una entity.

Campo	Tipo	Descripción
`entityAddress`	string	Entity a configurar.
`recoveryWallets`	array	Direcciones de billeteras autorizadas para aprobar la recuperación.
`threshold`	int	Número de aprobaciones requeridas para ejecutar la recuperación.

Quién puede enviarla: Solo el propietario de la entity.

Reglas de procesamiento: Se almacena como PendingRecoveryConfig con un período de espera antes de la activación.

`REQUEST_ENTITY_RECOVERY`

Inicia un proceso de recuperación para una entity.

Campo	Tipo	Descripción
`entityAddress`	string	Entity a recuperar.
`newOwnerAddress`	string	Billetera propuesta como nuevo propietario.

Quién puede enviarla: Cualquier billetera. (Las billeteras de recuperación deben aprobar a continuación.)

`APPROVE_ENTITY_RECOVERY`

Emite un voto de aprobación en una recuperación en curso.

Campo	Tipo	Descripción
`entityAddress`	string	Entity en proceso de recuperación.

Quién puede enviarla: Una billetera incluida en la lista RecoveryConfig.recoveryWallets de la entity.

`EXECUTE_ENTITY_RECOVERY`

Ejecuta una recuperación una vez alcanzado el umbral de aprobaciones.

Campo	Tipo	Descripción
`entityAddress`	string	Entity a recuperar.

Quién puede enviarla: Cualquier billetera (una vez alcanzado el umbral).

Reglas de procesamiento: El propietario de la entity cambia al newOwnerAddress de la solicitud de recuperación. Se elimina el backlink del propietario anterior; se establece el del nuevo propietario.

`CANCEL_ENTITY_RECOVERY`

Cancela una recuperación en curso.

Campo	Tipo	Descripción
`entityAddress`	string	Entity cuya recuperación se cancela.

Quién puede enviarla: El propietario de la entity o las billeteras de recuperación.

Transactions de Smart Contract

`DEPLOY_SMART_CONTRACT`

Despliega un nuevo contract WASM.

Campo	Tipo	Descripción
`sourceCode`	bytes	Binario WASM (o texto WAT).
`gasLimit`	uint64	Presupuesto de gas para la ejecución del despliegue.
`isUpgradeable`	bool	Indica si el contract puede actualizarse.
`governanceMode`	string	Etiqueta opcional del modo de gobernanza.

Quién puede enviarla: Cualquier billetera registrada.

Reglas de procesamiento: Dirección del contract = ID de la transaction. Propietario = billetera que despliega. Versión = 1.

`INVOKE_SMART_CONTRACT`

Llama a una función de un contract desplegado.

Campo	Tipo	Descripción
`contractAddress`	string	Dirección del contract de destino.
`function`	string	Nombre de la función a llamar.
`args`	array	Argumentos de la función.
`gasLimit`	uint64	Presupuesto de gas para la ejecución.

Quién puede enviarla: Cualquier billetera con una capability contract:invoke válida (o cualquier billetera si no hay capabilities configuradas en la chain).

Reglas de procesamiento: La ejecución se realiza en un sandbox. Los cambios de almacenamiento se revierten en caso de fallo. El gas se consume independientemente del éxito.

`UPGRADE_SMART_CONTRACT`

Reemplaza el bytecode de un contract.

Campo	Tipo	Descripción
`contractAddress`	string	Contract a actualizar.
`sourceCode`	bytes	Nuevo binario WASM.
`gasLimit`	uint64	Presupuesto de gas.

Quién puede enviarla: El propietario del contract (o una billetera con permiso de actualización). El contract debe tener IsUpgradeable == true.

Reglas de procesamiento: PreviousVersion = versión actual. Version se incrementa. El bytecode anterior se conserva para el rollback.

`ROLLBACK_SMART_CONTRACT`

Revierte un contract a su versión de bytecode anterior.

Campo	Tipo	Descripción
`contractAddress`	string	Contract a revertir.

Quién puede enviarla: El propietario del contract.

Reglas de procesamiento: Version se decrementa. El bytecode se restaura al estado de PreviousVersion.

Transactions de Token (Nativas)

Token Fungible (equivalente a ERC-20)

Transaction	Descripción
`CREATE_TOKEN`	Despliega un nuevo token fungible. Campos: `name`, `symbol`, `decimals`, `initialSupply`.
`MINT_TOKEN`	Emite nuevo suministro. Campos: `tokenAddress`, `amount`, `recipient`. Solo el propietario.
`BURN_TOKEN`	Quema suministro. Campos: `tokenAddress`, `amount`. Solo el titular.
`TRANSFER_TOKEN`	Transfiere tokens. Campos: `tokenAddress`, `recipient`, `amount`.
`APPROVE_TOKEN`	Aprueba al que gasta. Campos: `tokenAddress`, `spender`, `amount`.
`TRANSFER_FROM_TOKEN`	El que gasta transfiere en nombre del aprobador. Campos: `tokenAddress`, `from`, `to`, `amount`.

Token No Fungible (equivalente a ERC-721)

Transaction	Descripción
`MINT_NFT`	Emite un único NFT. Campos: `collectionAddress`, `tokenId`, `metadata`.
`TRANSFER_NFT`	Transfiere la propiedad del NFT. Campos: `collectionAddress`, `tokenId`, `recipient`.
`APPROVE_NFT`	Aprueba al que gasta para un NFT específico.
`SET_APPROVAL_FOR_ALL`	Aprueba a un operador para todos los NFTs de una colección.

Multi-Token (equivalente a ERC-1155)

Transaction	Descripción
`MINT_MULTI_TOKEN`	Emite múltiples tipos de token en una sola transaction.
`TRANSFER_MULTI_TOKEN`	Transferencia por lotes de múltiples tipos de token.
`CONVERT_TOKEN`	Convierte un balance de token fungible en un token no fungible.

Transactions de Datos y de Sistema

`TX_DATA`

Envía datos arbitrarios a la chain. Se utiliza para:

Registrar eventos off-chain con una marca de tiempo y una firma on-chain.
Enviar blobs de datos cuyo hash debe ser demostrable.
Impulsar la producción de bloques (las data transactions no-op avanzan la altura de la chain para pruebas).

Campo	Tipo	Descripción
`payload`	bytes	Datos arbitrarios (hasta 64 KiB).

Quién puede enviarla: Cualquier billetera con la capability data:submit (o sin restricción de capabilities).

Reglas de procesamiento: El payload se almacena en el registro de la transaction. No se realizan cambios de estado más allá de registrar la transaction.

`CHECKPOINT_MARKER`

Transaction de sistema escrita por el sidecar de Helix cuando se finaliza un checkpoint STARK.

No es enviada por usuarios ni agentes. Es escrita por el proceso sidecar de Helix. Marca el bloque en el que se ancló una prueba de checkpoint. La prueba incluida puede verificarse con la herramienta checkpoint_verify.

Transactions de Autenticación

`AUTHENTICATE_INTERNAL`

Autentica una billetera mediante un flujo de desafío-respuesta on-chain. Se utiliza para demostrar el control de una billetera sin enviar una transaction que cambie el estado.

`AUTHENTICATE_EXTERNAL`

Extiende las credenciales externas (identidades off-chain) anclándolas a un evento de autenticación on-chain.

Transactions de Billetera​

TX_CREATE_WALLET​

ALTER_WALLET​

Transactions de Entity​

CREATE_ENTITY​

ALTER_ENTITY​

TRANSFER_ENTITY​

LINK_WALLET_TO_ENTITY​

UNLINK_WALLET_FROM_ENTITY​

SET_ENTITY_ACCESS_LIST​

Transactions de Recuperación de Entity​

CONFIGURE_ENTITY_RECOVERY​

REQUEST_ENTITY_RECOVERY​

APPROVE_ENTITY_RECOVERY​

EXECUTE_ENTITY_RECOVERY​

CANCEL_ENTITY_RECOVERY​

Transactions de Smart Contract​

DEPLOY_SMART_CONTRACT​

INVOKE_SMART_CONTRACT​

UPGRADE_SMART_CONTRACT​

ROLLBACK_SMART_CONTRACT​

Transactions de Token (Nativas)​

Token Fungible (equivalente a ERC-20)​

Token No Fungible (equivalente a ERC-721)​

Multi-Token (equivalente a ERC-1155)​

Transactions de Datos y de Sistema​

TX_DATA​

CHECKPOINT_MARKER​

Transactions de Autenticación​

AUTHENTICATE_INTERNAL​

AUTHENTICATE_EXTERNAL​