Skip to main content
Use this page when you want a clean local setup before integrating your consumer with the hosted roll.codes coordinator.

​
Requirements

  • Node.js 20+
  • foundry-zksync
  • A Solidity project where you want to integrate roll.codes

​
Install foundry-zksync

Abstract uses the zkSync VM, so use the foundry-zksync fork instead of standard Foundry. 
curl -L https://raw.githubusercontent.com/matter-labs/foundry-zksync/main/install-foundry-zksync | bash
foundryup-zksync
forge build --help | grep -A 20 "ZKSync configuration:"

​
Install Solidity dependencies

forge install roll.codes=jarrodwatts/roll.codes@main --no-git
forge install forge-std=foundry-rs/forge-std --no-git

​
Add remappings

Your project should include these remappings: 
@rollcodes/=lib/roll.codes/src/
forge-std/=lib/forge-std/src/

​
Set the minimum deploy environment

cast wallet import deployer --interactive
export ABSTRACT_RPC_URL=https://api.testnet.abs.xyz
export ROLL_COORDINATOR=0x5ab0e04147A2A1BCa1D06da3c1cB48ea04294B5E
ROLL_COORDINATOR should be the roll.codes coordinator address for the same network as ABSTRACT_RPC_URL. See Deployed addresses for the current network-specific values.

​
Verify the setup

Run a compile before you move on: 
forge build --zksync
If you are using the starter CLI, you can scaffold first and then run the same verification step in the generated project.

​
Common setup mistakes

  • using the wrong repo ref in forge install
  • missing the @rollcodes remapping
  • pointing ROLL_COORDINATOR at a different network than ABSTRACT_RPC_URL
  • forgetting that requestRandomNumberWithTraceId is payable on roll.codes and must send requestFee()
  • using plaintext private keys instead of a Foundry keystore account

Quickstart

Continue to the minimal hosted-coordinator integration flow once local setup is ready.

CLI reference

Use the scaffold command and flags to start from a generated project.

Troubleshooting

Fix import, fee, and callback issues if the setup does not compile cleanly.
Last modified on March 9, 2026