> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ralphstudio.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Contracts

> Read contract state, query events, and interact with Ralph smart contracts.

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.

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

```json theme={null}
{
  "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.

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

```json theme={null}
{
  "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.

```bash theme={null}
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..."
      }
    ]
  }'
```

```json theme={null}
{
  "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.

```bash theme={null}
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.

```bash theme={null}
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}"
  }'
```

```json theme={null}
{
  "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.

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

```json theme={null}
{
  "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.

```bash theme={null}
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.

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

```json theme={null}
{
  "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)     |