Metadata-Version: 2.4
Name: knitweb-vein
Version: 0.1.1
Summary: Smart contract procedure engine: the vein through which Pulse flows
Author-email: Edwin Hauwert <develuse@gmail.com>
License: MIT
Project-URL: Repository, https://github.com/Knitweb/vein
Project-URL: Issues, https://github.com/Knitweb/vein/issues
Keywords: knitweb,pulse,smart-contracts,stored-procedures,pouw
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: knitweb-knitfield>=0.1.0
Requires-Dist: ecdsa>=0.18
Requires-Dist: cbor2>=5.4
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"

# vein — Smart Contract Procedure Engine

The vein (Ader) through which Pulse's logic flows. Deterministic, verifiable smart contract stored procedures as Proof-of-Useful-Work (PoUW) jobs.

## Architecture

```
Pulse (Hartslag)  →  triggers, clock, state-machine events
   ↓
Vein (Ader)  →  channels logic & data, executes smart contract procedures
   ↓
Settlement  →  verifiable, deterministic results settle in the ledger
```

## Design

**vein** provides:

- **SmartContractProcedureJob** — specification for calling a stored procedure on a contract
- **ExecutionContext** — deterministic sandbox for pure procedure execution
- **Expression evaluator** — support for simple logic, arithmetic, conditionals (MVP)
- **Bytecode format** — extensible path to EVM/Solidity compatibility
- **Fabric integration** — contracts as weaved records in the Knitweb P2P graph
- **PoUW settlement** — uniform (deterministic) verification policy for reward settlement

## Modules

```
src/knitweb_vein/
  __init__.py
  contract.py          — SmartContractProcedureJob, ContractProof, execute/verify
  executor.py          — ExecutionContext, expression evaluator, contract resolution
  items.py             — SmartContractRecord, ProcedureSpec (Fabric weaveable)
```

## Example

```python
from knitweb_vein import SmartContractProcedureJob, execute, verify

# Define a contract (stored in Fabric, weaved via Pulse)
contract = {
    "kind": "smart-contract",
    "name": "SettlementVault",
    "originator": pub_key,
    "procedures": {
        "transfer": {
            "name": "transfer",
            "params": {"from": "str", "to": "str", "amount": "int"},
            "body": {
                "type": "dict",
                "fields": {
                    "sender": {"type": "identity", "input": "from"},
                    "recipient": {"type": "identity", "input": "to"},
                    "value": {"type": "identity", "input": "amount"},
                }
            },
            "returns": "dict",
        }
    },
}

# Create a job (spider's work specification)
job = SmartContractProcedureJob(
    contract_asset=contract,
    procedure_name="transfer",
    arguments={"from": "alice", "to": "bob", "amount": 100},
    originator_pub=pub_key,
)

# Execute (Pulse triggers this; spider does the work)
proof = execute(job, private_key)

# Verify (sampled re-execution for settlement)
is_valid = verify(job, proof)
assert is_valid
```

## Integration with Knitweb

- **Pulse**: imports vein; registers "smart-contract-procedure" job class in PoUW
- **Molgang**: invokes contracts via the P2P settlement layer
- **Ledgerfield**: uses contracts for DAO voting, treaty settlement procedures
- **FinField**: deterministic on-chain oracle callbacks

## Future Extensions

- **EVM bytecode**: execute Solidity contracts deterministically
- **Cross-chain oracle**: verify on-chain procedure calls
- **Result attestation**: swarm-encoded result distribution for large outputs
- **Native gates**: ZK-circuit compilation for procedures
