README
¶
Kwil
The database for Web3.
Kwil is the node software for Kwil Networks. Built with PostgreSQL and CometBFT, Kwil enables byzantine fault tolerant networks to be built on top of relational databases.
Overview
To learn more about high-level Kwil concepts, refer to the Kwil documentation.
To test deploying and using a Kuneiform schema (Kwil's smart contract language) on the Kwil testnet, refer to the Kwil testnet tutorial.
For more information on kwil-db, check out the Kwil node documentation.
Quickstart
Build Instructions
Prerequisites
To build Kwil, you will need to install:
-
Go 1.21 or 1.22
-
(optional) Protocol Buffers, with the
protocexecutable binary on yourPATH. -
(optional) Taskfile
-
(optional) Protocol buffers go plugins and other command line tools. The
tooltask will install the required versions of the tools into yourGOPATH, so be sure to includeGOPATH/binon yourPATH.task tools
Only Go is required to build directly from the cmd/kwild folder or via go install, although developers may require the other tools.
To run Kwil, PostgreSQL is also required. See the documentation for more information.
Build
The build task will compile kwild, kwil-cli, and kwil-admin binaries. They will be generated in .build/:
task build
You may also build the individual applications manually:
cd cmd/kwild
go build
Or without even cloning the source repository:
go install github.com/kwilteam/kwil-db/cmd/kwild@v0.7.0
Just replace v0.7.0 with the desired version or latest.
Running kwild
Running kwild requires a PostgreSQL host running. Since the default
configuration of most PostgreSQL packages requires changes for kwild, the
easiest is to run our pre-configured Docker image:
docker run -p 5432:5432 -v kwil-pg-demo:/var/lib/postgresql/data \
--shm-size 256m -e "POSTGRES_HOST_AUTH_METHOD=trust" \
--name kwil-pg-demo kwildb/postgres:latest
The first time this is run, it will pull the kwildb/postgres image from Docker
Hub and create a new persistent Docker volume named kwil-pg-demo. NOTE: This
command requires no authentication with postgres, and should not be used in
production.
task pg may be used to run the above command.
You can then start a single node network using the kwild binary built in the previous section:
# Use the full path to kwild if it is not on your PATH.
kwild --autogen
With the --autogen flag, the node automatically creates a new random network
and validator key, and the node will begin producing blocks.
For more information on running nodes, and how to run a multi-node network, refer to the Kwil documentation.
Resetting node data
By default, kwild stores all data in ~/.kwild. To reset the data on a deployment, remove the data directory while the node is stopped:
rm -r ~/.kwild
Then delete the PostgreSQL database. If using the Docker image or service, delete the container and it's volume:
docker container rm -f kwil-pg-demo
docker volume rm -f kwil-pg-demo
task pg:clean may be used to run the above commands.
If using a system install of postgres, recreate the database with psql:
psql -U postgres -h 127.0.0.1 -d postgres \
-c "DROP DATABASE IF EXISTS kwild" \
-c "CREATE DATABASE kwild OWNER kwild"
Unified kwild + postgres Quickstart Docker Service
For development purposes, the deployments/compose/kwil folder contains a
Docker Compose service definition that starts both kwild and postgres,
configured so that they will work together out-of-the-box with no additional
configuration changes. Start it by running the following from the
deployments/compose/kwil folder in the repository:
cd deployments/compose/kwil
docker compose up --build -d
With the -d option, the service(s) will be started as background processes. To
stop them or view logs, use the docker container commands or the Docker
Desktop dashboard.
On start, this service definition will create a testnode folder in the same
location as the docker-compose.yml file, and a persistent Docker volume called
kwil_pgkwil for the postgres database cluster files.
This also runs with the --autogen flag, creating a new randomly generated
chain, and is not intended for production use. However, the service definition
may be used as a basis for a customized deployment.
Extensions
Kwil offers an extension system that allows you to extend the functionality of your network (e.g. building network oracles, customizing authentication, running deterministic compute, etc.). To learn more about the types of extensions and how to build them, refer to the extensions directory README.
Contributing
We welcome contributions to kwil-db. To contribute, please read our contributing guidelines.
License
The kwil-db repository (i.e. everything outside of the core directory) is licensed under the Apache License, Version 2.0. See LICENSE for more details.
The kwil Go SDK (i.e. everything inside of the core directory) is licensed under the MIT License. See core/LICENSE.md for more details.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
common/display
Package display provides interfaces and functions to format the command line output and print.
|
Package display provides interfaces and functions to format the command line output and print. |
|
kwil-admin/nodecfg
Package nodecfg provides functions to assist in the generation of new kwild node configurations.
|
Package nodecfg provides functions to assist in the generation of new kwild node configurations. |
|
kwild/config
Package config provides types and functions for node configuration loading and generation.
|
Package config provides types and functions for node configuration loading and generation. |
|
kwild/server
Package server defines the main Kwil server, which includes the blockchain node and the gRPC services that interface with the Kwil dataset engine.
|
Package server defines the main Kwil server, which includes the blockchain node and the gRPC services that interface with the Kwil dataset engine. |
|
sql
Package sql defines common type required by SQL database implementations and consumers.
|
Package sql defines common type required by SQL database implementations and consumers. |
|
core
module
|
|
|
auth
Package auth contains any known Authenticator extensions that may be selected at build-time for use in kwild.
|
Package auth contains any known Authenticator extensions that may be selected at build-time for use in kwild. |
|
listeners
package listeners provides the interface and registration for custom event-driven listeners.
|
package listeners provides the interface and registration for custom event-driven listeners. |
|
listeners/eth_deposits
package ethdeposits implements an listener that listens to Ethereum events and triggers the creation of deposit events in Kwil.
|
package ethdeposits implements an listener that listens to Ethereum events and triggers the creation of deposit events in Kwil. |
|
precompiles
package actions allows custom actions to be registered with the engine.
|
package actions allows custom actions to be registered with the engine. |
|
resolutions
package resolutions contains the interface and registration for resolution types.
|
package resolutions contains the interface and registration for resolution types. |
|
resolutions/credit
package credit implements a credit resolution, allowing accounts to be credited with a given amount.
|
package credit implements a credit resolution, allowing accounts to be credited with a given amount. |
|
internal
|
|
|
abci/meta
Package meta defines a chain metadata store for the ABCI application.
|
Package meta defines a chain metadata store for the ABCI application. |
|
engine/sqlanalyzer/attributes
Package attributes analyzes a returned relations attributes, maintaining order.
|
Package attributes analyzes a returned relations attributes, maintaining order. |
|
engine/sqlanalyzer/clean
Package clean cleans SQL queries.
|
Package clean cleans SQL queries. |
|
events
package events is used to track events that need to be included in a Kwil block.
|
package events is used to track events that need to be included in a Kwil block. |
|
events/broadcast
package broadcast contains logic for broadcasting events to the Kwil network
|
package broadcast contains logic for broadcasting events to the Kwil network |
|
ident
Package ident provides the functions required by kwild for message and transaction signature verification, and address derivation.
|
Package ident provides the functions required by kwild for message and transaction signature verification, and address derivation. |
|
services/grpc/function/v0
package function/v0 implements a grpc server for the Kwil function service.
|
package function/v0 implements a grpc server for the Kwil function service. |
|
sql/pg
Package pg defines the primary PostgreSQL-powered DB and Pool types used to support Kwil DB.
|
Package pg defines the primary PostgreSQL-powered DB and Pool types used to support Kwil DB. |
|
sql/versioning
package versioning provides standard schema versioning for Kwil databases.
|
package versioning provides standard schema versioning for Kwil databases. |
|
txapp
package tx_router routes transactions to the appropriate module(s)
|
package tx_router routes transactions to the appropriate module(s) |
|
utils/sync_map
Package syncmap provides a map that is safe for concurrent use.
|
Package syncmap provides a map that is safe for concurrent use. |
|
parse
module
|
|
|
test
module
|