# Scientist agreements · runtime 1.9

This is an operator-owned workflow, not a staffing marketplace. Provider accounts, counterparties, terms, identity checks, account eligibility and funding belong to the operator. No accounts, real messages, signatures or transfers are included with the package.

## Configure

Pair with the separate `engagements` scope in addition to `read`. Ordinary research and connection scopes cannot configure, authorize, send, accept or pay agreements. Example:

```sh
.venv/bin/python researchctl.py pair --origin https://YOUR-UI --scopes read,research,review,export,connections,engagements
```

In DocuSeal make a separate template with exactly two roles named `Client` and `Researcher`. Each needs its own **required signature** field. The Researcher role must own text fields named `0EX Terms` and `0EX Terms Hash`. Check the document layout accommodates the complete readable terms. The runtime fills those fields readonly; it never pre-fills a signature or uses `completed:true`. Both people sign in DocuSeal.

Configure the DocuSeal API key, exact template ID and optional Stripe platform secret/restricted key on the node. Stripe key permissions must support platform/account reads and transfers. Run the probe. The template snapshot is pinned; changing it requires a newly reviewed agreement. A Stripe test key does **not** suppress DocuSeal emails. Use your own separate testing template/account and test recipients when rehearsing.

Stripe uses `POST /v1/transfers` to a named Connected Account with active `capabilities.transfers`. It transfers a prefunded platform balance; it does not charge a customer and does not itself confirm a bank payout. USD/EUR/GBP/BRL amounts are integer minor units. The API's account-configured version must support these documented fields. Test and live mode are separate. A live key requires an explicit provider policy and a separate live payment mandate.

## One agreement

1. Record both names/emails, exact Connected Account, amount, deadline, scientific deliverable and agreed terms. SHA-256 commits the canonical JSON terms.
2. The owner checks the named parties and issues a 1–24 hour immutable mandate. Sending invitations and transferring money are separate permissions. Assign one admitted resident if its own agent loop should advance the workflow.
3. `advance` sends DocuSeal invitations once and stores the submission ID. It does not sign for either person. Further calls poll exact submission/template/roles/emails/external IDs and completed times. Both completed signatures must bind the exact readonly terms and hash.
4. The owner independently accepts a persisted Evidence, DatasetProfile, QuantumObservation or AgentWorkReport and records a reason. Residents cannot call the acceptance route. Acceptance pays for a deliverable; it does not certify scientific truth.
5. The designated resident or owner may advance the accepted agreement, under its unexpired mandate. The runtime reserves the amount durably before sending one Stripe transfer with a persisted idempotency key. Receipt amount/currency/destination/mode/metadata must match. Status `transfer_created` means a Connected Account transfer, not bank receipt.

Signature status is provider-attested; the node does not independently verify PDF cryptographic signatures. The software is not a jurisdiction-specific legal template. Governing law, rights, tax handling, disputes, provider eligibility and enforceability are terms the parties must settle before real use.

## Agent API and failures

The resident calls `POST /api/resident/engagement-advance` with `{"agreement_id":"engagement_..."}` using its private resident credential. Give it the exact agreement ID with the assigned task. It can only advance an agreement explicitly bound to that resident. It receives minimal state, not provider keys or the operator's full contracts. Example:

```sh
printf '%s' '{"agreement_id":"engagement_EXACT_ID"}' | .venv/bin/python resident-client.py engagement-advance --token-file resident.json --gateway http://127.0.0.1:8765
```

The agent supplies its own scheduling/reasoning loop. This endpoint does not start a background autonomous agent. Revoking either residency or the agreement mandate blocks future actions. It does not recall sent emails, reverse a transfer or cancel a provider-side document.

Unknown sends/transfers are never automatically retried, including after restart. Look up the exact submission or transfer in the provider dashboard, then use `inspect`/`reconcile`. The transfer reservation remains in the daily budget. Configure a new key to recover read access after rotation: DocuSeal must return the original parties/template/terms; Stripe must also match the original platform and mode. New credentials do not reauthorize an old mandate. Interrupted/expired mandates are not silently renewed.

Terms, recipient identities and acceptance text remain in private resource records. Generic graph/journal/export receives commitments and status, not the private contract body. Local runtime storage must be protected by the host operator. No automatic public contract publication is performed.

## Test-network escrow

`contracts/ResearchEscrow.sol` and its compiled artifact are an **unaudited testnet prototype**, limited to chain IDs 31337 and 11155111. Chain ID alone does not authenticate the RPC network. Choose a trusted wallet/RPC and test assets only. This is an alternative to the Stripe workflow; there is no cross-system double-payment prevention.

The browser prepares a transaction for the connected wallet, checks allowed chain, account, contract bytecode with pinned immutable layout, roles and state, and requires an explicit reviewed wallet action. Constructor terms hash can be the same exact SHA-256 document commitment; the contract treats it as opaque bytes32. Deposit is exact. The researcher submits evidence, the client accepts or a dispute freezes settlement until the immutable arbiter chooses one party. Settlement credits funds; the beneficiary must withdraw separately. An unavailable arbiter can lock funds indefinitely. There is no proof of legal consent, scientific correctness or real-world identity on chain.

Do not call submitted transactions successful until their receipt is checked. A missing response is uncertain; inspect the wallet before another action. No mainnet deployment or real wallet operation was performed in development.

Primary API contracts checked 2026-09-25: https://www.docuseal.com/docs/api ; https://www.docuseal.com/guides/pre-fill-pdf-document-form-fields-with-api ; https://docs.stripe.com/api/transfers/create ; https://docs.stripe.com/api/transfers/retrieve ; https://docs.stripe.com/api/idempotent_requests ; https://docs.stripe.com/connect/account-capabilities .