xian-tech-contracting 1.0.1__tar.gz

xian_tech_contracting-1.0.1/LICENSE

@@ -0,0 +1,7 @@
+Creative Commons Attribution‑NonCommercial 4.0 International
+
+Copyright © 2025 XIAN.org
+
+This work is licensed under CC BY‑NC 4.0.  
+You may copy, modify, and share it **for non‑commercial purposes only**, provided that you give appropriate credit.  
+Full legal text: https://creativecommons.org/licenses/by-nc/4.0/legalcode

xian_tech_contracting-1.0.1/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: xian-tech-contracting
+Version: 1.0.1
+Summary: Xian Network Python Contracting Engine
+Author-email: Xian Network <info@xian.org>
+License-Expression: GPL-3.0-only
+Project-URL: Repository, https://github.com/xian-technology/xian-contracting
+Keywords: blockchain,xian,contracting,python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Development Status :: 5 - Production/Stable
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: autopep8<2,>=1.5.7
+Requires-Dist: cachetools<8,>=5
+Requires-Dist: lmdb<2,>=1.6
+Requires-Dist: pynacl<2,>=1.5.0
+Requires-Dist: xian-tech-runtime-types<0.2,>=0.1.0
+Provides-Extra: native
+Requires-Dist: xian-tech-native-tracer<0.2,>=0.1.0; extra == "native"
+Provides-Extra: zk
+Requires-Dist: xian-tech-zk<0.2,>=0.1.0; extra == "zk"
+Dynamic: license-file
+
+# xian-contracting
+
+`xian-contracting` is the Python contract runtime for Xian. It owns contract
+compilation, secure execution, storage semantics, metering, and the runtime
+rules that contracts must obey.
+
+## Quick Start
+
+Install the runtime:
+
+```bash
+pip install xian-tech-contracting
+```
+
+If you want contract-side zk proof verification, install the optional zk
+backend too:
+
+```bash
+pip install 'xian-tech-contracting[zk]'
+```
+
+The published PyPI package name is `xian-tech-contracting`. The repo name
+remains `xian-contracting`, and the import surface remains `contracting`.
+
+Submit and call a contract:
+
+```python
+from contracting.client import ContractingClient
+
+client = ContractingClient()
+client.submit(name="con_token", code=contract_source)
+token = client.get_contract("con_token")
+token.transfer(amount=100, to="bob")
+```
+
+Access storage directly:
+
+```python
+from contracting.storage.driver import Driver
+
+driver = Driver()
+driver.set("example.key", "value")
+print(driver.get("example.key"))
+```
+
+## Principles
+
+- Contracts use Python syntax, but execution rules are consensus-sensitive and
+  intentionally narrower than general Python.
+- Metering, storage encoding, import restrictions, and runtime helpers must
+  stay version-aligned across validators.
+- Optional native tracing is an implementation detail. The contract model and
+  runtime rules should remain understandable without it.
+- Built-in helpers should serve the execution model, not grow into a general
+  convenience framework.
+
+## Key Directories
+
+- `src/contracting/`: runtime, storage, compilation, and stdlib bridge code
+- `packages/`: shared packages such as `xian-runtime-types`, `xian-accounts`,
+  the native tracer, and `xian-zk`
+- `tests/`: unit, integration, and security coverage
+- `docs/`: architecture, backlog, and execution notes
+
+## What It Covers
+
+- compilation and linting
+- runtime execution and metering
+- storage drivers and encoding
+- contract-side runtime helpers
+- optional native tracing backend
+- native zero-knowledge verifier building blocks
+
+## Validation
+
+```bash
+uv sync --group dev
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+```
+
+If you change the zk runtime surface or the native verifier package, run:
+
+```bash
+uv sync --group dev --extra zk
+uv run --extra zk pytest -q tests/unit/test_zk_stdlib.py tests/integration/test_zk_bridge.py
+cd packages/xian-zk && uv sync --group dev && uv run maturin develop && uv run pytest -q
+```
+
+If you change metering, tracing, storage encoding, or import restrictions, run
+the relevant `tests/security/` and `tests/integration/` paths explicitly too.
+
+## Related Docs
+
+- [AGENTS.md](AGENTS.md)
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- [docs/BACKLOG.md](docs/BACKLOG.md)
+- [docs/README.md](docs/README.md)

xian_tech_contracting-1.0.1/README.md

@@ -0,0 +1,99 @@
+# xian-contracting
+
+`xian-contracting` is the Python contract runtime for Xian. It owns contract
+compilation, secure execution, storage semantics, metering, and the runtime
+rules that contracts must obey.
+
+## Quick Start
+
+Install the runtime:
+
+```bash
+pip install xian-tech-contracting
+```
+
+If you want contract-side zk proof verification, install the optional zk
+backend too:
+
+```bash
+pip install 'xian-tech-contracting[zk]'
+```
+
+The published PyPI package name is `xian-tech-contracting`. The repo name
+remains `xian-contracting`, and the import surface remains `contracting`.
+
+Submit and call a contract:
+
+```python
+from contracting.client import ContractingClient
+
+client = ContractingClient()
+client.submit(name="con_token", code=contract_source)
+token = client.get_contract("con_token")
+token.transfer(amount=100, to="bob")
+```
+
+Access storage directly:
+
+```python
+from contracting.storage.driver import Driver
+
+driver = Driver()
+driver.set("example.key", "value")
+print(driver.get("example.key"))
+```
+
+## Principles
+
+- Contracts use Python syntax, but execution rules are consensus-sensitive and
+  intentionally narrower than general Python.
+- Metering, storage encoding, import restrictions, and runtime helpers must
+  stay version-aligned across validators.
+- Optional native tracing is an implementation detail. The contract model and
+  runtime rules should remain understandable without it.
+- Built-in helpers should serve the execution model, not grow into a general
+  convenience framework.
+
+## Key Directories
+
+- `src/contracting/`: runtime, storage, compilation, and stdlib bridge code
+- `packages/`: shared packages such as `xian-runtime-types`, `xian-accounts`,
+  the native tracer, and `xian-zk`
+- `tests/`: unit, integration, and security coverage
+- `docs/`: architecture, backlog, and execution notes
+
+## What It Covers
+
+- compilation and linting
+- runtime execution and metering
+- storage drivers and encoding
+- contract-side runtime helpers
+- optional native tracing backend
+- native zero-knowledge verifier building blocks
+
+## Validation
+
+```bash
+uv sync --group dev
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+```
+
+If you change the zk runtime surface or the native verifier package, run:
+
+```bash
+uv sync --group dev --extra zk
+uv run --extra zk pytest -q tests/unit/test_zk_stdlib.py tests/integration/test_zk_bridge.py
+cd packages/xian-zk && uv sync --group dev && uv run maturin develop && uv run pytest -q
+```
+
+If you change metering, tracing, storage encoding, or import restrictions, run
+the relevant `tests/security/` and `tests/integration/` paths explicitly too.
+
+## Related Docs
+
+- [AGENTS.md](AGENTS.md)
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- [docs/BACKLOG.md](docs/BACKLOG.md)
+- [docs/README.md](docs/README.md)

xian_tech_contracting-1.0.1/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xian-tech-contracting"
+version = "1.0.1"
+description = "Xian Network Python Contracting Engine"
+readme = "README.md"
+license = "GPL-3.0-only"
+authors = [{ name = "Xian Network", email = "info@xian.org" }]
+requires-python = ">=3.12"
+dependencies = [
+    "autopep8>=1.5.7,<2",
+    "cachetools>=5,<8",
+    "lmdb>=1.6,<2",
+    "pynacl>=1.5.0,<2",
+    "xian-tech-runtime-types>=0.1.0,<0.2",
+]
+keywords = ["blockchain", "xian", "contracting", "python"]
+classifiers = [
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Development Status :: 5 - Production/Stable",
+]
+
+[project.urls]
+Repository = "https://github.com/xian-technology/xian-contracting"
+
+[project.optional-dependencies]
+native = [
+    "xian-tech-native-tracer>=0.1.0,<0.2",
+]
+zk = [
+    "xian-tech-zk>=0.1.0,<0.2",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2,<10",
+    "pytest-cov>=7.0.0,<8",
+    "ruff>=0.15.6,<0.16",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+contracting = ["contracts/*.s.py"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 80
+target-version = "py312"
+exclude = [
+    "examples",
+    "tests/integration/test_contracts",
+    "tests",
+    "tests/performance/test_contracts",
+    "tests/security/contracts",
+    "tests/unit/contracts",
+    "tests/unit/precompiled",
+    "tests/unit/test_sys_contracts",
+    "src/contracting/contracts",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = ["E501"]
+
+[tool.uv.sources]
+xian-tech-runtime-types = { path = "packages/xian-runtime-types", editable = true }
+xian-tech-native-tracer = { path = "packages/xian-native-tracer", editable = true }
+xian-tech-zk = { path = "packages/xian-zk", editable = true }

xian_tech_contracting-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xian_tech_contracting-1.0.1/src/contracting/client.py

@@ -0,0 +1,389 @@
+import ast
+import inspect
+import os
+from datetime import datetime
+from functools import partial
+from types import FunctionType
+
+import autopep8
+from xian_runtime_types.time import Datetime
+
+from contracting.compilation.compiler import ContractingCompiler
+from contracting.execution import runtime
+from contracting.execution.executor import Executor
+from contracting.storage.driver import Driver
+
+from . import constants
+from .storage.orm import Hash, Variable
+
+
+class AbstractContract:
+    def __init__(
+        self,
+        name,
+        signer,
+        environment,
+        executor: Executor,
+        funcs,
+        return_full_output=False,
+    ):
+        self.name = name
+        self.signer = signer
+        self.environment = environment
+        self.executor = executor
+        self.functions = funcs
+
+        # set up virtual functions
+        for f in funcs:
+            # unpack tuple packed in SenecaClient
+            func, kwargs = f
+
+            # set the kwargs to None. these will fail if they are not provided
+            default_kwargs = {}
+            for kwarg in kwargs:
+                default_kwargs[kwarg] = None
+
+            # each function is a partial that allows kwarg overloading and overriding
+            setattr(
+                self,
+                func,
+                partial(
+                    self._abstract_function_call,
+                    signer=self.signer,
+                    contract_name=self.name,
+                    executor=self.executor,
+                    func=func,
+                    return_full_output=return_full_output,
+                    # environment=self.environment,
+                    **default_kwargs,
+                ),
+            )
+
+    def keys(self):
+        # Scope strictly to this contract's namespace
+        return self.executor.driver.keys(f"{self.name}.")
+
+    # a variable contains a DOT, but no __, and no :
+    # a hash contains a DOT, no __, and a :
+    # a constant contains __, a DOT, and :
+
+    def quick_read(self, variable, key=None, args=None):
+        a = []
+
+        if key is not None:
+            a.append(key)
+
+        if args is not None and isinstance(args, list):
+            for arg in args:
+                a.append(arg)
+
+        k = self.executor.driver.make_key(
+            contract=self.name, variable=variable, args=a
+        )
+        return self.executor.driver.get(k)
+
+    def quick_write(self, variable, key=None, value=None, args=None):
+        if key is not None:
+            a = [key]
+        else:
+            a = []
+
+        if args is not None and isinstance(args, list):
+            for arg in args:
+                a.append(arg)
+
+        k = self.executor.driver.make_key(
+            contract=self.name, variable=variable, args=a
+        )
+
+        self.executor.driver.set(k, value)
+        self.executor.driver.commit()
+
+    def run_private_function(self, f, signer=None, environment=None, **kwargs):
+        # Override kwargs if provided
+        signer = signer or self.signer
+        environment = environment or self.environment
+
+        # Let executor access private functions
+        self.executor.bypass_privates = True
+
+        try:
+            # Append private method prefix to function name if it isn't there already
+            if not f.startswith(constants.PRIVATE_METHOD_PREFIX):
+                f = "{}{}".format(constants.PRIVATE_METHOD_PREFIX, f)
+
+            return self._abstract_function_call(
+                signer=signer,
+                executor=self.executor,
+                contract_name=self.name,
+                environment=environment,
+                func=f,
+                metering=None,
+                now=None,
+                **kwargs,
+            )
+        finally:
+            # Always restore restricted mode, even if the private call fails.
+            self.executor.bypass_privates = False
+
+    def __getattr__(self, item):
+        try:
+            # return the attribute if it exists on the instance
+            return self.__getattribute__(item)
+        except AttributeError as e:
+            # otherwise, attempt to resolve it. full name is contract.item
+            fullname = "{}.{}".format(self.name, item)
+
+            # if the raw name exists, it is a __protected__ or a variable, so prepare for those
+            if fullname in self.keys():
+                variable = Variable(
+                    contract=self.name, name=item, driver=self.executor.driver
+                )
+
+                # return just the value if it is __protected__ to prevent sets
+                if item.startswith("__"):
+                    return variable.get()
+
+                # otherwise, return the variable object with allows sets
+                return variable
+
+            # otherwise, see if contract.items: has more than one entry
+            if (
+                len(
+                    self.executor.driver.values(
+                        prefix=self.name + "." + item + ":"
+                    )
+                )
+                > 0
+            ):
+                # if so, it is a hash. return the hash object
+                return Hash(
+                    contract=self.name, name=item, driver=self.executor.driver
+                )
+
+            # otherwise, the attribut does not exist, so throw the error.
+            raise e
+
+    def now(self):
+        d = datetime.today()
+        return Datetime(d.year, d.month, d.day, hour=d.hour, minute=d.minute)
+
+    def _abstract_function_call(
+        self,
+        signer,
+        executor,
+        contract_name,
+        func,
+        environment=None,
+        stamps=constants.DEFAULT_STAMPS,
+        metering=None,
+        now=None,
+        return_full_output=False,
+        **kwargs,
+    ):
+
+        # for k, v in kwargs.items():
+        #     assert v is not None, 'Keyword "{}" not provided. Must not be None.'.format(k)
+        environment = environment or self.environment
+
+        if now is None:
+            now = self.now()
+
+        if environment.get("now") is None:
+            environment.update({"now": now})
+
+        output = executor.execute(
+            sender=signer,
+            contract_name=contract_name,
+            function_name=func,
+            kwargs=kwargs,
+            stamps=stamps,
+            environment=environment,
+            metering=metering,
+        )
+
+        if executor.production:
+            executor.sandbox.terminate()
+
+        if output["status_code"] == 1:
+            raise output["result"] if not return_full_output else output
+        return output["result"] if not return_full_output else output
+
+
+class ContractingClient:
+    def __init__(
+        self,
+        signer="sys",
+        submission_filename=os.path.join(
+            os.path.dirname(__file__), "contracts/submission.s.py"
+        ),
+        storage_home=constants.STORAGE_HOME,
+        driver: Driver = None,
+        metering=False,
+        compiler=ContractingCompiler(),
+        environment={},
+        tracer_mode: str | None = None,
+    ):
+        if tracer_mode is not None:
+            runtime.rt.set_tracer_mode(tracer_mode)
+        driver = (
+            driver if driver is not None else Driver(storage_home=storage_home)
+        )
+        self.executor = Executor(metering=metering, driver=driver)
+        self.raw_driver = driver
+        self.signer = signer
+        self.compiler = compiler
+        self.submission_filename = submission_filename
+        self.environment = environment
+        # Get submission contract from file
+        if submission_filename is not None:
+            # Seed the genesis contracts into the instance
+            with open(self.submission_filename) as f:
+                contract = f.read()
+
+            self.raw_driver.set_contract(name="submission", code=contract)
+            self.raw_driver.commit()
+
+        # Get submission contract from state
+        self.submission_contract = self.get_contract("submission")
+
+    def set_submission_contract(self, filename=None, commit=True):
+        state_contract = self.get_contract("submission")
+
+        if filename is None:
+            filename = self.submission_filename
+
+        if filename is None and state_contract is None:
+            raise AssertionError(
+                "No submission contract provided or found in state."
+            )
+
+        if filename is not None:
+            with open(filename) as f:
+                contract = f.read()
+
+            self.raw_driver.delete_contract(name="submission")
+            self.raw_driver.set_contract(name="submission", code=contract)
+
+            if commit:
+                self.raw_driver.commit()
+
+        self.submission_contract = self.get_contract("submission")
+
+    def flush(self):
+        # flushes storage and resubmits genesis contracts
+        self.raw_driver.flush_full()
+        self.raw_driver.flush_cache()
+
+        if self.submission_filename is not None:
+            self.set_submission_contract()
+
+    # Returns abstract contract which has partial methods mapped to each exported function.
+    def get_contract(self, name):
+        contract = self.raw_driver.get_contract(name)
+
+        if contract is None:
+            return None
+
+        tree = ast.parse(contract)
+
+        function_defs = [
+            n for n in ast.walk(tree) if isinstance(n, ast.FunctionDef)
+        ]
+
+        funcs = []
+        for definition in function_defs:
+            func_name = definition.name
+            kwargs = [arg.arg for arg in definition.args.args]
+
+            funcs.append((func_name, kwargs))
+
+        return AbstractContract(
+            name=name,
+            signer=self.signer,
+            environment=self.environment,
+            executor=self.executor,
+            funcs=funcs,
+        )
+
+    def closure_to_code_string(self, f):
+        closure_code = inspect.getsource(f)
+        closure_code = autopep8.fix_code(closure_code)
+        closure_tree = ast.parse(closure_code)
+
+        # Remove the enclosing function by swapping out the function def node with its children
+        assert len(closure_tree.body) == 1, "Module has multiple body nodes."
+        assert isinstance(closure_tree.body[0], ast.FunctionDef), (
+            "Function definition not found at root."
+        )
+
+        func_def_body = closure_tree.body[0]
+        closure_tree.body = func_def_body.body
+
+        contract_code = ast.unparse(closure_tree)
+        name = func_def_body.name
+
+        return contract_code, name
+
+    def lint(self, f, raise_errors=False):
+        if isinstance(f, FunctionType):
+            f, _ = self.closure_to_code_string(f)
+
+        if raise_errors:
+            self.compiler.linter.check_raise(f)
+            return None
+
+        return self.compiler.linter.check(f)
+
+    def compile(self, f):
+        if isinstance(f, FunctionType):
+            f, _ = self.closure_to_code_string(f)
+
+        code = self.compiler.parse_to_code(f)
+        return code
+
+    def submit(
+        self,
+        f,
+        name=None,
+        metering=None,
+        owner=None,
+        constructor_args={},
+        signer=None,
+    ):
+
+        assert self.submission_contract is not None, (
+            "No submission contract set. Try set_submission_contract first."
+        )
+
+        if isinstance(f, FunctionType):
+            f, n = self.closure_to_code_string(f)
+            if name is None:
+                name = n
+
+        assert name is not None, "No name provided."
+
+        if signer is None:
+            signer = self.signer
+
+        self.submission_contract.submit_contract(
+            name=name,
+            code=f,
+            owner=owner,
+            constructor_args=constructor_args,
+            metering=metering,
+            signer=signer,
+        )
+
+    def get_contracts(self):
+        contracts = []
+        for key in self.raw_driver.keys():
+            if key.endswith(".__code__"):
+                contracts.append(key.replace(".__code__", ""))
+        return contracts
+
+    def get_var(self, contract, variable, arguments=[], mark=False):
+        return self.raw_driver.get_var(contract, variable, arguments, mark)
+
+    def set_var(self, contract, variable, arguments=[], value=None, mark=False):
+        self.raw_driver.set_var(contract, variable, arguments, value, mark)