sbn-sdk TypeScript

TypeScript SDK for the SmartBlocks Network.

This package gives you:

• SnapChore capture / verify / chain
• native gateway reads for blocks, proof surfaces, and receipts
• event streaming over the slot transport
• an agnostic surface wrapper for origin/branch/successor flows

Which wrapper should I use?

For most client integrations, start with one of these two wrappers:

| If your frontier feels like... | Use | Why | |---|---|---| | a live stream of events over time | sbn.streams.create(...) | best for generation windows, BitBlock emission, progressive seal(), and final close() | | a native object or branch that evolves | sbn.openSurface(...) | best for origin/branch/successor flows and consistent surface metadata |

Keep sbn.snapchore separate in your mental model:

• use SnapChore when you want local-first capture / verify / seal
• use promote() only when you explicitly want to hand that local proof into SBN later
• do not treat SnapChore as the third main wrapper for normal network lifecycle work

Install

npm install sbn-sdk

Release/publish hygiene for this package is tracked in:

• docs/ops/sdk_publish_checklist.md

Example source sanity check:

npm run typecheck:examples

Run a checked example through the in-repo runner:

npm run run:example -- ./examples/ops_audit_stream_profile.ts -- --api-key <sbn_live_key> --project-id <project_uuid>

Quick start

import { SbnClient } from "sbn-sdk";

const sbn = new SbnClient({
  baseUrl: "https://api.smartblocks.network",
});

sbn.authenticateApiKey("sbn_live_abc123");

Hello World: SnapChore

This is the smallest honest SnapChore flow:

1. capture a canonical hash
2. verify it
3. seal a local SmartBlock
4. inspect the local block
5. optionally promote it into SBN later

import { SbnClient } from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });
sbn.authenticateApiKey("sbn_live_abc123");

const payload = { event: "hello_world", message: "Hello, SnapChore" };

const captured = await sbn.snapchore.capture(payload);
console.log("hash:", captured.hash);

const verified = await sbn.snapchore.verify(captured.hash, payload);
console.log("valid:", verified.valid);

const sealed = await sbn.snapchore.seal(payload, { domain: "hello.world" });
console.log("block:", sealed.id);
console.log("record:", sealed.smartblock_record_id);

const detail = await sbn.snapchore.getBlock(sealed.smartblock_record_id as string);
console.log("lineage role:", detail.lineage_identity?.surface_role);

// Optional later handoff into the SBN attestation lane
const promotion = await sbn.snapchore.promote({
  smartblockRecordId: sealed.smartblock_record_id as string,
});
console.log("promotion status:", promotion.status);

Important:

• seal() is local-first
• the block exists before any receipt exists
• promote() is the explicit SBN handoff boundary

Artifact descriptor helper

When you want to attest an external file without inventing a new semantic layer, compute the canonical artifact descriptor from exact file bytes:

import { SbnClient, artifactDescriptorFromFile } from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });
sbn.authenticateApiKey("sbn_live_abc123");

const artifact = await artifactDescriptorFromFile(
  "docs/EXACT_CLOSURE_PATENT_SUPPORTING_ARTIFACT_MAP.md",
  {
    artifactUri: "repo://docs/EXACT_CLOSURE_PATENT_SUPPORTING_ARTIFACT_MAP.md",
  },
);

const captured = await sbn.snapchore.capture({ artifact });
console.log(captured.hash);

This gives you:

• exact file-byte identity via artifact_sha256
• a stable descriptor SnapChore hash
• a descriptor you can embed into a later SmartBlock payload before attestation

Golden path: hash local file bytes -> seal local proof block

If you want the normal proof-first builder flow:

1. hash the local file bytes
2. wrap them in the standard proof payload
3. seal a local SmartBlock with moment auth

use the SnapChore convenience wrapper directly:

import { SbnClient } from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });
sbn.authenticateApiKey("sbn_live_abc123");

const sealed = await sbn.snapchore.sealArtifactFile(
  "docs/EXACT_CLOSURE_PATENT_SUPPORTING_ARTIFACT_MAP.md",
  {
    artifactUri: "repo://docs/EXACT_CLOSURE_PATENT_SUPPORTING_ARTIFACT_MAP.md",
    summary: "exact closure support map ready for review",
    subjectRef: "exact-closure-milestone",
    claim: { milestone_ref: "patent-support-map-ready" },
  },
);

console.log(sealed.snapchore_hash);
console.log(sealed.smartblock_record_id);

This is the intended SnapChore-first golden path:

• file bytes are hashed first
• the sealed block carries the artifact descriptor
• moment auth is attached by the SnapChore seal path
• promotion into SBN still stays explicit and separate

You can also inspect the result in one stable local-proof shape before any promotion:

const status = await sbn.snapchore.localProofStatus(sealed);
console.log(status.status); // sealed_local
console.log(status.snapchore_hash);
console.log(status.moment_auth.present);

And when you promote later, normalize the handoff the same way:

const promotion = await sbn.snapchore.promote({
  smartblockRecordId: sealed.smartblock_record_id as string,
  frontierId: "artifact.review",
});
const handoff = sbn.snapchore.promotionStatus(promotion, {
  localStatus: status,
});
console.log(handoff.status); // submitted | queued_for_attestation | attested

If the attested receipt should land in a specific SBN project, target it explicitly at promotion time:

const promotion = await sbn.snapchore.promoteToProject({
  smartblockRecordId: sealed.smartblock_record_id as string,
  targetProjectId: "tenant-123",
  frontierId: "artifact.review",
});
console.log(promotion.target_project_id);

And if you need to create the target SBN project first:

const result = await sbn.snapchore.createProjectAndPromote({
  projectName: "Artifact Lane",
  contactEmail: "[email protected]",
  aggregatorEndpoint: "https://agg.example.com",
  ratePlanId: "plan-sandbox",
  smartblockRecordId: sealed.smartblock_record_id as string,
  frontierId: "artifact.review",
});
console.log(result.target_project_id);
console.log((result.promotion as { promotion_status?: string }).promotion_status);

If you want one copy-paste task-oriented example for this same lane, run:

py -3 scripts/examples/snapchore_artifact_task_flow.py docs/EXACT_CLOSURE_PATENT_SUPPORTING_ARTIFACT_MAP.md --api-key <sbn_live_key> --task-ref exact-closure-milestone --target-project-id <target_sbn_project_uuid>

Canonical task -> artifact -> audit flow

For a reusable infrastructure-level proof lane, use this shape:

1. TaskBlock records task_started
2. SnapChore seals the completed artifact
3. explicit promotion yields the attested receipt anchor
4. AuditBlock records reconciled

Minimal payload convention:

• TaskBlock
  • task_ref
  • task_state
  • recommended: workflow_ref, operator_ref, subject_ref
• SnapChore proof claim
  • task_ref
  • task_state = artifact_completed
  • task_block_id
• AuditBlock
  • subject_ref
  • evidence_ref
  • reviewer_class
  • recommended: review_state, reconciliation_status, task_ref

Recommended shared task_state ladder:

• task_declared
• task_started
• task_in_progress
• artifact_expected
• artifact_completed
• task_closed

Keep reconciled on the AuditBlock, not the TaskBlock.

Default allowed transitions:

• task_declared -> task_started
• task_started -> task_in_progress
• task_started -> artifact_expected
• task_in_progress -> artifact_expected
• task_in_progress -> artifact_completed
• artifact_expected -> artifact_completed
• artifact_completed -> task_closed

Reasonable shortcuts:

• task_declared -> artifact_expected
• task_started -> artifact_completed

Builder helper imports:

import {
  validateFinanceBlockMetadata,
  validateTaskBlockMetadata,
  validateTaskStateTransition,
  validateAuditBlockMetadata,
  validateAuditReviewTransition,
} from "sbn-sdk";

validateTaskBlockMetadata(
  { task_ref: "task-42", task_state: "artifact_completed" },
  { previousState: "task_started" },
);
validateAuditBlockMetadata(
  {
    subject_ref: "task-42",
    evidence_ref: "receipt:abc123",
    reviewer_class: "ops",
    review_state: "reconciled",
  },
  { previousState: "review_in_progress" },
);
validateFinanceBlockMetadata(
  {
    lifecycle_state: "settlement_observed",
    instrument_ref: "payable-100",
    position_ref: "position-100",
    counterparty_ref: "merchant-1",
    financial_interop: {
      standard: "iso20022",
      business_domain: "payments",
    },
  },
  { previousState: "obligation_attached" },
);

TypeScript example file:

• sdk/typescript/examples/task_artifact_audit_flow.ts

Default output artifact:

• artifacts/examples/task_artifact_audit_latest.json

The shared contract for this lane lives in:

• docs/SBN_TASK_ARTIFACT_AUDIT_FLOW.md

Minimal TypeScript shape:

const taskBlock = await sbn.blocks.create({
  domain: "workflow.task",
  payload: {
    type: "TaskBlock",
    domain: "workflow.task",
    metadata: {
      task_ref: "task-42",
      task_state: "task_started",
      workflow_ref: "task_artifact_audit_flow",
      operator_ref: "agent:builder",
      subject_ref: "task-42",
    },
  },
});

const sealed = await sbn.snapchore.sealArtifactFile("artifact.md", {
  artifactUri: "file://artifact.md",
  summary: "artifact completed for task-42",
  subjectRef: "task-42",
  claim: {
    task_ref: "task-42",
    task_state: "artifact_completed",
    task_block_id: String((taskBlock.data as { id?: string } | undefined)?.id ?? ""),
  },
});

const promotion = await sbn.snapchore.promote({
  smartblockRecordId: String(sealed.smartblock_record_id ?? ""),
  frontierId: "artifact.review",
});

await sbn.blocks.create({
  domain: "audit.core",
  payload: {
    type: "AuditBlock",
    domain: "audit.core",
    metadata: {
      subject_ref: "task-42",
      evidence_ref: `receipt:${promotion.receipt_hash}`,
      reviewer_class: "ops",
      review_state: "reconciled",
      reconciliation_status: "receipt_observed",
      task_ref: "task-42",
    },
  },
});

If you want the canonical receipt linkage object for downstream app logic:

const receiptAnchor = sbn.snapchore.resolveReceiptAnchor({
  handoff,
  promotionResult: promotion,
  blockDetail,
  receiptLookup,
  targetProjectId: "your-project-id",
});
console.log(receiptAnchor.evidence_ref);

The TypeScript example now also polls queue state long enough to emit:

• proofLadder.finalStatus
• queue.latestSummary
• queue.item
• queue.observation
• queue.operatorHealth

It also makes the fast-attestation seam explicit instead of leaving it ambiguous:

• summary.queueResolution
• summary.attestedWithoutQueueItem

Interpret those fields like this:

• queue_item
  • the queue page still showed the exact promotion entry
• receipt_anchor_fallback
  • the queue page no longer showed the exact entry, but the canonical receipt anchor still resolved the attested result truthfully
• queue_entry_pending
  • promotion exists but final attestation was not yet proven during the poll window
• no_queue_entry
  • no queue id was returned, which is a seam worth inspecting

If you want the reusable cross-project smoke for operators, run:

py -3 scripts/smoke/snapchore_target_project_smoke.py --api-key <sbn_live_key> --target-project-id <target_sbn_project_uuid> --service-api-key <service_client_secret>

Raw runtime states collapse into the normalized ladder like this:

• sealed_only / local_only -> sealed_local
• promotion_requested / submitted_to_sbn -> submitted
• handoff_prepared / queued_for_attestation -> queued_for_attestation
• any result carrying receipt_hash or receipt_id -> attested

If you want the reusable post-deploy smoke for this same handoff lane, run:

py -3 scripts/smoke/snapchore_attestation_smoke.py --api-key <sbn_live_key>

It writes:

• artifacts/smoke/snapchore_attestation_latest.json

and proves the normalized ladder all the way through:

• sealed_local
• submitted / queued_for_attestation
• attested

End-to-end artifact attestation example

import { SbnClient, artifactDescriptorFromFile } from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });
sbn.authenticateApiKey("sbn_live_abc123");

const artifact = await artifactDescriptorFromFile(
  "docs/EXACT_CLOSURE_PATENT_SUPPORTING_ARTIFACT_MAP.md",
  {
    artifactUri: "repo://docs/EXACT_CLOSURE_PATENT_SUPPORTING_ARTIFACT_MAP.md",
  },
);

const block = await sbn.blocks.create({
  domain: "audit.core",
  payload: {
    type: "AuditBlock",
    domain: "audit.core",
    metadata: {
      review_state: "reconciled",
      subject_ref: "exact-closure-milestone",
      evidence_ref: "artifact:exact-closure-map",
      reviewer_class: "ops",
    },
    artifact,
    claim: {
      milestone_ref: "patent-support-map-ready",
      summary: "supporting artifact map assembled for counsel handoff",
    },
  },
});

const detail = await sbn.blocks.get(block.data.id);
const receiptHash = detail.hash ?? detail.canonical_proof_hash;

if (receiptHash) {
  const receipt = await sbn.receipts.getByHash(receiptHash, {
    projectId: "your-project-id",
  });
  console.log(receipt.items[0]?.native_receipt?.subject_ref);
}

Hello World: SBN

This is the smallest native SBN flow using the agnostic surface wrapper:

1. open an origin surface
2. emit one event
3. seal canonical local state
4. close the stream
5. inspect the resulting proof/receipt surfaces

import { SbnClient } from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });
sbn.authenticateApiKey("sbn_live_abc123");

const origin = sbn.openSurface({
  name: "hello-world",
  workerId: "hello-agent",
  surfaceFamily: "hello.world",
  surfaceId: "hello-world-001",
});

await origin.open();
await origin.emit("hello_event", {
  payload: {
    event_type: "hello_event",
    score: 1.0,
    message: "Hello, SBN",
  },
});

const seal = await origin.seal();
console.log("anchor hash:", seal.anchor_hash);

const close = await origin.close();
console.log("canonical proof hash:", close.canonical_proof_hash);
console.log("canonical view:", close.canonical_view);
console.log("provenance view:", close.provenance_view);

Event stream wrapper

Use the stream wrapper when you want progressive BitBlock emission over the existing slot transport.

Mental model:

• one open stream = one live operational window
• BitBlocks capture what happened during that window
• seal() gives you progressive proof anchors while work continues
• close() gives you the final slot-summary receipt
• explicit extra attestation is optional and separate

import { SbnClient } from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });
sbn.authenticateApiKey("sbn_live_abc123");

const stream = sbn.streams.create({
  name: "grid-rental-stream",
  workerId: "grid-agent",
  taskType: "grid.atomic_rentals",
  domain: "grid.atomic_rentals",
});

await stream.open();
await stream.emit("rental_created", {
  payload: { event_type: "rental_created", score: 1.0 },
  operationId: "tower-outbox-123",
  idempotencyKey: "sha256:stable-provider-command",
});
const seal = await stream.seal();
const close = await stream.close();
console.log(seal.operation_refs);
console.log(close.operation_id, close.idempotency_key);
console.log(close.operation_refs);

Operation identity is evidence correlation only. It does not prove that SBN executed an external side effect or that the external provider enforces the idempotency key. Verify provider receipts before reconciling an uncertain action as successful.

Finance and audit examples

Finance block

Use a FinanceBlock when the app wants to record a financial lifecycle state, not when it wants SBN to move money or settle value.

import { SbnClient } from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });
sbn.authenticateApiKey("sbn_live_abc123");

const financeBlock = await sbn.blocks.create({
  domain: "finance.core",
  payload: {
    type: "FinanceBlock",
    domain: "finance.core",
    metadata: {
      lifecycle_state: "settlement_observed",
      instrument_ref: "payable-100",
      position_ref: "position-100",
      counterparty_ref: "merchant-1",
      external_settlement_ref: "sonicpay-8841",
      observed_at: "2026-06-07T10:30:00Z",
      financial_interop: {
        standard: "iso20022",
        business_domain: "payments",
        message_family_hint: "pacs",
        message_definition_hint: "pacs.008",
      },
      compliance_tags: [
        {
          tag: "kyc_reviewed",
          status: "passed",
        },
      ],
    },
  },
});

const financeDetail = await sbn.blocks.get(financeBlock.data.id);
console.log(financeDetail.block_type); // finance
console.log(financeDetail.block_type_profile.scalar_emphasis); // muted
console.log(financeDetail.scalar_gec); // null on public read surfaces

Audit block

Use an AuditBlock when Ops, NUMA, or an SBN cadence process wants to record review or reconciliation state.

import { SbnClient } from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });
sbn.authenticateApiKey("sbn_live_abc123");

const auditBlock = await sbn.blocks.create({
  domain: "audit.core",
  payload: {
    type: "AuditBlock",
    domain: "audit.core",
    metadata: {
      review_state: "reconciled",
      subject_ref: "finance-surface-demo-1",
      evidence_ref: "receipt:abc123",
      reviewer_class: "ops",
      reconciliation_status: "reconciled",
      reviewed_at: "2026-06-07T10:45:00Z",
    },
  },
});

const auditDetail = await sbn.blocks.get(auditBlock.data.id);
console.log(auditDetail.block_type); // audit
console.log(auditDetail.block_type_profile.authority_posture);
console.log(auditDetail.block_type_profile.minimal_fields);

App-oriented slot pattern

One common app pattern is:

1. submit several labor blocks into an open slot over a work window
2. submit one finance block describing the resulting financial state transition
3. close the slot

import { SbnClient } from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });
sbn.authenticateApiKey("sbn_live_abc123");

const stream = sbn.streams.create({
  name: "delivery-window",
  workerId: "delivery-agent",
  taskType: "delivery.window",
  domain: "gig.delivery",
});

await stream.open();

for (const deliveryId of ["d1", "d2", "d3", "d4"]) {
  await sbn.blocks.submit({
    slotId: stream.slotId,
    domain: "gig.delivery",
    payload: {
      type: "LaborBlock",
      domain: "gig.delivery",
      metadata: {
        delivery_id: deliveryId,
        completion_state: "completed",
        window_ref: "delivery-window-2026-06-07",
      },
    },
  });
}

await sbn.blocks.submit({
  slotId: stream.slotId,
  domain: "finance.core",
  payload: {
    type: "FinanceBlock",
    domain: "finance.core",
    metadata: {
      lifecycle_state: "settlement_observed",
      instrument_ref: "delivery-window-2026-06-07",
      position_ref: "cashout-position-1",
      counterparty_ref: "merchant-1",
      external_settlement_ref: "sonicpay-cashout-1",
      observed_amount: 100,
      financial_interop: {
        standard: "iso20022",
        business_domain: "payments",
        message_family_hint: "pacs",
      },
    },
  },
});

const close = await stream.close();
console.log(close.canonical_proof_hash);

This keeps the contract clean:

• the app decides when the labor window is complete
• the app decides when the financial state transition was observed
• SBN attests the lifecycle and groups the resulting blocks under one slot close

Paired finance -> audit follow-up

Use this when a finance state later needs authoritative review.

import { SbnClient } from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });
sbn.authenticateApiKey("sbn_live_abc123");

const financeBlock = await sbn.blocks.create({
  domain: "finance.core",
  payload: {
    type: "FinanceBlock",
    domain: "finance.core",
    metadata: {
      lifecycle_state: "settlement_observed",
      instrument_ref: "delivery-window-2026-06-07",
      position_ref: "cashout-position-1",
      counterparty_ref: "merchant-1",
      external_settlement_ref: "sonicpay-cashout-1",
      financial_interop: {
        standard: "iso20022",
        business_domain: "payments",
        message_family_hint: "pacs",
      },
    },
  },
});

const auditBlock = await sbn.blocks.create({
  domain: "audit.core",
  payload: {
    type: "AuditBlock",
    domain: "audit.core",
    metadata: {
      review_state: "reconciled",
      subject_ref: financeBlock.data.id,
      evidence_ref: "receipt:abc123",
      reviewer_class: "ops",
      reconciliation_status: "reconciled",
    },
  },
});

console.log(auditBlock.data.id);

Receipt lookup after finance -> audit

Use this when you want to inspect the read surface produced by the finance and audit flow.

import { SbnClient } from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });
sbn.authenticateApiKey("sbn_live_abc123");

const lookup = await sbn.receipts.getByHash("receipt-hash", {
  projectId: "project-id",
});
const item = lookup.items?.[0];

console.log(item?.block_type_profile?.block_type);
console.log(item?.trust_summary?.trust_class);
console.log(item?.cdna_state?.closure_regime);
console.log(item?.mutation_summary?.decision_divergence);

First law example from the same base

law is still maturing, but this is the intended follow-up shape when a finance or audit state needs an explicit obligation or constraint record.

import { SbnClient } from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });
sbn.authenticateApiKey("sbn_live_abc123");

const lawBlock = await sbn.blocks.create({
  domain: "law.core",
  payload: {
    type: "LawBlock",
    domain: "law.core",
    metadata: {
      law_state: "bound",
      subject_ref: "finance-or-audit-subject-id",
      constraint_ref: "derivative-exercise-window-1",
      issuer_class: "compliance_service",
      obligation_code: "exercise_window_active",
      binding_scope: "derivative_position",
    },
  },
});

console.log(lawBlock.data.id);

Law lifecycle proposal

The smallest honest lifecycle for law right now is:

declared -> bound -> active -> satisfied | expired

Use it as:

• declared for a newly stated rule or obligation
• bound when attached to a subject or position
• active while in force
• satisfied when fulfilled
• expired when no longer in force

Narrative pattern: labor -> finance -> audit -> law

One clean app-level narrative is:

1. submit labor blocks for the productive window
2. submit a FinanceBlock for the observed value-state transition
3. submit an AuditBlock for reconciliation
4. submit a LawBlock for the resulting obligation or constraint

Derivative-specific example: finance -> audit -> law

import { SbnClient } from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });
sbn.authenticateApiKey("sbn_live_abc123");

const financeBlock = await sbn.blocks.create({
  domain: "finance.core",
  payload: {
    type: "FinanceBlock",
    domain: "finance.core",
    metadata: {
      lifecycle_state: "obligation_attached",
      instrument_ref: "eth-call-option-2026-q3",
      position_ref: "position-eth-call-1",
      counterparty_ref: "desk-a",
    },
  },
});

const auditBlock = await sbn.blocks.create({
  domain: "audit.core",
  payload: {
    type: "AuditBlock",
    domain: "audit.core",
    metadata: {
      review_state: "reconciled",
      subject_ref: financeBlock.data.id,
      evidence_ref: "receipt:derivative-book-1",
      reviewer_class: "ops",
      reconciliation_status: "reconciled",
    },
  },
});

const lawBlock = await sbn.blocks.create({
  domain: "law.core",
  payload: {
    type: "LawBlock",
    domain: "law.core",
    metadata: {
      law_state: "active",
      subject_ref: financeBlock.data.id,
      constraint_ref: "exercise-window-2026-q3",
      issuer_class: "compliance_service",
      obligation_code: "cash_settlement_if_exercised",
      binding_scope: "derivative_position",
      effective_at: "2026-07-01T00:00:00Z",
      expires_at: "2026-09-30T23:59:59Z",
    },
  },
});

console.log(auditBlock.data.id, lawBlock.data.id);

Shared derivative payload convention

Prefer this shared reference vocabulary across the derivative lifecycle:

• instrument_ref
• position_ref
• counterparty_ref
• constraint_ref
• evidence_ref

Recommended by type:

1. FinanceBlock
   • instrument_ref
   • position_ref
   • counterparty_ref
2. AuditBlock
   • subject_ref
   • evidence_ref
3. LawBlock
   • subject_ref
   • constraint_ref
   • effective_at
   • expires_at

Stream profile examples

Use the stream wrapper metadata lane when you want the slot transport to stamp a deterministic frontier contract and canonical block-type posture without hand-building the full contract mapping first.

In the current TypeScript SDK surface, that means:

• use sbn.streams.create(...)
• pass generationWindowMs
• set metadata.stream_profile
• emit canonical yield / burden pulses through stream.pulse(...)

labor_v1

import { SbnClient } from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });
sbn.authenticateApiKey("sbn_live_abc123");

const stream = sbn.streams.create({
  name: "delivery-window",
  workerId: "grid-worker-1",
  taskType: "gig.delivery.window",
  domain: "gig.delivery",
  generationWindowMs: 30_000,
  metadata: {
    stream_profile: "labor_v1",
    frontier_hint: "grid.atomic_rentals",
    proof_intent: "delivery_window",
  },
});

await stream.open();
await stream.pulse({
  payload: {
    action: "delivery_complete",
    event_type: "delivery_complete",
    score: 1.0,
    reinforced: true,
    actions: [{ action: "delivery_complete", score: 1.0 }],
    events: { friendly: 1 },
    state_hint: "delivery_complete",
    delivery_state: "completed",
  },
});
await stream.pulse({
  payload: {
    action: "late_delivery",
    event_type: "late_delivery",
    burden_hint: 0.35,
    score: 0.2,
    reinforced: false,
    actions: [{ action: "late_delivery", score: 0.2 }],
    events: { hostile: 1 },
    severity: "warning",
    state_hint: "late_delivery",
    delivery_state: "late",
  },
});
const seal = await stream.seal();

await stream.finalize({
  requestAttestation: true,
  attestation: {
    snap_hash: String(seal.anchor_hash ?? ""),
    frontier_id: "grid.atomic_rentals",
    metadata: { type: "LaborBlock", domain: "gig.delivery" },
  },
});

Expected posture:

• composed block resolves as labor
• public block read exposes scalarGec
• receipt and block both surface bbContributionSummary

ops_audit_v1

const auditStream = sbn.streams.create({
  name: "ops-audit-window",
  workerId: "ops-review-1",
  taskType: "ops.audit.review.window",
  domain: "audit.core",
  generationWindowMs: 30_000,
  metadata: {
    stream_profile: "ops_audit_v1",
    frontier_hint: "ops.audit.review",
    proof_intent: "scheduled_review",
  },
});

await auditStream.open();
await auditStream.pulse({
  payload: {
    action: "cadence_snapshot",
    event_type: "cadence_snapshot",
    score: 1.0,
    reinforced: true,
    actions: [{ action: "cadence_snapshot", score: 1.0 }],
    events: { neutral: 1 },
    state_hint: "cadence_snapshot",
    review_state: "cadence_snapshot",
    subject_ref: "ops.audit.review",
    evidence_ref: "frontier:ops.audit.review",
    reviewer_class: "sbn_timer",
  },
});
await auditStream.pulse({
  payload: {
    action: "review_in_progress",
    event_type: "review_in_progress",
    burden_hint: 0.5,
    score: 0.2,
    reinforced: false,
    actions: [{ action: "review_in_progress", score: 0.2 }],
    events: { hostile: 1 },
    severity: "warning",
    state_hint: "review_in_progress",
    review_state: "review_in_progress",
    subject_ref: "ops.audit.review",
    evidence_ref: "frontier:ops.audit.review:delta",
    reviewer_class: "ops",
  },
});

Expected posture:

• composed block resolves as audit
• blockTypeProfile.groupingPattern = "scheduled_or_exception_review"
• blockTypeProfile.allowedEmitters includes ops, numa, and sbn_timer

Runnable example:

• sdk/typescript/examples/ops_audit_stream_profile.ts
• default artifact: artifacts/examples/ops_audit_stream_profile_ts_latest.json
• one-command runner: npm run example:ops-audit -- --api-key <sbn_live_key> --project-id <project_uuid>
• attested variant: npm run example:ops-audit -- --api-key <sbn_live_key> --project-id <project_uuid> --attest
• default attested artifact view: compact attestedReceiptSummary + attestedReceiptLookupSummary
• raw attested receipt debug view: add --include-raw-attested-receipt

finance_state_v1

const financeStream = sbn.streams.create({
  name: "finance-state-window",
  workerId: "finance-state-1",
  taskType: "finance.state.window",
  domain: "finance.core",
  generationWindowMs: 30_000,
  metadata: {
    stream_profile: "finance_state_v1",
    frontier_hint: "finance.state.window",
    proof_intent: "financial_lifecycle_state",
  },
});

await financeStream.open();
await financeStream.pulse({
  payload: {
    action: "allocation",
    event_type: "allocation",
    score: 1.0,
    reinforced: true,
    actions: [{ action: "allocation", score: 1.0 }],
    events: { friendly: 1 },
    state_hint: "allocation",
    lifecycle_state: "allocation",
    instrument_ref: "position-1:instrument",
    position_ref: "position-1",
    counterparty_ref: "venue.alpha",
  },
});
await financeStream.pulse({
  payload: {
    action: "obligation_attached",
    event_type: "obligation_attached",
    score: 0.9,
    reinforced: true,
    actions: [{ action: "obligation_attached", score: 0.9 }],
    events: { friendly: 1 },
    state_hint: "obligation_attached",
    lifecycle_state: "obligation_attached",
    instrument_ref: "position-1:instrument",
    position_ref: "position-1",
    counterparty_ref: "venue.alpha",
    obligation_ref: "position-1:obligation",
  },
});
await financeStream.pulse({
  payload: {
    action: "settlement_observed",
    event_type: "settlement_observed",
    burden_hint: 0.25,
    score: 0.4,
    reinforced: false,
    actions: [{ action: "settlement_observed", score: 0.4 }],
    events: { hostile: 1 },
    severity: "warning",
    state_hint: "settlement_observed",
    lifecycle_state: "settlement_observed",
    instrument_ref: "position-1:instrument",
    position_ref: "position-1",
    counterparty_ref: "venue.alpha",
    settlement_ref: "position-1:settlement",
    external_system_ref: "sonicpay",
  },
});

Expected posture:

• composed block resolves as finance
• public block read mutes scalarGec
• blockTypeProfile.settlementPosture = "observe_reference_reconcile"
• blockTypeProfile.externalSystemRole = "adjacent_non_settlement"

Runnable example:

• sdk/typescript/examples/finance_state_stream_profile.ts
• default artifact: artifacts/examples/finance_state_stream_profile_ts_latest.json
• one-command runner: npm run example:finance-state -- --api-key <sbn_live_key> --project-id <project_uuid>
• attested variant: npm run example:finance-state -- --api-key <sbn_live_key> --project-id <project_uuid> --attest
• default attested artifact view: compact attestedReceiptSummary + attestedReceiptLookupSummary
• raw attested receipt debug view: add --include-raw-attested-receipt

Agnostic surface wrapper

Use the surface wrapper when you want developers to think in terms of:

• surface family
• surface id
• parent block
• branch kind

instead of hand-building wrapper metadata every time.

Origin surface

import { SbnClient } from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });
sbn.authenticateApiKey("sbn_live_abc123");

const origin = sbn.openSurface({
  name: "rental-origin",
  workerId: "grid-agent",
  surfaceFamily: "grid.atomic_rentals",
  surfaceId: "rental-001",
});

await origin.open();
await origin.emit("rental_created", {
  payload: {
    event_type: "rental_created",
    score: 1.0,
    rental_id: "rental-001",
  },
});

const rootSeal = await origin.seal();
await origin.close();

Branch surface with auto-rollup

const activeBranch = sbn.openSurface({
  name: "rental-active",
  workerId: "grid-agent",
  surfaceFamily: "grid.atomic_rentals",
  surfaceId: "rental-001.active",
  parentBlockId: rootSeal.smartblock_id ?? undefined,
  branchKind: "active_rental",
});

await activeBranch.open();
await activeBranch.emit("vehicle_checkout", {
  payload: {
    event_type: "vehicle_checkout",
    score: 0.92,
    weight: 1.0,
    rental_id: "rental-001",
  },
});

const branchSeal = await activeBranch.seal();
await activeBranch.close();

Important:

• the native scalar law stays r = Y / X, g = r / c_max
• frontier contracts declare what Y, X, and c_max mean for that ecology
• X is customizable
• timed generation windows are a strong live-telemetry default, not a universal framework rule

Default behavior:

• origin surfaces omit fractal_parent_block_id
• branch surfaces set fractal_parent_block_id
• branch surfaces default to fractal_auto_rollup=true
• surfaceFamily becomes the default taskType / domain

Mental model:

• slots stay the operational transport
• surfaces give that transport a native object identity
• origin/branch/successor structure becomes explicit
• seal() and close() still preserve the same proof-bearing lifecycle underneath

SmartBlock-native frontier contracts

When you want a builder-friendly way to define BitBlock weights, keep that contract in the SmartBlock layer and pass it into your slot/surface flow. Atlas may catalogue the same frontier later, but this helper is not Atlas-owned.

import {
  FrontierContractBuilder,
  SbnClient,
} from "sbn-sdk";

const sbn = new SbnClient({ baseUrl: "https://api.smartblocks.network" });

const contract = new FrontierContractBuilder({
  frontier: "assistant",
  gecDomain: "ai",
  appName: "assistant-demo",
})
  .archetype("stream_efficiency")
  .nativeDefaults()
  .canonicalCostProfile("ai_assistant_v1")
  .actions(["prompt_submitted", "tool_call_completed", "response_delivered"], {
    prompt_submitted: 0.25,
    tool_call_completed: 0.6,
    response_delivered: 1.0,
  })
  .events(["assistant_turn"], {
    friendly: 1.0,
    neutral: 0.0,
    hostile: -1.0,
  })
  .strategy("weighted_mean")
  .yieldRule("completed_turns", { unit: "assistant_turn" })
  .costRule("blended", {
    compositionRule: "weighted_sum_v1",
    requiredComponents: ["compute"],
    optionalComponents: ["time", "resource", "intervention", "reversal_risk"],
  })
  .cmaxRule("frontier_registry")
  .interpretation({
    entropyMode: "structural_entropy_v1",
    compressionMode: "canonical_compression_v1",
    trustMode: "provenance_and_coherence",
    reflexMode: "trajectory_delta",
  })
  .build();

const surface = sbn.openSurface({
  name: "assistant-root",
  workerId: "assistant-demo",
  surfaceFamily: "ai.assistant",
  surfaceId: "conversation-001",
  gecContract: contract,
});

Or build the same contract in one call:

const contract = sbn.defineFrontier({
  frontier: "assistant",
  gecDomain: "ai",
  frontierArchetype: "stream_efficiency",
  applyNativeDefaults: true,
  canonicalCostProfile: "ai_assistant_v1",
  actionWeightMap: { response_delivered: 1.0 },
  interactionWeightMap: { tool_call_completed: 0.6 },
  eventPolarityWeights: { friendly: 1.0, hostile: -1.0 },
  weightingStrategy: "weighted_mean",
  costCompositionRule: "weighted_sum_v1",
  costRequiredComponents: ["compute"],
  costOptionalComponents: ["time", "resource", "intervention", "reversal_risk"],
  cMaxMode: "frontier_registry",
  entropyMode: "structural_entropy_v1",
  compressionMode: "canonical_compression_v1",
});

When a live telemetry frontier uses a generation window as its base X coordinate, read that as a frontier declaration:

• X = elapsed generation window
• Y = persisted useful output inside that window

That keeps interval comparisons stable and easy to interpret. Other frontiers may instead declare another lawful extensive X basis, such as labor, compute, tokens, or capital.

You can also compose an observed burden packet against the contract directly:

import { composeCostObservation } from "sbn-sdk";

const observedCost = composeCostObservation(contract, {
  time: 2.0,
  compute: 1.5,
  intervention: 0.5,
});

console.log(observedCost.rule);   // weighted_sum_v1
console.log(observedCost.total);  // 2.875
console.log(observedCost.valid);  // true

For a generic binary approval frontier, use the public-safe fixed-burden profile:

const approvalContract = sbn.defineFrontier({
  frontier: "approval",
  gecDomain: "workflow",
  frontierArchetype: "binary_phase",
  applyNativeDefaults: true,
  canonicalCostProfile: "workflow_approval_v1",
});

cDNA mutation lineage

When your runtime needs explicit mutation or adaptation history, use the public TypeScript helpers directly.

import {
  AgentClient,
  LineageManager,
  MutationStrategy,
} from "sbn-sdk";

const agent = new AgentClient({
  baseUrl: "https://api.smartblocks.network",
  auth: {
    tokenProvider: async () => mintAgentJwt({
      subject: "watcher-agent-v3",
      scopes: ["debug.read", "receipts.read", "attest.write"],
      cdna: "watcher:performance:g2:91ac",
      ttl: 300,
    }),
  },
});

const lineage = new LineageManager();
lineage.seed("watcher-agent-v3", "watcher:performance", "0.1.0");

const proof = await lineage.checkAndMutate("watcher-agent-v3", {
  strategy: MutationStrategy.ENTROPY_YIELD,
  yieldScore: 0.31,
  entropyScore: 0.82,
  reasoning: "low yield under chaotic conditions",
});

const slot = await agent.gateway.createSlot("watcher-agent-v3", "slot.performance.monitor", {
  metadata: {
    lineage_kind: "mutation_watch",
    candidate_cdna: proof?.afterCdna,
    mutation_reason: "yield_drop_under_entropy",
  },
});

const snap = await agent.snapchore.capture({
  event_type: "performance_window",
  score: 0.41,
  metadata: {
    candidate_cdna: proof?.afterCdna,
    mutation_reason: "yield_drop_under_entropy",
  },
});

console.log(slot.id, snap.snapchore_hash);

This matches the existing core lifecycle:

• agent JWTs can carry a cdna claim
• SmartBlock creation injects c_dna
• cDNA may mutate once pre-sign during metrics computation
• lineage material is preserved in downstream BitBlock and fusion state

Native receipt and block diagnostics

Current agent/runtime reads can now expose the richer native public summaries that sit on top of the scalar GEC and cDNA mutation lane:

• semantic_cdna
• cdna_state
• trust_summary
• mutation_summary
• scalar_gec
• carrier_state

These fields are the easiest way for an agent to inspect whether a block or receipt is native-complete enough for mutation parity, trust review, or later NUMA/control-side consumption.

import { AgentClient } from "sbn-sdk";

const agent = new AgentClient({ baseUrl: "https://api.smartblocks.network" });
agent.authenticateApiKey("sbn_live_abc123");

const receipt = await agent.receipts.getByHash("receipt-hash", {
  projectId: "project-id",
});

const item = receipt.items?.[0];
console.log(item?.scalar_gec?.g);
console.log(item?.trust_summary?.trust_class);
console.log(item?.cdna_state?.closure_regime);
console.log(item?.mutation_summary?.native_shadow_decision?.proposed_action);

const block = await agent.gateway.fetchBlock("block-id");
console.log(block.semantic_cdna?.reflex_mode);
console.log(block.mutation_summary?.decision_divergence);

Read these fields in layers:

• scalar_gec and carrier_state describe the native state
• trust_summary explains native validity/coherence
• mutation_summary compares legacy emission against native shadow posture
• semantic_cdna and cdna_state expose operational genotype plus current derived regime

Lifecycle policy

Recommended default:

• seal origin surfaces locally
• seal branch surfaces locally
• keep branch receipts and rollup receipts as native local proof
• promote / attest successor surfaces by default
• reserve public attestation for canonical surfaces that matter

That means:

• branch surfaces are valid local proof objects
• successor surfaces are the normal public publication target
• not every branch pulse needs public attestation

GEC and lifecycle state

GEC should be read in two layers:

1. local descriptive metrics
2. lifecycle-relevant state only when explicitly bridged into carrier logic

So:

• local metrics.gec can be computed during branch or surface seal
• carrier_state remains the canonical continuation substrate
• widening decides whether exact local reduction was sufficient for parent trust

Native proof reads

Useful reads after seal / rollup:

const block = await sbn.gateway.fetchBlock("block-id");
const successors = await sbn.gateway.listSuccessorSurfaces("block-id");
const proofSurfaces = await sbn.gateway.listProofSurfaces("block-id");
const fractalReceipts = await sbn.gateway.listFractalReceipts("block-id");

These are the best way to inspect:

• successor surfaces
• branch receipts
• rollup receipts
• attestation receipts

without collapsing everything into one flat receipt concept.