Skip to content

createWalletClient

createWalletClient<transport, chain, accountOrAddress, rpcSchema>(parameters): object

Defined in: src/clients/createWalletClient.ts:51

Creates a Wallet Client with a given Transport configured for a Chain and an account.

A Wallet Client signs and sends transactions, so it carries an account and exposes everything that mutates state — createEntity, patchEntity, deleteEntity, extendEntity, changeOwnership and executeBatch — alongside the viem actions those need, such as getBlockNumber, readContract and waitForTransactionReceipt. It does not have the Arkiv read actions (getEntity, query, select, watchEntityEvents, predictEntityKeys); read through a Public Client from createPublicClient for those.

transport extends Transport

chain extends Chain | undefined = undefined

accountOrAddress extends `0x${string}` | Account | undefined = undefined

rpcSchema extends RpcSchema | undefined = ArkivRpcSchema

Configuration object for the wallet client (chain, transport, account, etc.)

An Arkiv Wallet Client. WalletArkivClient

changeOwnership: (data, txParams?) => Promise<ChangeOwnershipReturnType>

Hands the entity with the given key to a new owner.

  • JSON-RPC Methods: eth_sendRawTransaction

ChangeOwnershipParameters

The ownership change parameters

TxParams

Optional transaction parameters

Promise<ChangeOwnershipReturnType>

The entity’s key and the transaction hash. ChangeOwnershipReturnType

createEntity: <S>(schema, values, options, txParams?) => Promise<CreateEntityReturnType>

Creates a new entity through a schema: each column becomes an attribute, written with the type and indexed flag the schema declares.

  • JSON-RPC Methods: eth_sendRawTransaction

S extends Schema<Columns>

S

The schema the entity is written through, built with defineSchema.

{ [K in string | number | symbol]: ({ readonly [K in string | number | symbol]: ColumnInput<ColumnsOf<S>[K][“type”]> } & { readonly [K in string | number | symbol]?: ColumnInput<ColumnsOf<(…)>[K][“type”]> })[K] }

The entity’s values, keyed by column. Required columns must be given; defaulted ones left out are written with their default. CreateEntityValues

CreateEntityOptions

The entity’s lifetime, plus its flags and salt. CreateEntityOptions

TxParams

Optional transaction parameters

Promise<CreateEntityReturnType>

The new entity’s key, the transaction hash, and the block it expires at, as the engine recorded it. CreateEntityReturnType

If the expiry exceeds a protocol bound or would leave the entity dead on arrival.

If the values do not fit the schema.

If a value does not fit its type.

If the bytes values add up to more than MAX_ENTITY_BYTES.

If the transaction fails or reverts.

import { createWalletClient, ExpirationTime } from "@arkiv-network/sdk"
import { addr, bytes, dec, defineSchema, str } from "@arkiv-network/sdk/schema"
import { rabdi } from "@arkiv-network/sdk/chains"
import { http } from "viem"
import { privateKeyToAccount } from "viem/accounts"
const Posts = defineSchema("posts", {
author: addr().indexed(),
category: str().indexed(),
score: dec().indexed(),
title: str(),
body: bytes(),
thumbnail: bytes().optional(),
mimeType: str().default("text/markdown"),
})
const client = createWalletClient({
account: privateKeyToAccount("0x..."),
chain: rabdi({ accessKey: "..." }),
transport: http(),
})
const { entityKey, txHash, expiresAt } = await client.createEntity(
Posts,
{
author: addr(client.account.address),
category: "docs",
score: dec("4.1"),
title: "Cells, not entities",
body: new TextEncoder().encode("# Hello"),
},
{ expiration: ExpirationTime.fromDays(30) },
)

deleteEntity: (data, txParams?) => Promise<DeleteEntityReturnType>

Deletes the entity with the given key.

  • JSON-RPC Methods: eth_sendRawTransaction

DeleteEntityParameters

The entity deletion parameters

TxParams

Optional transaction parameters

Promise<DeleteEntityReturnType>

The deleted entity’s key and the transaction hash. DeleteEntityReturnType

import { createWalletClient } from "@arkiv-network/sdk"
import { rabdi } from "@arkiv-network/sdk/chains"
import { http } from "viem"
import { privateKeyToAccount } from "viem/accounts"
const client = createWalletClient({
account: privateKeyToAccount("0x..."),
chain: rabdi({ accessKey: "..." }),
transport: http(),
})
// entityKey is the bytes32 key returned by createEntity.
const { txHash } = await client.deleteEntity({ entityKey })

executeBatch: <TCreates, TPatches>(data, txParams?) => Promise<ExecuteBatchReturnType>

Applies a batch of entity operations — creates, patches, deletes, extensions and ownership transfers — in one transaction.

  • JSON-RPC Methods: eth_sendRawTransaction

Every operation lands in one transaction, so the whole batch applies or none of it does. At least one operation is required. Each create and patch names its own schema and is typed by it, so one batch can write entities of several schemas.

TCreates extends readonly Schema<Columns>[] = []

TPatches extends readonly Schema<Columns>[] = []

ExecuteBatchParameters<TCreates, TPatches>

The batch parameters (creates, patches, deletes, extensions, ownershipChanges)

TxParams

Optional transaction parameters

Promise<ExecuteBatchReturnType>

The transaction hash, plus the keys touched by each kind of operation. ExecuteBatchReturnType

If the batch has no operations.

If an expiry exceeds a protocol bound or would leave the entity dead on arrival.

If a create’s or patch’s values do not fit its schema.

If a value does not fit its type.

If a patch has nothing to apply.

If a patch names a column in both set and unset.

If the bytes values of one create or patch add up to more than MAX_ENTITY_BYTES.

If the transaction fails or reverts.

import { createWalletClient, ExpirationTime } from "@arkiv-network/sdk"
import { dec } from "@arkiv-network/sdk/schema"
import { rabdi } from "@arkiv-network/sdk/chains"
import { http } from "viem"
import { privateKeyToAccount } from "viem/accounts"
const client = createWalletClient({
account: privateKeyToAccount("0x..."),
chain: rabdi({ accessKey: "..." }),
transport: http(),
})
// Posts is the schema from the createEntity example.
const { txHash, createdEntities } = await client.executeBatch({
creates: [{
schema: Posts,
values: { author, category: "docs", score: dec("4.1"), title: "Hi", body: new Uint8Array() },
expiration: ExpirationTime.fromDays(30),
}],
patches: [{ schema: Posts, entityKey: keyToRevise, set: { category: "archive" } }],
deletes: [{ entityKey: staleKey }],
extensions: [{
entityKey: keyToKeepAlive,
expiration: ExpirationTime.atBlock(1_200_000n),
}],
ownershipChanges: [{ entityKey: keyToHandOver, newOwner }],
})

extendEntity: (data, txParams?) => Promise<ExtendEntityReturnType>

Sets a new expiry on the entity with the given key.

The new lifetime is resolved the same way a create’s is: a duration counts from now rather than adding to what the entity has left, and atBlock / atDate pin an absolute deadline. The engine rejects an extension that would move the expiry earlier; one that resolves to the current expiry changes nothing.

  • JSON-RPC Methods: eth_sendRawTransaction

ExtendEntityParameters

The entity key and its new lifetime

TxParams

Optional transaction parameters

Promise<ExtendEntityReturnType>

The entity’s key, the transaction hash, and the block it now expires at, as the engine recorded it. ExtendEntityReturnType

If the expiry is malformed, exceeds a protocol bound, or would leave the entity dead on arrival.

import { createWalletClient, ExpirationTime } from "@arkiv-network/sdk"
import { rabdi } from "@arkiv-network/sdk/chains"
import { http } from "viem"
import { privateKeyToAccount } from "viem/accounts"
const client = createWalletClient({
account: privateKeyToAccount("0x..."),
chain: rabdi({ accessKey: "..." }),
transport: http(),
})
const { txHash, expiresAt } = await client.extendEntity({
entityKey,
expiration: ExpirationTime.fromDays(30),
})

patchEntity: <S>(schema, entityKey, changes, txParams?) => Promise<PatchEntityReturnType>

Patches the entity with the given key through a schema: sets some columns, unsets optional ones, and leaves everything it does not name alone.

  • JSON-RPC Methods: eth_sendRawTransaction

S extends Schema<Columns>

S

The schema the changes are typed by.

`0x${string}`

The entity to patch.

PatchEntityChanges<S>

The columns to set and the optional columns to unset. PatchEntityChanges

TxParams

Optional transaction parameters

Promise<PatchEntityReturnType>

The patched entity’s key and the transaction hash. PatchEntityReturnType

If the patch has nothing to apply.

If a name appears in both set and unset.

If the changes do not fit the schema.

If a value does not fit its type.

If the bytes values in set add up to more than MAX_ENTITY_BYTES.

If the transaction fails or reverts.

// Posts is the schema from the createEntity example.
// One column changes, an optional one goes away.
const { txHash } = await client.patchEntity(Posts, entityKey, {
set: { score: dec("4.5") },
unset: ["thumbnail"],
})
import { createWalletClient } from "@arkiv-network/sdk"
import { rabdi } from "@arkiv-network/sdk/chains"
import { http } from "viem"
import { privateKeyToAccount } from "viem/accounts"
const client = createWalletClient({
chain: rabdi({ accessKey: "..." }),
transport: http(),
account: privateKeyToAccount("0x..."),
})