Receipt Lineage & Buyer Packets
Look up the five artifacts a buyer packet binds and the state a hash-only verifier assigns to each review.
On this page
To check one cross-organization invocation, a buyer reads a packet that binds the artifacts explaining it by digest, including the receipt lineage statement, the cross-kernel continuation, the admission report, the bilateral invocation, and the DSSE envelope over that invocation.
chio federation treaty verify-packet checks those bindings from five JSON inputs, each a Chio artifact with a fixed schema. It compares digests, fetches no bytes, and ends each review in one of three states.
Every binding resolves against supplied bytes
Each digest the packet declares equals the canonical digest of the artifact it names. The lineage statement names the continuation and the bilateral invocation, and the admission report's verified evidence carries the lineage and invocation digests. With the DSSE envelope bytes supplied, the review reaches hash_resolved and accepted is true. Refusal codes.
Synopsis
The command takes the packet and four of the artifacts it binds, and writes one report.
chio federation treaty verify-packet \
--packet packet.json --lineage-statement lineage.json \
--continuation continuation.json --admission-report admission.json \
--bilateral-invocation bilateral.json --report report.jsonTry bilateralDsseSha256, verifiedEvidence, or unresolved. Each entry has its own link.
Verification checks
The verifier checks each schema, then each cross-reference. The packet's digests equal the canonical digest of the artifact each one names. The lineage statement names the continuation and the bilateral invocation. The admission report's verified evidence carries the lineage and invocation digests.
A packet whose declared DSSE digest has no supplied envelope bytes behind it ends in unresolved with the failure code chio_attest_buyer_packet_dsse_unresolved. A packet whose binding was altered ends in rejected with chio_attest_buyer_packet_hash_mismatch. Only a review with resolved DSSE bytes reaches hash_resolved.
Verification states
| State | accepted | Meaning |
|---|---|---|
hash_resolved | true | Every binding resolved against supplied bytes |
unresolved | false | Bindings consistent; DSSE bytes not supplied |
rejected | false | A binding does not match |
Buyer attestation packet
BuyerAttestationPacket binds one invocation to every artifact a buyer reviews, by digest.
schema
The buyer attestation packet schema id.
packetId
The packet's own identifier.
buyerId
The buyer kernel id.
capabilityId
The capability the invocation ran under.
treatyScopeSha256
Digest of the treaty scope.
ladderIntersectionSha256
Digest of the ladder intersection.
crossBoundaryAdmissionReportSha256
Digest of the admission report.
continuationSha256
Digest of the cross-kernel continuation.
receiptLineageStatementSha256
Digest of the receipt lineage statement.
bilateralInvocationSha256
Binding digest of the bilateral invocation.
bilateralDsseSha256
Digest of the DSSE envelope bytes the buyer holds.
workflowReceiptSha256
Digest of the workflow receipt.
proofPackageSha256
Digest of the proof package.
verifierReportSha256
Digest of the verifier report.
budgetRefs
The budget holds the invocation charged against.
settlementClaimed
Whether the packet claims settlement occurred.
Receipt lineage statement
ReceiptLineageStatement links the local parent receipt to the remote child receipt and names what carried the call.
The originating kernel records the same link in its lineage graph. Walking forward from the local parent receipt finds the continuation, the partner kernel's child receipt, and the statement that joins them:
chio lineage query --live --seed rcpt-01e7…2b40 --direction forwardwalk forward from rcpt-01e7…2b40, depth limit 20 depth 0 rcpt-01e7…2b40 receipt kernel 4f1c…a2e9 depth 1 cont-01e7…8f12 cross_kernel_continuation kernel 4f1c…a2e9 continued from rcpt-01e7…2b40 depth 2 rcpt-02c1…9e5a receipt kernel 9b07…d31c continued from cont-01e7…8f12 depth 1 rls-01e7…77c3 receipt_lineage_statement kernel 4f1c…a2e9 signed over rcpt-01e7…2b40 4 nodes, 3 edges, walk complete
The walk shows which records exist and how they connect. The packet verifier is what checks that their digests agree.
schema
The lineage statement schema id.
statementId
The statement's identifier.
parentReceiptSha256
Digest of the local parent receipt.
childReceiptSha256
Digest of the remote child receipt.
continuationSha256
Digest of the continuation that carried the call.
bilateralInvocationSha256
Binding digest of the bilateral invocation.
evidenceClass
The evidence class the statement claims, for example verified.
sourceKernelId
The originating kernel.
targetKernelId
The executing kernel.
Cross-kernel continuation
CrossKernelContinuation carries one capability from the originating kernel to the executing kernel, for one tool, once.
schema
The continuation schema id.
continuationId
The continuation's identifier.
sourceKernelId
The originating kernel.
targetKernelId
The executing kernel.
parentReceiptSha256
Digest of the parent receipt.
parentSessionAnchorSha256
Digest of the parent session anchor.
capabilityId
The capability carried across.
actionClassId
The treaty action class.
audienceTool
The server and tool the continuation is for.
nonce
Single-use nonce.
issuedAtUnixMs
Issue time.
expiresAtUnixMs
Expiry time.
Cross-boundary admission report
CrossBoundaryAdmissionReport records how the executing kernel admitted the action class under the treaty and which evidence it verified.
schema
The admission report schema id.
treatyId
The treaty evaluated.
actionClassId
The action class admitted.
accepted
The admission verdict.
failureCode
The refusal code when the action is not accepted.
mode
The ladder mode the class resolved to.
consistencyModel
The consistency model the class requires.
coSign
The co-sign requirement.
coSignQuorum
The quorum for n_of_m co-signing.
requiredEvidence
Evidence classes the class requires.
presentEvidence
Evidence classes presented.
verifiedEvidence
One entry per item, each with evidenceClass, artifactSha256, and verified.
treatyScopeSha256
Digest of the treaty scope.
ladderIntersectionSha256
Digest of the ladder intersection.
expectedLadderIntersectionSha256
The verifier's own expected digest of the intersection.
checks
The checks that ran.
Bilateral invocation
BilateralInvocation is the record both kernels sign for one cross-organization call.
schema
The bilateral invocation schema id.
invocationId
The invocation's identifier.
treatyId
The treaty the invocation ran under.
ladderIntersectionSha256
Digest of the ladder intersection.
continuationSha256
Digest of the continuation.
lineageStatementSha256
Digest of the lineage statement.
actionClassId
The action class.
consistencyModel
The consistency model.
capabilityId
The capability.
requestSha256
Digest of the tool arguments.
outcomeSha256
Digest of the outcome.
localReceiptSha256
Digest of the local receipt.
remoteReceiptSha256
Digest of the remote receipt.
signerKernelIds
Both signer kernel ids.
Example
A destructive class such as billing.charge also needs both operators to agree on evidence requirements and co-signing. Each --evidence class=digest argument asserts that the caller already verified the corresponding artifact; the digest alone verifies no signature and executes no payment. The evidence classes and fail-closed rules on Treaties describe those requirements.
Understand the buyer packet’s verification boundary
Construct every input to the hash-only packet verifier and inspect both an unresolved cryptographic dependency and an altered-binding refusal.
Complete the project setup, then run the program from federation-guide/. The download includes every constructor and input.
cargo run --locked --bin packetconsistent hash-only packet: unresolved; DSSE bytes and trust are still required altered artifact binding: rejected wrote all five input files; no execution or settlement is claimed
The example deliberately uses declared fixture digests. Consistent references are not verified DSSE bytes. A complete buyer review requires the actual signed artifacts, trusted peer keys, and verifier context; the hash-only command cannot turn these declarations into accepted evidence.
Read the complete program 278 lines · complete file
//! Complete hash-binding example adapted from the public runtime verifier fixtures.
//! Opaque digests and declared evidence grades are illustrative, not cryptographic evidence.
#![allow(unused_imports)]
use chio_core_types::crypto::Keypair;
use chio_core_types::receipt::{
body::ChioReceipt, body::ChioReceiptBody, decision::Decision, decision::ToolCallAction,
kinds::BoundaryClass, kinds::ReceiptKind, kinds::RedactionMode, kinds::ToolOrigin,
kinds::TrustLevel, metadata::ActorRef,
};
use chio_federation::{
bilateral_dsse::sign_chio_bilateral_dsse_envelope,
bilateral_dsse::BilateralPredicateExtensions, bilateral_dsse::CapabilityLeaseRef,
bilateral_dsse::DsseEnvelope, bilateral_dsse::GovernanceReceiptRef, bilateral_dsse::HashRecord,
bilateral_dsse::PolicyEvaluationSummary, bilateral_dsse::PolicyVerdict,
bilateral_dsse::TreatyBindingRef, bilateral_dsse::PAYLOAD_TYPE_IN_TOTO,
};
use chio_runtime_core::{
bilateral_dsse_consistency_model as dsse_consistency_model, tool_args_sha256,
verify_buyer_attestation_packet, verify_buyer_attestation_review_package_with_trust,
verify_receipt_lineage_bundle, BilateralInvocation, BuyerAttestationPacket,
BuyerAttestationReviewArtifactRef, BuyerAttestationReviewPackage, BuyerAttestationReviewReport,
BuyerAttestationReviewSource, BuyerAttestationReviewTrustContext, ChioRuntimeError,
CrossBoundaryAdmissionReport, CrossBoundaryEvidenceRef, CrossKernelContinuation,
ReceiptLineageBundle, ReceiptLineageStatement, RuntimeEvidenceManifest,
RuntimeEvidenceManifestEntry, RuntimeProofRegenerationInput, RuntimeProofRegenerationReport,
RuntimeProofSourceRecord, RuntimeStepEvidence, RuntimeWorkflowRunReport,
CHIO_BILATERAL_INVOCATION_SCHEMA, CHIO_BUYER_ATTESTATION_PACKET_SCHEMA,
CHIO_BUYER_ATTESTATION_REVIEW_PACKAGE_SCHEMA, CHIO_CROSS_BOUNDARY_ADMISSION_REPORT_SCHEMA,
CHIO_CROSS_KERNEL_CONTINUATION_SCHEMA, CHIO_FEDERATION_RECEIPT_LINEAGE_BUNDLE_SCHEMA,
CHIO_FEDERATION_RECEIPT_LINEAGE_STATEMENT_SCHEMA, CHIO_RECEIPT_LINEAGE_BUNDLE_SCHEMA,
CHIO_RECEIPT_LINEAGE_STATEMENT_SCHEMA, CHIO_RUNTIME_EVIDENCE_MANIFEST_SCHEMA,
CHIO_RUNTIME_PROOF_REGENERATION_INPUT_SCHEMA, CHIO_RUNTIME_PROOF_REGENERATION_REPORT_SCHEMA,
CHIO_RUNTIME_STEP_EVIDENCE_SCHEMA, CHIO_RUNTIME_WORKFLOW_RUN_REPORT_SCHEMA,
};
use std::io;
type BuyerFixture = (
BuyerAttestationPacket,
ReceiptLineageStatement,
CrossKernelContinuation,
CrossBoundaryAdmissionReport,
BilateralInvocation,
);
fn strict_dsse_fixture_receipt(
capability_id: &str,
signer_b: &Keypair,
receipt_action: Option<ToolCallAction>,
) -> Result<ChioReceipt, Box<dyn std::error::Error>> {
strict_dsse_fixture_receipt_with_id("rcpt-treaty-dsse", capability_id, signer_b, receipt_action)
}
fn strict_dsse_fixture_receipt_with_id(
receipt_id: &str,
capability_id: &str,
signer: &Keypair,
receipt_action: Option<ToolCallAction>,
) -> Result<ChioReceipt, Box<dyn std::error::Error>> {
ChioReceipt::sign(
ChioReceiptBody {
id: receipt_id.to_string(),
timestamp: 1_800_000_010,
capability_id: capability_id.to_string(),
tool_server: "vendor-ledger".to_string(),
tool_name: "close_account".to_string(),
action: receipt_action.unwrap_or(ToolCallAction::from_parameters(serde_json::json!({
"record": "vendor-ledger-7",
"value": "closed"
}))?),
decision: Some(Decision::Allow),
receipt_kind: ReceiptKind::MediatedDecision,
boundary_class: BoundaryClass::Prevent,
observation_outcome: None,
tool_origin: ToolOrigin::CallerExecuted,
redaction_mode: RedactionMode::None,
actor_chain: vec![ActorRef {
actor_id: "agent:chio-runtime/buyer-review".to_string(),
actor_kind: Some("agent".to_string()),
}],
content_hash: "c".repeat(64),
policy_hash: "policy-live".to_string(),
evidence: Vec::new(),
metadata: None,
trust_level: TrustLevel::default(),
tenant_id: None,
kernel_key: signer.public_key(),
bbs_projection_version: None,
},
signer,
)
.map_err(Into::into)
}
fn buyer_fixture() -> Result<BuyerFixture, Box<dyn std::error::Error>> {
let default_buyer_key = Keypair::from_seed(&[1; 32]);
let default_vendor_key = Keypair::from_seed(&[2; 32]);
let default_parent_receipt = strict_dsse_fixture_receipt_with_id(
"rcpt-parent-local",
"cap-live-1",
&default_buyer_key,
None,
)?;
let default_parent_receipt_sha256 = chio_core_types::crypto::sha256_hex(
&chio_core_types::crypto::canonical_json_bytes(&default_parent_receipt)?,
);
let default_child_receipt =
strict_dsse_fixture_receipt("cap-live-1", &default_vendor_key, None)?;
let default_child_receipt_sha256 = chio_core_types::crypto::sha256_hex(
&chio_core_types::crypto::canonical_json_bytes(&default_child_receipt)?,
);
let continuation = CrossKernelContinuation {
schema: CHIO_CROSS_KERNEL_CONTINUATION_SCHEMA.to_string(),
continuation_id: "continue-1".to_string(),
source_kernel_id: "kernel.buyer".to_string(),
target_kernel_id: "kernel.vendor-b".to_string(),
parent_receipt_sha256: default_parent_receipt_sha256.clone(),
parent_session_anchor_sha256: "2".repeat(64),
capability_id: "cap-live-1".to_string(),
action_class_id: "workflow.destructive.vendor_call".to_string(),
audience_tool: "vendor-ledger.close_account".to_string(),
nonce: "nonce-1".to_string(),
issued_at_unix_ms: 1_800_000_000_000,
expires_at_unix_ms: 1_800_003_600_000,
};
let continuation_sha256 = chio_core_types::crypto::sha256_hex(
&chio_core_types::crypto::canonical_json_bytes(&continuation)?,
);
let mut lineage = ReceiptLineageStatement {
schema: CHIO_RECEIPT_LINEAGE_STATEMENT_SCHEMA.to_string(),
statement_id: "lineage-1".to_string(),
parent_receipt_sha256: default_parent_receipt_sha256,
child_receipt_sha256: default_child_receipt_sha256,
continuation_sha256,
bilateral_invocation_sha256: String::new(),
evidence_class: "verified".to_string(),
source_kernel_id: "kernel.buyer".to_string(),
target_kernel_id: "kernel.vendor-b".to_string(),
};
let mut admission = CrossBoundaryAdmissionReport {
schema: CHIO_CROSS_BOUNDARY_ADMISSION_REPORT_SCHEMA.to_string(),
treaty_id: "treaty-buyer-vendor".to_string(),
action_class_id: "workflow.destructive.vendor_call".to_string(),
accepted: true,
failure_code: None,
mode: "receipt_backed".to_string(),
consistency_model: "totally_ordered".to_string(),
co_sign: "bilateral_required".to_string(),
co_sign_quorum: None,
required_evidence: vec![
"governance_receipt".to_string(),
"bilateral_invocation".to_string(),
"receipt_lineage".to_string(),
],
present_evidence: vec![
"governance_receipt".to_string(),
"bilateral_invocation".to_string(),
"receipt_lineage".to_string(),
],
verified_evidence: vec![
CrossBoundaryEvidenceRef {
evidence_class: "governance_receipt".to_string(),
artifact_sha256: "d".repeat(64),
verified: true,
},
CrossBoundaryEvidenceRef {
evidence_class: "bilateral_invocation".to_string(),
artifact_sha256: "4".repeat(64),
verified: true,
},
CrossBoundaryEvidenceRef {
evidence_class: "bilateral_dsse".to_string(),
artifact_sha256: "4".repeat(64),
verified: true,
},
CrossBoundaryEvidenceRef {
evidence_class: "receipt_lineage".to_string(),
artifact_sha256: String::new(),
verified: true,
},
],
treaty_scope_sha256: "5".repeat(64),
ladder_intersection_sha256: "6".repeat(64),
expected_ladder_intersection_sha256: Some("6".repeat(64)),
checks: vec!["chio_treaty.required_evidence_present".to_string()],
};
let mut bilateral = BilateralInvocation {
schema: CHIO_BILATERAL_INVOCATION_SCHEMA.to_string(),
invocation_id: "invoke-1".to_string(),
treaty_id: "treaty-buyer-vendor".to_string(),
ladder_intersection_sha256: admission.ladder_intersection_sha256.clone(),
continuation_sha256: lineage.continuation_sha256.clone(),
lineage_statement_sha256: String::new(),
action_class_id: "workflow.destructive.vendor_call".to_string(),
consistency_model: "totally_ordered".to_string(),
capability_id: "cap-live-1".to_string(),
request_sha256: tool_args_sha256(&serde_json::json!({
"record": "vendor-ledger-7",
"value": "closed"
}))?,
outcome_sha256: "c".repeat(64),
local_receipt_sha256: lineage.parent_receipt_sha256.clone(),
remote_receipt_sha256: lineage.child_receipt_sha256.clone(),
signer_kernel_ids: vec!["kernel.buyer".to_string(), "kernel.vendor-b".to_string()],
};
let bilateral_invocation_sha256 =
chio_runtime_core::bilateral_invocation_binding_sha256(&bilateral)?;
lineage.bilateral_invocation_sha256 = bilateral_invocation_sha256.clone();
let lineage_hash = chio_core_types::crypto::sha256_hex(
&chio_core_types::crypto::canonical_json_bytes(&lineage)?,
);
bilateral.lineage_statement_sha256 = lineage_hash.clone();
for evidence in &mut admission.verified_evidence {
if evidence.evidence_class == "receipt_lineage" {
evidence.artifact_sha256 = lineage_hash.clone();
} else if evidence.evidence_class == "bilateral_invocation" {
evidence.artifact_sha256 = bilateral_invocation_sha256.clone();
}
}
let admission_hash = chio_core_types::crypto::sha256_hex(
&chio_core_types::crypto::canonical_json_bytes(&admission)?,
);
let packet = BuyerAttestationPacket {
schema: CHIO_BUYER_ATTESTATION_PACKET_SCHEMA.to_string(),
packet_id: "buyer-packet-1".to_string(),
buyer_id: "kernel.buyer".to_string(),
capability_id: bilateral.capability_id.clone(),
treaty_scope_sha256: admission.treaty_scope_sha256.clone(),
ladder_intersection_sha256: admission.ladder_intersection_sha256.clone(),
cross_boundary_admission_report_sha256: admission_hash,
continuation_sha256: lineage.continuation_sha256.clone(),
receipt_lineage_statement_sha256: lineage_hash,
bilateral_invocation_sha256,
bilateral_dsse_sha256: "4".repeat(64),
workflow_receipt_sha256: "8".repeat(64),
proof_package_sha256: "9".repeat(64),
verifier_report_sha256: "a".repeat(64),
budget_refs: vec!["budget.reserve:local-demo".to_string()],
settlement_claimed: false,
};
Ok((packet, lineage, continuation, admission, bilateral))
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
let (packet, lineage, continuation, admission, bilateral) = buyer_fixture()?;
std::fs::create_dir("packet-inputs")?;
for (name, value) in [
("packet", serde_json::to_value(&packet)?),
("lineage", serde_json::to_value(&lineage)?),
("continuation", serde_json::to_value(&continuation)?),
("admission", serde_json::to_value(&admission)?),
("bilateral", serde_json::to_value(&bilateral)?),
] {
std::fs::write(
format!("packet-inputs/{name}.json"),
serde_json::to_vec_pretty(&value)?,
)?;
}
let report =
verify_buyer_attestation_packet(&packet, &lineage, &continuation, &admission, &bilateral)?;
assert!(!report.accepted);
assert_eq!(report.verification_state, "unresolved");
assert_eq!(
report.failure_code.as_deref(),
Some("chio_buyer_packet_dsse_unresolved")
);
println!("consistent hash-only packet: unresolved; DSSE bytes and trust are still required");
let mut changed = packet;
changed.bilateral_invocation_sha256 = "b".repeat(64);
let denied =
verify_buyer_attestation_packet(&changed, &lineage, &continuation, &admission, &bilateral)?;
assert_eq!(
denied.failure_code.as_deref(),
Some("chio_buyer_packet_hash_mismatch")
);
println!("altered artifact binding: rejected");
println!("wrote all five input files; no execution or settlement is claimed");
Ok(())
}Open the source file. Each program asserts its expected refusals; keys, timestamps, and digests change between runs.
Verify the complete hash-only input set
chio federation treaty verify-packet \
--packet packet-inputs/packet.json --lineage-statement packet-inputs/lineage.json \
--continuation packet-inputs/continuation.json --admission-report packet-inputs/admission.json \
--bilateral-invocation packet-inputs/bilateral.json --report packet-inputs/report.jsonerror[CHIO-TRANSACTION-BUYER-REVIEW-REJECTED]: buyer attestation rejected the proof package: chio_attest_buyer_packet_dsse_unresolved help: rebuild the buyer packet with its DSSE envelope resolved, then verify the packet again code: urn:chio:error:transaction:buyer-review-rejected docs: https://chio.computer/docs/reference/errors#error-transaction-buyer-review-rejected
Exit 1 is the expected refusal. A shell running with set -e stops at this command, so run it on its own.
Full review roles
A review that resolves the DSSE binding supplies bytes for twelve roles, plus a verifier trust bundle and a verification context. The packet verifier is the hash-only half of that review.
buyer_attestation_packetreceipt_lineage_statementreceipt_lineage_bundlecross_kernel_continuationcross_boundary_admission_reportbilateral_invocationbilateral_dsse_envelopeworkflow_receiptproof_packageverifier_reportproof_regeneration_reportruntime_run_report
Source files
Field names and types are as the types in crates/kernel/chio-runtime-core/src/types.rs serialize them. The CLI report prefixes the runtime's failure codes with chio_attest_. The twelve review roles are hydrated in crates/kernel/chio-runtime-core/src/buyer/review_hydration.rs.