Contracts - Ralph Studio

Alephium smart contracts are written in Ralph and compiled to bytecode before deployment. Contract addresses are base58-encoded like regular addresses. You can read contract state, call view functions, and query emitted events through the RPC API.

Get contract state

Returns the current state of a deployed contract including its fields and token balances.

curl "https://rpc.ralphstudio.xyz/{slug}/contracts/{address}/state" \
  -H "Authorization: Bearer API_KEY"

{
  "address": "27Gsc5...",
  "bytecode": "0201402c...",
  "codeHash": "a1b2c3...",
  "initialStateHash": "d4e5f6...",
  "immFields": [
    {
      "type": "Address",
      "value": "1DrDyTr9..."
    }
  ],
  "mutFields": [
    {
      "type": "U256",
      "value": "1000000000000000000"
    }
  ],
  "asset": {
    "attoAlphAmount": "1000000000000000000",
    "tokens": []
  }
}

immFields are set at deployment and never change. mutFields are the contract’s mutable state that changes with each transaction.

Get contract bytecode

Returns the deployed bytecode for a contract.

curl "https://rpc.ralphstudio.xyz/{slug}/contracts/{address}/bytecode" \
  -H "Authorization: Bearer API_KEY"

{
  "bytecode": "0201402c..."
}

Call a contract function

Calls a view function on a contract without creating a transaction. View functions read state but don’t modify it.

curl -X POST "https://rpc.ralphstudio.xyz/{slug}/contracts/call-contract" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group": 0,
    "address": "27Gsc5...",
    "methodIndex": 0,
    "args": [
      {
        "type": "Address",
        "value": "1DrDyTr9..."
      }
    ]
  }'

{
  "returns": [
    {
      "type": "U256",
      "value": "1000000000000000000"
    }
  ],
  "gasUsed": 5000,
  "contracts": [...],
  "txInputs": [],
  "txOutputs": []
}

Test a contract

Runs a contract function in a sandboxed environment without submitting to the chain. Useful for testing logic before deployment.

curl -X POST "https://rpc.ralphstudio.xyz/{slug}/contracts/test-contract" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group": 0,
    "address": "27Gsc5...",
    "bytecode": "0201402c...",
    "initialFields": [...],
    "testMethodIndex": 0,
    "testArgs": [...]
  }'

Compile a contract

Compiles Ralph source code and returns the bytecode. This is what the Ralph Studio IDE uses under the hood.

curl -X POST "https://rpc.ralphstudio.xyz/{slug}/contracts/compile-contract" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "Contract MyToken(name: ByteVec) {\n  pub fn getName() -> ByteVec {\n    return name\n  }\n}"
  }'

{
  "bytecode": "0201402c...",
  "codeHash": "a1b2c3...",
  "fields": {
    "names": ["name"],
    "types": ["ByteVec"],
    "isMutable": [false]
  },
  "functions": [...],
  "events": [...]
}

Get contract events

Returns events emitted by a contract. Events are indexed by contract address and block hash.

curl "https://rpc.ralphstudio.xyz/{slug}/events/contract/{address}?start=0&limit=20" \
  -H "Authorization: Bearer API_KEY"

{
  "events": [
    {
      "blockHash": "00000000ab3c...",
      "txId": "503a2c...",
      "contractAddress": "27Gsc5...",
      "eventIndex": 0,
      "fields": [
        {
          "type": "Address",
          "value": "1DrDyTr9..."
        },
        {
          "type": "U256",
          "value": "1000000000000000000"
        }
      ]
    }
  ],
  "nextStart": 20
}

Get events by transaction

Returns all events emitted in a specific transaction.

curl "https://rpc.ralphstudio.xyz/{slug}/events/tx-id/{tx-hash}" \
  -H "Authorization: Bearer API_KEY"

Get subcontracts

Returns contracts that were created by a parent contract.

curl "https://rpc.ralphstudio.xyz/{slug}/contracts/{address}/sub-contracts" \
  -H "Authorization: Bearer API_KEY"

{
  "subContracts": ["28Hsc7...", "29Isc8..."]
}

Parameters reference

Parameter	Type	Description
address	string	Base58-encoded contract address
group	integer	Shard group the contract belongs to (0–3)
methodIndex	integer	Index of the function to call
args	array	Function arguments as typed values
start	integer	Event offset for pagination
limit	integer	Number of events to return (max: 100)

​Get contract state

​Get contract bytecode

​Call a contract function

​Test a contract

​Compile a contract

​Get contract events

​Get events by transaction

​Get subcontracts

​Parameters reference