xian-vm-core

xian-vm-core is the Rust-side consumer of the frozen xian_vm_v1 compiler IR emitted by xian-contracting.

flowchart LR
  Source["Contract source"] --> Compiler["xian-contracting compiler"]
  Compiler --> IR["xian_vm_v1 IR"]
  IR --> Validator["Rust IR validator"]
  Validator --> VM["Native VM execution slice"]
  VM --> Host["Host storage and syscall bridge"]
  Host --> State["Deterministic state and events"]
  Fixtures["Python parity fixtures"] --> Validator
  Fixtures --> VM

Supported scope:

  • deserialize the structural JSON IR
  • validate its top-level invariants and recursive node shapes
  • instantiate validated modules and execute a direct-IR interpreter slice
  • provide one Rust-owned contract for the Python frontend to target
  • expose a minimal Python-facing native capability surface for xian-abci probing via xian_vm_core._native

Execution coverage is intentionally narrow but real:

  • local function calls and builtin calls such as len, range, str, and isinstance
  • aggregate/container helpers such as sorted, sum, min, max, all, any, reversed, and zip
  • explicit storage ops for Variable and Hash
  • foreign storage reads for ForeignVariable and ForeignHash, including function-local references with dynamic contract/variable targets
  • arbitrary-precision integer values instead of i64-only VM integers
  • fixed-precision decimal(...) construction and arithmetic
  • native datetime.datetime / datetime.timedelta values, including datetime.datetime.strptime(...), arithmetic, comparison, and common field access
  • bigint-oriented builtins needed by the shielded contracts, including int(..., base), pow(base, exp, mod), and format(value, "064x")
  • hashlib.sha3(...) and hashlib.sha256(...)
  • crypto.verify(...) and crypto.key_is_valid(...)
  • LogEvent emission
  • static-import and dynamic-import contract export calls
  • native container method calls used by contracts today, including dict.keys(), dict.values(), dict.items(), dict.get(), and the common mutable list helpers append, extend, insert, remove, and pop
  • native string helpers used by the shielded contracts, including lower(), isalnum(), startswith(...), and join(...)
  • Python-style subscript slicing for list, tuple, and str, including the value[2:] helper pattern used in the shielded contracts
  • sequence repetition for list, tuple, and str
  • host-delegated zk.* syscalls, which remain explicit runtime boundary calls instead of Rust-local protocol logic

It is a bounded execution slice, not the full executor.

The crate includes curated conformance fixtures generated from the current local harness. Those fixtures are checked from Rust so the VM can match actual contract behavior on a controlled contract subset alongside hand-written executor tests.

Metering covers both host-side data costs and VM execution:

  • storage reads, writes, transaction bytes, and return-value bytes are charged directly in the VM host path
  • execution cost is driven by an explicit xian_vm_v1 gas schedule over VM statements, expressions, calls, and loop iterations
  • module initialization is metered, so first-load authored contracts do not get free global-declaration and module-body execution
  • contract.exists(...), contract.has_export(...), contract.info(...), and related contract metadata syscalls resolve directly against the driver/IR in the native host bridge
  • authored contract storage persists __xian_ir_v1__, and the native host requires that validator-derived artifact for xian_vm_v1 execution; stored __source__ remains available for dashboards, BDS, and other inspection tooling
  • native deployment accepts cleartext source only, rejects submitted deployment_artifacts, and derives vm_ir_json through the pinned compiler before staging writes
  • native deployment requires explicit deterministic now context from the caller; the host does not fall back to local wall-clock time for submission metadata
  • the native deployment path validates the compiler-produced IR before staging writes or executing constructors
  • the Python deployment path and offline tooling keep canonical source-to-runtime recompilation in the Python artifact validator; the native path is Rust-native for bundle validation, not a Rust recompiler
  • the five-node make localnet-parallel-e2e native-authority soak passes end to end, including shielded token flows and parallel prefix-scan access patterns

That parity corpus covers:

  • storage/event flows
  • range/list/dict control-flow helpers
  • foreign storage reads
  • fixed-precision decimal semantics
  • datetime/timedelta behavior
  • bigint parsing, modular arithmetic, hex formatting, and shielded-style helper flows
  • hashing and ed25519 verification helpers
  • static-import and dynamic-import nested contract calls
  • real authored shielded contract sources for shielded-note-token and shielded-commands, including constructor-seeded state snapshots and hash-helper exports
  • real authored token, registry, game, and oracle flows across repos, including: currency.transfer(...), stable_token.burn(...), reflection_token.transfer(...), profile_registry.create_channel(...), turn_based_games.join_match(...), and oracle.price_info(...)

The intent is to keep the Xian VM implementation Rust-first for performance, while still freezing semantics in the Python compiler frontend before runtime execution work starts.

The crate ships a small PyO3/maturin surface for integration work:

  • runtime_info() / runtime_info_json()
  • supports_execution_policy(...)
  • validate_module_ir(...) / validate_module_ir_json(...)

That surface is intentionally narrow. It is there so node-side code can probe the VM runtime honestly before transaction execution is wired through the Rust engine.

The largest remaining runtime work is metering drift on the heaviest authored flows and the host-operation split between delegated calls and Rust-owned implementations. Integer width, basic authored shielded execution, and pre-call setup flows are covered by the authored parity corpus and fixture generator.

Releases

Push a vm-core-vX.Y.Z tag with matching versions in pyproject.toml and Cargo.toml after ../../scripts/validate-release.sh passes. The release workflow builds native wheels for Linux, macOS Intel/ARM and Windows, and a source distribution. PyPI Trusted Publishing uses project xian-tech-vm-core, owner xian-technology, repository xian-contracting, workflow release.yml and environment pypi-xian-vm-core.

Runtime semantics are consensus-sensitive. Validators must use the same accepted VM version; existing histories containing previously failed dynamic foreign-storage calls need an explicit upgrade boundary.

Project links

Data verified by PyPI on Sep 11, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Endogen from gravatar.com Endogen

Credits

Author: Xian Network

GitHub Statistics

Data verified by PyPI on Sep 11, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python <3.15, >=3.14

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

xian_tech_vm_core-0.1.2.tar.gz (775.9 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

xian_tech_vm_core-0.1.2-cp314-abi3-win_amd64.whl (812.9 kB view details)

Uploaded CPython 3.14+Windows x86-64

xian_tech_vm_core-0.1.2-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (979.3 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ x86-64

xian_tech_vm_core-0.1.2-cp314-abi3-macosx_11_0_arm64.whl (860.3 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

xian_tech_vm_core-0.1.2-cp314-abi3-macosx_10_12_x86_64.whl (911.4 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

Details for the file xian_tech_vm_core-0.1.2.tar.gz.

File metadata

  • Download URL: xian_tech_vm_core-0.1.2.tar.gz
  • Upload date:
  • Size: 775.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for xian_tech_vm_core-0.1.2.tar.gz
Algorithm Hash digest
SHA256 8280587f0561509b153ce6edf035dd16576d8cfa2bbea67acef39100cf208645
MD5 f12325cda2ba6ea65079e404504eab5b
BLAKE2b-256 cc76f8e963015f3b06167e1220d4e8e56129be6cfa0572ac2052f8f123276550

See more details on using hashes here.

Provenance

The following attestation bundles were made for xian_tech_vm_core-0.1.2.tar.gz:

Publisher: release.yml on xian-technology/xian-contracting

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file xian_tech_vm_core-0.1.2-cp314-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for xian_tech_vm_core-0.1.2-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 d3f847d78f7918385665d473be0b271fd9bbd36b3d95ddc4ca2133ac7134075b
MD5 5d8a1e556400efd8045b35d79cbd99a7
BLAKE2b-256 0f767f5888a3f45a6d67c158814593073dba9303922dd3327434b52a1f95f5cb

See more details on using hashes here.

Provenance

The following attestation bundles were made for xian_tech_vm_core-0.1.2-cp314-abi3-win_amd64.whl:

Publisher: release.yml on xian-technology/xian-contracting

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file xian_tech_vm_core-0.1.2-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for xian_tech_vm_core-0.1.2-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 3c5eb2f474d06f1483a7be19cb2a51b5854763030b3a928363d0c09f0dcf43ec
MD5 4fa5f337ac41fe325faf4266da88b57b
BLAKE2b-256 330e949429cf4ccacc0b479c29b6b2ff360e598f8872136f5698517ab3f5a87d

See more details on using hashes here.

Provenance

The following attestation bundles were made for xian_tech_vm_core-0.1.2-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on xian-technology/xian-contracting

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file xian_tech_vm_core-0.1.2-cp314-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for xian_tech_vm_core-0.1.2-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 e648f01758a844221eb4a70a262ec58badf1d8c91681684624766f9075c5f0be
MD5 c36854d4232c5c0d3e8a964a4124ac87
BLAKE2b-256 53a2d87875ac0e17ff6c65c3306a576c9b43fe77804c03824425da0162d09f48

See more details on using hashes here.

Provenance

The following attestation bundles were made for xian_tech_vm_core-0.1.2-cp314-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on xian-technology/xian-contracting

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file xian_tech_vm_core-0.1.2-cp314-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for xian_tech_vm_core-0.1.2-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 91cd1f4b91df93989434b38b5461035e53da040f5d70abd6d2a134b0c8e2d690
MD5 dcc309e0e694bc02b38d05c4fbf970f5
BLAKE2b-256 b6bba965fe573494e45230f57da6d52951aa3f9fd9b9282b95c25a161cfc4063

See more details on using hashes here.

Provenance

The following attestation bundles were made for xian_tech_vm_core-0.1.2-cp314-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on xian-technology/xian-contracting

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.2 This release

5 files

0.1.1

5 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page