> ## 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.

# What is Ralph

> An introduction to Ralph, the smart contract language of Alephium.

Ralph is the smart contract programming language built specifically for Alephium. It is statically typed, compiled, and designed around the UTXO model, which makes it fundamentally different from Solidity and most EVM-compatible languages.

## How Ralph differs from Solidity

|                    | Ralph                             | Solidity               |
| ------------------ | --------------------------------- | ---------------------- |
| Execution model    | UTXO-based                        | Account-based          |
| Asset handling     | Built into the language           | Via ERC standards      |
| Reentrancy attacks | Not possible by design            | Require guards         |
| Gas model          | Predictable, fixed per opcode     | Variable               |
| State storage      | Explicit mutable/immutable fields | Single storage mapping |

## Contracts and scripts

Ralph has two top-level constructs:

**Contracts** hold state and can be called repeatedly. They live at a fixed address on-chain and persist between transactions.

**TxScripts** are one-shot transaction scripts. They execute once as part of a transaction and have no persistent address. Use them to interact with contracts, transfer assets, call functions, deploy new contracts.

## Mutable and immutable fields

Every contract declares its fields upfront. Fields are either `mut` (can change after deployment) or immutable (set once at deployment, cheaper to read):

```ralph theme={null}
Contract TokenFaucet(
  symbol: ByteVec,        // immutable
  name: ByteVec,          // immutable
  decimals: U256,         // immutable
  mut balance: U256       // mutable
) {
  pub fn getSymbol() -> ByteVec {
    return symbol
  }

  @using(updateFields = true)
  pub fn withdraw(amount: U256) -> () {
    balance = balance - amount
  }
}
```

Attempting to modify an immutable field is a compile error.

## Asset permissions

Ralph uses annotations to declare when a function touches assets. This prevents accidental asset loss and makes auditing straightforward:

| Annotation                            | Meaning                                      |
| ------------------------------------- | -------------------------------------------- |
| `@using(assetsInContract = true)`     | Function can use assets held by the contract |
| `@using(preapprovedAssets = true)`    | Caller must approve assets before calling    |
| `@using(updateFields = true)`         | Function modifies mutable contract fields    |
| `@using(checkExternalCaller = false)` | Disables the default caller check            |

## Events

Contracts emit events to log activity. Events are indexed by the explorer and queryable via the API:

```ralph theme={null}
Contract TokenFaucet(...) {
  event Withdraw(to: Address, amount: U256)

  pub fn withdraw(to: Address, amount: U256) -> () {
    emit Withdraw(to, amount)
  }
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Deploying contracts" icon="rocket" href="/smart-contracts/deploying">
    Deploy a Ralph contract via the Ralph Studio IDE
  </Card>

  <Card title="Interacting with contracts" icon="plug" href="/smart-contracts/interacting">
    Call functions on deployed contracts
  </Card>
</CardGroup>