Referencia de la API de Smart Contracts

Los smart contracts de ULedger se escriben en WebAssembly Text Format (.wat) y son ejecutados por la ULVM, la máquina virtual WebAssembly propia de ULedger. Cada despliegue, actualización e invocación es una transaction firmada en la blockchain.

Desplegar Contrato

Despliega un smart contract .wat en una blockchain. La solicitud es multiparte porque el archivo del contrato se sube junto con los parámetros de la transaction. La billetera ya debe estar registrada en la blockchain de destino.

Solicitud

POST /api/v1/smartcontracts/deploy

Encabezados

X-AccessKey — La clave de acceso de entidad
Content-Type: multipart/form-data

Campos del formulario

walletAddress (requerido) — La billetera que despliega el contrato
blockchainId (requerido) — ID de la blockchain de destino
from (requerido) — Dirección del remitente (generalmente igual que walletAddress)
file (requerido) — El archivo de contrato .wat
payload — Etiqueta o nota de despliegue opcional
passphrase — Solo si la billetera fue creada con una

Respuesta

Devuelve el resultado de la transaction en caso de éxito. La dirección del contrato se deriva del ID de la transaction, por lo que se debe recuperar el bloque en la altura actual para encontrarla.

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/smartcontracts/deploy' \
-H 'X-AccessKey: your-entity-access-key' \
-F 'walletAddress=54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585' \
-F 'blockchainId=08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2' \
-F 'from=54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585' \
-F 'payload=my first contract' \
-F 'file=@./contract.wat'

import fs from 'fs';
import FormData from 'form-data';

const form = new FormData();
form.append('walletAddress', '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585');
form.append('blockchainId', '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2');
form.append('from', '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585');
form.append('payload', 'my first contract');
form.append('file', fs.createReadStream('./contract.wat'));

const res = await fetch('https://your-tms-url/api/v1/smartcontracts/deploy', {
method: 'POST',
headers: {
  'X-AccessKey': 'your-entity-access-key',
  ...form.getHeaders(),
},
body: form,
});

const data = await res.json();
console.log(data);

Actualizar Contrato

Actualiza un contrato desplegado existente con un nuevo archivo .wat. La dirección del contrato permanece igual mientras solo cambia el código. Las versiones anteriores se conservan en la blockchain.

Solicitud

POST /api/v1/smartcontracts/upgrade

Encabezados

X-AccessKey — La clave de acceso de entidad
Content-Type: multipart/form-data

Campos del formulario

walletAddress (requerido) — La billetera que realiza la actualización
blockchainId (requerido) — ID de la blockchain de destino
contractAddress (requerido) — Dirección del contrato a actualizar
file (requerido) — El nuevo archivo de contrato .wat
upgradeReason — Una nota que describe qué cambió
passphrase — Solo si la billetera fue creada con una

Respuesta

Devuelve el resultado de la transaction de actualización en caso de éxito.

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/smartcontracts/upgrade' \
-H 'X-AccessKey: your-entity-access-key' \
-F 'walletAddress=54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585' \
-F 'blockchainId=08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2' \
-F 'contractAddress=your-contract-address' \
-F 'upgradeReason=fixed a bug in the main function' \
-F 'file=@./contract-v2.wat'

import fs from 'fs';
import FormData from 'form-data';

const form = new FormData();
form.append('walletAddress', '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585');
form.append('blockchainId', '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2');
form.append('contractAddress', 'your-contract-address');
form.append('upgradeReason', 'fixed a bug in the main function');
form.append('file', fs.createReadStream('./contract-v2.wat'));

const res = await fetch('https://your-tms-url/api/v1/smartcontracts/upgrade', {
method: 'POST',
headers: {
  'X-AccessKey': 'your-entity-access-key',
  ...form.getHeaders(),
},
body: form,
});

const data = await res.json();
console.log(data);

Invocar Contrato

Llama a una función en un smart contract desplegado. Los argumentos tienen tipos definidos porque la ULVM necesita conocer el tipo de cada argumento para codificarlo correctamente antes de la ejecución.

Solicitud

POST /api/v1/smartcontracts/invoke/payload

Encabezados

X-AccessKey — La clave de acceso de entidad
Content-Type: application/json

Cuerpo

walletAddress — La billetera que firma la invocación
blockchainId — ID de la blockchain de destino
contractAddress (requerido) — La dirección del contrato desplegado
functionName (requerido) — La función exportada a llamar
arguments — Array de argumentos tipados. Cada entrada tiene un type y value. Tipos soportados: int32, int64, float32, float64, bool, string, bytes
gasLimit — Gas máximo para la ejecución. El rango válido va de 100000 a 10000000, y 0 no significa sin límite porque se eleva al mínimo de 100000.
passphrase — Solo si la billetera fue creada con una

Respuesta

Devuelve el resultado de la transaction de invocación incluyendo cualquier salida de la función del contrato.

Ejemplo de respuesta

{
"transactionId": "a1b2c3...",
"status": "confirmed",
"output": "42",
"gasUsed": 100
}

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/smartcontracts/invoke/payload' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Content-Type: application/json' \
-d '{
"walletAddress": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"blockchainId": "08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2",
"contractAddress": "your-contract-address",
"functionName": "main",
"arguments": [
  { "type": "string", "value": "hello" },
  { "type": "int32", "value": "42" }
],
"gasLimit": 0
}'

const res = await fetch('https://your-tms-url/api/v1/smartcontracts/invoke/payload', {
method: 'POST',
headers: {
  'X-AccessKey': 'your-entity-access-key',
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  walletAddress: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  blockchainId: '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2',
  contractAddress: 'your-contract-address',
  functionName: 'main',
  arguments: [
    { type: 'string', value: 'hello' },
    { type: 'int32', value: '42' },
  ],
  gasLimit: 0,
}),
});

const data = await res.json();
console.log('Output:', data.output);

Revertir Contrato

Revierte un smart contract desplegado a una versión anteriormente desplegada. Todas las versiones se conservan en la cadena, así que esto simplemente vuelve a activar el bytecode de la versión especificada sin perder el historial.

Solicitud

POST /api/v1/smartcontracts/rollback

Encabezados

X-AccessKey — La clave de acceso de entidad
Content-Type: application/json

Cuerpo

walletAddress (requerido) — La billetera que desplegó el contrato
blockchainId (requerido) — ID del blockchain de destino
contractAddress (requerido) — El contrato a revertir
targetVersion (requerido) — El número de versión a restaurar (p. ej. 1)
passphrase (opcional) — Solo si la billetera fue creada con una
rollbackReason (opcional) — Una nota que describe por qué se revierte

Respuesta

Devuelve el resultado de la transaction de reversión en caso de éxito.

Ejemplo de respuesta

{
"transactionId": "rb1b2c3...",
"status": "confirmed",
"contractAddress": "your-contract-address",
"targetVersion": 1
}

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/smartcontracts/rollback' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Content-Type: application/json' \
-d '{
"walletAddress": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"blockchainId": "08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2",
"contractAddress": "your-contract-address",
"targetVersion": 1,
"rollbackReason": "Error crítico encontrado en V2"
}'

const res = await fetch('https://your-tms-url/api/v1/smartcontracts/rollback', {
method: 'POST',
headers: {
  'X-AccessKey': 'your-entity-access-key',
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  walletAddress: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  blockchainId: '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2',
  contractAddress: 'your-contract-address',
  targetVersion: 1,
  rollbackReason: 'Error crítico encontrado en V2',
}),
});

const data = await res.json();
console.log('Transaction de rollback:', data.transactionId);

Obtener Estado del Contrato

Recupera el estado clave-valor actual almacenado por un smart contract. El estado es escrito por las funciones del contrato durante la invocación y persiste entre llamadas.

Solicitud

GET /api/v1/smartcontracts/{blockchainId}/{contractAddress}/state

Encabezados

X-AccessKey — La clave de acceso de entidad

Parámetros de ruta

blockchainId — El blockchain en el que está desplegado el contrato
contractAddress — La dirección del contrato

Respuesta

Devuelve un mapa de todas las claves y valores que el contrato ha escrito en el almacenamiento de estado.

Ejemplo de respuesta

{
"contract:version": "1",
"contract:owner": "54677be3...",
"counter": "42"
}

cURL
TypeScript

curl -X GET \
'https://your-tms-url/api/v1/smartcontracts/08c28f29.../your-contract-address/state' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Accept: application/json'

const blockchainId = '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2';
const contractAddress = 'your-contract-address';

const res = await fetch(
`https://your-tms-url/api/v1/smartcontracts/${blockchainId}/${contractAddress}/state`,
{
  headers: {
    'X-AccessKey': 'your-entity-access-key',
    'Accept': 'application/json',
  },
}
);

const state = await res.json();
console.log('Estado del contrato:', state);

Obtener Traza de Ejecución del Contrato

Devuelve la traza de ejecución de una invocación específica del contrato. Útil para depuración, ya que muestra qué instrucciones WASM se ejecutaron, su costo en gas y los valores leídos o escritos durante la llamada.

Solicitud

GET /api/v1/smartcontracts/{blockchainId}/{contractAddress}/trace/{txId}

Encabezados

X-AccessKey — La clave de acceso de entidad

Parámetros de ruta

blockchainId — El blockchain en el que está desplegado el contrato
contractAddress — La dirección del contrato
txId — El ID de transaction de la invocación a rastrear

Respuesta

Devuelve la traza de ejecución completa para la transaction de invocación dada.

Ejemplo de respuesta

{
"txId": "a1b2c3...",
"functionName": "getVersion",
"gasUsed": 120,
"output": "2",
"steps": [
  { "op": "i32.const", "value": 2 },
  { "op": "return" }
]
}

cURL
TypeScript

curl -X GET \
'https://your-tms-url/api/v1/smartcontracts/08c28f29.../your-contract-address/trace/a1b2c3...' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Accept: application/json'

const blockchainId = '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2';
const contractAddress = 'your-contract-address';
const txId = 'a1b2c3d4e5f6...';

const res = await fetch(
`https://your-tms-url/api/v1/smartcontracts/${blockchainId}/${contractAddress}/trace/${txId}`,
{
  headers: {
    'X-AccessKey': 'your-entity-access-key',
    'Accept': 'application/json',
  },
}
);

const trace = await res.json();
console.log('Gas utilizado:', trace.gasUsed);
console.log('Salida:', trace.output);

Desplegar Contrato​

Solicitud

Encabezados

Campos del formulario

Respuesta

Actualizar Contrato​

Solicitud

Encabezados

Campos del formulario

Respuesta

Invocar Contrato​

Solicitud

Encabezados

Cuerpo

Respuesta

Ejemplo de respuesta

Revertir Contrato​

Solicitud

Encabezados

Cuerpo

Respuesta

Ejemplo de respuesta

Obtener Estado del Contrato​

Solicitud

Encabezados

Parámetros de ruta

Respuesta

Ejemplo de respuesta

Obtener Traza de Ejecución del Contrato​

Solicitud

Encabezados

Parámetros de ruta

Respuesta

Ejemplo de respuesta

Desplegar Contrato

Actualizar Contrato

Invocar Contrato

Revertir Contrato

Obtener Estado del Contrato

Obtener Traza de Ejecución del Contrato