Skip to main content

API Reference

Below is a full list of APIs available in Kwil JS.

Kwil Object​

The main class for interacting with the Kwil network.

constructor()​

constructor(config: Config): Kwil

interface Config {
    kwilProvider: string;
    chainId: string;
    unconfirmedNonce?: boolean;
    autoAuthenticate?: boolean
    timeout?: number;
    logging?: boolean;
    logger?: (msg: string) => any;
}

Creates a new instance of the Kwil class. Can be initialized with WebKwil in browser or NodeKwil in NodeJS.

Parameters​

  • config: The configuration object for the Kwil class.
  • config.kwilProvider: The JSON RPC address of the Kwil node.
  • config.chainId: The chain ID of the Kwil network.
  • config.unconfirmedNonce: (optional) If true, the SDK will use the unconfirmed nonce for the account. If false, the SDK will use the confirmed nonce for the account. Default is false. This is useful when sending multiple transactions in parallel.
  • config.autoAuthenticate: (optional) If true, the SDK will automatically try to authenticate the user when using Kwild in private mode or Kwil Gateway. Default is true.
  • config.timeout: (optional) The timeout for JSON RPC requests to the Kwil node. Default is 10000ms.
  • config.logging: (optional) If true, the SDK will log debug messages to the console. Default is false.
  • config.logger: (optional) A custom logger function. If provided, the SDK will use this function to log debug messages.

Returns​

A new instance of the Kwil class.

auth​

kwil.auth: Auth

The auth property accesses the authentication methods for the Kwil Gateway. See the Auth section below for more information.

call()​

async call<T>(callBody: CallBody, kwilSigner?: KwilSigner): Promise<GenericResponse<MsgReceipt<T>>>

interface ActionBody {
    namespace: string;
    name: string;
    inputs?: NamesParams | PositionalParams
    description?: string;
    authBody?: AuthBody;
    cookie?: string; // only if using NodeKwil
}

interface AuthBody {
    signature: Base64String
    challenge: HexString
}

type NamedParams = { [key: string]: string | number | null };
type PositionalParams = ValueType[]

type ValueType =
  | string
  | number
  | null
  | undefined
  | Array<ValueType>
  | boolean
  | Uint8Array
  | UUID;

inteference MsgReceipt<T> {
    result: T[] | null | undefined;
}

Calls a view procedure on the network. The kwilSigner is required if any of the following conditions are met:

  • The procedure uses a @caller contextual variable.
  • The Kwil network is running in Private mode.
  • The Kwil network is connected to a Kwil Gateway.

For the last two conditions, the SDK will automatically prompt the user to authenticate.

Parameters​

  • callBody: The message to call. This object should match the CallBody interface and contain the namespace, action name, and inputs (if required).
  • kwilSigner (optional): The kwilSigner for the call request. This is required if the procedure uses a @caller contextual variable, the Kwil network is running in Private mode, or you are using KGW and the action/procedure has the @kgw(authn='true') annotation. The SDK will use the identifier in the kwilSigner to fill in the @caller contextual variable.

Returns​

A promise that resolves to the result of the procedure / query.

chainInfo()​

async chainInfo(opts?: ChainInfoOpts): Promise<GenericResponse<ChainInfo>>

interface ChainInfoOpts {
    disableWarning?: boolean;
}

Retrieves the chain id, latest block height, and latest block hash on the specified Kwil provider.

Parameters​

  • opts: The options object for the chain info request.
  • opts.disableWarning: If true, the SDK will disable the warning message when the chain ID does not match the expected chain ID. Default is false.

Returns​

A promise that resolves to a ChainInfo object, containing the chain id, latest block height, and latest block hash.

execSql()​

async execSql(
    query: string,
    params: QueryParams,
    signer: KwilSigner,
    synchronous?: boolean
): Promise<GenericResponse<TxReceipt>>

type QueryParams = Record<string, ValueType>;
type ValueType =
  | string
  | number
  | null
  | undefined
  | Array<ValueType>
  | boolean
  | Uint8Array
  | UUID;

Executes a state changing SQL query (CREATE/INSERT/UPDATE/DELETE/ALTER).

Parameters​

  • query: The query string to execute. E.g., INSERT INTO table (col) VALUES ($str).
  • params: The query parameters, if defined on the query. If none, pass {}. E.g., {$str: 'helo world'}
  • signer: The signer for the transaction. This can be created with the KwilSigner class.
  • synchronous: If true, the SDK will wait for the transaction to be confirmed on the chain before returning. If false, the SDK will return the tx_hash immediately after the transaction is sent. Default is false.

execute()​

async execute(actionBody: ActionBody, kwilSigner: KwilSigner, synchronous: boolean): Promise<GenericResponse<TxReceipt>>

interface ActionBody {
    namespace: string
    name: string;
    inputs?: NamedParams[] | PositionalParams[];
    description?: string;
    nonce?: string;
}

type NamedParams = { [key: string]: string | number | null };
type PositionalParams = ValueType[]

type ValueType =
  | string
  | number
  | null
  | undefined
  | Array<ValueType>
  | boolean
  | Uint8Array
  | UUID;

Executes a state-changing (Create, Update, Delete) action on the Kwil database.

Parameters​

  • actionBody: The action body to execute. This object should match the ActionBody interface and contain the action name and its namespace. It should also include an array of inputs, if inputs are required. Pass multiple NamedParams or PositionalParams to execute the action multiple times in a single transaction.

  • kwilSigner: The signer for the procedure transaction. This can be created with the KwilSigner class.

  • synchronous: If true, the SDK will wait for the transaction to be confirmed on the chain before returning. If false, the SDK will return the tx_hash immediately after the transaction is sent. Default is false.

Returns​

A promise that resolves to the hash of the transaction. The status of the transaction can be checked with the kwil.txInfo() method and passing the hash of the transaction.

funder​

kwil.funder: funder

The funder property accesses the funding methods for the Kwil network.' See the Funder section below for more information.

getAccount()​

async getAccount(owner: string | Uint8Array, keyType?: string): Promise<GenericResponse<Account>>

Retrieves account info using the owner's account identifier.

Parameters​

  • owner: The owner's account identifier. If string, it should be the hex encoded representation of the owner's identifier.
  • keyType: (optional) The name of the signer type. This is only required if your database uses a custom signer. This is not required if you are using a secp256k1 (EVM) or ed25519 signer.

Returns​

A promise that resolves to an Account object. The account object includes the owner's identifier, balance, and nonce.

ping()​

async ping(): Promise<GenericResponse<string>>

Pings the server and gets a response.

Returns​

A promise that resolves to a string indicating the server's response.

selectQuery()​

async selectQuery(query: string, params?: QueryParams): Promise<GenericResponse<Object[]>>

type QueryParams = Record<string, ValueType>;

Performs a SELECT query on a database. The query must be a read-only query.

Note: selectQuery() will error if the Kwil network is running in Private mode.

Parameters​

  • query: The select query to execute. E.g., SELECT * FROM posts WHERE msg = $msg
  • params: (optional) The paramers in the query string, if provided. E.g., {$msg: 'hello world'}.

Returns​

A promise that resolves to an array of objects of database records.

txInfo()​

async txInfo(hash: string): Promise<GenericResponse<TxInfoReceipt>>

Retrieves information about a transaction given its hash.

Parameters​

  • hash: The hash of the transaction.

Returns​

A promise that resolves to the transaction information, including the hash, blockheight of the transaction, the tx payload, and the tx result.

KwilSigner​

The KwilSigner is a class that is used to sign transactions and messages on Kwil.

constructor()​

constructor(signer: EthSigner, identifier: HexString | Uint8Array): KwilSigner;

constructor(signer: (msg: Uint8Array) => Promise<Uint8Array>, identifier: HexString | Uint8Array, signatureType: string): KwilSigner;

Creates a new instance of the KwilSigner class.

Parameters​

  • signer: The signer for the procedure transaction. It can receive an EtherJS (v5 or v6) signer or a custom signer function.

  • identifier: The identifier of the user that is executing the procedure transaction. This can be a hex string or a Uint8Array.

  • signatureType: The signature type enumerator. This is only required if a custom signer function is provided.

The following signature types and corresponding identifiers can be used:

TypeIdentifierEnumeratorDescription
Secp256k1Ethereum Wallet Address'secp256k1'The Kwil Signer will use a secp256k1 elliptic curve signature, which is the same signature used in Ethereum's personal sign.
ED25519ED25519 Public Key'ed25519'The Kwil Signer will use an ED25519 signature.signature.

Returns​

A new instance of the KwilSigner class.

Auth​

The Auth class is used to execute authentication-related operations on a Kwil Gateway or if the Kwil network is running in Private mode.

danger

The Auth class will only work if you are connected to a Kwil Gateway or running the Kwil network in Private mode. If you are connected directly to a Kwil Node, none of the methods in the Auth class will work.

constructor()​

The auth class is automatically initialized with the Kwil class. It can be accessed with kwil.auth.

authenticateKGW()​

async authenticateKGW<T extends EnvironmentType>(signer: KwilSigner): Promise<GenericResponse<AuthSuccess<T>>>

// AuthSuccess interface browser (WebKwil)
interface AuthSuccess<EnvironmentType.Browser> {
    result: string;
}

// AuthSuccess interface node (NodeKwil)
interface AuthSuccess<EnvironmentType.Node> {
    result: string;
    cookie: string;
}

Authenticates a user with the Kwil Gateway.

Parameters​

  • signer: The signer for the authentication request. This can be created with the KwilSigner class.

Returns​

A promise that resolves to an AuthSuccess object. The object contains the result of the authentication request. If the environment is a browser, the object will contain the result. If the environment is NodeJS, the object will contain the result and a cookie.

authenticatePrivateMode()​

async authenticatePrivateMode(actionBody: ActionBody, signer: KwilSigner): Promise<AuthBody>;

interface AuthBody {
    signature: Base64String;
    challenge: HexString;
}

Authenticates a user in Private mode.

Parameters​

  • actionBody: The body of the read / view procedure to send.
  • signer: The signer for the authentication request. This can be created with the KwilSigner class.

Returns​

A promise that resolves an AuthBody object, consisting of a signature and a challenge. AuthBody can be passed to CallBody to manually authenticate users.

logoutKGW()​

async logoutKGW<T extends EnvironmentType>(signer?: KwilSigner): Promise<GenericResponse<LogoutResponse<T>>>;

// LogoutResponse interface browser (WebKwil)
interface LogoutResponse<EnvironmentType.Browser> {
    result: string;
}

// LogoutResponse interface node (NodeKwil)
interface LogoutResponse<EnvironmentType.Node> {
    result: string;
    cookie: string;
}

Logs out the current user(s) from the Kwil Gateway by expiring the cookie.

Parameters​

  • signer: The signer to be logged out. This can be created with the KwilSigner class. If no signer is provided, all users will be logged out.

Returns​

A promise that resolves to a LogoutResponse object. The object contains the result of the logout request. If the environment is a browser, the object will contain the result. If the environment is NodeJS, the object will contain the result and an expired cookie.

Funder​

The Funder class is used to execute funding-related operations on a Kwil network (if funding is enabled).

constructor()​

The funder class is automatically initialized with the Kwil class. It can be accessed with kwil.funder.

transfer()​

async transfer(transferBody: TransferBody, kwilSigner: KwilSigner, synchronous: boolean): Promise<GenericResponse<TxReceipt>>

interface TransferBody {
    to: string | Uint8Array;
    amount: BigInt;
    keyType?: string;
    description?: string;
};

Parameters​

  • transferBody: The transfer body to execute. This object should match the TransferBody interface and contain the recipient's identifier and the amount to transfer. Funds amount should be in BigInt format, e.g. BigInt(1 * 10 ** 18) for 1 token on the Kwil Network. It can also contain a custom signature message. keyType is required if the account you are transferring to uses a custom signer (i.e., any account that is not secp256k1 or ed25519).

  • kwilSigner: The signer for the procedure transaction. This can be created with the KwilSigner class.

  • synchronous: If true, the SDK will wait for the transaction to be confirmed on the chain before returning. If false, the SDK will return the tx_hash immediately after the transaction is sent. Default is false.

Returns​

A promise that resolves to the hash of the transaction. The status of the transaction can be checked with the kwil.txInfo() method and passing the hash of the transaction.