Smart Contracts API Reference

ULedger smart contracts are written in WebAssembly Text Format (.wat) and executed by the ULVM, ULedger's own WebAssembly virtual machine. Every deploy, upgrade, and invocation is a signed transaction on the blockchain.

Deploy Contract

Deploys a .wat smart contract to a blockchain. The request is multipart because the contract file is uploaded alongside the transaction parameters. The wallet must already be registered on the target blockchain.

Request

POST /api/v1/smartcontracts/deploy

Headers

X-AccessKey — Your entity access key
Content-Type: multipart/form-data

Form fields

walletAddress (required) — The wallet deploying the contract
blockchainId (required) — Target blockchain ID
from (required) — Sender address (usually same as walletAddress)
file (required) — The .wat contract file
payload — Optional deployment label or note
passphrase — Only if the wallet was created with one

Response

Returns the transaction result on success. The contract address is derived from the transaction ID, so retrieve the block at the current height to find it.

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);

Upgrade Contract

Upgrades an existing deployed contract with a new .wat file. The contract address stays the same while only the code changes. Previous versions are preserved on-chain.

Request

POST /api/v1/smartcontracts/upgrade

Headers

X-AccessKey — Your entity access key
Content-Type: multipart/form-data

Form fields

walletAddress (required) — The wallet performing the upgrade
blockchainId (required) — Target blockchain ID
contractAddress (required) — Address of the contract to upgrade
file (required) — The new .wat contract file
upgradeReason — A note describing what changed
passphrase — Only if the wallet was created with one

Response

Returns the upgrade transaction result on success.

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);

Invoke Contract

Calls a function on a deployed smart contract. Arguments are typed because the ULVM needs to know the type of each argument to encode it correctly before execution.

Request

POST /api/v1/smartcontracts/invoke/payload

Headers

X-AccessKey — Your entity access key
Content-Type: application/json

Body

walletAddress — The wallet signing the invocation
blockchainId — Target blockchain ID
contractAddress (required) — The deployed contract address
functionName (required) — The exported function to call
arguments — Array of typed arguments. Each entry has a type and value. Supported types: int32, int64, float32, float64, bool, string, bytes
gasLimit — Max gas for execution. The valid range is 100000 to 10000000, and 0 does not mean unlimited because it is raised to the 100000 minimum.
passphrase — Only if the wallet was created with one

Response

Returns the invocation transaction result including any output from the contract function.

Example response

{
"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);

Rollback Contract

Rolls back a deployed smart contract to a previously deployed version. All versions are preserved on-chain, so this swaps the active bytecode back to the specified version number without losing history.

Request

POST /api/v1/smartcontracts/rollback

Headers

X-AccessKey — Your entity access key
Content-Type: application/json

Body

walletAddress (required) — The wallet that deployed the contract
blockchainId (required) — Target blockchain ID
contractAddress (required) — The contract to roll back
targetVersion (required) — The version number to restore (e.g. 1)
passphrase (optional) — Only if the wallet was created with one
rollbackReason (optional) — A note describing why you are rolling back

Response

Returns the rollback transaction result on success.

Example response

{
"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": "Reverting due to critical bug in 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: 'Reverting due to critical bug in V2',
}),
});

const data = await res.json();
console.log('Rollback tx:', data.transactionId);

Get Contract State

Retrieves the current key-value state stored by a smart contract. State is written by the contract's functions during invocation and persists between calls.

Request

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

Headers

X-AccessKey — Your entity access key

Path parameters

blockchainId — The blockchain the contract is deployed on
contractAddress — The contract address

Response

Returns a map of all keys and values the contract has written to state storage.

Example response

{
"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('Contract state:', state);

Get Contract Execution Trace

Returns the execution trace for a specific contract invocation. Useful for debugging, as it shows which WASM instructions executed, their gas cost and any values read or written during the call.

Request

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

Headers

X-AccessKey — Your entity access key

Path parameters

blockchainId — The blockchain the contract is deployed on
contractAddress — The contract address
txId — The transaction ID of the invocation to trace

Response

Returns the full execution trace for the given invocation transaction.

Example response

{
"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 used:', trace.gasUsed);
console.log('Output:', trace.output);

Deploy Contract​

Request

Headers

Form fields

Response

Upgrade Contract​

Request

Headers

Form fields

Response

Invoke Contract​

Request

Headers

Body

Response

Example response

Rollback Contract​

Request

Headers

Body

Response

Example response

Get Contract State​

Request

Headers

Path parameters

Response

Example response

Get Contract Execution Trace​

Request

Headers

Path parameters

Response

Example response

Deploy Contract

Upgrade Contract

Invoke Contract

Rollback Contract

Get Contract State

Get Contract Execution Trace