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;
    timeout?: number;
    logging?: boolean;
    logger?: Function;
    cache?: seconds;
}

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 URL of the Kwil provider.
  • 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.timeout: (optional) The timeout for the Kwil provider. 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.
  • config.cache: (optional) The TTL cache for the SDK. Default is 600 seconds (10 minutes). See the TTL Cache section for more information.

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(actionBody: ActionBody, kwilSigner?: KwilSigner): Promise<GenericResponse<MessageReceipt>>

interface ActionBody {
    name: string;
    dbid: string;
    inputs?: ActionInput[] | Entries[];
    description?: string;
}

type Entries = { [key: string]: string | number | null };

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 and the procedure has the @kgw(authn='true') annotation.

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

Parameters​

  • actionBody: The message to call. This object should match the ActionBody interface and contain the procedure name and database ID. The inputs array must only have one entry.
  • 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.

deploy()​

async deploy(deployBody: DeployBody, kwilSigner: KwilSigner, synchronous: boolean): Promise<GenericResponse<TxReceipt>>

interface DeployBody {
    schema: CompiledKuneiform;
    description?: string;
};

Deploys a new database to the Kwil network.

Parameters​

  • deployBody: The deploy body to execute. This object should match the DeployBody interface and contain the compiled Kuneiform schema. It can also contain a custom signature message. You can create a compile Kuneiform file by right clicking a compiled file in the Kuneiform IDE and selecting "Export to JSON".

  • 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.

drop()​

async drop(dropBody: DropBody, kwilSigner: KwilSigner, synchronous: boolean): Promise<GenericResponse<TxReceipt>>

interface DropBody {
    dbid: string;
    description?: string;
};

Drops a database from the Kwil network.

Parameters​

  • dropBody: The drop body to execute. This object should match the DropBody interface and contain the database ID. It can also contain a custom signature message.

  • 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.

execute()​

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

interface ActionBody {
    name: string;
    dbid: string;
    inputs?: ActionInput[] | Entries[];
    description?: string;
}

type Entries = { [key: string]: string | number | null };

Executes a state-changing (Create, Update, Delete) procedure on the Kwil network.

Parameters​

  • actionBody: The action body to execute. This object should match the ActionBody interface and contain the procedure name and database ID. It can also contain an array of ActionInputs and a custom signature message.

  • 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): Promise<GenericResponse<Account>>

Retrieves an account using the owner's account identifier.

Parameters​

  • owner: The owner's account identifier

Returns​

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

getDBID()​

getDBID(owner: string, name: string): string

Generates a unique database identifier (DBID) from the provided owner's identifier (e.g. wallet address, public key, etc.) and a database name.

Parameters​

  • owner: The owner's identifier (e.g. wallet address, public key, etc.)
  • name: The name of the database. This should be the name of the database as defined in Kuneiform.

Returns​

A string that represents the unique identifier for the database.

getSchema()​

async getSchema(dbid: string): Promise<GenericResponse<Database<string>>>

Retrieves the schema of a database given its unique identifier (DBID).

Parameters​

  • dbid: The unique identifier of the database. The DBID can be generated using the getDBID method.

Returns​

A promise that resolves to the schema of the database.

tip

The result of .getSchema() is stored in the TTL cache for 10 minutes. You can customize or disable the TTL cache by setting the cache option in the WebKwil or NodeKwil constructor.

listDatabases()​

async listDatabases(owner?: string): Promise<GenericResponse<DatasetInfo[]>>

interface DatasetInfo {
    name: string;
    owner: Uint8Array;
    dbid: string;
}

Lists all databases owned by a particular owner. If no owner is provided, it will list all databases on the network.

Parameters​

  • owner(optional): The owner's identifier (e.g. wallet address, public key, etc.).

Returns​

A promise that resolves to an array of DatasetInfo objects. Each object contains the database name, owner's identifier, and database ID.

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(dbid: string, query: string): Promise<GenericResponse<Object[]>>

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​

  • dbid: The unique identifier of the database. The DBID can be generated using the getDBID method.
  • query: The SELECT query to execute.

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>, publicKey: HexString | Uint8Array, signatureType: SignatureType): 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_ep'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(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()​

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. Both a signature and a challenge are needed to authenticate a user in Private mode.

logout()​

logout(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;
    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.

  • 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.

Action Inputs​

The ActionInput class is a utility class to build inputs to be passed and executed in an procedure transaction. It is found in the Utils namespace, which can be imported from the kwil package.

constructor()​

constructor(): ActionInput

Creates a new instance of the ActionInput class.

Returns​

A new instance of the ActionInput class.

put()​

put(key: string, value: any): ActionInput

Adds or replaces a value for a single input.

Parameters​

  • key: The input name .
  • value: he value to put for the input.

Returns​

The ActionInput instance for chaining.

putIfAbsent()​

putIfAbsent(key: string, value: any): ActionInput

Adds a value for a single input if the key is not already present.

Parameters​

  • key: The input name.
  • value: The value to put for the input.

Returns​

The current ActionInput class for chaining.

replace()​

replace(key: string, value: any): ActionInput

Replaces a value for a single input if the key is already present.

Parameters​

  • key: The input name.
  • value: The value to replace for the input.

Returns​

The current ActionInput class for chaining.

get()​

get(key: string): any

Retrieves an input value given its key.

Parameters​

  • key: The input name.

Returns​

The value associated with the input name.

getOrDefault()​

getOrDefault(key: string, defaultValue: any): any

Retrieves a value by its input name, or a default value if the input name is not present.

Parameters​

  • key: The input name.
  • defaultValue: The default value to return if the key is not present.

Returns​

The value associated with the key, or the default value.

containsKey()​

containsKey(key: string): boolean

Checks if the map contains a specific input name.

Parameters​

  • key: The input name.

Returns​

True if the input name is present, false otherwise.

remove()​

remove(key: string): boolean

Removes an input name and its associated value from the map.

Parameters​

  • key: The input name to remove.

Returns​

True if the key was present and is now removed, false otherwise.

toArray()​

toArray(filter?: Predicate): ReadonlyArray<EntryType>

Converts the map of inputs to an array of entries.

Parameters​

  • filter: An optional filter function.

Returns​

A read-only array of entries.

putFromObject()​

putFromObject(obj: object): ActionInput

Adds or replaces values from and object of procedure name/key-value pairs.

Parameters​

  • obj: The object from which to extract procedure name/key-value pairs.

Returns​

The current ActionInput instance for chaining.

putIfAbsentFromObject()​

putIfAbsentFromObject(obj: object): ActionInput

Adds values from and object of procedure name/key-value pairs if the key is not already present.

Parameters​

  • obj: The object from which to extract procedure name/key-value pairs.

Returns​

The current ActionInput instance for chaining.

replaceFromObject()​

replaceFromObject(obj: object): ActionInput

Replaces values from and object of procedure name/key-value pairs if the key is already present.

Parameters​

  • obj: The object from which to extract procedure name/key-value pairs.

Returns​

The current ActionInput instance for chaining.

putFromObjects()​

putFromObjects(objs: object[]): ActionInput[]

Creates multiple ActionInput instances from an array of objects.

Parameters​

  • objs: An array of objects from which to create ActionInput instances.

Returns​

An array of ActionInput instances.

static of()​

static of(): ActionInput

Factory method to create a new instance of ActionInput.

Returns​

A new ActionInput instance.

static from()​

static from(entries: Iterable<EntryType>): ActionInput

Creates a new ActionInput instance from an iterable array of entries.

Parameters​

  • entries: The iterable of set of entries. Entries should be formatted as an array of [inputName, value].

Returns​

A new ActionInput instance.

static fromObject()​

static fromObject(obj: object): ActionInput

Creates a new ActionInput instance from an object.

Parameters​

  • obj: The object from which to create the ActionInput.

Returns​

A new ActionInput instance.

static fromObjects()​

static fromObjects(objs: objects[]): ActionInput[]

Creates multiple ActionInput instances from an array of objects.

Parameters​

  • objs: An array of objects from which to create ActionInput instances.

Returns​

An array of ActionInput instances.

Utils​

The Utils namespace contains utility functions or classes for interacting with the Kwil network.

ActionInput​

Please see the ActionInput section above.

generateDBID()​

generateDBID(owner: string, name: string): string

An alternative to the kwil.getDBID() method, allowing developers to retrieve a database ID without instantiating the Kwil class.

Parameters​

  • owner: The owner's account identifier.
  • name: The name of the database. This should be the name of the database as defined in Kuneiform.

Returns​

A string that represents the unique identifier for the database.