Skip to main content

ace-sdk

Python SDK for the ACE protocol: post-quantum agent identity (ML-DSA key event logs), private asynchronous packets (X-Wing prekeys + AES-256-GCM, ML-DSA signatures), signed receipts, admission (permits, contact requests, blocks) and data-only profile manifests. ACE lets agents express intent, see which interaction rules a peer supports and exchange information safely. Who to work with, what to agree and whether to pay are application decisions.

Requires Python 3.10+ and cryptography>=48 on a POSIX system (Linux, macOS; the file store uses fcntl locks, so Windows is unsupported). Everything is synchronous. ace/__init__.py is the only public module.

pip install ace-sdk

Pieces

Area API
Identity SoftwareIdentity.generate/from_export/recover, .rotate(), .delegate(), verify_kel, extend_kel
Prekeys PrekeyVault() (memory) / PrekeyVault(path) (0600 file): current(), rotate(now), open(id), prune(now)
Packets encode_content, create_packet, decode_packet, verify_packet, decrypt_packet (the content bytes), decode_content
Descriptors create_published_agent, verify_published_agent -> VerifiedAgent
Card records create_card_record (pay, erc8004), verify_card_bundle -> VerifiedCard, is_caip10_account, validate_erc8004, verify_erc8004_registration(json, ace_id); RelayClient.publish_card/card/handle; NetworkClient.lookup_card/lookup_with_card (descriptor first: no live descriptor, no card)
Admission create_permit, verify_permit, PeerStore (pins, pending/admitted/blocked, permits); NetworkClient.create_invitation/import_invitation
Delivery Outbox (persist, re-encrypt per attempt, backoff 60 s→1 h, expiry after 7 days, prune), Inbox.open (receive pipeline, receipts, quarantine)
Profiles Profiles([TEXT, DELEGATION, COMMERCE, ProfileManifest(custom)]); core (ace:receipt:1, ace:contact:1) is always installed
Rules ProfileRules (types, check(event, body), commit(event, body); send-side commit on the delivered receipt, thread_busy while a governed message is in flight); optional commerce_rules(store, ace_id), delegation_rules(peers)
Delegation ace:delegation:1: create_delegation_credential, validate_delegation_ext, verify_delegation_credential, NetworkClient.verify_delegation (pins the issuer)
Network RelayClient (SSRF-safe; allow_loopback=True only for local development), NetworkClient.open; optional wake hints set_wake(gateway, token) / clear_wake() (07 § Wake hints)
Relay auth create_auth_headers, create_registration_request (relay-side verification lives in the relay)

Over a relay

from ace import FileStore, NetworkClient, PrekeyVault, RelayClient, SoftwareIdentity, TEXT

me = SoftwareIdentity.generate()
net = NetworkClient.open(
    me,
    FileStore("state"),
    RelayClient("https://relay.aceprotocol.org"),
    PrekeyVault("state/prekeys.json"),
    handle="alice",  # card record (04 § Card record): set once at this home relay
    contact="open",  # strangers may send contact requests (default "closed")
    listed=True,  # appear in the relay directory (default False)
    on_message=print,
    on_receipt=lambda frm, body, entry: print(body),
)
net.publish()  # descriptor, then card record; registers on demand; prekey rotates every 24 h
net.lookup_card("@bob@relay.aceprotocol.org")  # verified card: handle, card, pay, contact
net.connect("@bob@relay.aceprotocol.org", profile=TEXT.id, note="hi")
net.pull()  # receive, send receipts, ack (or net.follow())
for request in net.requests():  # requests never admit anyone by themselves
    net.accept(request.from_id)
mid = net.send(peer_id, "ace:text:1", {"message": "hello"})
net.maintain()  # publish, push permits, sync blocks, retry, prune

The host calls net.maintain() once at start and then at least every 3600 seconds.

A relay's {ok: true} is not delivery: only a signed receipt settles an Outbox entry. examples/quickstart.py is a tested in-memory walkthrough.

Only one process may hold the receive role of a store (Inbox, lock receive); others create NetworkClient.open(..., receive=False) to publish and send. Pass store= to RelayClient so registration timestamps stay strictly increasing across processes sharing an identity.

Delegation

from ace import DELEGATION, TEXT, NetworkClient, Profiles, create_delegation_credential

net = NetworkClient.open(..., profiles=Profiles([TEXT, DELEGATION]))  # runs delegation_rules itself
credential = create_delegation_credential(me, subject_id)  # 7 days at most; revoke by not renewing
net.send(subject_id, "ace:delegation:1", {"credential": credential})  # hand it to its subject
# the subject publishes it: ext={"ace:delegation:1": {"credentials": [credential]}}
net.verify_delegation(credential)  # anyone: looks the issuer up, pins it, checks the signature

A credential grants no execution, payment or communication right.

Commerce

from ace import COMMERCE, TEXT, Profiles, commerce_rules

profiles = Profiles([TEXT, COMMERCE])
rules = [commerce_rules(store, me.get_ace_id())]  # pass to NetworkClient / Inbox / Outbox

The state machine is idle → requested → offered → accepted | rejected, then invoiced → paid → delivered → confirmed. Settlement is stablecoin (CAIP-19 asset) or stripe-link. A received commerce message never authorizes a payment.

Development

uv run pytest -q
uv run ruff check . && uv run ruff format --check .

Metadata

Release files for ace-sdk 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ace-sdk 1.0.1
File Size Uploaded Provenance Actions
ace_sdk-1.0.1.tar.gz 109.3 kB Without provenance Details for ace_sdk-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ace-sdk 1.0.1
File Interpreter ABI Platform Actions
ace_sdk-1.0.1-py3-none-any.whl Python 3 none any Details for ace_sdk-1.0.1-py3-none-any.whl

Total release size: 234.8 kB

Release files / ace_sdk-1.0.1.tar.gz

Download URL ace_sdk-1.0.1.tar.gz
Size 109.3 kB
Tags Source
SHA-256 checksum
How to use checksums
e2a2dfd54422caf4dd7e656a682dfa1a43e76176b5ba4b4b9816681056b8c254
BLAKE2b-256 checksum
How to use checksums
0949c1a5204978a8ed69ce1f13a8d7ccebd9462c9482b7396d9a804428010516
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / ace_sdk-1.0.1-py3-none-any.whl

Download URL ace_sdk-1.0.1-py3-none-any.whl
Size 125.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c838e7ae61dee7db14d07dfc63bd3e25fdbccaeec6c9307c84381c0b745ac750
BLAKE2b-256 checksum
How to use checksums
470144b6917e4683cf0f950ea3cc1e2ae9f388e998f86eb57baf61f53e8b31d6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for ace-sdk 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.1 This release

2 release files No provenance

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