Getting Started

Welcome to the Quick Start Guide for Keelung!

We'll guide you through running and compiling your first Keelung program in this tutorial!

Keelung Playground

In this tutorial, we're using GitHub Codespaces so you can quickly explore Keelung without needing to install anything on your machine.

This playground includes a functional Visual Studio Code editor, direct access to the underlying Ubuntu Linux system, the Keelung compiler, and the Aurora prover and verifier.

Getting Started with Codespaces

To begin, head over to our Keelung examples repository and click the "Code" button on the repository page to start the Codespace. It's free for personal GitHub accounts.

Editor Extensions (optional)

Upon initiation, it could require some time to download and configure the editor extensions. You can opt to follow its recommendations and install the Haskell Language Server via GHCup. This language server provides helpful functions like code navigation and type hints. However, it's completely okay if you don't want these features.

Ready to Roll

If you're seeing something like this, you're all set!

Hello World

Open the tutorial

Now, let's open src/Tutorial.hs; all the necessary materials for this tutorial are contained within this file.

Open the REPL and load the tutorial

Go to the TERMINAL at the bottom, and enter stack repl to load the whole project into the REPL.

After the REPL has been opened, enter the following command to load the module in src/Tutorial.hs:

ghci> :l Tutorial

We are actually using GHCi as Keelung's REPL, checkout its manual if you want to know more commands like :l

The First Example

echo is a Keelung program that takes a private input and then immediately returns it as the output.

echo :: Comp Field
echo = do
  x <- input Private -- request for a private input and bind it to 'x'
  return x           -- return 'x'

Interpret echo

If you want to check if a program is working correctly, you can simulate its execution using the interpreter:

ghci

ghci> interpret gf181 echo [] [3]
[3]

The interpret command takes a field type, a Keelung program, a list of public inputs, and a list of private inputs, and returns the result of interpreting the function with those inputs.

Compile echo

The compile command takes a field type and a Keelung program as inputs, and outputs a set of constraints that can be used for verification:

ghci

ghci> compile gf181 echo
Right R1CS {
  Constriant (1): 
    Ordinary constraints (1):

      1552511030102430251236801561344621993261920897571225600$0 + $1 = 0

  Variables (2):

    Output variable : $0
    Private Input variable : $1

}

The outcome is a representation of R1CS (Rank-1 Constraint System).

It consists of constraints that describe how variables relate to each other. Some of these variables stand for the inputs and outputs of this constraint system, while others work as intermediaries between them.

Imagine a Keelung program as a circuit. The I/O variables are like the pins you'd find on a circuit, used to communicate with the outside world. And the constraints are like the wires that connect these pins.

In the case of the echo program, we can observe that there are just 2 variables: $1 serves as the private input, and $0 is the sole output. The entire system features just one constraint that connects these two variables. We can interpret the coefficient 1552511030102430251236801561344621993261920897571225600 as -1, and the constraint as $0 = $1, because there are only 1552511030102430251236801561344621993261920897571225601 elements in the underlying field gf181 that we have chosen.

Congratulations on completing this introductory tutorial! You've taken your first steps into the world of Keelung, getting a glimpse of its capabilities and functionality. If you're eager to learn more, proceed to the next tutorial where we'll dive into the fundamental aspects of Keelung. You'll uncover the core concepts that underlie its power and versatility.

Install Keelung on Your Machine (Optional)

We recommend using Codespaces to explore Keelung and its fundamentals. Setting up Keelung requires installing both Haskell and Keelung toolchains, which can be challenging for those unfamiliar with Haskell. If you're experienced with installations and seek enhanced performance or wish to integrate Keelung into your preferred editors or workflow, refer to our Installation guide on setting up Keelung locally.

After you have installed Keelung, clone the tutorial repository and load it with:

bash

git clone [e-mail]:btq-ag/keelung-examples.git
cd keelung-examples
stack repl

Next Up: Keelung Basics

Congratulations on completing this introductory tutorial! Let's continue to our next tutorial, where we'll delve into Keelung's fundamentals.

Keelung Basics