@cascade-fyi/sati-sdk 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-02-06
+
+### Added
+
+- `updateReputationScore` method for updating existing reputation scores
+- `validateReputationScoreContent` helper function
+- `SAS_DATA_LEN_OFFSET` constant for cleaner SAS account parsing
+- Content validation in `createReputationScore` and `updateReputationScore`
+- Bounds check on content length in `deserializeReputationScore`
+- Known Issues documentation section
+
+### Fixed
+
+- **BREAKING**: Migrated reputation scores to ReputationScoreV3 with VecU8 content layout, fixing variable-length JSON content support
+- Fixed SAS credential authorized signers: `satiPda` is now correctly added as an authorized signer, enabling `createReputationScore` to succeed
+- Fixed `fetchMaybeSchema` truthiness check that caused false negatives
+- Fixed `deriveReputationAttestationPda` to use correct nonce format
+- Deploy script is now fully idempotent for authorized signer management
+
+### Changed
+
+- `updateReputationScore` defaults to `ContentType.None` (was `ContentType.JSON`)
+- Replaced magic number 97 with named `SAS_DATA_LEN_OFFSET` constant
+
 ## [0.3.0] - 2025-01-27
 
 ### Added
@@ -43,5 +67,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Compressed attestation storage via Light Protocol
 - Basic querying via Photon RPC
 
+[0.4.0]: https://github.com/cascade-protocol/sati/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/cascade-protocol/sati/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/cascade-protocol/sati/releases/tag/v0.2.0

package/README.md

@@ -16,10 +16,10 @@ pnpm add @solana/kit @solana-program/token-2022 @coral-xyz/anchor
 ## Quick Start
 
 ```typescript
-import { SATI, Outcome } from "@cascade-fyi/sati-sdk";
+import { Sati, Outcome } from "@cascade-fyi/sati-sdk";
 
 // Initialize client
-const sati = new SATI({
+const sati = new Sati({
   network: "devnet",
   photonRpcUrl: "https://devnet.helius-rpc.com?api-key=YOUR_KEY", // For compressed attestations
 });
@@ -67,22 +67,15 @@ import {
 } from "@cascade-fyi/sati-sdk";
 
 // 1. Agent signs BEFORE knowing outcome (blind commitment)
-const interactionHash = computeInteractionHash({
+const interactionHash = computeInteractionHash(
   sasSchema,
   taskRef,          // 32-byte task identifier
-  tokenAccount,     // Agent's token address
   dataHash,         // Hash of request data
-});
+);
 const agentSig = await signMessage(agentKeypair, interactionHash);
 
-// 2. After task completion, counterparty signs WITH outcome
-const feedbackHash = computeFeedbackHash({
-  sasSchema,
-  taskRef,
-  tokenAccount,
-  outcome: Outcome.Positive,
-});
-const counterpartySig = await signMessage(clientKeypair, feedbackHash);
+// 2. After task completion, counterparty signs human-readable SIWS message
+// (built automatically by the SDK)
 ```
 
 ### Create Feedback Attestation
@@ -92,12 +85,10 @@ const result = await sati.createFeedback({
   payer,
   sasSchema,
   taskRef: new Uint8Array(32),    // CAIP-220 tx hash or arbitrary ID
-  tokenAccount: agentMint,
+  agentMint,                      // Agent's NFT mint address
   counterparty: clientAddress,
   dataHash: requestHash,
   outcome: Outcome.Positive,      // Negative, Neutral, Positive
-  tag1: "quality",                // Optional, max 32 chars
-  tag2: "speed",                  // Optional, max 32 chars
   content: JSON.stringify({ ... }), // Optional extended data
   agentSignature: {
     pubkey: agentAddress,
@@ -121,29 +112,21 @@ Validation attestations are for third-party validators assessing agent work:
 import { computeValidationHash, ValidationType } from "@cascade-fyi/sati-sdk";
 
 // 1. Agent signs blind (same as Feedback)
-const interactionHash = computeInteractionHash({
-  sasSchema: validationSchema,
+const interactionHash = computeInteractionHash(
+  validationSchema,
   taskRef,
-  tokenAccount: agentMint,
-  dataHash: workHash,             // Hash of work being validated
-});
+  workHash,             // Hash of work being validated
+);
 const agentSig = await signMessage(agentKeypair, interactionHash);
 
-// 2. Validator signs WITH response score
-const validationHash = computeValidationHash({
-  sasSchema: validationSchema,
-  taskRef,
-  tokenAccount: agentMint,
-  response: 95,                   // 0-100 score
-});
-const validatorSig = await signMessage(validatorKeypair, validationHash);
+// 2. Validator signs human-readable SIWS message (built by SDK)
 
 // 3. Create attestation
 const result = await sati.createValidation({
   payer,
   sasSchema: validationSchema,
   taskRef,
-  tokenAccount: agentMint,
+  agentMint,
   counterparty: validatorAddress,
   dataHash: workHash,
   validationType: ValidationType.Automated,  // Manual, Automated, Hybrid
@@ -163,31 +146,66 @@ const result = await sati.createValidation({
 });
 ```
 
-### Create ReputationScore (Regular Attestation)
+### Create ReputationScoreV3 (Regular Attestation)
+
+ReputationScoreV3 uses VecU8 for variable-length content and CounterpartySigned mode (provider only).
 
 ```typescript
-import { computeReputationHash } from "@cascade-fyi/sati-sdk";
+import {
+  computeInteractionHash,
+  computeReputationNonce,
+  zeroDataHash,
+  createJsonContent,
+  ContentType,
+} from "@cascade-fyi/sati-sdk";
 
-// Provider signs the score
-const reputationHash = computeReputationHash({
-  sasSchema,
-  tokenAccount: agentMint,
+// Compute deterministic nonce and taskRef
+const nonce = computeReputationNonce(providerAddress, agentMint);
+const taskRef = nonce; // same as nonce per spec
+const dataHash = zeroDataHash();
+
+// Provider signs the interaction hash
+const interactionHash = computeInteractionHash(sasSchema, taskRef, dataHash);
+const providerSig = await signMessage(providerKeypair, interactionHash);
+
+const result = await sati.createReputationScore({
+  payer,
   provider: providerAddress,
-  score: 85,
+  providerSignature: providerSig,
+  sasSchema,
+  satiCredential,
+  agentMint,
+  taskRef,
+  dataHash,
+  outcome: Outcome.Positive,
+  contentType: ContentType.JSON,
+  content: createJsonContent({
+    score: 85,
+    methodology: "weighted_feedback",
+    feedbackCount: 127,
+    validationCount: 5,
+  }),
 });
-const providerSig = await signMessage(providerKeypair, reputationHash);
+```
 
-const result = await sati.createReputationScore({
+### Update ReputationScoreV3
+
+High-level convenience method that closes the existing score and creates a new one:
+
+```typescript
+const result = await sati.updateReputationScore({
   payer,
+  provider: providerKeypair,  // Must be KeyPairSigner (signs close + create)
   sasSchema,
   satiCredential,
-  tokenAccount: agentMint,
-  provider: providerAddress,
-  score: 85,                      // 0-100 normalized score
-  providerSignature: providerSig,
-  content: JSON.stringify({
+  agentMint,
+  outcome: Outcome.Positive,
+  contentType: ContentType.JSON,
+  content: createJsonContent({
+    score: 90,
     methodology: "weighted_feedback",
-    feedback_count: 127,
+    feedbackCount: 150,
+    validationCount: 8,
   }),
 });
 ```
@@ -206,7 +224,7 @@ const attestations = await rpc.getCompressedAccountsByOwner({
   owner: SATI_PROGRAM_ADDRESS,
   filters: [
     { memcmp: { offset: 8, bytes: feedbackSchema } },
-    { memcmp: { offset: 40, bytes: agentTokenAccount } },
+    { memcmp: { offset: 40, bytes: agentMint } },
   ],
 });
 
@@ -216,7 +234,7 @@ const toClose = attestations.value.items[0];
 const result = await sati.closeAttestation({
   payer,
   sasSchema: feedbackSchema,
-  tokenAccount: agentTokenAccount,
+  agentMint,
   // Current attestation state (for proof verification)
   dataType: DataType.Feedback,
   currentData: toClose.data,
@@ -229,20 +247,20 @@ const result = await sati.closeAttestation({
 console.log(result.signature);    // Transaction signature
 ```
 
-### Close Regular Attestation (ReputationScore)
+### Close Regular Attestation (ReputationScoreV3)
 
 ```typescript
-// ReputationScore uses SAS storage, close via PDA
+// ReputationScoreV3 uses SAS storage, close via PDA
 const result = await sati.closeReputationScore({
   payer,
   sasSchema: reputationSchema,
   satiCredential,
-  tokenAccount: agentMint,
+  agentMint,
   provider: providerAddress,      // Provider who created it
 });
 ```
 
-**Note:** Only the original provider can close a ReputationScore. Compressed attestations can be closed by anyone with the proof, but the rent goes back to the original payer.
+**Note:** Only the original provider can close a ReputationScoreV3. Compressed attestations can be closed by anyone with the proof, but the rent goes back to the original payer.
 
 ---
 
@@ -262,8 +280,8 @@ const feedbacks = await rpc.getCompressedAccountsByOwner({
   filters: [
     // sas_schema at offset 8 (after 8-byte Light discriminator)
     { memcmp: { offset: 8, bytes: feedbackSchemaAddress } },
-    // token_account at offset 40
-    { memcmp: { offset: 40, bytes: agentTokenAccount } },
+    // agent_mint at offset 40
+    { memcmp: { offset: 40, bytes: agentMint } },
   ],
   limit: 50,
 });
@@ -282,7 +300,7 @@ The SDK exports offset constants for filtering:
 
 ```typescript
 import {
-  COMPRESSED_OFFSETS,   // Base offsets (sas_schema, token_account)
+  COMPRESSED_OFFSETS,   // Base offsets (sas_schema, agent_mint)
   FEEDBACK_OFFSETS,     // Feedback-specific (outcome at 129 + 8)
   VALIDATION_OFFSETS,   // Validation-specific (response at 130 + 8)
 } from "@cascade-fyi/sati-sdk";
@@ -291,7 +309,7 @@ import {
 | Field | Offset | Notes |
 |-------|--------|-------|
 | `sas_schema` | 8 | Filter by attestation type |
-| `token_account` | 40 | Filter by agent |
+| `agent_mint` | 40 | Filter by agent |
 | `outcome` (Feedback) | 137 | 0=Negative, 1=Neutral, 2=Positive |
 | `response` (Validation) | 138 | Score 0-100 |
 
@@ -345,7 +363,7 @@ const result = await sati.createFeedback({
   payer,
   sasSchema,
   taskRef,
-  tokenAccount: agentMint,
+  agentMint,
   counterparty: clientAddress,
   dataHash: requestHash,
   outcome: Outcome.Positive,
@@ -545,7 +563,7 @@ try {
 |-------|-------|----------|
 | `InvalidSignatureCount` | Wrong number of sigs for SignatureMode | DualSignature needs 2, SingleSigner needs 1 |
 | `SignatureMismatch` | Sig pubkey doesn't match expected | Verify agent signs interaction hash, counterparty signs feedback hash |
-| `SelfAttestationNotAllowed` | `tokenAccount == counterparty` | Use different addresses for agent and counterparty |
+| `SelfAttestationNotAllowed` | `agentMint == counterparty` | Use different addresses for agent and counterparty |
 | `InvalidAuthority` | Signer is not registry authority | Only authority can register schemas |
 | `ImmutableAuthority` | Registry authority was renounced | Cannot modify immutable registry |
 | `AttestationNotCloseable` | Schema has `closeable: false` | Use a different schema or don't close |
@@ -602,7 +620,7 @@ function validateFeedbackParams(params: CreateFeedbackParams) {
   if (params.content && params.content.length > MAX_CONTENT_SIZE) {
     throw new Error(`content exceeds ${MAX_CONTENT_SIZE} bytes`);
   }
-  if (params.tokenAccount === params.counterparty) {
+  if (params.agentMint === params.counterparty) {
     throw new Error("Self-attestation not allowed");
   }
 }
@@ -616,10 +634,12 @@ function validateFeedbackParams(params: CreateFeedbackParams) {
 
 ```typescript
 import {
-  computeInteractionHash,  // Agent signs (blind to outcome)
-  computeFeedbackHash,     // Counterparty signs (with outcome)
-  computeValidationHash,   // Validator signs (with response)
-  computeReputationHash,   // Provider signs (with score)
+  computeInteractionHash,   // Agent signs (blind to outcome)
+  computeAttestationNonce,  // Deterministic nonce for compressed attestation address
+  computeReputationNonce,   // Deterministic nonce for ReputationScoreV3 (one per provider+agent)
+  computeDataHash,          // Hash request + response content
+  computeDataHashFromStrings, // Convenience wrapper for string content
+  zeroDataHash,             // Zero-filled hash for CounterpartySigned schemas
 } from "@cascade-fyi/sati-sdk";
 ```