arkiv-first-write

Files (3)

• SKILL.md
• estimate.md · references/
• testing.md · references/

SKILL.md (first lines)

# First Arkiv write

Target **SDK 1.0.0, Rabdi, chain 7794095 (`0x76edaf`)**. Inspect the application's manifest, lockfile and installed declarations before giving executable SDK code. If evidence is unavailable, obtain it first. Read write-safety before bulk work or an uncertain submission.

## Prepare inputs and authorization

Use the app's package manager and explain an SDK upgrade before doing it. The SDK requires viem as a peer; do not force peer requirements. Get a free RPC key at [Hub access keys](https://hub.arkiv.network/access-keys) and fund a dedicated development EOA through the [Hub faucet](https://hub.arkiv.network/faucet). Never request a private key in chat. Keep locally held signing keys in the server's secret store.

Configure `rabdi({ accessKey })` and `http()` from viem. The SDK places the encoded access key in the URL path. Missing or non-string keys raise `MissingAccessKeyError`; an explicitly empty key opts into a heavily limited endpoint that can return HTTP 429. Keep operator keys server-side, sanitize transport errors and never expose keyed URLs in logs. Browser wallets use the RPC configured by their user.

Announce network, signer, entity and spend scope before broadcasting. Verify RPC chain ID and signer balance; compare an unsigned exact gas estimate plus current fee cap and margin with both available funds and the approved budget. An access key does not pay gas or authenticate app users. SDK 1.0.0 has no public create-estimator method: use [the guarded estimator](references/estimate.md), which blocks signing and broadcast.

## Define and create a note

This module exports helpers and performs no write on import. The caller supplies an authorized wallet, matching reader and explicit retention choice. A `recordIntent` callback must durably register this operation before entry; for process-crash recovery use [the importer](../arkiv-write-safety/references/resumable-import.md), which also captures signed bytes before forwarding.

```typescript
import { createPublicClient, createWalletClient, ExpirationTime, type Expiry, type TxParams } from '@arkiv-network/sdk';
import { defineSchema, str, bytes, u64 } from '@arkiv-network/sdk/schema';
import { eq } from '@arkiv-network/sdk/query';
import { rabdi } from '@arkiv-network/sdk/chains';
import { http, type LocalAccount } from 'viem';
import { getGasPrice } from 'viem/actions';

// Diagnostics contain only fixed messages and validated local transaction identifiers.
type SafeDetails = { txHash?: string; entityKey?: string; expiresAt?: bigint };
const safeErrors = new WeakMap<object, { message: string; details: SafeDetails }>();
function safeError(message = 'Arkiv operation failed', details: SafeDetails = {}): Error & SafeDetails {
  const allowed: SafeDetails = {};
  for (const field of ['txHash', 'entityKey'] as const) {
    const value = details[field];
    if (typeof value === 'string' && /^0x[0-9a-fA-F]{64}$/.test(value)) allowed[field] = value;
  }
  if (typeof details.expiresAt === 'bigint' && details.expiresAt >= 0n && details.expiresAt < 2n ** 64n) allowed.expiresAt = details.expiresAt;
  const result = Object.assign(new Error(message), allowed);
  safeErrors.set(result, { message, details: { ...allowed } });
  return result;
}
function sanitizedFailure(error: unknown, fallback = 'Arkiv request failed; reconcile any admitted write before retrying'): Error & SafeDetails {
  const own = error !== null && typeof error === 'object' ? safeErrors.get(error) : undefined;
  if (own) return safeError(own.message, own.details);
  // Preserve this exact cross-recipe preflight verdict, never any attached diagnostics.
  try { if (error instanceof Error && error.message === 'Unsigned preparation/estimate failed') return safeError('Unsigned preparation/estimate failed'); } catch {}
  return safeError(fallback);
}



export const Notes = defineSchema('example_first_note', {
  seed_id: str().indexed(), created_at: u64(), body: bytes(),
  media_type: str().default('application/json'),
});
export function clients(account: LocalAccount, accessKey: string) {
  try {
    const chain = rabdi({ accessKey });
    const transport = http(undefined, { retryCount: 0, timeout: 10000,
      fetchOptions: { cache: 'no-store', redirect: 'error' } });
    return { reader: createPublicClient({ chain, transport, cacheTime: 0 }),
      wallet: createWalletClient({ account, chain, transport, cacheTime: 0 }) };
  } catch (error) {
    throw sanitizedFailure(error);
  }
}
export function firstNoteParameters(expiration: Expiry = ExpirationTime.fromDays(1)) {
  return { schema: Notes, values: { seed_id: 'welcome_v1', created_at: u64(Date.now()),
    body: new TextEncoder().encode(JSON.stringify({ text: 'Hello, Arkiv' })) },
    expiration, flags: { readonly: true, permissionlessExtension: false } };
}
type Clients = ReturnType<typeof clients>;
type Wallet = ReturnType<typeof createWalletClient>;
type EstimateLatest = (prepare: (unsigned: Wallet) => Promise<unknown>) => Promise<bigint>;
export async function rabdiTxParams(reader: Clients['reader'], address: LocalAccount['address'],
  approvedMaximumCost: bigint, estimate: bigint, operations = 1): Promise<TxParams> {
  try {
    if (estimate <= 0n || !Number.isSafeInteger(operations) || operations < 1) throw safeError('Valid unsigned estimate and operation count required');
    const floor = 1000000n + 400000n * BigInt(operations - 1);
    const gas = floor > 2n * estimate ? floor : 2n * estimate;
    const block = await reader.getBlock({ blockTag: 'latest' });
    if (typeof block.gasLimit !== 'bigint' || block.gasLimit <= 0n) throw safeError('Latest block gas limit required');
    if (gas > block.gasLimit / 2n) throw safeError('Gas exceeds half the latest block limit; split unprepared work');
    const latest = await reader.getTransactionCount({ address, blockTag: 'latest' });
    if (await reader.getTransactionCount({ address, blockTag: 'pending' }) !== latest) throw safeError('Reconcile pending nonce first');
    const gasPrice = await getGasPrice(reader);
    if (gas * gasPrice > approvedMaximumCost || gas * gasPrice > await reader.getBalance({ address })) throw safeError('Gas cap exceeds budget/balance');
    return await { nonce: latest, gas, gasPrice };
  } catch (error) {
    throw sanitizedFailure(error);
  }
}
export async function ensureFirstNote({ reader, wallet }: Clients,
  recordIntent: (txParams: TxParams) => Promise<void>, expiration: Expiry, approvedMaximumCost: bigint,
  estimateLatest: EstimateLatest) {
  try {
    if (await reader.getChainId() !== 7794095 || wallet.chain?.id !== 7794095) throw safeError('Wrong chain');
    const prior = await reader.select({ $key: true, $creator: true, $creationFlags: true, body: true, media_type: true })
      .from(Notes, { onMismatch: 'throw' }).createdBy(wallet.account.address)
      .where(eq('seed_id', 'welcome_v1')).limit(2).fetch();
    if (prior.entities.length > 1) throw safeError('Duplicate seed; reconcile');
    const expected = new TextEncoder().encode(JSON.stringify({ text: 'Hello, Arkiv' }));
    const existing = prior.entities[0];
    if (existing) {
      const expectedHex = '0x' + Array.from(expected, b => b.toString(16).padStart(2, '0')).join('');
      if (!existing.$creationFlags.readonly || existing.$creationFlags.permissionlessExtension ||
        existing.media_type.value !== 'application/json' || existing.body.value !== expectedHex) throw safeError('Seed differs; reconcile');
      return await { entityKey: existing.$key, reused: true as const };
    }
    // Precondition: exclusive writer, sufficient funding, successful unsigned estimate,
    // and no unresolved earlier seed attempt in the durable operation registry.
    const input = { ...firstNoteParameters(expiration), salt: 1n };
    const options = { expiration: input.expiration, flags: input.flags, salt: input.salt };
    const estimate = await estimateLatest(unsigned => unsigned.createEntity(input.schema, input.values, options));
    const txParams = await rabdiTxParams(reader, wallet.account.address, approvedMaximumCost, estimate);
    await recordIntent(txParams);
    const result = await wallet.createEntity(input.schema, input.values,
      options, txParams);
    // Persist returned hash/key immediately in the caller's durable writer.
    try {
      const receipt = await reader.getTransactionReceipt({ hash: result.txHash });
      const entity = await reader.getEntity(result.entityKey, Notes);

From Arkiv-Network/skills, MIT.

More from Arkiv-Network/skills