xian-tech-vm-core 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. xian_tech_vm_core-0.1.1/PKG-INFO +158 -0
  2. xian_tech_vm_core-0.1.1/README.md +144 -0
  3. xian_tech_vm_core-0.1.1/pyproject.toml +26 -0
  4. xian_tech_vm_core-0.1.1/python/xian_vm_core/__init__.py +759 -0
  5. xian_tech_vm_core-0.1.1/xian-vm-core/Cargo.lock +1770 -0
  6. xian_tech_vm_core-0.1.1/xian-vm-core/Cargo.toml +35 -0
  7. xian_tech_vm_core-0.1.1/xian-vm-core/README.md +144 -0
  8. xian_tech_vm_core-0.1.1/xian-vm-core/build.rs +4 -0
  9. xian_tech_vm_core-0.1.1/xian-vm-core/src/artifacts.rs +343 -0
  10. xian_tech_vm_core-0.1.1/xian-vm-core/src/foreign_storage.rs +233 -0
  11. xian_tech_vm_core-0.1.1/xian-vm-core/src/interpreter.rs +6089 -0
  12. xian_tech_vm_core-0.1.1/xian-vm-core/src/interpreter_support.rs +3271 -0
  13. xian_tech_vm_core-0.1.1/xian-vm-core/src/lib.rs +1263 -0
  14. xian_tech_vm_core-0.1.1/xian-vm-core/src/metering.rs +420 -0
  15. xian_tech_vm_core-0.1.1/xian-vm-core/src/python_bindings.rs +1032 -0
  16. xian_tech_vm_core-0.1.1/xian-vm-core/src/values.rs +1122 -0
  17. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/authored_currency_transfer.json +6016 -0
  18. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/authored_dex_swap_path.json +72993 -0
  19. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/authored_oracle_price_info.json +10254 -0
  20. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/authored_profile_channel.json +15605 -0
  21. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/authored_reflection_transfer.json +14441 -0
  22. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/authored_shielded_commands_hash.json +57437 -0
  23. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/authored_shielded_note_hash.json +51856 -0
  24. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/authored_stable_token_burn.json +8927 -0
  25. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/authored_turn_based_join.json +17160 -0
  26. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/authored_validators_reward_change.json +76937 -0
  27. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/bigint_shielded_primitives.json +1171 -0
  28. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/collection_helpers.json +848 -0
  29. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/decimal_arithmetic.json +795 -0
  30. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/dynamic_import_factory_ctx.json +1057 -0
  31. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/foreign_state_probe.json +563 -0
  32. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/range_summary.json +788 -0
  33. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/static_import_ctx.json +863 -0
  34. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/time_hash_crypto.json +978 -0
  35. xian_tech_vm_core-0.1.1/xian-vm-core/tests/fixtures/transfer_event.json +734 -0
  36. xian_tech_vm_core-0.1.1/xian-vm-core/tests/parity_fixtures.rs +1259 -0
  37. xian_tech_vm_core-0.1.1/xian-vm-core/uv.lock +156 -0
  38. xian_tech_vm_core-0.1.1/xian-zk/.gitignore +11 -0
  39. xian_tech_vm_core-0.1.1/xian-zk/Cargo.toml +45 -0
  40. xian_tech_vm_core-0.1.1/xian-zk/README.md +138 -0
  41. xian_tech_vm_core-0.1.1/xian-zk/examples/generate_shielded_note_fixture.rs +9 -0
  42. xian_tech_vm_core-0.1.1/xian-zk/examples/generate_test_vector.rs +9 -0
  43. xian_tech_vm_core-0.1.1/xian-zk/pyproject.toml +43 -0
  44. xian_tech_vm_core-0.1.1/xian-zk/python/xian_zk/__init__.py +221 -0
  45. xian_tech_vm_core-0.1.1/xian-zk/python/xian_zk/bundles.py +242 -0
  46. xian_tech_vm_core-0.1.1/xian-zk/python/xian_zk/cli.py +700 -0
  47. xian_tech_vm_core-0.1.1/xian-zk/python/xian_zk/prover_service.py +681 -0
  48. xian_tech_vm_core-0.1.1/xian-zk/python/xian_zk/shielded_commands.py +487 -0
  49. xian_tech_vm_core-0.1.1/xian-zk/python/xian_zk/shielded_notes.py +2104 -0
  50. xian_tech_vm_core-0.1.1/xian-zk/python/xian_zk/shielded_relay.py +416 -0
  51. xian_tech_vm_core-0.1.1/xian-zk/python/xian_zk/shielded_scheduler_auth.py +178 -0
  52. xian_tech_vm_core-0.1.1/xian-zk/src/core.rs +273 -0
  53. xian_tech_vm_core-0.1.1/xian-zk/src/lib.rs +37 -0
  54. xian_tech_vm_core-0.1.1/xian-zk/src/poseidon.rs +242 -0
  55. xian_tech_vm_core-0.1.1/xian-zk/src/python_bindings.rs +613 -0
  56. xian_tech_vm_core-0.1.1/xian-zk/src/shielded_notes.rs +3231 -0
  57. xian_tech_vm_core-0.1.1/xian-zk/tests/fixtures/groth16_bn254_demo.json +7 -0
  58. xian_tech_vm_core-0.1.1/xian-zk/tests/fixtures/shielded_note_flow.json +138 -0
  59. xian_tech_vm_core-0.1.1/xian-zk/tests/test_bundle_artifacts.py +140 -0
  60. xian_tech_vm_core-0.1.1/xian-zk/tests/test_prover_service.py +225 -0
  61. xian_tech_vm_core-0.1.1/xian-zk/tests/test_shielded_commands.py +169 -0
  62. xian_tech_vm_core-0.1.1/xian-zk/tests/test_shielded_relay.py +164 -0
  63. xian_tech_vm_core-0.1.1/xian-zk/tests/test_shielded_toolkit.py +316 -0
  64. xian_tech_vm_core-0.1.1/xian-zk/tests/test_shielded_wallet.py +1007 -0
  65. xian_tech_vm_core-0.1.1/xian-zk/tests/test_verify.py +123 -0
@@ -0,0 +1,158 @@
1
+ Metadata-Version: 2.4
2
+ Name: xian-tech-vm-core
3
+ Version: 0.1.1
4
+ Classifier: Programming Language :: Python :: 3.14
5
+ Classifier: Programming Language :: Rust
6
+ Requires-Dist: xian-tech-contracting>=1.1.0,<2
7
+ Summary: Native VM capability surface for the future Xian execution engine
8
+ Home-Page: https://github.com/xian-technology/xian-contracting
9
+ Author-email: Xian Network <info@xian.org>
10
+ License-Expression: MIT
11
+ Requires-Python: >=3.14, <3.15
12
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
13
+
14
+ # xian-vm-core
15
+
16
+ `xian-vm-core` is the Rust-side consumer of the frozen `xian_vm_v1` compiler IR
17
+ emitted by `xian-contracting`.
18
+
19
+ ```mermaid
20
+ flowchart LR
21
+ Source["Contract source"] --> Compiler["xian-contracting compiler"]
22
+ Compiler --> IR["xian_vm_v1 IR"]
23
+ IR --> Validator["Rust IR validator"]
24
+ Validator --> VM["Native VM execution slice"]
25
+ VM --> Host["Host storage and syscall bridge"]
26
+ Host --> State["Deterministic state and events"]
27
+ Fixtures["Python parity fixtures"] --> Validator
28
+ Fixtures --> VM
29
+ ```
30
+
31
+ Supported scope:
32
+
33
+ - deserialize the structural JSON IR
34
+ - validate its top-level invariants and recursive node shapes
35
+ - instantiate validated modules and execute a direct-IR interpreter slice
36
+ - provide one Rust-owned contract for the Python frontend to target
37
+ - expose a minimal Python-facing native capability surface for `xian-abci`
38
+ probing via `xian_vm_core._native`
39
+
40
+ Execution coverage is intentionally narrow but real:
41
+
42
+ - local function calls and builtin calls such as `len`, `range`, `str`, and
43
+ `isinstance`
44
+ - aggregate/container helpers such as `sorted`, `sum`, `min`, `max`, `all`,
45
+ `any`, `reversed`, and `zip`
46
+ - explicit storage ops for `Variable` and `Hash`
47
+ - foreign storage reads for `ForeignVariable` and `ForeignHash`, including
48
+ function-local references with dynamic contract/variable targets
49
+ - arbitrary-precision integer values instead of `i64`-only VM integers
50
+ - fixed-precision `decimal(...)` construction and arithmetic
51
+ - native `datetime.datetime` / `datetime.timedelta` values, including
52
+ `datetime.datetime.strptime(...)`, arithmetic, comparison, and common field
53
+ access
54
+ - bigint-oriented builtins needed by the shielded contracts, including
55
+ `int(..., base)`, `pow(base, exp, mod)`, and `format(value, "064x")`
56
+ - `hashlib.sha3(...)` and `hashlib.sha256(...)`
57
+ - `crypto.verify(...)` and `crypto.key_is_valid(...)`
58
+ - `LogEvent` emission
59
+ - static-import and dynamic-import contract export calls
60
+ - native container method calls used by contracts today, including
61
+ `dict.keys()`, `dict.values()`, `dict.items()`, `dict.get()`, and the common
62
+ mutable list helpers `append`, `extend`, `insert`, `remove`, and `pop`
63
+ - native string helpers used by the shielded contracts, including
64
+ `lower()`, `isalnum()`, `startswith(...)`, and `join(...)`
65
+ - Python-style subscript slicing for `list`, `tuple`, and `str`, including
66
+ the `value[2:]` helper pattern used in the shielded contracts
67
+ - sequence repetition for `list`, `tuple`, and `str`
68
+ - host-delegated `zk.*` syscalls, which remain explicit runtime boundary calls
69
+ instead of Rust-local protocol logic
70
+
71
+ It is a bounded execution slice, not the full executor.
72
+
73
+ The crate includes curated conformance fixtures generated from the current local
74
+ harness. Those fixtures are checked from Rust so the VM can match actual
75
+ contract behavior on a controlled contract subset alongside hand-written
76
+ executor tests.
77
+
78
+ Metering covers both host-side data costs and VM execution:
79
+
80
+ - storage reads, writes, transaction bytes, and return-value bytes are charged
81
+ directly in the VM host path
82
+ - execution cost is driven by an explicit `xian_vm_v1` gas schedule over VM
83
+ statements, expressions, calls, and loop iterations
84
+ - module initialization is metered, so first-load authored contracts do not get
85
+ free global-declaration and module-body execution
86
+ - `contract.exists(...)`, `contract.has_export(...)`, `contract.info(...)`, and
87
+ related contract metadata syscalls resolve directly against the driver/IR in
88
+ the native host bridge
89
+ - authored contract storage persists `__xian_ir_v1__`, and the native host
90
+ requires that validator-derived artifact for `xian_vm_v1` execution; stored
91
+ `__source__` remains available for dashboards, BDS, and other inspection
92
+ tooling
93
+ - native deployment accepts cleartext source only, rejects submitted
94
+ `deployment_artifacts`, and derives `vm_ir_json` through the pinned compiler
95
+ before staging writes
96
+ - native deployment requires explicit deterministic `now` context from the
97
+ caller; the host does not fall back to local wall-clock time for submission
98
+ metadata
99
+ - the native deployment path validates the compiler-produced IR before staging
100
+ writes or executing constructors
101
+ - the Python deployment path and offline tooling keep canonical
102
+ source-to-runtime recompilation in the Python artifact validator; the native
103
+ path is Rust-native for bundle validation, not a Rust recompiler
104
+ - the five-node `make localnet-parallel-e2e` native-authority soak passes end to
105
+ end, including shielded token flows and parallel prefix-scan access patterns
106
+
107
+ That parity corpus covers:
108
+
109
+ - storage/event flows
110
+ - range/list/dict control-flow helpers
111
+ - foreign storage reads
112
+ - fixed-precision decimal semantics
113
+ - datetime/timedelta behavior
114
+ - bigint parsing, modular arithmetic, hex formatting, and shielded-style helper
115
+ flows
116
+ - hashing and ed25519 verification helpers
117
+ - static-import and dynamic-import nested contract calls
118
+ - real authored shielded contract sources for `shielded-note-token` and
119
+ `shielded-commands`, including constructor-seeded state snapshots and
120
+ hash-helper exports
121
+ - real authored token, registry, game, and oracle flows across repos, including:
122
+ `currency.transfer(...)`, `stable_token.burn(...)`,
123
+ `reflection_token.transfer(...)`, `profile_registry.create_channel(...)`,
124
+ `turn_based_games.join_match(...)`, and `oracle.price_info(...)`
125
+
126
+ The intent is to keep the Xian VM implementation Rust-first for performance,
127
+ while still freezing semantics in the Python compiler frontend before runtime
128
+ execution work starts.
129
+
130
+ The crate ships a small PyO3/maturin surface for integration work:
131
+
132
+ - `runtime_info()` / `runtime_info_json()`
133
+ - `supports_execution_policy(...)`
134
+ - `validate_module_ir(...)` / `validate_module_ir_json(...)`
135
+
136
+ That surface is intentionally narrow. It is there so node-side code can probe
137
+ the VM runtime honestly before transaction execution is wired through the Rust
138
+ engine.
139
+
140
+ The largest remaining runtime work is metering drift on the heaviest authored
141
+ flows and the host-operation split between delegated calls and Rust-owned
142
+ implementations. Integer width, basic authored shielded execution, and
143
+ pre-call setup flows are covered by the authored parity corpus and fixture
144
+ generator.
145
+
146
+ ## Releases
147
+
148
+ Push a `vm-core-vX.Y.Z` tag with matching versions in `pyproject.toml` and
149
+ `Cargo.toml` after `../../scripts/validate-release.sh` passes. The release
150
+ workflow builds native wheels for Linux, macOS Intel/ARM and Windows, and a
151
+ source distribution. PyPI Trusted Publishing uses project `xian-tech-vm-core`,
152
+ owner `xian-technology`, repository `xian-contracting`, workflow `release.yml`
153
+ and environment `pypi-xian-vm-core`.
154
+
155
+ Runtime semantics are consensus-sensitive. Validators must use the same
156
+ accepted VM version; existing histories containing previously failed dynamic
157
+ foreign-storage calls need an explicit upgrade boundary.
158
+
@@ -0,0 +1,144 @@
1
+ # xian-vm-core
2
+
3
+ `xian-vm-core` is the Rust-side consumer of the frozen `xian_vm_v1` compiler IR
4
+ emitted by `xian-contracting`.
5
+
6
+ ```mermaid
7
+ flowchart LR
8
+ Source["Contract source"] --> Compiler["xian-contracting compiler"]
9
+ Compiler --> IR["xian_vm_v1 IR"]
10
+ IR --> Validator["Rust IR validator"]
11
+ Validator --> VM["Native VM execution slice"]
12
+ VM --> Host["Host storage and syscall bridge"]
13
+ Host --> State["Deterministic state and events"]
14
+ Fixtures["Python parity fixtures"] --> Validator
15
+ Fixtures --> VM
16
+ ```
17
+
18
+ Supported scope:
19
+
20
+ - deserialize the structural JSON IR
21
+ - validate its top-level invariants and recursive node shapes
22
+ - instantiate validated modules and execute a direct-IR interpreter slice
23
+ - provide one Rust-owned contract for the Python frontend to target
24
+ - expose a minimal Python-facing native capability surface for `xian-abci`
25
+ probing via `xian_vm_core._native`
26
+
27
+ Execution coverage is intentionally narrow but real:
28
+
29
+ - local function calls and builtin calls such as `len`, `range`, `str`, and
30
+ `isinstance`
31
+ - aggregate/container helpers such as `sorted`, `sum`, `min`, `max`, `all`,
32
+ `any`, `reversed`, and `zip`
33
+ - explicit storage ops for `Variable` and `Hash`
34
+ - foreign storage reads for `ForeignVariable` and `ForeignHash`, including
35
+ function-local references with dynamic contract/variable targets
36
+ - arbitrary-precision integer values instead of `i64`-only VM integers
37
+ - fixed-precision `decimal(...)` construction and arithmetic
38
+ - native `datetime.datetime` / `datetime.timedelta` values, including
39
+ `datetime.datetime.strptime(...)`, arithmetic, comparison, and common field
40
+ access
41
+ - bigint-oriented builtins needed by the shielded contracts, including
42
+ `int(..., base)`, `pow(base, exp, mod)`, and `format(value, "064x")`
43
+ - `hashlib.sha3(...)` and `hashlib.sha256(...)`
44
+ - `crypto.verify(...)` and `crypto.key_is_valid(...)`
45
+ - `LogEvent` emission
46
+ - static-import and dynamic-import contract export calls
47
+ - native container method calls used by contracts today, including
48
+ `dict.keys()`, `dict.values()`, `dict.items()`, `dict.get()`, and the common
49
+ mutable list helpers `append`, `extend`, `insert`, `remove`, and `pop`
50
+ - native string helpers used by the shielded contracts, including
51
+ `lower()`, `isalnum()`, `startswith(...)`, and `join(...)`
52
+ - Python-style subscript slicing for `list`, `tuple`, and `str`, including
53
+ the `value[2:]` helper pattern used in the shielded contracts
54
+ - sequence repetition for `list`, `tuple`, and `str`
55
+ - host-delegated `zk.*` syscalls, which remain explicit runtime boundary calls
56
+ instead of Rust-local protocol logic
57
+
58
+ It is a bounded execution slice, not the full executor.
59
+
60
+ The crate includes curated conformance fixtures generated from the current local
61
+ harness. Those fixtures are checked from Rust so the VM can match actual
62
+ contract behavior on a controlled contract subset alongside hand-written
63
+ executor tests.
64
+
65
+ Metering covers both host-side data costs and VM execution:
66
+
67
+ - storage reads, writes, transaction bytes, and return-value bytes are charged
68
+ directly in the VM host path
69
+ - execution cost is driven by an explicit `xian_vm_v1` gas schedule over VM
70
+ statements, expressions, calls, and loop iterations
71
+ - module initialization is metered, so first-load authored contracts do not get
72
+ free global-declaration and module-body execution
73
+ - `contract.exists(...)`, `contract.has_export(...)`, `contract.info(...)`, and
74
+ related contract metadata syscalls resolve directly against the driver/IR in
75
+ the native host bridge
76
+ - authored contract storage persists `__xian_ir_v1__`, and the native host
77
+ requires that validator-derived artifact for `xian_vm_v1` execution; stored
78
+ `__source__` remains available for dashboards, BDS, and other inspection
79
+ tooling
80
+ - native deployment accepts cleartext source only, rejects submitted
81
+ `deployment_artifacts`, and derives `vm_ir_json` through the pinned compiler
82
+ before staging writes
83
+ - native deployment requires explicit deterministic `now` context from the
84
+ caller; the host does not fall back to local wall-clock time for submission
85
+ metadata
86
+ - the native deployment path validates the compiler-produced IR before staging
87
+ writes or executing constructors
88
+ - the Python deployment path and offline tooling keep canonical
89
+ source-to-runtime recompilation in the Python artifact validator; the native
90
+ path is Rust-native for bundle validation, not a Rust recompiler
91
+ - the five-node `make localnet-parallel-e2e` native-authority soak passes end to
92
+ end, including shielded token flows and parallel prefix-scan access patterns
93
+
94
+ That parity corpus covers:
95
+
96
+ - storage/event flows
97
+ - range/list/dict control-flow helpers
98
+ - foreign storage reads
99
+ - fixed-precision decimal semantics
100
+ - datetime/timedelta behavior
101
+ - bigint parsing, modular arithmetic, hex formatting, and shielded-style helper
102
+ flows
103
+ - hashing and ed25519 verification helpers
104
+ - static-import and dynamic-import nested contract calls
105
+ - real authored shielded contract sources for `shielded-note-token` and
106
+ `shielded-commands`, including constructor-seeded state snapshots and
107
+ hash-helper exports
108
+ - real authored token, registry, game, and oracle flows across repos, including:
109
+ `currency.transfer(...)`, `stable_token.burn(...)`,
110
+ `reflection_token.transfer(...)`, `profile_registry.create_channel(...)`,
111
+ `turn_based_games.join_match(...)`, and `oracle.price_info(...)`
112
+
113
+ The intent is to keep the Xian VM implementation Rust-first for performance,
114
+ while still freezing semantics in the Python compiler frontend before runtime
115
+ execution work starts.
116
+
117
+ The crate ships a small PyO3/maturin surface for integration work:
118
+
119
+ - `runtime_info()` / `runtime_info_json()`
120
+ - `supports_execution_policy(...)`
121
+ - `validate_module_ir(...)` / `validate_module_ir_json(...)`
122
+
123
+ That surface is intentionally narrow. It is there so node-side code can probe
124
+ the VM runtime honestly before transaction execution is wired through the Rust
125
+ engine.
126
+
127
+ The largest remaining runtime work is metering drift on the heaviest authored
128
+ flows and the host-operation split between delegated calls and Rust-owned
129
+ implementations. Integer width, basic authored shielded execution, and
130
+ pre-call setup flows are covered by the authored parity corpus and fixture
131
+ generator.
132
+
133
+ ## Releases
134
+
135
+ Push a `vm-core-vX.Y.Z` tag with matching versions in `pyproject.toml` and
136
+ `Cargo.toml` after `../../scripts/validate-release.sh` passes. The release
137
+ workflow builds native wheels for Linux, macOS Intel/ARM and Windows, and a
138
+ source distribution. PyPI Trusted Publishing uses project `xian-tech-vm-core`,
139
+ owner `xian-technology`, repository `xian-contracting`, workflow `release.yml`
140
+ and environment `pypi-xian-vm-core`.
141
+
142
+ Runtime semantics are consensus-sensitive. Validators must use the same
143
+ accepted VM version; existing histories containing previously failed dynamic
144
+ foreign-storage calls need an explicit upgrade boundary.
@@ -0,0 +1,26 @@
1
+ [build-system]
2
+ requires = ["maturin>=1.13.1,<2"]
3
+ build-backend = "maturin"
4
+
5
+ [project]
6
+ name = "xian-tech-vm-core"
7
+ version = "0.1.1"
8
+ description = "Native VM capability surface for the future Xian execution engine"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ authors = [{ name = "Xian Network", email = "info@xian.org" }]
12
+ requires-python = ">=3.14,<3.15"
13
+ classifiers = [
14
+ "Programming Language :: Python :: 3.14",
15
+ "Programming Language :: Rust",
16
+ ]
17
+ dependencies = ["xian-tech-contracting>=1.1.0,<2"]
18
+
19
+ [tool.maturin]
20
+ module-name = "xian_vm_core._native"
21
+ features = ["python-extension"]
22
+ manifest-path = "xian-vm-core/Cargo.toml"
23
+ python-source = "python"
24
+
25
+ [tool.uv.sources]
26
+ xian-tech-contracting = { path = "../..", editable = true }