Sessions and identity

await fourBtd.identity.create({
  characterId: mira.id,
  wallet: 'local-wallet',
});

const session = await fourBtd.sessions.start({
  characterId: mira.id,
  hydrate: true,
});

const scoped = fourBtd.withContext({
  sessionId: session.id,
  worldId: 'forest',
});

await scoped.events.capture({
  characterId: mira.id,
  type: 'quest',
  content: 'Reached the lost city.',
  importance: 1,
});

const ended = await scoped.sessions.end(session.id, {
  checkpoint: true,
});

if (ended.checkpoint) {
  const verification = await fourBtd.identity.verify({
    checkpointId: ended.checkpoint.id,
  });
}

const hydrated = await fourBtd.sync(mira, {
  checkpoint: true,
});

Run the local identity example using the local client from the quickstart.

start can optionally hydrate the session with character, memory, relationship, inventory, and achievement context.

end creates an extractive summary by joining events with importance >= 0.5 in capture order. Set summarize: false to omit the summary. Repeated calls to end return the already-ended session. Checkpointing requires an existing identity.

State Root

Each local mutation recomputes the character stateRoot using SHA-256 over canonical JSON containing:

• Character, with its root set to null

• All events

• All memories, including forgotten entries

• Relationships

• Inventory

• Achievements

Records are included in stored order.

The identity stateRoot represents the last checkpointed root. Sessions and identity records are not included in the state root.

The schema version starts at 4btd.character/v1.

Checkpoints

Checkpoints retain:

• Wallet

• Public key

• Network

• Portability

• Transaction signature

• Slot

• Confirmation state

• UTC timestamps

The local adapter automatically records checkpoints and verifies exact records against its own in-process registry. Keep the same adapter or transport across sessions.

Local verification provides offline integrity checking. It is not cryptographic proof of wallet ownership.

Solana verification and wallet delegation

import {
  FourBTDClient,
  InMemoryTransport,
  SolanaIdentityAdapter,
  type CheckpointSigner,
} from '@fourbtd/sdk';

// Your wallet integration implements this interface:
// construct, sign, and submit a transaction containing
// the exact supplied memo, then await finalization.
async function checkpointOnSolana(wallet: string, signer: CheckpointSigner) {
  const adapter = new SolanaIdentityAdapter({
    network: 'solana-devnet',
    rpcUrl: 'https://api.devnet.solana.com',
    signer,
  });

  const sdk = new FourBTDClient({
    network: 'solana-devnet',
    transport: new InMemoryTransport({
      identityAdapter: adapter,
    }),
  });

  const character = await sdk.characters.create({
    name: 'Mira',
    owner: 'player-one',
  });

  await sdk.identity.create({
    characterId: character.id,
    wallet,
  });

  const checkpoint = await sdk.identity.checkpoint({
    characterId: character.id,
  });

  const published = await sdk.identity.publish({
    checkpointId: checkpoint.id,
  });

  return sdk.identity.verify({
    checkpointId: published.id,
  });
}

The signer exposes:

publish(
  checkpoint,
  memo,
  signal?,
): Promise<{
  signature: string;
  slot: number;
}>;

Signer implementations must deduplicate submissions by checkpoint ID. The SDK does not hold private keys or construct wallet transactions.

Without a signer, the Solana adapter still validates keys and can verify supplied checkpoint records directly:

await adapter.verify(checkpoint);

Solana Verification

Verification uses Solana's getTransaction RPC with:

• jsonParsed encoding

• finalized commitment

• Transaction version 0 support

Verification checks:

• 32-byte base58 public keys

• 64-byte base58 transaction signatures

• Successful transaction metadata

• Exact transaction slot and signature

• Wallet signer participation

• Exact checkpointMemo stored through the SPL Memo program

The SPL Memo program is:

MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr

The checkpoint memo binds the schema, character, checkpoint, network, wallet, public key, and state root.

The RPC URL must be trusted and point to the configured Solana cluster. Confirmation is never inferred from a caller-supplied signature alone.

create records a claimed identity. Successful publication and verification establish its wallet signature.

Portability is descriptive metadata, not an interoperability guarantee.