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 action on the network. If authentication for the view action is enforced by a Kwil Gateway, a kwilSigner must be provided. The call method will prompt the user to authenticate if they have not already done so, and will retain a cookie to authenticate with the Kwil Gateway for all subsequent calls.

Parameters

• actionBody: The message to call. This object should match the ActionBody interface and contain the action name and database ID. The inputs array must only have one entry.
• kwilSigner (optional): The kwilSigner for the call request. This is only required if the action uses a @caller contextual variable. 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 action / 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 action 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 action 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) action on the Kwil network.

Parameters

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

• kwilSigner: The signer for the action 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.

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 action 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 action 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:

Type	Identifier	Enumerator	Description
Secp256k1	Ethereum 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.
ED25519	ED25519 Public Key	'ed25519'	The Kwil Signer will use an ED25519 signature.

Returns

A new instance of the KwilSigner class.

Auth

The Auth class is used to execute authentication-related operations on a Kwil Gateway.

danger

The Auth class will only work if you are connected to a Kwil Gateway. 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.

authenticate()

async authenticate(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.

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 action 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 action inputs to be executed in an action 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 action input.

Parameters

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

Returns

The ActionInput instance for chaining.

putIfAbsent()

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

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

Parameters

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

Returns

The current ActionInput class for chaining.

replace()

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

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

Parameters

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

Returns

The current ActionInput class for chaining.

get()

get(key: string): any

Retrieves an action input value given its key.

Parameters

• key: The action input name.

Returns

The value associated with the action input name.

getOrDefault()

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

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

Parameters

• key: The action 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 action input name.

Parameters

• key: The action input name.

Returns

True if the action input name is present, false otherwise.

remove()

remove(key: string): boolean

Removes a action input name and its associated value from the map.

Parameters

• key: The action 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 action 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 action name/key-value pairs.

Parameters

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

Returns

The current ActionInput instance for chaining.

putIfAbsentFromObject()

putIfAbsentFromObject(obj: object): ActionInput

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

Parameters

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

Returns

The current ActionInput instance for chaining.

replaceFromObject()

replaceFromObject(obj: object): ActionInput

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

Parameters

• obj: The object from which to extract action 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.