Python SDK 4.8.0 — full 1:1 parity with TypeScript SDK 4.8.0

.gitignore

@@ -20,6 +20,10 @@ lib64/
 # generic `lib/` rule above is meant for build/venv directories.
 !src/agirails/cli/lib/
 !src/agirails/cli/lib/**
+# ...but the blanket un-ignore above also re-includes byte-compiled caches;
+# re-exclude them so __pycache__ under cli/lib stays out of the worktree status.
+src/agirails/cli/lib/**/__pycache__/
+src/agirails/cli/lib/**/*.py[cod]
 parts/
 sdist/
 var/

CHANGELOG.md

@@ -5,6 +5,60 @@ All notable changes to AGIRAILS Python SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.8.0] — 2026-06-19
+
+> **Full 1:1 parity with `@agirails/sdk` (TypeScript) 4.8.0.** The Python SDK
+> jumped 3.0.1 → 4.8.0 to align with the TS line after a six-wave parity
+> campaign closing 303 reported gaps (59 P0 · 162 P1 · 70 P2). Every
+> cross-SDK hashed/signed surface is now **byte-for-byte identical** to the TS
+> SDK, verified by 185 golden-vector tests generated from the real TS
+> functions. Test suite grew 2398 → 3312 passing.
+
+### Added
+
+- **AIP-16 secure delivery channel** (`agirails.delivery`): X25519 ECDH +
+  HKDF-SHA256 session keys, AES-256-GCM AEAD with `txId‖signer` AAD binding,
+  EIP-712 `DeliverySetup`/`DeliveryEnvelope` signing (domain `AGIRAILS
+  Delivery`), FIX-1 body encoding, Mock + Relay delivery channels. New
+  dependency: `cryptography`.
+- **Native x402 v2** `X402Adapter`: real EIP-3009 `TransferWithAuthorization`
+  signing + Permit2 (ERC-1271/ERC-6492 Smart-Wallet path), `x402Version=2`
+  `X-PAYMENT` header, opt-in safety gate, per-tx caps. Legacy direct-transfer
+  adapter preserved as `LegacyX402Adapter`. Auto-registered when the wallet
+  provider exposes `sign_typed_data`.
+- **AIP-2 `QuoteBuilder`** (EIP-712 signed, `agirails.quote.v1`); **AIP-7
+  receipt push** (`ReceiptWriteV2`, `receiptUrl`, `render_receipt_v3`);
+  **AIP-2.1** `ProviderOrchestrator`, buyer channel-driven multi-round
+  negotiation, injectable buyer/provider decider hooks, `NegotiationChannel`
+  (Mock + Relay).
+- **AIP-18** buyer privacy: `budget`/`claim_code` stripped from `configHash`,
+  pay-only off-chain short-circuit, V4 `AGIRAILS.md` parser, `buyer_link`,
+  gasless-buyer gate.
+- `ACTPClient` lifecycle methods (`start_work`/`deliver`/`release`/
+  `get_status`/`route_url_payment`/`get_activation_calls`/`to_json`/
+  `check_config_drift`); unified `UnifiedPayResult`; `actp agent` CLI command
+  (+ public-RPC warning), `.env` auto-load.
+
+### Fixed (cross-SDK correctness — were silent interop breaks)
+
+- **canonical JSON** now follows the ECMAScript Number→String algorithm
+  (integer-valued floats lose the fraction, `-0`→`0`, V8 positional/exponential
+  boundary) so keccak hashes match TS over any float-valued number.
+- **EIP-712 domain** `ACTP` → `AGIRAILS`; `ProofGenerator` defaults to
+  keccak256 (was sha256); `compute_output_hash` JSON-quotes string deliverables.
+- `kernel.submit_quote` (was missing → `AttributeError` on the on-chain QUOTED
+  path); ERC-8004 bridge now resolves against the **mode-derived** registry
+  (testnet clients no longer hit the mainnet registry); bytes32 keccak routing
+  key (was a JSON blob); `parse_deadline` semantics; AgentRegistry ABI refreshed
+  to the TS ABI; EAS 3-schema decode; runtime sweep adaptive `getLogs` chunking;
+  Smart-Wallet `create_transaction` routing; AA failover; Filebase AWS SigV4.
+
+### Known divergences (documented)
+
+- Arweave **upload** fails closed (ANS-104 DataItem signing is not byte-exact
+  achievable without the Irys lib); download + Filebase upload work.
+- x402 seller-side `buildX402Server` helper not ported (buyer SDK).
+
 ## [3.0.1] — 2026-05-24
 
 > README-only patch. The 3.0.0 long description on PyPI carried over

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agirails"
-version = "3.0.1"
+version = "4.8.0"
 description = "AGIRAILS Python SDK - Agent Commerce Transaction Protocol"
 readme = "README.md"
 license = "Apache-2.0"
@@ -46,13 +46,18 @@ dependencies = [
     # explicitly so the install doesn't depend on eth-account keeping it
     # in its requirement set.
     "eth-hash[pycryptodome]>=0.7.0,<1.0.0",
+    # AIP-16 delivery channel crypto: X25519 ECDH, HKDF-SHA256, AES-256-GCM
+    # (byte-exact parity with the TS delivery surface). pyca/cryptography.
+    "cryptography>=46.0.7,<49.0.0",
     "pydantic>=2.6.0,<3.0.0",
     "python-dateutil>=2.8.0,<3.0.0",
     "httpx>=0.27.0,<1.0.0",
     "typer>=0.12.0,<1.0.0",
     "rich>=13.0.0,<14.0.0",
     # AGIRAILS.md frontmatter parsing in config.agirailsmd.
     "pyyaml>=6.0,<7.0",
+    # CLI .env auto-load (AIP-18 §4.6.2) — parity with the TS CLI dotenv load.
+    "python-dotenv>=1.0.0,<2.0.0",
     "typing_extensions>=4.0.0,<5.0.0;python_version<'3.10'",
 ]
 
@@ -84,6 +89,11 @@ mutation = [
 server = [
     "fastapi>=0.110.0",             # actp serve daemon (AIP-2.1 quote channel)
     "uvicorn>=0.30.0",
+    # CVE-2026-54283 fix is starlette 1.3.1. fastapi only pulls starlette 1.x on
+    # Python >=3.10 (fastapi>=0.129 requires 3.10+); on 3.9 it pulls the
+    # unaffected 0.x line. So force the fix only where the vulnerable 1.3.0 would
+    # otherwise be resolved — keeps the package installable on 3.9.
+    "starlette>=1.3.1; python_version >= '3.10'",
 ]
 
 [project.scripts]

scripts/test_installed_wheel.sh

@@ -55,12 +55,13 @@ trap 'rm -rf "$SMOKE_VENV"' EXIT
 
 echo "== imports =="
 "$SMOKE_VENV/bin/python" - <<'PYEOF'
+import re
 import sys
 
 import agirails
 print(f"version: {agirails.__version__}")
-assert agirails.__version__.startswith("3."), \
-    f"version {agirails.__version__} doesn't start with 3.x"
+assert re.match(r"^\d+\.\d+\.\d+", agirails.__version__), \
+    f"version {agirails.__version__} is not a valid semantic version"
 
 # Top-level re-exports promised in CHANGELOG.
 from agirails import (

src/agirails/__init__.py

@@ -34,390 +34,419 @@
 - `storage`: Hybrid storage layer (AIP-7 §4) - IPFS (Filebase) + Arweave (Irys)
 """
 
 from agirails.version import __version__, __version_info__
 
 # Client
 from agirails.client import (
     ACTPClient,
     ACTPClientConfig,
     ACTPClientInfo,
     ACTPClientMode,
 )
 
 # Adapters
 from agirails.adapters import (
     BaseAdapter,
     BasicAdapter,
     BasicPayParams,
     BasicPayResult,
     CheckStatusResult,
     StandardAdapter,
     StandardTransactionParams,
     TransactionDetails,
+    TransactionStatus,
     X402Adapter,
     DEFAULT_DEADLINE_SECONDS,
     DEFAULT_DISPUTE_WINDOW_SECONDS,
     MIN_AMOUNT_WEI,
     MAX_DEADLINE_HOURS,
     MAX_DEADLINE_DAYS,
 )
 
 # Wallet providers (Tier 1 = AA gasless, Tier 2 = EOA)
 from agirails.wallet import (
     AutoWalletProvider,
     EOAWalletProvider,
     IWalletProvider,
     WalletTier,
     WalletInfo,
 )
 
 # ERC-8004 identity + reputation
 from agirails.erc8004 import (
     ERC8004Bridge,
     ReputationReporter,
 )
 
 # Service discovery (agirails.app API)
 from agirails.api import discover_agents
 
 # Transaction ID computation (canonical hash used by Smart Wallet
 # routing + AIP-2 quote anchoring)
 from agirails.wallet.aa.transaction_batcher import compute_transaction_id
 
 # Runtime Layer
 from agirails.runtime import (
     # Types
     State,
     TransactionStateValue,
     MockTransaction,
     MockEscrow,
     MockAccount,
     MockBlockchain,
     MockEvent,
     MockState,
     STATE_TRANSITIONS,
     is_valid_transition,
     is_terminal_state,
     MOCK_STATE_DEFAULTS,
     # Interfaces
     CreateTransactionParams,
     TimeInterface,
     IACTPRuntime,
     IMockRuntime,
     is_mock_runtime,
     # Implementations
     MockStateManager,
     MockRuntime,
 )
 
 # Errors
 from agirails.errors import (
     ACTPError,
     TransactionNotFoundError,
     InvalidStateTransitionError,
     EscrowNotFoundError,
     DeadlinePassedError,
     DeadlineExpiredError,
     DisputeWindowActiveError,
     ContractPausedError,
     InsufficientBalanceError,
     ValidationError,
     InvalidAddressError,
     InvalidAmountError,
     NetworkError,
     TransactionRevertedError,
     SignatureVerificationError,
     StorageError,
     InvalidCIDError,
     UploadTimeoutError,
     DownloadTimeoutError,
     FileSizeLimitExceededError,
     StorageAuthenticationError,
     StorageRateLimitError,
     ContentNotFoundError,
     NoProviderFoundError,
     ACTPTimeoutError,
     ProviderRejectedError,
     DeliveryFailedError,
     DisputeRaisedError,
     ServiceConfigError,
     AgentLifecycleError,
     QueryCapExceededError,
     MockStateCorruptedError,
     MockStateVersionError,
     MockStateLockError,
 )
 
 # Utilities - Security
 from agirails.utils import (
     timing_safe_equal,
     validate_path,
     validate_service_name,
     is_valid_address,
     safe_json_parse,
     LRUCache,
     Logger,
     Semaphore,
     RateLimiter,
     # PARITY: SecureNonce
     generate_secure_nonce,
     is_valid_nonce,
     generate_secure_nonces,
     # PARITY: UsedAttestationTracker
     IUsedAttestationTracker,
     InMemoryUsedAttestationTracker,
     FileBasedUsedAttestationTracker,
     create_used_attestation_tracker,
     # PARITY: ReceivedNonceTracker
     NonceValidationResult,
     IReceivedNonceTracker,
     InMemoryReceivedNonceTracker,
     SetBasedReceivedNonceTracker,
     create_received_nonce_tracker,
 )
 
 # Utilities - Helpers
 from agirails.utils.helpers import (
     USDC,
     Deadline,
     Address,
     Bytes32,
     StateHelper,
     DisputeWindow,
     ServiceHash,
     ServiceMetadata,
     parse_usdc,
     format_usdc,
     shorten_address,
     hash_service_metadata,
 )
 
 # Utilities - Validation
 from agirails.utils.validation import (
     validate_address,
     validate_amount,
     validate_deadline,
     validate_tx_id,
     validate_endpoint_url,
     validate_dispute_window,
     validate_bytes32,
 )
 
 # Utilities - Canonical JSON
 from agirails.utils.canonical_json import (
     canonical_json_dumps,
     compute_type_hash,
     hash_struct,
     compute_domain_separator,
 )
 
 # Level 0 API - Low-level primitives
 from agirails.level0 import (
     ServiceDirectory,
     ServiceEntry,
     ServiceQuery,
     Provider,
     ProviderConfig,
     ProviderStatus,
     provide,
     ProvideOptions,
     request,
     RequestOptions,
     RequestResult,
 )
 
 # Level 1 API - Agent abstraction
 from agirails.level1 import (
     Agent,
     AgentConfig,
     AgentBehavior,
     AgentStatus,
     AgentStats,
     AgentBalance,
     Job,
     JobContext,
     JobHandler,
     JobResult,
     ServiceConfig,
     ServiceFilter,
     RetryConfig,
     PricingStrategy,
     CostModel,
     PriceCalculation,
     calculate_price,
 )
 
 # Types
 from agirails.types import (
     AgentDID,
     DIDDocument,
     Transaction,
     TransactionState,
     TransactionReceipt,
     TransactionFilter,
     EIP712Domain,
     ServiceRequest,
     ServiceResponse,
     DeliveryProof,
     DeliveryProofMessage,
     DeliveryProofMetadata,
     SignedMessage,
     TypedData,
     compute_result_hash,
 )
 
 # Protocol Layer (PARITY: Match TS SDK exports)
 from agirails.protocol import (
     # Messages
     MessageSigner,
     SignatureComponents,
     hash_typed_data,
     create_typed_data,
     HAS_MESSAGES,
     # Proofs
     ProofGenerator,
     ContentProof,
     MerkleProof,
     verify_merkle_proof,
     hash_service_input,
     hash_service_output,
     # DID
     DIDManager,
     DIDResolver,
     VerificationMethod,
     ServiceEndpoint,
     create_did_from_address,
     did_to_address,
 )
 
 # Protocol modules (conditional, require web3)
 try:
     from agirails.protocol import (
         # Kernel
         ACTPKernel,
         TransactionView,
         # Escrow
         EscrowVault,
         CreateEscrowParams,
         EscrowInfo,
         generate_escrow_id,
         # Events
         EventMonitor,
         EventFilter,
         EventType,
         ACTPEvent,
         TransactionCreatedEvent,
         StateTransitionedEvent,
         EscrowCreatedEvent,
         EscrowPayoutEvent,
         # Nonce
         NonceManager,
         NonceManagerPool,
         # EAS
         EASHelper,
         Attestation,
         DeliveryAttestationData,
         Schema,
         DELIVERY_SCHEMA,
         ZERO_BYTES32,
         # Agent Registry
         AgentRegistry,
         AgentProfile,
         ServiceDescriptor,
         compute_service_type_hash,
     )
     HAS_WEB3_PROTOCOL = True
 except ImportError:
     HAS_WEB3_PROTOCOL = False
 
 # Builders
 from agirails.builders import (
     CounterAcceptBuilder,
     CounterAcceptMessage,
     CounterAcceptParams,
     CounterOfferBuilder,
     CounterOfferJustification,
     CounterOfferMessage,
     CounterOfferParams,
     DeliveryProofBuilder,
+    LegacyQuoteBuilder,
     MessageNonceManager,
     QuoteBuilder,
+    QuoteMessage,
+    QuoteParams,
+    AIP2QuoteTypes,
 )
 
 # Web Receipts (AIP-7 §6 — agirails.app public receipt artifact)
 from agirails.receipts import (
     ReceiptUploadFailure,
     ReceiptUploadOptions,
     ReceiptUploadPayload,
     ReceiptUploadResult,
     ReceiptUploadSuccess,
     upload_receipt,
+    push_receipt_on_settled,
+    format_settled_line,
+    PushReceiptArgs,
+    PushReceiptResult,
 )
 
 # Storage Layer (AIP-7 §4 - Hybrid Storage)
 from agirails.storage import (
     # Clients
     FilebaseClient,
     ArweaveClient,
     # Builders
     ArchiveBundleBuilder,
     compute_content_hash,
     compute_json_hash,
     validate_archive_bundle,
     PROTOCOL_VERSION,
     ARCHIVE_SCHEMA_VERSION,
     # Types - Filebase
     FilebaseConfig,
     # Types - Arweave
     ArweaveConfig,
     IrysCurrency,
     IrysNetwork,
     # Types - Archive Bundle
     ArchiveBundle,
     ArchiveChainId,
     ArchiveFinalState,
     ArchiveParticipants,
     ArchiveReferences,
     ArchiveHashes,
     ArchiveSignatures,
     ArchiveAttestation,
     ArchiveSettlement,
     EscrowRelease,
     ArchiveTags,
     ARCHIVE_BUNDLE_TYPE,
     # Types - Results
     IPFSUploadResult,
     ArweaveUploadResult,
     DownloadResult,
     # Types - Circuit Breaker
     CircuitBreakerConfig,
 )
 
 # Negotiation Module (autonomous buyer-side negotiation)
 from agirails.negotiation import (
     DEFAULT_WEIGHTS,
     PolicyEngine,
     BuyerPolicy,
     Constraints,
     MaxUnitPrice,
     MaxDailySpend,
     Negotiation,
     Selection,
     QuoteOffer,
     PolicyViolation,
     PolicyResult,
     DecisionEngine,
     ScoringWeights,
     CandidateStats,
     ScoredCandidate,
     ScoreBreakdown,
     SessionStore,
     SessionMapping,
     BuyerOrchestrator,
     NegotiationResult,
     RoundResult,
     OrchestratorConfig,
+    RequoteGuardViolation,
+    ProviderPolicyEngine,
+    verify_quote_hash_on_chain,
+    VerifyOnChainResult,
+)
+
+# AIP-16 secure delivery channel (encrypted envelopes, EIP-712, Mock/Relay).
+from agirails.delivery import (
+    DeliverySetupBuilder,
+    BuildSetupParams,
+    DeliveryEnvelopeBuilder,
+    BuildPublicEnvelopeParams,
+    BuildEncryptedEnvelopeParams,
+    MockDeliveryChannel,
+    MockDeliveryChannelOptions,
+    RelayDeliveryChannel,
+    RelayDeliveryChannelOptions,
+    DeliveryChannel,
+    DeliverySubscription,
+    build_envelope_aad,
 )
 
 __all__ = [
     # Version
@@ -437,6 +466,7 @@
     "StandardAdapter",
     "StandardTransactionParams",
     "TransactionDetails",
+    "TransactionStatus",
     "X402Adapter",
     "DEFAULT_DEADLINE_SECONDS",
     "DEFAULT_DISPUTE_WINDOW_SECONDS",
@@ -665,6 +695,10 @@
     # Builders
     "DeliveryProofBuilder",
     "QuoteBuilder",
+    "QuoteMessage",
+    "QuoteParams",
+    "AIP2QuoteTypes",
+    "LegacyQuoteBuilder",
     "CounterOfferBuilder",
     "CounterOfferMessage",
     "CounterOfferParams",
@@ -680,6 +714,10 @@
     "ReceiptUploadResult",
     "ReceiptUploadSuccess",
     "upload_receipt",
+    "push_receipt_on_settled",
+    "format_settled_line",
+    "PushReceiptArgs",
+    "PushReceiptResult",
     # Storage Layer (AIP-7 §4 - Hybrid Storage)
     # Clients
     "FilebaseClient",
@@ -736,6 +774,23 @@
     "SessionStore",
     "SessionMapping",
     "BuyerOrchestrator",
+    "ProviderPolicyEngine",
+    "verify_quote_hash_on_chain",
+    "VerifyOnChainResult",
+    "RequoteGuardViolation",
+    # AIP-16 delivery channel
+    "DeliverySetupBuilder",
+    "BuildSetupParams",
+    "DeliveryEnvelopeBuilder",
+    "BuildPublicEnvelopeParams",
+    "BuildEncryptedEnvelopeParams",
+    "MockDeliveryChannel",
+    "MockDeliveryChannelOptions",
+    "RelayDeliveryChannel",
+    "RelayDeliveryChannelOptions",
+    "DeliveryChannel",
+    "DeliverySubscription",
+    "build_envelope_aad",
     "NegotiationResult",
     "RoundResult",
     "OrchestratorConfig",