Skip to content

docs: add Task Validation V2 helper docs to SDK #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
signerless merged 1 commit into from
Mar 25, 2026
Merged

docs: add Task Validation V2 helper docs to SDK #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ agenc-sdk/
## Public API Families

- Proofs and prover wiring: `proofs.ts`, `prover.ts`, `proof-validation.ts`
- Task lifecycle and queries: `tasks.ts`, `queries.ts`, `tokens.ts`
- Task lifecycle, validation flows, and queries: `tasks.ts`, `queries.ts`, `tokens.ts`
- Agent, dispute, governance, and protocol helpers: `agents.ts`, `disputes.ts`, `governance.ts`, `protocol.ts`, `state.ts`
- Diagnostics and compatibility: `errors.ts`, `logger.ts`, `process-identity.ts`, `version.ts`
- Convenience wrapper: `client.ts`
Expand Down Expand Up @@ -113,6 +113,23 @@ The SDK derives and submits the required verification accounts:
- `completeTask(...)`
- `completeTaskPrivate(...)`
- `completeTaskPrivateWithPreflight(...)`
- `configureTaskValidation(...)`
- `submitTaskResult(...)`
- `acceptTaskResult(...)`
- `rejectTaskResult(...)`
- `autoAcceptTaskResult(...)`
- `validateTaskResult(...)`

## Task Validation V2

The SDK exposes the full reviewed public-task surface introduced by protocol Task Validation V2.

- `configureTaskValidation(...)` enables creator review, validator quorum, or external attestation on an open public task
- `submitTaskResult(...)` records a reviewed submission without paying out immediately
- `acceptTaskResult(...)`, `rejectTaskResult(...)`, and `autoAcceptTaskResult(...)` resolve creator-review tasks
- `validateTaskResult(...)` records validator-quorum votes and external attestations

Important: raw SDK `completeTask(...)` still calls on-chain `complete_task` directly. It does not auto-route manual-validation tasks into `submit_task_result`. That auto-routing exists in the runtime wrapper, not in the SDK.

### Preflight validation

Expand Down
2 changes: 1 addition & 1 deletion docs/DOCS_INDEX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,6 @@ This is the developer-documentation entrypoint for `agenc-sdk`.

- I need the repo layout: [CODEBASE_MAP.md](./CODEBASE_MAP.md)
- I need the exported API families: [MODULE_INDEX.md](./MODULE_INDEX.md)
- I need reviewed task-validation helpers: [MODULE_INDEX.md](./MODULE_INDEX.md)
- I need release or CI commands: [MAINTAINER_GUIDE.md](./MAINTAINER_GUIDE.md)
- I need a runnable example: [examples/private-task-demo/README.md](../examples/private-task-demo/README.md)

11 changes: 7 additions & 4 deletions docs/MODULE_INDEX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,18 +15,22 @@ Everything else in the repo is support material, tests, examples, or release too

- `generateProof`, `computeHashes`, `generateSalt`
- `runProofSubmissionPreflight`
- `completeTaskPrivateSafe`
- `completeTaskPrivateWithPreflight`, `completeTaskPrivateSafe`
- `ProverConfig`, `RemoteProverConfig`, `ProverError`

Use this family for private completion payload construction, prover transport wiring, and client-side safety checks before submission.

### Task lifecycle

- `createTask`, `createDependentTask`, `claimTask`, `expireClaim`
- `completeTask`, `completeTaskPrivate`, `completeTaskPrivateSafe`
- `completeTask`, `completeTaskPrivate`, `completeTaskPrivateWithPreflight`, `completeTaskPrivateSafe`
- `configureTaskValidation`, `submitTaskResult`
- `acceptTaskResult`, `rejectTaskResult`, `autoAcceptTaskResult`, `validateTaskResult`
- `cancelTask`, `getTask`, `getTasksByCreator`
- `deriveTaskPda`, `deriveClaimPda`, `deriveEscrowPda`

Use the explicit Task Validation V2 helpers when a task has been configured for review or attestation. The low-level SDK `completeTask` helper still sends `complete_task` directly and does not auto-route reviewed tasks into `submit_task_result`.

### Queries and replay-oriented reads

- `getTasksByDependency`, `getDependentTaskCount`, `getRootTasks`
Expand Down Expand Up @@ -62,6 +66,5 @@ Use `PrivacyClient` when you want one object to wrap common flows. Use the lower
## Deprecated And Compatibility Notes

- `validateProofPreconditions` remains exported as a deprecated alias for `runProofSubmissionPreflight`.
- The canonical safe private-completion helper is `completeTaskPrivateSafe`.
- `completeTaskPrivateSafe` remains exported as a deprecated compatibility wrapper around `completeTaskPrivateWithPreflight`.
- Version compatibility state is defined in `src/version.ts` and must stay aligned with `package.json` and released protocol expectations.

2 changes: 1 addition & 1 deletion src/tasks.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1422,7 +1422,7 @@ export async function configureTaskValidation(
}

/**
* Submit a worker result for Task Validation V2 creator review.
* Submit a worker result for Task Validation V2 manual validation.
*/
export async function submitTaskResult(
connection: Connection,
Expand Down
Loading