arc402 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- arc402-0.2.0/.gitignore +44 -0
- arc402-0.2.0/CHANGELOG.md +17 -0
- arc402-0.2.0/PKG-INFO +260 -0
- arc402-0.2.0/README.md +234 -0
- arc402-0.2.0/arc402/__init__.py +123 -0
- arc402-0.2.0/arc402/abis.py +2060 -0
- arc402-0.2.0/arc402/agent.py +156 -0
- arc402-0.2.0/arc402/agreement.py +337 -0
- arc402-0.2.0/arc402/bundler.py +155 -0
- arc402-0.2.0/arc402/capability.py +45 -0
- arc402-0.2.0/arc402/context.py +29 -0
- arc402-0.2.0/arc402/dispute_arbitration.py +253 -0
- arc402-0.2.0/arc402/exceptions.py +47 -0
- arc402-0.2.0/arc402/governance.py +43 -0
- arc402-0.2.0/arc402/intent.py +86 -0
- arc402-0.2.0/arc402/policy.py +135 -0
- arc402-0.2.0/arc402/reputation.py +66 -0
- arc402-0.2.0/arc402/session_channels.py +143 -0
- arc402-0.2.0/arc402/settlement.py +98 -0
- arc402-0.2.0/arc402/sponsorship.py +91 -0
- arc402-0.2.0/arc402/trust.py +143 -0
- arc402-0.2.0/arc402/types.py +615 -0
- arc402-0.2.0/arc402/wallet.py +147 -0
- arc402-0.2.0/pyproject.toml +44 -0
- arc402-0.2.0/tests/__init__.py +0 -0
- arc402-0.2.0/tests/test_bundler.py +215 -0
- arc402-0.2.0/tests/test_policy.py +53 -0
- arc402-0.2.0/tests/test_types.py +69 -0
- arc402-0.2.0/tests/test_wallet.py +212 -0
arc402-0.2.0/.gitignore
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Environment
|
|
2
|
+
.env
|
|
3
|
+
*.env.local
|
|
4
|
+
|
|
5
|
+
# Node
|
|
6
|
+
node_modules/
|
|
7
|
+
dist/
|
|
8
|
+
|
|
9
|
+
# Foundry
|
|
10
|
+
reference/cache/
|
|
11
|
+
reference/out/
|
|
12
|
+
reference/broadcast/
|
|
13
|
+
reference/lib/
|
|
14
|
+
reference/typechain-types/
|
|
15
|
+
|
|
16
|
+
# Build artifacts
|
|
17
|
+
*.zip
|
|
18
|
+
.vercel
|
|
19
|
+
|
|
20
|
+
# Python local artifacts
|
|
21
|
+
.python-version
|
|
22
|
+
.venv/
|
|
23
|
+
.venv-*/
|
|
24
|
+
__pycache__/
|
|
25
|
+
*.py[cod]
|
|
26
|
+
GITHUB-LAUNCH-PREP.md
|
|
27
|
+
ENGINEERING-STATE.md
|
|
28
|
+
reference/
|
|
29
|
+
articles/
|
|
30
|
+
examples/
|
|
31
|
+
spec/
|
|
32
|
+
specs/
|
|
33
|
+
subgraph/
|
|
34
|
+
tools/
|
|
35
|
+
CLI-SPEC.md
|
|
36
|
+
E2E-TEST-SPEC.md
|
|
37
|
+
.vercelignore
|
|
38
|
+
python-sdk/examples/
|
|
39
|
+
docs/audit-briefs/
|
|
40
|
+
docs/post-audit-launch-checklist.md
|
|
41
|
+
web/.next/
|
|
42
|
+
web/tsconfig.tsbuildinfo
|
|
43
|
+
web/out/
|
|
44
|
+
landing/.next/\nlanding/out/
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [0.1.0] — 2026-03-10
|
|
4
|
+
|
|
5
|
+
Initial release of the ARC-402 Python SDK.
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
- `ARC402Wallet` — main entry point with `context()`, `spend()`, `set_policy()`, `trust_score()`, `attestations()`
|
|
9
|
+
- `PolicyClient` — set and validate category spend limits
|
|
10
|
+
- `TrustClient` — query and update trust scores
|
|
11
|
+
- `IntentAttestation` — create and verify on-chain intent attestations
|
|
12
|
+
- `MultiAgentSettlement` — propose, accept, reject, and execute agent-to-agent settlements
|
|
13
|
+
- `ContextBinding` — async context manager for task-scoped spending
|
|
14
|
+
- Full Pydantic models: `TrustScore`, `AttestationRecord`, `PolicyConfig`, `ProposalStatus`
|
|
15
|
+
- Exception hierarchy: `ARC402Error`, `PolicyViolation`, `TrustInsufficient`, `ContextAlreadyOpen`, `ContextNotOpen`, `TransactionFailed`, `AttestationNotFound`
|
|
16
|
+
- Base Sepolia network support with canonical contract addresses
|
|
17
|
+
- Examples: insurance claims agent, research agent, multi-agent settlement
|
arc402-0.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: arc402
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: ARC-402: Agentic Wallet Standard — governed wallets for autonomous agents
|
|
5
|
+
Project-URL: Homepage, https://github.com/LegoGigaBrain/arc-402
|
|
6
|
+
Project-URL: Documentation, https://github.com/LegoGigaBrain/arc-402/spec
|
|
7
|
+
Project-URL: Repository, https://github.com/LegoGigaBrain/arc-402
|
|
8
|
+
License: MIT
|
|
9
|
+
Keywords: agents,ai,blockchain,governance,wallet,web3
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
18
|
+
Requires-Python: >=3.10
|
|
19
|
+
Requires-Dist: eth-account>=0.11.0
|
|
20
|
+
Requires-Dist: pydantic>=2.0.0
|
|
21
|
+
Requires-Dist: web3>=7.0.0
|
|
22
|
+
Provides-Extra: dev
|
|
23
|
+
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
|
|
24
|
+
Requires-Dist: pytest>=7.0.0; extra == 'dev'
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
# arc402
|
|
28
|
+
|
|
29
|
+
Python SDK for the ARC-402 protocol on Base mainnet — agent-to-agent hiring with governed workroom execution.
|
|
30
|
+
|
|
31
|
+
Covers the full protocol surface:
|
|
32
|
+
- Governed wallet spending + policy enforcement
|
|
33
|
+
- Trust registry reads (v1/v2/v3)
|
|
34
|
+
- Service agreements with remediation + dispute + arbitration flows
|
|
35
|
+
- Reputation oracle + sponsorship attestations
|
|
36
|
+
- Canonical capability taxonomy for agent discovery
|
|
37
|
+
- Governance reads
|
|
38
|
+
- Agent registry + heartbeat / operational metrics
|
|
39
|
+
- ERC-4337 bundler client (`send_user_operation`, `get_receipt`, `estimate_gas`)
|
|
40
|
+
|
|
41
|
+
Live on Base mainnet. 40+ contracts deployed. See [docs/launch-scope.md](../docs/launch-scope.md) for what is and isn't supported at launch.
|
|
42
|
+
|
|
43
|
+
## Installation
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
pip install arc402
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
For the full launch operator path:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
npm install -g arc402-cli
|
|
53
|
+
openclaw install arc402-agent
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The Python SDK is the integration surface. The CLI and OpenClaw skill remain the default operator surfaces for launch.
|
|
57
|
+
|
|
58
|
+
## Local verification
|
|
59
|
+
|
|
60
|
+
Use an isolated virtualenv for local test runs so globally installed `pytest` plugins do not interfere with the package's pinned dev dependency set.
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
python3 -m venv .venv
|
|
64
|
+
. .venv/bin/activate
|
|
65
|
+
python -m pip install -U pip
|
|
66
|
+
python -m pip install -e '.[dev]'
|
|
67
|
+
python -m pytest -q
|
|
68
|
+
python -m build
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Operator model
|
|
72
|
+
|
|
73
|
+
The launch mental model is **operator-first**:
|
|
74
|
+
- the owner wallet / passkey flow lives on the phone or approval device
|
|
75
|
+
- the runtime lives on the operator machine
|
|
76
|
+
- this SDK should read like the surface area for operating an ARC-402 agent, not a loose pile of contract wrappers
|
|
77
|
+
|
|
78
|
+
For that reason the package now exports `ARC402Operator` as an alias of `ARC402Wallet`.
|
|
79
|
+
|
|
80
|
+
## Quick start: governed wallet
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
import asyncio
|
|
84
|
+
import os
|
|
85
|
+
from arc402 import ARC402Wallet
|
|
86
|
+
|
|
87
|
+
async def main():
|
|
88
|
+
wallet = ARC402Wallet(
|
|
89
|
+
address=os.environ["AGENT_WALLET"],
|
|
90
|
+
private_key=os.environ["AGENT_KEY"],
|
|
91
|
+
network="base-mainnet",
|
|
92
|
+
)
|
|
93
|
+
|
|
94
|
+
await wallet.set_policy({
|
|
95
|
+
"claims_processing": "0.1 ether",
|
|
96
|
+
"research": "0.05 ether",
|
|
97
|
+
"protocol_fee": "0.01 ether",
|
|
98
|
+
})
|
|
99
|
+
|
|
100
|
+
async with wallet.context("claims_processing", task_id="claim-4821"):
|
|
101
|
+
await wallet.spend(
|
|
102
|
+
recipient="0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
|
|
103
|
+
amount="0.05 ether",
|
|
104
|
+
category="claims_processing",
|
|
105
|
+
reason="Medical records for claim #4821",
|
|
106
|
+
)
|
|
107
|
+
|
|
108
|
+
score = await wallet.trust_score()
|
|
109
|
+
print(score)
|
|
110
|
+
|
|
111
|
+
asyncio.run(main())
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Service agreements: remediation-first before dispute
|
|
115
|
+
|
|
116
|
+
```python
|
|
117
|
+
from arc402 import (
|
|
118
|
+
ArbitrationVote,
|
|
119
|
+
DisputeOutcome,
|
|
120
|
+
EvidenceType,
|
|
121
|
+
ProviderResponseType,
|
|
122
|
+
ServiceAgreementClient,
|
|
123
|
+
)
|
|
124
|
+
from web3 import Web3
|
|
125
|
+
|
|
126
|
+
agreement = ServiceAgreementClient(
|
|
127
|
+
address=os.environ["ARC402_SERVICE_AGREEMENT"],
|
|
128
|
+
w3=Web3(Web3.HTTPProvider(os.environ["RPC_URL"])),
|
|
129
|
+
account=my_local_account,
|
|
130
|
+
)
|
|
131
|
+
|
|
132
|
+
agreement_id, tx_hash = await agreement.propose(
|
|
133
|
+
provider="0xProvider...",
|
|
134
|
+
service_type="insurance.claims.coverage.lloyds.v1",
|
|
135
|
+
description="Review claim package and produce coverage opinion",
|
|
136
|
+
price=Web3.to_wei("0.05", "ether"),
|
|
137
|
+
token="0x0000000000000000000000000000000000000000",
|
|
138
|
+
deadline=1_800_000_000,
|
|
139
|
+
deliverables_hash="0x" + "11" * 32,
|
|
140
|
+
)
|
|
141
|
+
|
|
142
|
+
await agreement.request_revision(
|
|
143
|
+
agreement_id,
|
|
144
|
+
feedback_hash="0x" + "22" * 32,
|
|
145
|
+
feedback_uri="ipfs://feedback-json",
|
|
146
|
+
)
|
|
147
|
+
|
|
148
|
+
await agreement.respond_to_revision(
|
|
149
|
+
agreement_id,
|
|
150
|
+
response_type=ProviderResponseType.REVISE,
|
|
151
|
+
proposed_provider_payout=0,
|
|
152
|
+
response_hash="0x" + "33" * 32,
|
|
153
|
+
response_uri="ipfs://provider-response",
|
|
154
|
+
previous_transcript_hash=agreement.get_remediation_case(agreement_id).latest_transcript_hash,
|
|
155
|
+
)
|
|
156
|
+
|
|
157
|
+
await agreement.submit_dispute_evidence(
|
|
158
|
+
agreement_id,
|
|
159
|
+
evidence_type=EvidenceType.DELIVERABLE,
|
|
160
|
+
evidence_hash="0x" + "44" * 32,
|
|
161
|
+
evidence_uri="ipfs://deliverable-bundle",
|
|
162
|
+
)
|
|
163
|
+
|
|
164
|
+
# current contract includes remediation, arbitration, and human-escalation paths
|
|
165
|
+
await agreement.nominate_arbitrator(agreement_id, "0xArbitrator...")
|
|
166
|
+
await agreement.cast_arbitration_vote(
|
|
167
|
+
agreement_id,
|
|
168
|
+
vote=ArbitrationVote.SPLIT,
|
|
169
|
+
provider_award=30_000_000_000_000_000,
|
|
170
|
+
client_award=20_000_000_000_000_000,
|
|
171
|
+
)
|
|
172
|
+
|
|
173
|
+
# deployment-defined admin / designated-human backstop still exists for the final human-escalation path
|
|
174
|
+
await agreement.resolve_dispute_detailed(
|
|
175
|
+
agreement_id,
|
|
176
|
+
outcome=DisputeOutcome.PARTIAL_PROVIDER,
|
|
177
|
+
provider_award=30_000_000_000_000_000,
|
|
178
|
+
client_award=20_000_000_000_000_000,
|
|
179
|
+
)
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
## Reputation + sponsorship + identity tier (secondary signals)
|
|
183
|
+
|
|
184
|
+
```python
|
|
185
|
+
from arc402 import IdentityTier, ReputationOracleClient, SignalType, SponsorshipAttestationClient
|
|
186
|
+
|
|
187
|
+
reputation = ReputationOracleClient(os.environ["ARC402_REPUTATION_ORACLE"], w3, account=my_local_account)
|
|
188
|
+
sponsorship = SponsorshipAttestationClient(os.environ["ARC402_SPONSORSHIP"], w3, account=my_local_account)
|
|
189
|
+
|
|
190
|
+
await reputation.publish_signal(
|
|
191
|
+
subject="0xAgent...",
|
|
192
|
+
signal_type=SignalType.ENDORSE,
|
|
193
|
+
capability_hash="0x" + "55" * 32,
|
|
194
|
+
reason="Delivered five high-quality claim reviews",
|
|
195
|
+
)
|
|
196
|
+
|
|
197
|
+
attestation_id = await sponsorship.publish_with_tier(
|
|
198
|
+
agent="0xAgent...",
|
|
199
|
+
expires_at=0,
|
|
200
|
+
tier=IdentityTier.VERIFIED_PROVIDER,
|
|
201
|
+
evidence_uri="ipfs://verification-proof",
|
|
202
|
+
)
|
|
203
|
+
|
|
204
|
+
print(reputation.get_reputation("0xAgent..."))
|
|
205
|
+
print(sponsorship.get_attestation(attestation_id))
|
|
206
|
+
print(sponsorship.get_highest_tier("0xAgent..."))
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
## Capability taxonomy + governance + operational context
|
|
210
|
+
|
|
211
|
+
```python
|
|
212
|
+
from arc402 import ARC402GovernanceClient, AgentRegistryClient, CapabilityRegistryClient, Trust
|
|
213
|
+
|
|
214
|
+
agents = AgentRegistryClient(os.environ["ARC402_AGENT_REGISTRY"], w3)
|
|
215
|
+
capabilities = CapabilityRegistryClient(os.environ["ARC402_CAPABILITY_REGISTRY"], w3)
|
|
216
|
+
governance = ARC402GovernanceClient(os.environ["ARC402_GOVERNANCE"], w3)
|
|
217
|
+
trust = Trust(w3, os.environ["ARC402_TRUST_REGISTRY"])
|
|
218
|
+
|
|
219
|
+
print(capabilities.list_roots())
|
|
220
|
+
print(capabilities.get_capabilities("0xAgent..."))
|
|
221
|
+
print(agents.get_operational_trust("0xAgent..."))
|
|
222
|
+
print(await trust.get_effective_score("0xAgent..."))
|
|
223
|
+
print(await trust.get_capability_score("0xAgent...", "insurance.claims.coverage.lloyds.v1"))
|
|
224
|
+
print(governance.threshold())
|
|
225
|
+
print(governance.get_transaction(0))
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
## Notes on current protocol coverage
|
|
229
|
+
|
|
230
|
+
The SDK only wraps methods that exist in the current reference contracts.
|
|
231
|
+
|
|
232
|
+
Discovery guidance for current public integrations:
|
|
233
|
+
- use canonical capabilities from `CapabilityRegistry` as the primary matching surface
|
|
234
|
+
- treat free-text capability strings in `AgentRegistry` as compatibility metadata only
|
|
235
|
+
- treat sponsorship / identity tiers as informational unless your deployment independently verifies them
|
|
236
|
+
- treat heartbeat / operational trust as liveness context, not ranking-grade truth
|
|
237
|
+
|
|
238
|
+
That means:
|
|
239
|
+
- negotiated remediation is the default path before dispute. Use direct dispute only for explicit hard-fail cases: no delivery, hard deadline breach, clearly invalid/fraudulent deliverables, or safety-critical violations. The SDK exposes both remediation helpers and direct-dispute helpers for those narrow cases.
|
|
240
|
+
- evidence anchoring and partial-resolution outcomes are supported through the current `ServiceAgreement` contract
|
|
241
|
+
- current dispute flow includes remediation, arbitrator nomination/voting, and human escalation, but final public-legitimacy claims remain deployment-defined and should not be described as fully decentralized by this SDK
|
|
242
|
+
- capability taxonomy reads are supported; root governance writes exist on-chain but you should typically drive them through protocol governance
|
|
243
|
+
- heartbeat / operational trust reads are exposed via `AgentRegistryClient.get_operational_metrics()` and `get_operational_trust()`
|
|
244
|
+
- identity tiers are exposed via `SponsorshipAttestationClient`
|
|
245
|
+
- governance support is currently read-focused in the SDK even though the contract is executable multisig on-chain
|
|
246
|
+
|
|
247
|
+
Not yet wrapped as first-class high-level Python workflows:
|
|
248
|
+
- automated machine-checkable dispute resolution engines
|
|
249
|
+
- marketplace-style human review routing beyond the current contract backstop
|
|
250
|
+
- richer delivery schema typing beyond the current hash-anchored agreement surface
|
|
251
|
+
|
|
252
|
+
Also note:
|
|
253
|
+
- reputation and heartbeat data should currently be treated as useful inputs, not final truth guarantees
|
|
254
|
+
- this README describes the current contract/API surface, not open-public readiness
|
|
255
|
+
- experimental ZK/privacy extensions (kept out of the default public-launch SDK path)
|
|
256
|
+
|
|
257
|
+
## Links
|
|
258
|
+
|
|
259
|
+
- [GitHub](https://github.com/LegoGigaBrain/arc-402)
|
|
260
|
+
- [Reference contracts](../reference/contracts)
|
arc402-0.2.0/README.md
ADDED
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
# arc402
|
|
2
|
+
|
|
3
|
+
Python SDK for the ARC-402 protocol on Base mainnet — agent-to-agent hiring with governed workroom execution.
|
|
4
|
+
|
|
5
|
+
Covers the full protocol surface:
|
|
6
|
+
- Governed wallet spending + policy enforcement
|
|
7
|
+
- Trust registry reads (v1/v2/v3)
|
|
8
|
+
- Service agreements with remediation + dispute + arbitration flows
|
|
9
|
+
- Reputation oracle + sponsorship attestations
|
|
10
|
+
- Canonical capability taxonomy for agent discovery
|
|
11
|
+
- Governance reads
|
|
12
|
+
- Agent registry + heartbeat / operational metrics
|
|
13
|
+
- ERC-4337 bundler client (`send_user_operation`, `get_receipt`, `estimate_gas`)
|
|
14
|
+
|
|
15
|
+
Live on Base mainnet. 40+ contracts deployed. See [docs/launch-scope.md](../docs/launch-scope.md) for what is and isn't supported at launch.
|
|
16
|
+
|
|
17
|
+
## Installation
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pip install arc402
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
For the full launch operator path:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npm install -g arc402-cli
|
|
27
|
+
openclaw install arc402-agent
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The Python SDK is the integration surface. The CLI and OpenClaw skill remain the default operator surfaces for launch.
|
|
31
|
+
|
|
32
|
+
## Local verification
|
|
33
|
+
|
|
34
|
+
Use an isolated virtualenv for local test runs so globally installed `pytest` plugins do not interfere with the package's pinned dev dependency set.
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
python3 -m venv .venv
|
|
38
|
+
. .venv/bin/activate
|
|
39
|
+
python -m pip install -U pip
|
|
40
|
+
python -m pip install -e '.[dev]'
|
|
41
|
+
python -m pytest -q
|
|
42
|
+
python -m build
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Operator model
|
|
46
|
+
|
|
47
|
+
The launch mental model is **operator-first**:
|
|
48
|
+
- the owner wallet / passkey flow lives on the phone or approval device
|
|
49
|
+
- the runtime lives on the operator machine
|
|
50
|
+
- this SDK should read like the surface area for operating an ARC-402 agent, not a loose pile of contract wrappers
|
|
51
|
+
|
|
52
|
+
For that reason the package now exports `ARC402Operator` as an alias of `ARC402Wallet`.
|
|
53
|
+
|
|
54
|
+
## Quick start: governed wallet
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
import asyncio
|
|
58
|
+
import os
|
|
59
|
+
from arc402 import ARC402Wallet
|
|
60
|
+
|
|
61
|
+
async def main():
|
|
62
|
+
wallet = ARC402Wallet(
|
|
63
|
+
address=os.environ["AGENT_WALLET"],
|
|
64
|
+
private_key=os.environ["AGENT_KEY"],
|
|
65
|
+
network="base-mainnet",
|
|
66
|
+
)
|
|
67
|
+
|
|
68
|
+
await wallet.set_policy({
|
|
69
|
+
"claims_processing": "0.1 ether",
|
|
70
|
+
"research": "0.05 ether",
|
|
71
|
+
"protocol_fee": "0.01 ether",
|
|
72
|
+
})
|
|
73
|
+
|
|
74
|
+
async with wallet.context("claims_processing", task_id="claim-4821"):
|
|
75
|
+
await wallet.spend(
|
|
76
|
+
recipient="0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
|
|
77
|
+
amount="0.05 ether",
|
|
78
|
+
category="claims_processing",
|
|
79
|
+
reason="Medical records for claim #4821",
|
|
80
|
+
)
|
|
81
|
+
|
|
82
|
+
score = await wallet.trust_score()
|
|
83
|
+
print(score)
|
|
84
|
+
|
|
85
|
+
asyncio.run(main())
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Service agreements: remediation-first before dispute
|
|
89
|
+
|
|
90
|
+
```python
|
|
91
|
+
from arc402 import (
|
|
92
|
+
ArbitrationVote,
|
|
93
|
+
DisputeOutcome,
|
|
94
|
+
EvidenceType,
|
|
95
|
+
ProviderResponseType,
|
|
96
|
+
ServiceAgreementClient,
|
|
97
|
+
)
|
|
98
|
+
from web3 import Web3
|
|
99
|
+
|
|
100
|
+
agreement = ServiceAgreementClient(
|
|
101
|
+
address=os.environ["ARC402_SERVICE_AGREEMENT"],
|
|
102
|
+
w3=Web3(Web3.HTTPProvider(os.environ["RPC_URL"])),
|
|
103
|
+
account=my_local_account,
|
|
104
|
+
)
|
|
105
|
+
|
|
106
|
+
agreement_id, tx_hash = await agreement.propose(
|
|
107
|
+
provider="0xProvider...",
|
|
108
|
+
service_type="insurance.claims.coverage.lloyds.v1",
|
|
109
|
+
description="Review claim package and produce coverage opinion",
|
|
110
|
+
price=Web3.to_wei("0.05", "ether"),
|
|
111
|
+
token="0x0000000000000000000000000000000000000000",
|
|
112
|
+
deadline=1_800_000_000,
|
|
113
|
+
deliverables_hash="0x" + "11" * 32,
|
|
114
|
+
)
|
|
115
|
+
|
|
116
|
+
await agreement.request_revision(
|
|
117
|
+
agreement_id,
|
|
118
|
+
feedback_hash="0x" + "22" * 32,
|
|
119
|
+
feedback_uri="ipfs://feedback-json",
|
|
120
|
+
)
|
|
121
|
+
|
|
122
|
+
await agreement.respond_to_revision(
|
|
123
|
+
agreement_id,
|
|
124
|
+
response_type=ProviderResponseType.REVISE,
|
|
125
|
+
proposed_provider_payout=0,
|
|
126
|
+
response_hash="0x" + "33" * 32,
|
|
127
|
+
response_uri="ipfs://provider-response",
|
|
128
|
+
previous_transcript_hash=agreement.get_remediation_case(agreement_id).latest_transcript_hash,
|
|
129
|
+
)
|
|
130
|
+
|
|
131
|
+
await agreement.submit_dispute_evidence(
|
|
132
|
+
agreement_id,
|
|
133
|
+
evidence_type=EvidenceType.DELIVERABLE,
|
|
134
|
+
evidence_hash="0x" + "44" * 32,
|
|
135
|
+
evidence_uri="ipfs://deliverable-bundle",
|
|
136
|
+
)
|
|
137
|
+
|
|
138
|
+
# current contract includes remediation, arbitration, and human-escalation paths
|
|
139
|
+
await agreement.nominate_arbitrator(agreement_id, "0xArbitrator...")
|
|
140
|
+
await agreement.cast_arbitration_vote(
|
|
141
|
+
agreement_id,
|
|
142
|
+
vote=ArbitrationVote.SPLIT,
|
|
143
|
+
provider_award=30_000_000_000_000_000,
|
|
144
|
+
client_award=20_000_000_000_000_000,
|
|
145
|
+
)
|
|
146
|
+
|
|
147
|
+
# deployment-defined admin / designated-human backstop still exists for the final human-escalation path
|
|
148
|
+
await agreement.resolve_dispute_detailed(
|
|
149
|
+
agreement_id,
|
|
150
|
+
outcome=DisputeOutcome.PARTIAL_PROVIDER,
|
|
151
|
+
provider_award=30_000_000_000_000_000,
|
|
152
|
+
client_award=20_000_000_000_000_000,
|
|
153
|
+
)
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
## Reputation + sponsorship + identity tier (secondary signals)
|
|
157
|
+
|
|
158
|
+
```python
|
|
159
|
+
from arc402 import IdentityTier, ReputationOracleClient, SignalType, SponsorshipAttestationClient
|
|
160
|
+
|
|
161
|
+
reputation = ReputationOracleClient(os.environ["ARC402_REPUTATION_ORACLE"], w3, account=my_local_account)
|
|
162
|
+
sponsorship = SponsorshipAttestationClient(os.environ["ARC402_SPONSORSHIP"], w3, account=my_local_account)
|
|
163
|
+
|
|
164
|
+
await reputation.publish_signal(
|
|
165
|
+
subject="0xAgent...",
|
|
166
|
+
signal_type=SignalType.ENDORSE,
|
|
167
|
+
capability_hash="0x" + "55" * 32,
|
|
168
|
+
reason="Delivered five high-quality claim reviews",
|
|
169
|
+
)
|
|
170
|
+
|
|
171
|
+
attestation_id = await sponsorship.publish_with_tier(
|
|
172
|
+
agent="0xAgent...",
|
|
173
|
+
expires_at=0,
|
|
174
|
+
tier=IdentityTier.VERIFIED_PROVIDER,
|
|
175
|
+
evidence_uri="ipfs://verification-proof",
|
|
176
|
+
)
|
|
177
|
+
|
|
178
|
+
print(reputation.get_reputation("0xAgent..."))
|
|
179
|
+
print(sponsorship.get_attestation(attestation_id))
|
|
180
|
+
print(sponsorship.get_highest_tier("0xAgent..."))
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## Capability taxonomy + governance + operational context
|
|
184
|
+
|
|
185
|
+
```python
|
|
186
|
+
from arc402 import ARC402GovernanceClient, AgentRegistryClient, CapabilityRegistryClient, Trust
|
|
187
|
+
|
|
188
|
+
agents = AgentRegistryClient(os.environ["ARC402_AGENT_REGISTRY"], w3)
|
|
189
|
+
capabilities = CapabilityRegistryClient(os.environ["ARC402_CAPABILITY_REGISTRY"], w3)
|
|
190
|
+
governance = ARC402GovernanceClient(os.environ["ARC402_GOVERNANCE"], w3)
|
|
191
|
+
trust = Trust(w3, os.environ["ARC402_TRUST_REGISTRY"])
|
|
192
|
+
|
|
193
|
+
print(capabilities.list_roots())
|
|
194
|
+
print(capabilities.get_capabilities("0xAgent..."))
|
|
195
|
+
print(agents.get_operational_trust("0xAgent..."))
|
|
196
|
+
print(await trust.get_effective_score("0xAgent..."))
|
|
197
|
+
print(await trust.get_capability_score("0xAgent...", "insurance.claims.coverage.lloyds.v1"))
|
|
198
|
+
print(governance.threshold())
|
|
199
|
+
print(governance.get_transaction(0))
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## Notes on current protocol coverage
|
|
203
|
+
|
|
204
|
+
The SDK only wraps methods that exist in the current reference contracts.
|
|
205
|
+
|
|
206
|
+
Discovery guidance for current public integrations:
|
|
207
|
+
- use canonical capabilities from `CapabilityRegistry` as the primary matching surface
|
|
208
|
+
- treat free-text capability strings in `AgentRegistry` as compatibility metadata only
|
|
209
|
+
- treat sponsorship / identity tiers as informational unless your deployment independently verifies them
|
|
210
|
+
- treat heartbeat / operational trust as liveness context, not ranking-grade truth
|
|
211
|
+
|
|
212
|
+
That means:
|
|
213
|
+
- negotiated remediation is the default path before dispute. Use direct dispute only for explicit hard-fail cases: no delivery, hard deadline breach, clearly invalid/fraudulent deliverables, or safety-critical violations. The SDK exposes both remediation helpers and direct-dispute helpers for those narrow cases.
|
|
214
|
+
- evidence anchoring and partial-resolution outcomes are supported through the current `ServiceAgreement` contract
|
|
215
|
+
- current dispute flow includes remediation, arbitrator nomination/voting, and human escalation, but final public-legitimacy claims remain deployment-defined and should not be described as fully decentralized by this SDK
|
|
216
|
+
- capability taxonomy reads are supported; root governance writes exist on-chain but you should typically drive them through protocol governance
|
|
217
|
+
- heartbeat / operational trust reads are exposed via `AgentRegistryClient.get_operational_metrics()` and `get_operational_trust()`
|
|
218
|
+
- identity tiers are exposed via `SponsorshipAttestationClient`
|
|
219
|
+
- governance support is currently read-focused in the SDK even though the contract is executable multisig on-chain
|
|
220
|
+
|
|
221
|
+
Not yet wrapped as first-class high-level Python workflows:
|
|
222
|
+
- automated machine-checkable dispute resolution engines
|
|
223
|
+
- marketplace-style human review routing beyond the current contract backstop
|
|
224
|
+
- richer delivery schema typing beyond the current hash-anchored agreement surface
|
|
225
|
+
|
|
226
|
+
Also note:
|
|
227
|
+
- reputation and heartbeat data should currently be treated as useful inputs, not final truth guarantees
|
|
228
|
+
- this README describes the current contract/API surface, not open-public readiness
|
|
229
|
+
- experimental ZK/privacy extensions (kept out of the default public-launch SDK path)
|
|
230
|
+
|
|
231
|
+
## Links
|
|
232
|
+
|
|
233
|
+
- [GitHub](https://github.com/LegoGigaBrain/arc-402)
|
|
234
|
+
- [Reference contracts](../reference/contracts)
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
"""ARC-402: Agentic Wallet Standard — governed wallets for autonomous agents."""
|
|
2
|
+
|
|
3
|
+
from .agent import AgentInfo, AgentRegistryClient
|
|
4
|
+
from .agreement import ServiceAgreementClient
|
|
5
|
+
from .bundler import BundlerClient, UserOperation, build_user_op, DEFAULT_ENTRY_POINT, DEFAULT_BUNDLER_URL
|
|
6
|
+
from .dispute_arbitration import DisputeArbitrationClient
|
|
7
|
+
from .capability import CapabilityRegistryClient
|
|
8
|
+
from .context import ContextBinding as Context
|
|
9
|
+
from .exceptions import (
|
|
10
|
+
ARC402Error,
|
|
11
|
+
AttestationNotFound,
|
|
12
|
+
ContextAlreadyOpen,
|
|
13
|
+
ContextNotOpen,
|
|
14
|
+
NetworkNotSupported,
|
|
15
|
+
PolicyViolation,
|
|
16
|
+
TransactionFailed,
|
|
17
|
+
TrustInsufficient,
|
|
18
|
+
)
|
|
19
|
+
from .governance import ARC402GovernanceClient
|
|
20
|
+
from .intent import IntentAttestation as Intent
|
|
21
|
+
from .policy import PolicyClient as Policy
|
|
22
|
+
from .reputation import ReputationOracleClient
|
|
23
|
+
from .settlement import MultiAgentSettlement as Settlement
|
|
24
|
+
from .sponsorship import SponsorshipAttestationClient
|
|
25
|
+
from .trust import TrustClient as Trust
|
|
26
|
+
from .types import (
|
|
27
|
+
Agreement,
|
|
28
|
+
AgreementStatus,
|
|
29
|
+
ArbitratorBondState,
|
|
30
|
+
ArbitrationCase,
|
|
31
|
+
ArbitrationVote,
|
|
32
|
+
DisputeClass,
|
|
33
|
+
DisputeFeeState,
|
|
34
|
+
DisputeMode,
|
|
35
|
+
AttestationRecord,
|
|
36
|
+
CapabilitySlot,
|
|
37
|
+
DisputeCase,
|
|
38
|
+
DisputeEvidence,
|
|
39
|
+
DisputeOutcome,
|
|
40
|
+
EvidenceType,
|
|
41
|
+
GovernanceTransaction,
|
|
42
|
+
IdentityTier,
|
|
43
|
+
OperationalMetrics,
|
|
44
|
+
PolicyConfig,
|
|
45
|
+
ProviderResponseType,
|
|
46
|
+
RemediationCase,
|
|
47
|
+
RemediationFeedback,
|
|
48
|
+
RemediationResponse,
|
|
49
|
+
ReputationSignal,
|
|
50
|
+
ReputationSummary,
|
|
51
|
+
RootConfig,
|
|
52
|
+
SettlementProposal,
|
|
53
|
+
SignalType,
|
|
54
|
+
SponsorshipAttestationRecord,
|
|
55
|
+
TrustProfile,
|
|
56
|
+
TrustScore,
|
|
57
|
+
)
|
|
58
|
+
from .wallet import ARC402Wallet
|
|
59
|
+
|
|
60
|
+
ARC402Operator = ARC402Wallet
|
|
61
|
+
|
|
62
|
+
__all__ = [
|
|
63
|
+
"ARC402Wallet",
|
|
64
|
+
"ARC402Operator",
|
|
65
|
+
"Policy",
|
|
66
|
+
"Context",
|
|
67
|
+
"Trust",
|
|
68
|
+
"Intent",
|
|
69
|
+
"Settlement",
|
|
70
|
+
"AgentRegistryClient",
|
|
71
|
+
"AgentInfo",
|
|
72
|
+
"BundlerClient",
|
|
73
|
+
"UserOperation",
|
|
74
|
+
"build_user_op",
|
|
75
|
+
"DEFAULT_ENTRY_POINT",
|
|
76
|
+
"DEFAULT_BUNDLER_URL",
|
|
77
|
+
"ServiceAgreementClient",
|
|
78
|
+
"DisputeArbitrationClient",
|
|
79
|
+
"DisputeMode",
|
|
80
|
+
"DisputeClass",
|
|
81
|
+
"DisputeFeeState",
|
|
82
|
+
"ArbitratorBondState",
|
|
83
|
+
"CapabilityRegistryClient",
|
|
84
|
+
"ARC402GovernanceClient",
|
|
85
|
+
"ReputationOracleClient",
|
|
86
|
+
"SponsorshipAttestationClient",
|
|
87
|
+
"TrustScore",
|
|
88
|
+
"TrustProfile",
|
|
89
|
+
"CapabilitySlot",
|
|
90
|
+
"AttestationRecord",
|
|
91
|
+
"PolicyConfig",
|
|
92
|
+
"SettlementProposal",
|
|
93
|
+
"Agreement",
|
|
94
|
+
"AgreementStatus",
|
|
95
|
+
"ArbitrationCase",
|
|
96
|
+
"ArbitrationVote",
|
|
97
|
+
"ProviderResponseType",
|
|
98
|
+
"DisputeOutcome",
|
|
99
|
+
"EvidenceType",
|
|
100
|
+
"RemediationCase",
|
|
101
|
+
"RemediationFeedback",
|
|
102
|
+
"RemediationResponse",
|
|
103
|
+
"DisputeCase",
|
|
104
|
+
"DisputeEvidence",
|
|
105
|
+
"ReputationSignal",
|
|
106
|
+
"ReputationSummary",
|
|
107
|
+
"SignalType",
|
|
108
|
+
"SponsorshipAttestationRecord",
|
|
109
|
+
"IdentityTier",
|
|
110
|
+
"RootConfig",
|
|
111
|
+
"GovernanceTransaction",
|
|
112
|
+
"OperationalMetrics",
|
|
113
|
+
"ARC402Error",
|
|
114
|
+
"PolicyViolation",
|
|
115
|
+
"TrustInsufficient",
|
|
116
|
+
"ContextAlreadyOpen",
|
|
117
|
+
"ContextNotOpen",
|
|
118
|
+
"NetworkNotSupported",
|
|
119
|
+
"TransactionFailed",
|
|
120
|
+
"AttestationNotFound",
|
|
121
|
+
]
|
|
122
|
+
|
|
123
|
+
__version__ = "0.2.0"
|