sardis-core
Core AP2/TAP-aligned domain primitives for the Sardis stablecoin execution layer.
Overview
sardis-core provides foundational components shared across all Sardis services:
- Domain Models: Wallets, transactions, holds, agents, mandates, and virtual cards
- Configuration Management: Deterministic config loading with validation
- Security Utilities: Ed25519/ECDSA key management, MPC connectors
- Resilience Patterns: Retry mechanisms, circuit breakers, rate limiting
- Structured Logging: Sensitive data masking, request tracing
- Validation: Comprehensive input validation for payments and blockchain data
Installation
pip install sardis-core
Optional Dependencies
# For natural language policy parsing (OpenAI-powered)
pip install sardis-core[nl-parser]
# For Redis-based spending tracking
pip install sardis-core[spending-tracker]
# Install all optional dependencies
pip install sardis-core[all]
Quick Start
from sardis_v2_core import (
# Configuration
load_config_from_env,
validate_startup,
# Domain models
Wallet,
Transaction,
Hold,
Agent,
# Utilities
retry,
get_circuit_breaker,
get_logger,
validate_wallet_id,
)
# Load and validate configuration
config = load_config_from_env()
validate_startup(config)
# Get a structured logger
logger = get_logger("my_service")
# Use retry with exponential backoff
@retry(max_attempts=3, base_delay=1.0)
async def fetch_wallet(wallet_id: str) -> Wallet:
validate_wallet_id(wallet_id)
# ... fetch wallet logic
Features
Domain Models
from sardis_v2_core import Wallet, Transaction, TransactionStatus
# Create a wallet
wallet = Wallet(
wallet_id="wal_abc123",
owner_id="user_xyz",
chain="base",
address="0x...",
)
# Track transactions
tx = Transaction(
tx_id="tx_123",
wallet_id=wallet.wallet_id,
amount=100_00, # $100.00 in cents
status=TransactionStatus.PENDING,
)
Resilience Patterns
from sardis_v2_core import (
retry_async,
get_circuit_breaker,
CircuitBreakerConfig,
)
# Circuit breaker for external services
cb = get_circuit_breaker(
"mpc_service",
config=CircuitBreakerConfig(
failure_threshold=5,
recovery_timeout=30.0,
)
)
async with cb:
result = await call_mpc_service()
Structured Logging
from sardis_v2_core import get_logger, mask_sensitive_data
logger = get_logger("payments")
# Automatically masks sensitive fields
logger.info("Processing payment", extra={
"wallet_id": "wal_123",
"amount": 1000,
"card_number": "4111111111111111", # Will be masked
})
Architecture
sardis-core is designed as a pure domain library with no persistence or transport dependencies:
sardis-core/
├── exceptions.py # Comprehensive error hierarchy
├── config.py # Configuration models and loading
├── validators.py # Input validation utilities
├── retry.py # Retry mechanisms with backoff
├── circuit_breaker.py # Circuit breaker pattern
├── logging.py # Structured logging with masking
├── wallets.py # Wallet domain models
├── transactions.py # Transaction models
├── holds.py # Payment hold models
├── agents.py # AI agent models
├── mandates.py # AP2 mandate models
└── ...
Requirements
- Python 3.11+
- pydantic >= 2.6
- pydantic-settings >= 2.0
- PyNaCl >= 1.5
- cryptography >= 41.0
Documentation
Full documentation is available at docs.sardis.sh.
License
MIT License - see LICENSE for details.
Contributing
Contributions are welcome! Please see our Contributing Guide for details.
Metadata
Release files for sardis-core 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sardis_core-1.1.0.tar.gz | 461.6 kB | Without provenance | Details for sardis_core-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sardis_core-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for sardis_core-1.1.0-py3-none-any.whl |
Total release size: 963.2 kB
Release files / sardis_core-1.1.0.tar.gz
| Download URL | sardis_core-1.1.0.tar.gz |
|---|---|
| Size | 461.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b9f5838be021ef16f022dac1a43c0425bf79be8f83f37a1ba09c4807797c288d
|
|
BLAKE2b-256 checksum How to use checksums |
7e60659101ceeae8e3bfd68f96a0df2cebe341d507d2f40390fe825baddefae2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.22 {"installer":{"name":"uv","version":"0.9.22","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 / sardis_core-1.1.0-py3-none-any.whl
| Download URL | sardis_core-1.1.0-py3-none-any.whl |
|---|---|
| Size | 501.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c5bd90b44eaba58396abcbb9cf86f9aac59e6f0c2972e7c2481679912c37a8bc
|
|
BLAKE2b-256 checksum How to use checksums |
1de54a17ffd9cea4d7b2f7401bd9810fa86999b084cbf06ba3d71dc0c05cd304
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.22 {"installer":{"name":"uv","version":"0.9.22","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 sardis-core 1.1.0
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.