arkiv-entity-lifecycle

Files (2)

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

SKILL.md (first lines)

# Arkiv entity lifecycle

Use the installed SDK declarations and Tiramisu behavior. Writes use the native entity operation address `0x4400000000000000000000000000000000000044`; this does not enable user-deployed contracts.

## Choose the operation

- Use this skill for flags, patching, ownership transfer, replacement, deletion, and relationships between new keys.
- Use `arkiv-entity-expiration` for renewal targets and expiration monitoring, `arkiv-write-safety` for signer queues and uncertain receipts, and `arkiv-query` for paginated reads.
- Run the write examples only within the user's authorized scope. A read or estimate does not authorize deleting an existing entity or spending GLM.

## Flags and permissions

Create uses `flags: { readonly, permissionlessExtension }`. Both default to `false` and are immutable: patching, extending, or transferring cannot change them.

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

These permissions apply to live entities. Choose a later deadline to add lifetime; transfers to the current owner or zero address fail. A previous owner loses owner-only rights after transfer. A readonly entity can still be transferred, extended, or deleted by its owner.

To add N blocks, target `ExpirationTime.atBlock(current.expiresAt + N)`. `fromHours(1)` means one hour from inclusion, not one additional hour on the current deadline; see `arkiv-entity-expiration`.

For a typo in readonly content, create a corrected entity with a new key and update references. Verify the replacement and preserve the old-to-new mapping and creation provenance. **A correction never authorizes deletion of the original. Retain the original unless the user separately authorizes its removal.** Authorization to change references also needs its own operation and spending scope. Readonly refers to payload and attributes, not the entity's entire lifecycle.

Ownership transfer uses `wallet.changeOwnership({ entityKey, newOwner })`, authorized by the current owner to a different, nonzero address. After confirmation, inspect `owner`, immutable `creator` and creation flags with `reader.getEntity(entityKey)`. Explain the transfer operation even when diagnosing a completed transfer, but never replay it just to verify: later head reads and the confirmed transaction are different observations. The current owner may patch mutable content; the creator field identifies the creating wallet and cannot prove authorship of a later replacement payload.

Permissionless extension lets others pay to keep an entity alive. It grants no patch, transfer, or delete permission, and another party can postpone expiration the owner wanted. Neither expiration nor readonly is a privacy control; plaintext data is public.

## Ownership, creator, and patching

- `$owner` is the current owner. `$creator` is the creating wallet and never changes. After transfer, a new owner can rewrite mutable content while the creator still names the original wallet. Creator filtering does not prove who authored the current payload.
- Patch `set` writes only named attributes; `unset` removes named attributes. Omitting payload or content type preserves it; an empty payload explicitly replaces it with empty bytes. Unsetting an absent attribute is allowed.
- Patch cannot change the key, owner, flags, or expiration. Use `changeOwnership` or `extendEntity` for those fields.
- Patch has no compare-and-set condition: concurrent owner writes are last-writer-wins. Only the current owner can patch; use an application writer queue or an explicit conflict policy.
- Each patch has at most 32 mutation cells: distinct `set` names + distinct `unset` names + one for a supplied payload + one for a supplied content type. A name cannot appear in both `set` and `unset`. Create reserves two cells, leaving 30 user attributes. Use snake_case names and lowercase MIME types without parameters.
- Separately, the observed Tiramisu engine caps the resulting entity at **32 user attributes**, excluding payload/content type. Count the union of retained and `set` names after removing `unset` names; replacing an existing name adds no slot. Only a mutable entity can grow from 30 to 31–32 by patching. Splitting writes cannot fit a 33rd attribute; remove an attribute or explicitly revise the payload/schema instead.

## Worked operations

This module exports functions; it performs no writes on import. The caller supplies an explicitly connected wallet and a reader on the same Tiramisu network.

```typescript
import {
  createWalletClient, createPublicClient, ExpirationTime, jsonToPayload,
  NO_SALT, type AttributeInputs, type Expiry,
} from "@arkiv-network/sdk"
import { key, u64 } from "@arkiv-network/sdk/attr"
import { isAddressEqual, zeroAddress, type Address, type Hex } from "viem"

type Wallet = ReturnType<typeof createWalletClient>
type Reader = ReturnType<typeof createPublicClient>

export async function publishSnapshot(
  wallet: Wallet, communityRenewal = false, expires: Expiry = ExpirationTime.fromDays(30),
) {
  return wallet.createEntity({
    payload: jsonToPayload({ title: "Published note", body: "Example body" }),
    contentType: "application/json",
    attributes: {
      project: "example_notes", entity_type: "note", created_at: u64(Date.now()),
    },
    expires,
    flags: { readonly: true, permissionlessExtension: communityRenewal },
  })
}

export async function replaceReadonlyNote(
  reader: Reader, wallet: Wallet, oldKey: Hex, title: string, expires: Expiry,
) {
  const old = await reader.getEntity(oldKey)
  if (!old.creationFlags.readonly) throw new Error("Expected a readonly note")
  if (!wallet.account || !isAddressEqual(wallet.account.address, old.owner)) {
    throw new Error("The connected wallet must own the note")
  }
  if (!isAddressEqual(old.creator, wallet.account.address)) {
    throw new Error("Only replace a note created by this publisher")
  }
  if (old.contentType !== "application/json") {
    throw new Error("Expected application/json")
  }
  const note: unknown = old.toJson()
  if (typeof note !== "object" || note === null ||
      !("body" in note) || typeof note.body !== "string") {
    throw new Error("Invalid note payload")
  }
  const attributes: AttributeInputs = Object.fromEntries(
    Object.entries(old.attributes).map(([name, value]) => {
      if (value.type === "bytes") throw new Error("Unexpected system-only attribute")
      return [name, value] as const
    }),
  )
  if (Object.keys(attributes).length > 30) {
    throw new Error("A readonly replacement must fit 30 user attributes; choose an explicit revised schema")
  }
  const created = await wallet.createEntity({
    payload: jsonToPayload({ title, body: note.body }),
    contentType: "application/json", attributes, expires,
    flags: {
      readonly: true,
      permissionlessExtension: old.creationFlags.permissionlessExtension,
    },
  })
  return { ...created, replaces: oldKey, previousCreator: old.creator }
}

export async function patchDraft(wallet: Wallet, entityKey: Hex) {
  return wallet.patchEntity({
    entityKey,
    set: { status: "published", updated_at: u64(Date.now()) },
    unset: ["draft_reason"],
  })
}

export async function transferAndInspect(
  reader: Reader, wallet: Wallet, entityKey: Hex, newOwner: Address,
) {

From Arkiv-Network/skills, MIT.

More from Arkiv-Network/skills