Quickstart Guide
To use Kwil, we will need to lock up some tokens in an escrow smart contract. Right now, the Kwil testnet is programmed to accept a test ERC20 deployed on the Goerli testnet. In the future, dApp developers will be able to choose the token that they use to pay for their usage.
In order to start using Kwil, you will need 3 things:
To access Kwil, you will need to use a Kwil Endpoint:
The quickest way to begin using Kwil is with our Javascript/Typescript SDK. The SDK can be installed by running:
npm i kwil
To initialize Kwil, you need to create a new Kwil object, as well as either a wallet or provider
const { ethers } = require('ethers');
const kwiljs = require('kwil');
// instead of a provider, nodeJS requires a wallet
const wallet = new ethers.Wallet("my_ethereum_private_key")
// create a new Kwil web client
const kwil = new kwiljs.NodeKwil({
kwilProvider: "kwil_provider_endpoint",
});
import { ethers } from 'ethers';
import kwiljs from 'kwil';
// prompt metamask to connect
const provider = new ethers.providers.Web3Provider(window.ethereum)
await provider._ready()
await ethereum.request({ method: 'eth_requestAccounts' });
// create a new Kwil web client
const kwil = new kwiljs.WebKwil({
kwilProvider: "kwil_provider_endpoint",
});
Payment to the Kwil network occurs through deposit contracts that exist on other chains. Right now, a testnet contract using testnet tokens is deployed to Ethereum's Goerli Testnet. The SDK will automatically retrieve the necessary smart contract and token information from your Kwil RPC provider.
Since Kwil is built to handle any number of tokens, the tooling does not currently handle token decimals. Values passed to the SDK need to use the integer representation of an ERC20 amount. Read more on ERC20 decimals here.
// get funder
const funder = await kwil.getFunder(ethereum_signer);
// approve funds
const approve = await funder.approve(ethers.BigNumber.from("1000000000"));
// Deposit funds
const deposit = await funder.deposit(ethers.BigNumber.from("1000000000"));
The database schema returns a JSON representations of a database. Information on full JSON representations can be found in the databases section.
const res = await kwil.getSchema("0xOwner_address", "database_name")
/*
res.data = {
name: "database_name",
owner: "0xowner_address",
tables: [ tableObject1, tableObject2, tableObject3 ]
sqlQueries: [ sqlQueryObject1, sqlQueryObject2, sqlQueryObject3 ]
roles: [ roleObject1, roleObject2, roleObject3 ]
indexes: [ indexObject1, indexObject2, indexObject3 ]
}
*/
Different from schemas, Database Interfaces (DBIs) are small structures that provide an easy-to-use interface for databases. They are conceptually similar to smart contract ABIs.
let dbi = await kwil.selectDatabase("0xOwner_address", "database_name")
/*
dbi = DBI {
owner: "0xOwner_address",
name: "database_name",
queries: map<name, executable>
DBID: "0xDBID"
}
*/
// getting a query
const query = dbi.getQuery("my_query")
Data can be written by using executables provided through the DBI. The setInput method receives two arguments: the name of the input being set and the value.
// setting query inputs
query.setInput("input_name", "satoshi")
query.setInput("other_input_name", 20)
// you can check if all required inputs have been set
if (!query.isComplete()) {
throw new Error("Executable is not complete")
}
// generated a new transaction from the filled query
let tx = query.newTx()
// prepare tx
tx = await kwil.prepareTx(tx, provider) // can also use the "wallet" here
// broadcast the transaction
const res = await kwil.broadcast(tx)
/*
res.data = {
hash: "TxHash",
fee: "some_spent_fee"
}
*/
Data can be read from schemas with GraphQL. Our team is actively working to provide more ways to read data.
const res = await kwil.graphql(`query GraphQLQuery {
0xDbid_tableName(
where: {col1: {_eq: "my_val"}}
) {
col1
col2
col3
}
}
`)
Last modified 20d ago