arkiv-entity-lifecycle

Files (2)

• SKILL.md
• backup-restore.md · references/

SKILL.md (first lines)

# Arkiv entity lifecycle

Use installed SDK 1.0.0 declarations and Rabdi. Native operations target `0x4400000000000000000000000000000000000044`; this does not enable arbitrary application contracts. Run mutations only within the user's entity, signer and spending authorization. Read access does not authorize deletion.

## Flags and permissions

| readonly | permissionlessExtension | Patch | Extend | Transfer | Delete |
| --- | --- | --- | --- | --- | --- |
| false | false | Owner | Owner | Owner | Owner |
| false | true | Owner | Anyone | Owner | Owner |
| true | false | Nobody | Owner | Owner | Owner |
| true | true | Nobody | Anyone | Owner | Owner |

Both flags default false and are immutable. They apply to live entities. Readonly protects attributes, including bytes columns; owner operations can still affect availability. Permissionless extension grants no patch, transfer or deletion right, and can postpone an owner's preferred expiration.

`$owner` is current authority; `$creator` is the creating wallet. A transfer needs no recipient consent. Creator plus current owner cannot authenticate mutable values after a transfer away/edit/transfer back. Follow the [publication policy](../arkiv-security-trust/SKILL.md#trust-a-publication-not-a-namespace).

## Exact write signatures

```typescript
import { createWalletClient, createPublicClient, ExpirationTime, type Expiry, type TxParams } from '@arkiv-network/sdk';
import { defineSchema, str, bytes, u64 } from '@arkiv-network/sdk/schema';
import { isAddressEqual, zeroAddress, type Address, type Hex } 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_notes', {
  status: str().indexed(), created_at: u64(), body: bytes(),
  draft_reason: str().optional(),
});
type Wallet = ReturnType<typeof createWalletClient>;
type Reader = ReturnType<typeof createPublicClient>;
type EstimateLatest = (prepare: (unsigned: Wallet) => Promise<unknown>) => Promise<bigint>;
async function txParams(reader: Reader, wallet: Wallet, estimate: bigint): Promise<TxParams> {
  const gas = 2n * estimate > 1000000n ? 2n * estimate : 1000000n;
  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');
  if (estimate <= 0n || !wallet.account) throw safeError('Authorized account and Rabdi gas floor required');
  const address = wallet.account.address;
  const latest = await reader.getTransactionCount({ address, blockTag: 'latest' });
  if (await reader.getTransactionCount({ address, blockTag: 'pending' }) !== latest) throw safeError('Resolve pending nonce');
  return { nonce: latest, gas, gasPrice: await getGasPrice(reader) };
}
async function checked<T extends { txHash: Hex }>(reader: Reader, result: T): Promise<T> {
  const receipt = await reader.getTransactionReceipt({ hash: result.txHash });
  if (receipt.status !== 'success') throw safeError('Receipt disagrees after SDK success; reconcile without resending', { txHash: result.txHash });
  return result;
}
export async function publish(reader: Reader, wallet: Wallet, expiration: Expiry, salt: bigint, estimateLatest: EstimateLatest) {
  try {
    const values = { status: 'published', created_at: u64(Date.now()), body: new TextEncoder().encode('Public example') };
    const options = { expiration, salt, flags: { readonly: true } };
    const estimate = await estimateLatest(unsigned => unsigned.createEntity(Notes, values, options));
    return await checked(reader, await wallet.createEntity(Notes, values, options, await txParams(reader, wallet, estimate)));
  } catch (error) {
    throw sanitizedFailure(error);
  }
}
export async function patchDraft(reader: Reader, wallet: Wallet, entityKey: Hex, estimateLatest: EstimateLatest) {
  try {
    const estimate = await estimateLatest(unsigned => unsigned.patchEntity(Notes, entityKey, { set: { status: 'published' }, unset: ['draft_reason'] }));
    return await checked(reader, await wallet.patchEntity(Notes, entityKey, { set: { status: 'published' }, unset: ['draft_reason'] }, await txParams(reader, wallet, estimate)));
  } catch (error) {
    throw sanitizedFailure(error);
  }
}
export async function transferAndInspect(reader: Reader, wallet: Wallet, entityKey: Hex, newOwner: Address, estimateLatest: EstimateLatest) {
  try {
    const before = await reader.getEntity(entityKey, Notes);
    if (isAddressEqual(newOwner, zeroAddress) || isAddressEqual(newOwner, before.$owner)) throw safeError('Choose another nonzero owner');
    const estimate = await estimateLatest(unsigned => unsigned.changeOwnership({ entityKey, newOwner }));
    const transferred = await checked(reader, await wallet.changeOwnership({ entityKey, newOwner }, await txParams(reader, wallet, estimate)));
    try {
      const after = await reader.getEntity(entityKey, Notes);
      return await { ...transferred, ownerAtRead: after.$owner,
        creatorUnchanged: isAddressEqual(before.$creator, after.$creator) };
    } catch { return await { ...transferred, status: 'confirmed_read_failed' as const }; }
  } catch (error) {
    throw sanitizedFailure(error);
  }
}
export async function extend(reader: Reader, wallet: Wallet, entityKey: Hex, deadline: bigint, estimateLatest: EstimateLatest) {
  try {
    const operation = { entityKey, expiration: ExpirationTime.atBlock(deadline) };
    const estimate = await estimateLatest(unsigned => unsigned.extendEntity(operation));
    return await checked(reader, await wallet.extendEntity(operation, await txParams(reader, wallet, estimate)));
  } catch (error) {
    throw sanitizedFailure(error);
  }
}
// Only invoke when deletion of this exact entity is independently authorized.
export async function remove(reader: Reader, wallet: Wallet, entityKey: Hex, estimateLatest: EstimateLatest) {
  try {
    const estimate = await estimateLatest(unsigned => unsigned.deleteEntity({ entityKey }));
    return await checked(reader, await wallet.deleteEntity({ entityKey }, await txParams(reader, wallet, estimate)));

From Arkiv-Network/skills, MIT.

More from Arkiv-Network/skills