Interacting with Contracts

Once a contract is deployed you interact with it in two ways view calls that read state without a transaction, and script executions that change state and cost gas.

View calls reading data

View calls are free and instant. Use them to read contract fields or call pure/view functions:

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": []
  }'

{
  "returns": [
    {
      "type": "ByteVec",
      "value": "546f6b656e"
    }
  ],
  "gasUsed": 1000
}

methodIndex is the zero-based position of the function in the contract source. The first public function is 0, the second is 1, and so on.

Passing arguments

Match the type names to the Ralph types declared in the function signature:

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": 2,
    "args": [
      { "type": "Address", "value": "1DrDyTr9..." },
      { "type": "U256", "value": "1000000000000000000" }
    ]
  }'

Ralph type	API type string	Example value
`U256`	`"U256"`	`"1000000000000000000"`
`I256`	`"I256"`	`"-500"`
`Bool`	`"Bool"`	`true`
`ByteVec`	`"ByteVec"`	`"546f6b656e"`
`Address`	`"Address"`	`"1DrDyTr9..."`

State-changing calls TxScript

To execute a function that modifies state you build and submit a transaction using a TxScript. First build the unsigned transaction:

curl -X POST "https://rpc.ralphstudio.xyz/{slug}/contracts/unsigned-tx/execute-script" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromPublicKey": "03a6b9c2d4e5f1...",
    "bytecode": "0101...",
    "attoAlphAmount": "1000000000000000000"
  }'

{
  "unsignedTx": "0201010...",
  "txId": "503bfb16...",
  "fromGroup": 0,
  "toGroup": 0,
  "gasAmount": 20000,
  "gasPrice": "100000000000"
}

Then sign the txId with your private key and submit:

curl -X POST "https://rpc.ralphstudio.xyz/{slug}/transactions/submit" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "unsignedTx": "0201010...",
    "signature": "9e1a35b2..."
  }'

Compile a TxScript on the fly

If you have Ralph source for a script you can compile it before building the transaction:

curl -X POST "https://rpc.ralphstudio.xyz/{slug}/contracts/compile-script" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "TxScript Withdraw(faucet: TokenFaucet) { faucet.withdraw{callerAddress!() -> ALPH: 1 alph}(callerAddress!(), 1 alph) }"
  }'

{
  "bytecodeTemplate": "0101...",
  "fields": {
    "names": ["faucet"],
    "types": ["Address"],
    "isMutable": [false]
  }
}

Use the returned bytecodeTemplate in the execute-script call above.

Reading state after a transaction

After a state-changing transaction confirms, read the updated mutFields:

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

{
  "mutFields": [
    {
      "type": "U256",
      "value": "999000000000000000000"
    }
  ]
}

Smart Contracts

Interacting with Contracts

View calls reading data

Passing arguments

State-changing calls TxScript

Compile a TxScript on the fly

Reading state after a transaction

Next steps

Contract events

Reading contracts via API

​View calls reading data

​Passing arguments

​State-changing calls TxScript

​Compile a TxScript on the fly

​Reading state after a transaction

​Next steps

Contract events

Reading contracts via API

View calls reading data

Passing arguments

State-changing calls TxScript

Compile a TxScript on the fly

Reading state after a transaction

Next steps