@occa/sdk 0.4.0 → 0.5.0

package/src/idl/registry.json

@@ -140,6 +140,162 @@
         }
       ]
     },
+    {
+      "name": "commit_trace",
+      "docs": [
+        "Anchor a single completed, verified deliverable on-chain — per-task",
+        "provenance. Where `commit_daily_anchor` commits one Merkle root over",
+        "a day's task stream, this records ONE deliverable: a link to the",
+        "result, the content hash that locks it, and the verification verdict",
+        "+ quality score.",
+        "",
+        "Only deliverables that PASSED the off-chain verification gate are",
+        "anchored (policy: keep unverified / spam output off the chain).",
+        "`verdict` is therefore always written `TRACE_VERDICT_PASSED`; failed",
+        "work is simply never committed through this ix.",
+        "",
+        "Per Whitepaper §2 trace architecture: the deliverable itself stays",
+        "off-chain. `content_hash` makes the result tamper-evident and",
+        "`evidence_hash` locks the off-chain verification report. Anyone can",
+        "re-hash the artifact + report and verify against these. The on-chain",
+        "`quality_score` + `rubric_version` make the quality signal itself",
+        "tamper-evident — the agent cannot self-assert it.",
+        "",
+        "Seeds: `[\"trace\", task_id]`. PDA collision = at most one anchor per",
+        "task. Re-attempts on the same `task_id` fail naturally (Anchor `init`",
+        "rejects).",
+        "",
+        "Authorization: identical model to `commit_daily_anchor` — signed by",
+        "the Anchor Wallet registered as `OperationsAccount[Anchor]`; this",
+        "ix's discriminator must be whitelisted on that account. Resolved via",
+        "cross-program PDA lookup (`seeds::program = treasury::ID`).",
+        "",
+        "Phase 1 rate limit: NOT enforced (same constraint as",
+        "`commit_daily_anchor` — registry cannot mutate the treasury-owned",
+        "ops counter without an extra CPI). PDA-per-task dedup + rent burn",
+        "cap griefing."
+      ],
+      "discriminator": [
+        58,
+        140,
+        230,
+        51,
+        170,
+        109,
+        228,
+        125
+      ],
+      "accounts": [
+        {
+          "name": "deployment",
+          "docs": [
+            "Deployment that produced this deliverable."
+          ]
+        },
+        {
+          "name": "company",
+          "docs": [
+            "CompanyAccount referenced by deployment. Verified via",
+            "`deployment.company == company.key()` in the handler so we can also",
+            "resolve the OperationsAccount[Anchor] PDA from it."
+          ]
+        },
+        {
+          "name": "anchor_signer",
+          "docs": [
+            "Anchor Wallet — pubkey verified against `operations.signer`."
+          ],
+          "signer": true
+        },
+        {
+          "name": "operations",
+          "docs": [
+            "`OperationsAccount[Anchor]` from treasury program. Resolved via",
+            "cross-program PDA derivation; Anchor `Account<T>` auto-verifies",
+            "owner = treasury::ID."
+          ]
+        },
+        {
+          "name": "trace_anchor",
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  116,
+                  114,
+                  97,
+                  99,
+                  101
+                ]
+              },
+              {
+                "kind": "arg",
+                "path": "task_id"
+              }
+            ]
+          }
+        },
+        {
+          "name": "payer",
+          "docs": [
+            "Pays rent for the TraceAnchorAccount PDA."
+          ],
+          "writable": true,
+          "signer": true
+        },
+        {
+          "name": "system_program",
+          "address": "11111111111111111111111111111111"
+        }
+      ],
+      "args": [
+        {
+          "name": "task_id",
+          "type": {
+            "array": [
+              "u8",
+              32
+            ]
+          }
+        },
+        {
+          "name": "result_uri",
+          "type": "string"
+        },
+        {
+          "name": "content_hash",
+          "type": {
+            "array": [
+              "u8",
+              32
+            ]
+          }
+        },
+        {
+          "name": "quality_score",
+          "type": "u8"
+        },
+        {
+          "name": "rubric_version",
+          "type": "u8"
+        },
+        {
+          "name": "evidence_hash",
+          "type": {
+            "array": [
+              "u8",
+              32
+            ]
+          }
+        },
+        {
+          "name": "completed_at",
+          "type": "i64"
+        }
+      ]
+    },
     {
       "name": "create_company",
       "docs": [
@@ -286,23 +442,29 @@
       ],
       "accounts": [
         {
-          "name": "company"
+          "name": "company",
+          "docs": [
+            "Company the agent is being deployed into. Referenced only — the",
+            "company owner's consent to the hire is captured off-chain (the",
+            "invite), so the company owner is NOT a required signer here."
+          ]
         },
         {
           "name": "identity",
           "docs": [
-            "AgentIdentity to deploy. Phase 1: must be owned by the same",
-            "wallet as the company (enforced in handler)."
+            "AgentIdentity being deployed. The IDENTITY owner signs — deploying",
+            "an agent (incl. into another owner's company, the marketplace case)",
+            "is authorized by the agent's owner accepting."
           ]
         },
         {
           "name": "owner",
           "docs": [
-            "Company owner (signer). Authority for state changes."
+            "Agent owner (signer) — authorizes deploying THEIR agent."
           ],
           "signer": true,
           "relations": [
-            "company"
+            "identity"
           ]
         },
         {
@@ -508,6 +670,44 @@
       ],
       "args": []
     },
+    {
+      "name": "set_agent_receiving_address",
+      "docs": [
+        "Set or replace the agent's PERSONAL receiving wallet — the passive",
+        "destination for funds disbursed to this agent, intrinsic to the",
+        "identity (no company/deployment required). Pass `Pubkey::default()`",
+        "to clear. Identity-owner only. NEVER a signer — it only receives."
+      ],
+      "discriminator": [
+        197,
+        126,
+        122,
+        18,
+        38,
+        62,
+        179,
+        218
+      ],
+      "accounts": [
+        {
+          "name": "identity",
+          "writable": true
+        },
+        {
+          "name": "owner",
+          "signer": true,
+          "relations": [
+            "identity"
+          ]
+        }
+      ],
+      "args": [
+        {
+          "name": "new_receiving_address",
+          "type": "pubkey"
+        }
+      ]
+    },
     {
       "name": "set_receiving_address",
       "docs": [
@@ -822,6 +1022,19 @@
         64,
         178
       ]
+    },
+    {
+      "name": "TraceAnchorAccount",
+      "discriminator": [
+        159,
+        101,
+        186,
+        98,
+        211,
+        217,
+        119,
+        232
+      ]
     }
   ],
   "errors": [
@@ -924,6 +1137,21 @@
       "code": 6019,
       "name": "InvalidDiscriminator",
       "msg": "could not parse instruction discriminator"
+    },
+    {
+      "code": 6020,
+      "name": "ResultUriTooLong",
+      "msg": "result_uri exceeds MAX_RESULT_URI_LEN"
+    },
+    {
+      "code": 6021,
+      "name": "InvalidQualityScore",
+      "msg": "quality_score exceeds MAX_QUALITY_SCORE (0-100)"
+    },
+    {
+      "code": 6022,
+      "name": "InvalidCompletedAt",
+      "msg": "completed_at must be > 0 and not in the future"
     }
   ],
   "types": [
@@ -953,6 +1181,18 @@
             ],
             "type": "pubkey"
           },
+          {
+            "name": "receiving_address",
+            "docs": [
+              "The agent's PERSONAL receiving wallet — a passive destination for",
+              "funds disbursed to this agent, intrinsic to the identity (like a",
+              "person's bank account). Owner-set anytime via",
+              "`set_agent_receiving_address`, independent of any company/deployment.",
+              "At `create_deployment` the deployment's `receiving_address` defaults",
+              "to this. `Pubkey::default()` = unset. NEVER a signer."
+            ],
+            "type": "pubkey"
+          },
           {
             "name": "created_at",
             "docs": [
@@ -1410,6 +1650,150 @@
           }
         ]
       }
+    },
+    {
+      "name": "TraceAnchorAccount",
+      "docs": [
+        "Per-deliverable provenance record. One per completed, verified task.",
+        "The deliverable content lives off-chain; this account locks its",
+        "identity, content hash, and verified quality so it is tamper-evident",
+        "and attributable. Reputation views are derived off-chain by folding",
+        "over these accounts per `agent`."
+      ],
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "version",
+            "docs": [
+              "Schema version."
+            ],
+            "type": "u8"
+          },
+          {
+            "name": "task_id",
+            "docs": [
+              "Hash of task creation params — globally unique task id, also baked",
+              "into the PDA seed."
+            ],
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            "name": "company",
+            "docs": [
+              "CompanyAccount the work was produced in (denormalized for indexing)."
+            ],
+            "type": "pubkey"
+          },
+          {
+            "name": "agent",
+            "docs": [
+              "AgentIdentity PDA that produced the deliverable. Reputation",
+              "aggregates against this (stable across redeployments), NOT the",
+              "per-company deployment."
+            ],
+            "type": "pubkey"
+          },
+          {
+            "name": "deployment",
+            "docs": [
+              "Deployment PDA active when the work was produced (company context)."
+            ],
+            "type": "pubkey"
+          },
+          {
+            "name": "result_uri",
+            "docs": [
+              "Link to the deliverable (article URL, PR, etc). Off-chain pointer."
+            ],
+            "type": "string"
+          },
+          {
+            "name": "content_hash",
+            "docs": [
+              "SHA-256 of the deliverable content at completion — tamper-evidence",
+              "for the result behind `result_uri`."
+            ],
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            "name": "verdict",
+            "docs": [
+              "Verification verdict. Always `TRACE_VERDICT_PASSED` — only passed",
+              "deliverables are anchored."
+            ],
+            "type": "u8"
+          },
+          {
+            "name": "quality_score",
+            "docs": [
+              "Rubric quality score 0-100 (see `MAX_QUALITY_SCORE`). Tamper-evident",
+              "quality signal, produced by the deterministic gate, not the agent."
+            ],
+            "type": "u8"
+          },
+          {
+            "name": "rubric_version",
+            "docs": [
+              "Version of the scoring rubric that produced `quality_score`. Scores",
+              "are only comparable within the same rubric version."
+            ],
+            "type": "u8"
+          },
+          {
+            "name": "evidence_hash",
+            "docs": [
+              "SHA-256 of the off-chain verification report (claims checked +",
+              "sources). Lets anyone audit WHY the verdict/score was assigned."
+            ],
+            "type": {
+              "array": [
+                "u8",
+                32
+              ]
+            }
+          },
+          {
+            "name": "completed_at",
+            "docs": [
+              "Unix timestamp the deliverable was completed off-chain."
+            ],
+            "type": "i64"
+          },
+          {
+            "name": "committed_at",
+            "docs": [
+              "Unix timestamp this commit landed on-chain."
+            ],
+            "type": "i64"
+          },
+          {
+            "name": "committed_by",
+            "docs": [
+              "Anchor Wallet pubkey that signed the commit. Mirror of",
+              "`OperationsAccount[Anchor].signer` at commit time."
+            ],
+            "type": "pubkey"
+          },
+          {
+            "name": "bump",
+            "docs": [
+              "Bump for PDA verification."
+            ],
+            "type": "u8"
+          }
+        ]
+      }
     }
   ]
 }

package/src/instructions.ts

@@ -4,6 +4,8 @@ import {
   TransactionInstruction,
 } from "@solana/web3.js";
 import {
+  MAX_QUALITY_SCORE,
+  MAX_RESULT_URI_LEN,
   OPERATIONS_KIND,
   REGISTRY_PROGRAM_ID,
   SOL_PSEUDO_MINT,
@@ -18,6 +20,7 @@ import {
   deriveOperationsPda,
   derivePolicyPda,
   deriveProtocolFeePda,
+  deriveTraceAnchorPda,
   deriveTreasuryPda,
   u32LeBytes,
 } from "./pda";
@@ -42,7 +45,9 @@ export const INSTRUCTION_DISCRIMINATOR = {
   updateDeploymentStatus: Buffer.from([225, 195, 150, 254, 178, 203, 53, 147]),
   retireDeployment: Buffer.from([45, 188, 162, 197, 136, 180, 202, 153]),
   setReceivingAddress: Buffer.from([70, 63, 44, 87, 16, 6, 156, 200]),
+  setAgentReceivingAddress: Buffer.from([197, 126, 122, 18, 38, 62, 179, 218]),
   commitDailyAnchor: Buffer.from([18, 7, 3, 65, 58, 148, 164, 0]),
+  commitTrace: Buffer.from([58, 140, 230, 51, 170, 109, 228, 125]),
 } as const;
 
 // ── Borsh primitives ────────────────────────────────────────────────────────
@@ -461,6 +466,40 @@ export function buildSetReceivingAddressInstruction(
   return { instruction };
 }
 
+export interface SetAgentReceivingAddressParams {
+  /** AgentIdentity PDA whose personal receiving wallet is being set. */
+  identityPda: PublicKey;
+  /** User wallet — must equal `identity.owner`. */
+  owner: PublicKey;
+  /** New personal receiving address (passive destination for funds
+   *  disbursed to this agent). Pass `PublicKey.default` to clear. NEVER a
+   *  signer — it never authorizes any on-chain action. */
+  newReceivingAddress: PublicKey;
+  programId?: PublicKey;
+}
+
+// Sets the agent's PERSONAL receiving wallet on the AgentIdentity itself —
+// independent of any company/deployment (Phase 4 marketplace). The deployment
+// receiving_address defaults from this at create_deployment.
+export function buildSetAgentReceivingAddressInstruction(
+  params: SetAgentReceivingAddressParams,
+): { instruction: TransactionInstruction } {
+  const programId = params.programId ?? REGISTRY_PROGRAM_ID;
+  const data = Buffer.concat([
+    INSTRUCTION_DISCRIMINATOR.setAgentReceivingAddress,
+    encodePubkey(params.newReceivingAddress),
+  ]);
+  const instruction = new TransactionInstruction({
+    programId,
+    keys: [
+      { pubkey: params.identityPda, isSigner: false, isWritable: true },
+      { pubkey: params.owner, isSigner: true, isWritable: false },
+    ],
+    data,
+  });
+  return { instruction };
+}
+
 // ── Treasury program ────────────────────────────────────────────────────────
 //
 // The treasury program is a SEPARATE program from registry — these
@@ -1169,3 +1208,113 @@ export function buildCommitDailyAnchorInstruction(
   });
   return { instruction };
 }
+
+export interface CommitTraceParams {
+  deploymentPda: PublicKey;
+  companyPda: PublicKey;
+  /** Anchor Wallet — must equal `operations.signer` (kind=Anchor). */
+  anchorSigner: PublicKey;
+  /** Anchor-kind OperationsAccount for this company (in TREASURY program,
+   *  read-only here). Caller derives via `deriveOperationsPda(company,
+   *  OPERATIONS_KIND.Anchor)`. */
+  operationsPda: PublicKey;
+  /** 32-byte hash of the task creation params — globally unique, becomes
+   *  part of the TraceAnchor PDA seed. */
+  taskId: Uint8Array | Buffer;
+  /** Link to the deliverable (article URL, PR, etc). Max
+   *  `MAX_RESULT_URI_LEN` bytes. */
+  resultUri: string;
+  /** SHA-256 of the deliverable content at completion (32 bytes). */
+  contentHash: Uint8Array | Buffer;
+  /** Rubric quality score, 0..=`MAX_QUALITY_SCORE`. */
+  qualityScore: number;
+  /** Version of the scoring rubric that produced `qualityScore`. */
+  rubricVersion: number;
+  /** SHA-256 of the off-chain verification report (32 bytes). */
+  evidenceHash: Uint8Array | Buffer;
+  /** Unix seconds the deliverable was completed off-chain. Must be > 0 and
+   *  not in the future. */
+  completedAt: bigint;
+  /** Rent payer (typically the operator hot wallet). */
+  payer: PublicKey;
+  programId?: PublicKey;
+}
+
+/**
+ * Build a `commit_trace` instruction — Anchor-class single-tx commit of one
+ * completed, VERIFIED deliverable. Signed by the Anchor Wallet bound to the
+ * company's Anchor-kind OperationsAccount (same authority as
+ * `commit_daily_anchor`).
+ *
+ * Only deliverables that passed the off-chain verification gate should be
+ * committed — the on-chain `verdict` is always Passed. Caller is
+ * responsible for:
+ *   1. Computing `contentHash` (SHA-256 of the deliverable)
+ *   2. Running the verification gate + scoring rubric off-chain
+ *   3. Computing `evidenceHash` (SHA-256 of the verification report)
+ *
+ * The verdict byte is fixed on-chain; it is not a caller arg.
+ */
+export function buildCommitTraceInstruction(params: CommitTraceParams): {
+  instruction: TransactionInstruction;
+  traceAnchorPda: PublicKey;
+} {
+  const programId = params.programId ?? REGISTRY_PROGRAM_ID;
+  if (params.taskId.length !== 32) {
+    throw new RangeError(`taskId must be 32 bytes, got ${params.taskId.length}`);
+  }
+  if (params.contentHash.length !== 32) {
+    throw new RangeError(
+      `contentHash must be 32 bytes, got ${params.contentHash.length}`,
+    );
+  }
+  if (params.evidenceHash.length !== 32) {
+    throw new RangeError(
+      `evidenceHash must be 32 bytes, got ${params.evidenceHash.length}`,
+    );
+  }
+  if (Buffer.from(params.resultUri, "utf8").length > MAX_RESULT_URI_LEN) {
+    throw new RangeError(
+      `resultUri exceeds MAX_RESULT_URI_LEN (${MAX_RESULT_URI_LEN} bytes)`,
+    );
+  }
+  if (params.qualityScore < 0 || params.qualityScore > MAX_QUALITY_SCORE) {
+    throw new RangeError(
+      `qualityScore out of range 0..=${MAX_QUALITY_SCORE}: ${params.qualityScore}`,
+    );
+  }
+
+  const taskId = Buffer.from(params.taskId);
+  const { pda: traceAnchorPda } = deriveTraceAnchorPda(taskId, programId);
+
+  // Wire arg order must match the Rust handler: task_id, result_uri,
+  // content_hash, quality_score, rubric_version, evidence_hash,
+  // completed_at. verdict is NOT a wire arg (fixed Passed on-chain).
+  const data = Buffer.concat([
+    INSTRUCTION_DISCRIMINATOR.commitTrace,
+    taskId,
+    encodeString(params.resultUri),
+    Buffer.from(params.contentHash),
+    encodeU8(params.qualityScore),
+    encodeU8(params.rubricVersion),
+    Buffer.from(params.evidenceHash),
+    encodeI64(params.completedAt),
+  ]);
+
+  const instruction = new TransactionInstruction({
+    programId,
+    // Order: deployment, company, anchor_signer, operations, trace_anchor,
+    // payer, system_program.
+    keys: [
+      { pubkey: params.deploymentPda, isSigner: false, isWritable: false },
+      { pubkey: params.companyPda, isSigner: false, isWritable: false },
+      { pubkey: params.anchorSigner, isSigner: true, isWritable: false },
+      { pubkey: params.operationsPda, isSigner: false, isWritable: false },
+      { pubkey: traceAnchorPda, isSigner: false, isWritable: true },
+      { pubkey: params.payer, isSigner: true, isWritable: true },
+      { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+    ],
+    data,
+  });
+  return { instruction, traceAnchorPda };
+}

package/src/pda.ts

@@ -8,6 +8,7 @@ import {
   POLICY_SEED,
   PROTOCOL_FEES_SEED,
   REGISTRY_PROGRAM_ID,
+  TRACE_SEED,
   TREASURY_PROGRAM_ID,
   TREASURY_SEED,
   type OperationsKind,
@@ -197,3 +198,27 @@ export function deriveDailyAnchorPda(
   );
   return { pda, bump };
 }
+
+/**
+ * TraceAnchorAccount PDA — owned by Registry program. One per completed,
+ * verified deliverable (article, PR, etc).
+ *
+ *   seeds = ["trace", task_id_32bytes]
+ *
+ * `taskId` is a 32-byte hash of the task creation params. Collision on the
+ * same `taskId` means the task is already anchored — a re-commit fails
+ * naturally (Anchor `init` rejects).
+ */
+export function deriveTraceAnchorPda(
+  taskId: Uint8Array,
+  programId: PublicKey = REGISTRY_PROGRAM_ID,
+): { pda: PublicKey; bump: number } {
+  if (taskId.length !== 32) {
+    throw new RangeError(`taskId must be 32 bytes, got ${taskId.length}`);
+  }
+  const [pda, bump] = PublicKey.findProgramAddressSync(
+    [TRACE_SEED, Buffer.from(taskId)],
+    programId,
+  );
+  return { pda, bump };
+}