Ambiente di test

La demo è una sola, su Base Sepolia, con EURC di prova: niente soldi veri.

Stai leggendo questi docs dalla demo stessa. Questi sono i suoi parametri, letti adesso dalla chain:

Cosa serve

• EURC di prova, dal faucet di Circle, scegliendo Base Sepolia. Vanno a chi versa: la persona che apre uno scontratto, o il wallet dell'agente cliente.
• ETH di prova, solo per gli scontratti tra persone: chi apre e versa paga il gas delle sue tre transazioni. Gli agenti non ne hanno bisogno, perché il gas lo paga il facilitatore.
• Il token del pilota, per le scritture dell'API degli scontratti. Chiedilo al team.

I limiti

La demo è per provare, non per conservare. Può essere azzerata, e i contratti possono cambiare indirizzo a ogni nuova versione. Il facilitatore sponsorizza al massimo 60 richieste all'ora per indirizzo e 300 in tutto.

In locale

In locale si prova il giro degli agenti: una chain con anvil, i contratti, il Worker con il suo database, e due agenti MCP. Per gli scontratti tra persone serve un oracolo vero, quindi si usa la demo. Servono Node 22 o più recente e Foundry.

1. La chain

anvil --block-time 1

anvil stampa dieci account con le loro chiavi. Sono pubblici e valgono solo in locale.

--block-time 1 fa nascere un blocco al secondo, come su una chain vera. Senza, anvil crea un blocco solo quando arriva una transazione, e l'attesa di una conferma può restare appesa fino al suo limite di un minuto.

2. I contratti

cd packages/scontract-contracts
MINT_TO=0x976EA74026E726554dB657fA54763abd0C3a0aa9 PLATFORM_FEE_BP=100 EVALUATOR_FEE_BP=50 \
  forge script script/Deploy.s.sol:Deploy --rpc-url http://127.0.0.1:8545 \
  --private-key <chiave dell'account 0 di anvil> --broadcast
cat deployments/31337.json

Senza EURC, lo script crea un EURC di prova e ne dà 1000 agli indirizzi in MINT_TO. Quello dell'esempio è l'account 6 di anvil, che la demo usa come agente cliente.

3. Il Worker

Crea un file di variabili fuori dal repository, per esempio /tmp/locale.vars, con due righe:

• BASE_SEPOLIA_RPC_URL=http://127.0.0.1:8545;
• ATTESTOR_PRIVATE_KEY, con la chiave dell'account 2 di anvil. In locale fa da attestatore, da facilitatore e da SchemaEval. GitHubEval usa una chiave derivata da questa. Facoltativa: GITHUB_TOKEN, un token GitHub di sola lettura, per non restare nel limite di 60 richieste all'ora.

Poi, con gli indirizzi di deployments/31337.json:

cd apps/api
npx wrangler d1 migrations apply scontratto --local
npx wrangler dev --port 8790 --env-file /tmp/locale.vars --var CHAIN_ID:31337 \
  --var ACP_ADDRESS:0x... --var MANDATE_HOOK_ADDRESS:0x... --var FORWARDER_ADDRESS:0x...

I docs sono anche su http://127.0.0.1:8790/docs, con gli indirizzi del tuo ambiente locale.

4. La demo

npm run build -w @scontract/mcp
SCONTRACT_API_URL=http://127.0.0.1:8790 node scripts/scontract-e2e.mjs

La demo fa firmare un mandato al titolare, poi fa lavorare due agenti via MCP:

1. un job conforme viene pagato, con le fee;
2. il mandato ne ferma uno oltre il massimo per job;
3. il mandato ne ferma uno verso un fornitore non ammesso;
4. una consegna non conforme viene respinta, i soldi tornano al cliente e il tetto si libera;
5. un agente senza mandato non ottiene il gas;
6. la traccia del job contiene ogni passo.

Deve finire con 19 ok, 0 ko.

Far scadere un job

Per provare il rimborso automatico, porta avanti l'orologio di anvil e lancia il cron degli agenti:

cast rpc evm_increaseTime 864000 && cast rpc evm_mine
curl -X POST "http://127.0.0.1:8790/cdn-cgi/local/explorer/api/local/scheduled?worker=scontratto-api" \
  -H 'content-type: application/json' -d '{"cron":"* * * * *"}'

I job finanziati e scaduti passano a Expired, i soldi tornano al cliente e il tetto del mandato si libera.

Con CON_GITHUB=1 la demo aggiunge un job per GitHubEval: commissiona una PR vera di wevm/viem, già unita, la consegna e controlla che il fornitore sia pagato. Serve la rete verso GitHub.

CON_GITHUB=1 SCONTRACT_API_URL=http://127.0.0.1:8790 node scripts/scontract-e2e.mjs

I test

npm test
cd packages/contracts && forge test
cd packages/scontract-contracts && forge test

Il primo esegue i test in TypeScript: la macchina a stati degli scontratti, l'oracolo, il dominio degli agenti e la politica del facilitatore. Gli altri due quelli in Solidity: l'escrow degli scontratti, e il core e il hook degli agenti. In entrambi i casi TypeScript e Solidity condividono un vettore: l'hash dello stesso mandato deve uscire identico dalle due parti.