P0.4: Canonical Agent SDK#7
Merged
Merged
Conversation
Introduces kernel-sdk crate providing the canonical interface for zkVM agent development. ## kernel-sdk (new crate) - AgentContext: Execution context with version checking, snapshot helpers - Action constructors: echo, open_position, close_position, adjust_position, swap - Payload decode helpers with structural validation - Math module: checked/saturating arithmetic, basis points, drawdown calculations - Bytes module: fixed-offset and cursor-style readers/writers - Prelude with common exports (Vec but NOT vec! macro to discourage unbounded alloc) - Reference echo_agent example with comprehensive tests ## kernel-core hardening - no_std support with extern crate alloc - Codec refactor: encode_into/encoded_len trait methods to avoid per-action allocation - Fixed get_var_bytes offset rewind footgun, uses checked_add throughout - Version validation in encode_into (prevents encoding invalid structures) - MAX_AGENT_OUTPUT_BYTES enforcement on encode/decode - sha256() canonical helper with thin wrapper commitment functions - debug_assert checks for encoded_len/encode_into consistency ## Documentation - spec/sdk.md: Complete SDK specification (690 lines) - docs/P0.4_DOCUMENTATION.md: Comprehensive usage guide (1117 lines) ## Feature hygiene - kernel-sdk: default-features = false, no_std - kernel-core: default-features = false for sha2, std feature for host tooling - kernel-guest: default-features = false for kernel-core - host-tests: features = ["std"] for kernel-core
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduces the
kernel-sdkcrate providing the canonical interface for zkVM agent development, along with significant hardening tokernel-core.kernel-sdk (new crate)
AgentContext: Execution context with version checking, snapshot helpersecho,open_position,close_position,adjust_position,swapVecbut NOTvec!macro to discourage unbounded allocations)echo_agentexample with comprehensive testskernel-core hardening
no_stdsupport withextern crate allocencode_into/encoded_lentrait methods to avoid per-action allocationget_var_bytesoffset rewind footgun, useschecked_addthroughoutencode_into(prevents encoding invalid structures)MAX_AGENT_OUTPUT_BYTESenforcement on encode/decodesha256()canonical helper with thin wrapper commitment functionsdebug_assertchecks forencoded_len/encode_intoconsistencyDocumentation
spec/sdk.md: Complete SDK specification (690 lines)docs/P0.4_DOCUMENTATION.md: Comprehensive usage guide (1117 lines)Feature hygiene
default-features = false,no_stddefault-features = falsefor sha2,stdfeature for host toolingdefault-features = falsefor kernel-corefeatures = ["std"]for kernel-coreTest plan
cargo test- All 159 tests passcargo build- No warnings