Skip to main content

Building kwild With Extensions

In order to use extensions in Kwil, users need to build custom kwild binaries that include the extensions they want to use. This guide will walk you through the process of building a custom kwild binary with extensions.

Prerequisites​

Before building a custom kwild binary, ensure you have the following installed:

Step 1: Setting up the environment​

Start by setting up the repo for building the custom kwild binary. This will be a standard Go repo setup.

Create a new directory for the custom kwild binary and navigate to it:

mkdir custom-kwild
cd custom-kwild

Initialize a new Go module:

go mod init custom-kwild

Install the Kwil SDK:

go get github.com/kwilteam/[email protected]

Run go mod tidy to ensure all dependencies are installed.

go mod tidy

Step 2: Set up main.go​

Create a new file called main.go in the root of the project directory:

touch main.go

Add the following code to main.go:

main.go
package main

import (
    "fmt"
    "os"

    "github.com/kwilteam/kwil-db/cmd/kwild/root"
)

func main() {
    if err := root.RootCmd().Execute(); err != nil {
        fmt.Println(err)
        os.Exit(1)
    }
    os.Exit(0)
}

Step 3: Add a custom extension​

In the same directory as main.go, create a new file called custom_extension.go:

touch custom_extension.go

Add the following code to custom_extension.go. This example uses a custom authenticator extension, however any type of extension can be added in this step using their respective Register function in the init function of the extension file.

tip

Examples on how to implement each type of extensions can be found in their respective sections.

danger

This example is for demonstration purposes only and should not be used in a production environment. For a production-ready Ed25519 authenticator, please refer to the Ed25519 authenticator guide.

custom_extension.go
package main

import (
    "crypto/ed25519"
    "fmt"
    "encoding/hex"

    "github.com/kwilteam/kwil-db/extensions/auth"
)

// init registers the Ed25519Authenticator with the Kwil node
func init() {
    err := auth.RegisterAuthenticator("ed25519_example", Ed25519Authenticator{})
    if err != nil {
        panic(err)
    }
}

type Ed25519Authenticator struct{}

// Verify verifies the signature of a message
func (Ed25519Authenticator) Verify(sender, msg, signature []byte) error {
    if !ed25519.Verify(sender, msg, signature) {
        return fmt.Errorf("signature verification failed")
    }

    return nil
}

// Identifier returns the hex encoding of the public key
func (Ed25519Authenticator) Identifier(sender []byte) (string, error) {
    return hex.EncodeToString(sender), nil
}

Step 4: Build the custom kwild binary​

Build the custom kwild binary. This will compile all the files in the project directory, as well as any that are imported:

go build -o kwild

Step 5: Run Postgres​

Before running the custom kwild binary, you will have to start Postgres. The Kwil team has provided a default image with the necessary configurations. For more information on how to configure your own Postgres database, please refer to the Postgres setup guide.

docker run -d -p 5432:5432 --name kwil-postgres -e "POSTGRES_HOST_AUTH_METHOD=trust" \
    kwildb/postgres:latest

Step 6: Run the custom kwild binary​

After running Postgres, you can run the custom kwild binary. The --autogen flag will automatically generate a new node key, a network genesis file, and a default node configuration:

./kwild --autogen

Conclusion​

In this guide, you built a custom kwild binary with extensions. You can now use the custom kwild binary to run a Kwil node with the custom extension. For more information on how to use the custom extension, please refer to the respective extension documentation.

Next Steps​

Additional extension types and tutorials found below: