Build your first zkGame on Aleo in under an hour

Work in progress

The Puzzle SDK and Aleo are in early development. The Puzzle SDK is open source. If you find something that’s not working, let us know on Telegram.

Build your first zkGame on Aleo with Puzzle Wallet & Puzzle SDK!

The game will be the simplest version of a battleship game where one user hides the location of an object and another user has to guess the location. Instead of having a 20x20 board like battleship, Where’s Alex is a simple 2x1 board.

At Puzzle, we call this a PvP hidden information game with spot hiding as the only input.

You can expand on this game by adding more hiding spots in your Leo Program and the UI!

In the future, we will be publishing other game tutorials on the following:

• PvP hidden information game with spot hiding inputs AND spot type inputs.
• small N v P hidden information game with spot hiding inputs AND spot type inputs like Blackjack!
• many N v P hidden information game with spot hiding inputs AND spot type inputs like Sudoku!

From this tutorial, you will learn 2 key things:

1. how to create your own zkGame utilizing privacy features only possible on Aleo with it’s ZK by design.
2. how to create your own hidden information game utilizing multiparty privacy features only possible with Puzzle Wallet & Puzzle SDK.

By the end of the hour, you will have:

• created your first Aleo account with Puzzle Wallet
• played your first zkGame on Aleo
• deployed your first zkGame contracts on Aleo
• deployed your own zkGame FE to Vercel
• Played Puzzle in your very own zkGame on Aleo!
• Earn eligibility for Puzzle Rewards!

Previous zkGames developed from tutorial:

• https://leo-wheres-luna.vercel.app/
• https://wheres-adam.vercel.app/
• https://wheres-joe.vercel.app/
• https://wheres-dominion.vercel.app/
• https://wheres-daniel.vercel.app/

Overview

1. Play — Download Puzzle Wallet, use Puzzle’s Devtools, & play Where’s Alex.
2. Deploy — Fork Where’s Alex, deploy your own contracts, and deploy your own front-end!
3. Earn! — Earn a special Puzzle Dev Giveaway by challenging us on your newly deployed game!

1. Play! (~10 min)

Create an Aleo account with Puzzle Wallet

Download Puzzle Wallet

Create an account following the instructions in the extension.

Wait 2 minutes for your Aleo credits & Puzzle Pieces to hit your account!

Play Where’s Alex!

Go to play Where’s Alex by going to that link and connecting your wallet.

After you connect your wallet — verify that it reads that you have no Puzzle Prudens.

Mint some Puzzle Prudens with Puzzle’s Devtools

Go to use Puzzle’s Devtools to mint some Prudens by going to link and connecting your wallet.

About Puzzle’s Devtools

Puzzle’s Devtools is here to help you as you develop.

Here you can test decryption, view records, and view events with the connected wallet or any other address in your wallet.

Deployments via Devtools will be available soon!

Once your wallet is connected, navigate to the “Create Event” section.

In order to mint yourself some Puzzle Prudens on Devtools — you’ll need to call the mint_private function on the deployed Aleo Program by following the steps below.

1. Program ID:

In the program ID section — input:

puzzle_pieces_v015.aleo

** This is the ID of the Aleo program (ie smart contract) for the game deployed to the Aleo network!

2. Function ID:

In the function ID section — input:

mint_private

** This is the function to mint Puzzle Prudens for the game deployed to the Aleo network!

3. Function Inputs:

In the function inputs section — input:

500u64 YOUR_ALEO_ACCOUNT_ADDRESS

Copy your Aleo address in your Puzzle Wallet and replace ‘YOUR_ALEO_ACCOUNT_ADDRESS’ with your address.

This should look like the below:

500u64 aleo19e7p64a8luh99s9gly7t0x9kkm5updzfklglx6a3wtysgdgh8ygsea9z0k

4. Create Event Press create event and watch as Puzzle Wallet executes, proves, and broadcasts the transaction to the Aleo Network!

This should take ~40 seconds to execute, settle on the network and the wallet to find & decrypt your private transaction

About Puzzle’s Events Nomenclature

You may have noticed that Puzzle calls transaction requests events.

Our wallet is capable of handling more than just Aleo transactions — so all actions out of the wallet are referred to as events!

Play Puzzle in Where’s Alex!

Once your transaction lands — you can hop back to wheresalex.puzzle.online and click through the new game prompt to play!

Challenge the Puzzle team to a game at our Aleo address to be eligible for Earn!

aleo1u66muyfx8kp9zw957m4tkkpmrpjdnem4q4zpddh6zd2dejds3y9qa6p32u

You can also challenge a friend at their aleo address as well!

2. Deploy! (~45 min)

Now let’s fork this game and make your very own zkGame! This will be 3 steps:

• Setup your Where’s Alex Fork
• Deploy your own zkGame Aleo programs to Aleo (~15 min)
• Deploy your own zkGame FE to Vercel (~30 min)

It’s as easy as A, B, C!

A. Setup your Where’s Alex fork

Visit our GH repo for Where’s Alex at github.com/puzzlehq/wheres_alex to:

• Fork the FE Repo
• Fork the Aleo programs

Video: How to fork the Where’s Alex repo

Review the programs section readme to better understand the Aleo Programs under the hood of Where’s Alex.

Review the main section readme to better understand how Where’s Alex & Puzzle addresses the problems of multiparty privacy!

B. Deploy your own zkGame Aleo programs to Aleo

This should take ~15 min and will be 3 sections of steps:

• Step 1: Getting tools for Aleo program deployment using snarkOS CLI
• Steps 2-6: Making your own “zkGame pieces” program & “zkGame” program
• Steps 7-9: Deploying your zkGame programs to Aleo

Getting tools for Aleo program deployment using snarkOS CLI

1. Install Rust, snarkVM, snarkOS, & Leo if you haven’t already (We recommend to also add the Leo Extension if using VS Code)

**If you do not have Leo installed or are running into errors with snarkOS, see videos below to uninstall/install rust, snarkVM, snarkOS, and Leo:

Video: Uninstalling Rust, snarkVM, snarkOS, & Leo

Video: Installing Rust, snarkVM, snarkOS, & Leo

Making your own “zkGame pieces” program & “zkGame” program

2. Open VS Code in your new forked repo & cd into the programs folder
3. Update the puzzle_pieces_v015.leo program to your own unique title/version.
4. Update the “puzzle_pieces” program.json file to your new name and use test.sh scripts to ensure all works!
5. Update the wheres_alex_v018.leo program to import your own token and use your own unique title/version
6. Update the program.json file and test.sh scripts and ensure all works!

See the video below for a walkthrough of steps 3-6

Video: Steps 3 - 6 on Forking Wheres Alex Programs

Deploying your programs to Aleo

7. Fund your Aleo Account for deploying the contracts with 70 Aleo Credits in Puzzle Wallet

In order to deploy your 2 new programs, you will need an Aleo account with at least 70 Aleo Credits. On new account creation in Puzzle Wallet, you will automatically be given 10 Aleo credits from our faucet. In order to get 70 Aleo Credits for deploying both contracts, create 6 new accounts in your Puzzle Wallet in addition to your existing. For each account, do a public transfer of the 10 Aleo Credits in the account the account you will be using to deploy.

See video for walkthrough of generating new accounts and sending Aleo Credits to that account below:

Video: Steps 7 Creating Accounts & Sending Credits

8. Deploy your new “zkGame pieces” program to the Aleo network using snarkOS cli and command below:

snarkos developer deploy "INSERT_YOUR_PIECES_FORK_PROGRAM_NAME_HERE.aleo" --private-key "INSERT_YOUR_ALEO_PRIVATE_KEY_HERE" --query "https://api.explorer.aleo.org/v1" --broadcast "https://api.explorer.aleo.org/v1/testnet3/transaction/broadcast" --priority-fee 16000000

The zkGame pieces program costs ~16 credits to store on the Aleo network and giving the deployment transaction an additional 16 credits typically guarantees the deployment transaction will land onchain.

See video below for walkthrough of deploying:

Video: Step 8 Deploying your own zkGame pieces program. Enjoy Mr. Boat.

9. Deploy your new “zkGame” program to the Aleo network using snarkOS cli

snarkos developer deploy "INSERT_YOUR_WHERES_ALEX_FORK_PROGRAM_NAME_HERE.aleo" --private-key "INSERT_YOUR_ALEO_PRIVATE_KEY_HERE" --query "https://api.explorer.aleo.org/v1" --broadcast "https://api.explorer.aleo.org/v1/testnet3/transaction/broadcast" --priority-fee 17000000

The wheres_alex program costs ~17 credits to store on the Aleo network and giving the deployment transaction an additional 17 credits typically guarantees the deployment transaction will land onchain.

See video below for walkthrough of deploying:

Video: Step 9 Deploying your own zkGame program

C. Deploy your own zkGame FE to Vercel!

Updating the Aleo programs the FE is referencing

1. Open VS Code in your forked repo and Control F in src for puzzle_pieces_v015.aleo and replace with your deployed version of zkGame pieces
2. Control F in src for wheres_alex_v018.aleo and replace with your deployed version of the zkGame
3. Control F in src for “fees” and change the last result and add 1 to every function to make sure the fee is high enough.

Video: Steps 1-3 Updating FE to read your own zkGame program with correct fees

Testing the FE with the new programs and starting your own zkGame!

4. Run the following command to compile and test locally

pnpm i && pnpm run dev

5. Connect Wallet to local version of your zkGame and verify that it works!

About first time contract testing with Puzzle Wallet

Puzzle Wallet does a lot of optimizations under the hood to improve proving time including key synthesis.

First time executing functions on new Aleo programs through puzzle wallet WILL take longer than normal. Expect 5-7 minutes for minting & 7-10 minutes for proposing games.

You also may find the Wallet buggy or not returning anything — this may actually be if the smart contract has a bug in it that wasn’t caught in testing scripts earlier.

If you find something that’s not working, let us know on Telegram

• You should see 0 Puzzle Prudens when you first connect to your zkGame
• Go to Devtools and mint yourself some of the new zkGame piece you just made
• Go back to your zkGame and verify your zkGame Pieces balance is updated on the FE

Video: Steps 4-5 Starting your FE and minting your first very own zkGame pieces!

6. Verify that propose game executes, proves, and settles on the network!

Video: Step 6 — starting your first very own zkGame!

Add flavor to your new zkGame and deploy to vercel!

7. Spice up the front-end to your choosing! Some ideas including:

• Control F on Prudens and updating to be the name of your own token you just deployed!
• Changing title of game to idea of your choosing and background images!
• Changing choices and pictures in the game to match your title!
• Change the Website and WalletConnect Adapter Image & Title

Video: Steps 1-3 Updating FE to read your own zkGame program with correct fees

8. Deploy via Vercel!

Congrats on making your first public zkGame for people to play! Post the link on Twitter and tag us @puzzlehq so we can highlight it! Make sure to post it to the Awesome Aleo repo as well!

Video: Steps 1-3 Updating FE to read your own zkGame program with correct fees

3. Earn! (~5 min)

Challenge the Puzzle Account to a game on your newly deployed site!

Play the Puzzle team in a full game at our Aleo address to be eligible for Earn!

aleo1u66muyfx8kp9zw957m4tkkpmrpjdnem4q4zpddh6zd2dejds3y9qa6p32u

We will take care of minting ourselves tokens based on your deployed contract address in order to play you — just don’t add permissions to it!

Join the Puzzle Devs Community Telegram & tag us

We will be announcing our Puzzle Dev Giveaways every Friday at 5PM ET in the telegram!

Tag @puzzlematt in the Devs Community Telegram after you deploy and propose a game to be eligible!

Join here

Troubleshooting

Issues playing Where’s Alex

You may find issues with our current Where’s Alex deployment if you are in a high latency environment (>300MS). Issues might include getting stuck at requesting event or requesting signature flows on propose game. Subsequently after failure, you might find the extension locking when retry-ing to send.

The fix for now is to go in your settings in the wallet and lock the wallet, refresh the dApp page, and re-connect to try again.

We are working on fixes for this and will update in the telegram when this is fixed.

See link here for testing your internet latency.

Issues downloading and using snarkOS

Another common issue is trying to get snarkOS to download to your computer especially if you are on Windows or Ubuntu with the error below:

RocksDB C++ / LLVM error

Could not find clang error

If you get the below error, it is likely because you don’t have C++ or LLVM properly setup on your machine. To solve you should:

• Download LLVM for Windows 64 bits from their GitHub here: https://github.com/llvm/llvm-project/releases/tag/llvmorg-17.0.6
• Install it. Chose option to add to path when it prompts.
• Close that terminal. Open another terminal and redo the cargo install —path .

Issues downloading Leo and running Leo test scripts

One common issue when trying to run the Leo test scripts is to get the error below: Leo: command does not exist error

The root of this issue has been found to be from the issue above — snarkOS/c++/LLVM is not properly installed.

Please refer to section above to fix.

If you have further issues at this step — please join our Puzzle devs telegram and ask in the support channel. Join here

Issues deploying with snarkOS

One common issue when deploying is getting the error below. If you get this error, just retry deploying again and it should go through!

rust backtrace error

Another common issue is to run into issues with the deploying script like below:

snarkOS deployment error

The solution is to run the following:

snarkos update

and

leo update

If either of those fail, it may be due to older versions or non-nightly versions of rust to have issues with the most recent snarkOS or Leo builds. At that point, we recommend you follow the videos in the tutorial to uninstall/reinstall rust, snarkVM, snarkOS, and Leo.

If you have further issues at this step — please join our Puzzle devs telegram and ask in the support channel. Join here

Issues minting pieces for your new zkGame

A couple people have reported a bug where pieces minted for their new zkGame via devtools will arrive in the wallet but the wallet doesn’t have the record associated. This is a known bug that we are looking into right now.

The fix for this found has been to mint pieces to another account in your wallet that is different than the one you are using to execute on devtools.

Issues starting a game for your new zkGame

Many people ran into the issue of propose_game transactions on their new zkGame never landing onchain.

The fix for this is to increase the fees in the FE code on your game. Reference the video in steps 1-3 to see how to do this.