Metadata-Version: 2.4
Name: alberta-buck
Version: 0.2.0
Summary: Alberta Buck reference implementation (protocol v2): identity credentials and accumulator, Notes, payment receipts, and agent simulations over the contracts
Author-email: Perry Kundert <perry@dominionrnd.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/alberta-buck/alberta-buck
Project-URL: Bug Tracker, https://github.com/alberta-buck/alberta-buck/issues
Keywords: stablecoin,ethereum,zero-knowledge,identity,bn254,simulation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: web3<8,>=7
Requires-Dist: python-dotenv<2,>=1.0
Requires-Dist: py_ecc>=8.0
Requires-Dist: alberta-buck-core<0.3,>=0.2.0
Provides-Extra: kernel
Requires-Dist: alberta-buck-core[kernel]<0.3,>=0.2.0; extra == "kernel"
Provides-Extra: fast
Requires-Dist: pyrevm>=0.3; extra == "fast"
Provides-Extra: plots
Requires-Dist: matplotlib>=3.8; extra == "plots"
Provides-Extra: server
Requires-Dist: websockets>=12; extra == "server"
Provides-Extra: sim
Requires-Dist: alberta-buck[fast,kernel,plots,server]; extra == "sim"
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Requires-Dist: alberta-buck[fast,plots]; extra == "tests"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: setuptools; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Dynamic: license-file

# alberta-buck

The Alberta Buck reference implementation in Python, protocol v2: the
identity layer, the Notes, the receipts, and the agent simulations that run
them against the real contracts.

- **`alberta_buck.wallet`** -- the executable specification: Pointcheval-Sanders
  identity credentials and the A' hiding registration presentation, ElGamal
  account credentials, the sigma protocols, the Notes flows (A1 and A2
  addressed notes, B1 bearer notes: commitments, deliveries, the folded
  deposit gates' witnesses), and AB-RCPT/2 payment receipts.  The compiled
  kernels (`alberta-buck-kernel`, in Rust) are proven bit-identical to it.
- **`alberta_buck.registry`** -- the identity accumulator: salted Poseidon
  trees, registry certificates, the aggregator, attribute proofs, the
  insurance regulator, and particulars certificates for details that change.
- **`alberta_buck.sim`** -- agent simulations over the contracts, on anvil or
  in-process (pyrevm): the BUCK_K PID controller, the baskets, the equilibrium
  experiments (`sim/experiments/*.toml`), and the Notes privacy world.
- **`alberta_buck.oracle`** -- Chainlink price-history readers (against a fork).

**Unaudited prototype software for a monetary system.**  It is published so
the research can be reproduced and built on -- not to hold anything of value.

## Install

```sh
pip install alberta-buck               # pure Python; installs everywhere
pip install alberta-buck[kernel]       # + the compiled kernels, where a wheel exists
pip install alberta-buck[sim]          # everything: kernel, pyrevm, plots, server
```

| extra    | adds                                   |
|----------|----------------------------------------|
| `kernel` | the Rust kernels (same bytes, faster)  |
| `fast`   | `pyrevm`, the in-process EVM backend   |
| `plots`  | `matplotlib`, for the `sim.plot_*` renderers |
| `server` | `websockets`, for `sim.server`         |
| `sim`    | all of the above                       |

The extras never change a result, only how fast it arrives or what it can
draw: every heavy dependency is imported where it is used.

## Use

```python
from alberta_buck.wallet import backend, identity_scalar, ps_keygen, ps_sign, ps_verify

issuer = ps_keygen()                                   # a credential issuer's key pair
m = identity_scalar({"registry": "ab", "person": "0001", "birth": "1970-01-01"})
sigma = ps_sign(issuer, m)                             # the issuer certifies the identity
print(backend(), ps_verify(issuer.pk_X, issuer.pk_Y, sigma, m))   # "kernel True" / "py True"
```

`BUCK_IDENTITY_BACKEND=py` forces the pure-Python path; `kernel` requires the
compiled one.

## The Notes use a DEVELOPMENT trusted setup

The simulations deploy the contracts from
[`alberta-buck-contracts`](https://pypi.org/project/alberta-buck-contracts/),
whose Groth16 verifiers come, **until v1.0.0, from a development trusted setup
whose toxic waste is public: anyone can forge a proof they accept.**  That is
deliberate -- it lets a simulation model forged-proof attacks and the
defences around them -- and it means nothing here may guard value.  The
real-proof fixture worlds shipped under `alberta_buck/test/vectors` were
proven with that setup.

## What needs a repository checkout

- New proofs: the circuits and proving keys live in the repository
  (`circuits/`, `make nix-snark-*`), not in this package.
- Worlds routed through Uniswap: Uniswap's contracts are not redistributed
  here, and those worlds load them from a checkout.
- The papers: executable Org documents in the repository.

## Status

0.2.0, prototype, protocol v2.  Unaudited.

## Licence

GPL-3.0-or-later.  The kernels and core platform it can use are CAL-1.0; see
[LICENSING.md](https://github.com/alberta-buck/alberta-buck/blob/master/LICENSING.md).

Repository: <https://github.com/alberta-buck/alberta-buck>
