@perena/vault-sdk 1.0.40 → 1.0.41

package/README.md

@@ -127,25 +127,33 @@ tracker fetches during submission.
 
 ## Incentive campaigns
 
-All six incentive instructions have exported `getTx` / `getIx` builders on
+All seven incentive instructions have exported `getTx` / `getIx` builders on
 `client.tx`: `createIncentive`, `addIncentiveRecipient`, `setIncentiveLimits`,
-`submitIncentive`, `cancelIncentiveProposal`, and `distributeIncentive`. Their
+`submitIncentive`, `cancelIncentiveProposal`, `distributeIncentive`, and
+`claimIncentive`. Their
 argument types are exported from `@perena/vault-sdk` alongside the builders.
-Submission resolves the oracle PDA and any tranche accounts. Distribution resolves
-registered recipients and creates their canonical share ATAs, including PDA wallet
-owners, for both SPL Token and Token-2022.
+Creation and enrollment take `oracle`, authorized against either of the first two
+active reporting slots; `getTx` derives the vault oracle PDA. Submission also resolves
+any tranche accounts. Distribution resolves registered recipients, creates canonical
+share ATAs for both token programs, and requires every paid recipient to co-sign.
 
 ```typescript
 import {
   getIncentiveRecipients,
+  getIncentiveReportRecipients,
   getIncentiveTotals,
   getIncentiveRecipientShareAtas,
   MAX_INCENTIVE_RECIPIENTS,
 } from "@perena/vault-sdk";
 
 const [incentive] = await client.pda.deriveIncentivePda(vault, 1n);
+const create = await client.tx.createIncentive.getTx({
+  oracle, vault, id: 1n, recipients: [recipient], maxTotalShares: 1_000_000n,
+});
+// Send with the oracle, then fetch the created account.
 const data = await client.account.fetchIncentiveForVault(vault, 1n);
 const recipients = getIncentiveRecipients(data); // registration order, bigint amounts
+const reportRecipients = getIncentiveReportRecipients(data); // frozen prefix while pending
 const totals = getIncentiveTotals(data); // settledShares, distributedShares, outstandingShares
 
 // Discover IDs instead of maintaining an off-chain list.
@@ -163,15 +171,40 @@ const proposal = {
   vault,
   incentive,
   roundId: BigInt(data.roundId.toString()),
-  totals: recipients.map(recipient => recipient.settledTotal + 100n),
+  totals: reportRecipients.map(recipient => recipient.settledTotal + 100n),
   expiresAt: (await client.account.fetchClockUnixTimestamp()) + 600n,
   maxSurplusValue: 0n,
 };
 const report = await client.tx.submitIncentive.getTx({ ...proposal, oracle });
-// After both oracle reports agree and funding is reserved:
+// After both reports agree and funding is reserved, the user signs when ready:
+const claim = await client.tx.claimIncentive.getTx({ recipient, vault, incentive });
+// Optional batch: collect signatures from every funded recipient as well as the cranker.
 const payout = await client.tx.distributeIncentive.getTx({ cranker, vault, incentive });
 ```
 
+`claimIncentive` reads the signing recipient's existing batch entry and creates no
+per-wallet program account. Reporting remains batched. Its payout updates the same
+lifetime counter as `distributeIncentive`, so claims and batch cranks can interleave
+without duplicate payment. The SDK creates only the claiming recipient's missing
+ATA. Five append-only recipients share each 408-byte batch account. Oracle enrollment
+preserves pending reports: new wallets join the following round. When pending,
+`getIncentiveReportRecipients` excludes those new slots; when idle, it returns all
+registered recipients. Persist and share the original payload for both signers.
+
+`distributeIncentive.getTx` adds required signer metas for each outstanding recipient;
+it does not collect signatures. Supply them when sending the transaction. A curator
+or oracle signature cannot replace recipient consent. For custom composition,
+`getIx` accepts optional `recipientSigners` (default: all `recipients`); append these
+after the full ordered ATA list. The program rejects any nonzero payout without
+that wallet's signature, including attempts with the old unsigned batch layout.
+A PDA recipient must consent through a signed CPI from its owning program.
+
+Creation/enrollment `getIx` calls now require `vaultOracle`; their signer argument is
+`oracle`, not `curator`. Upgrade the SDK with the program. Existing funded accounts
+remain valid: `proposalRecipientCount` uses former padding and the report helper
+handles pending version-1 accounts. Curator cap/floor changes and cancellation
+permissions are unchanged.
+
 Incentive fetches always read fresh state. Raw decoded integers use Anchor `BN`;
 the recipient and total helpers expose `bigint` without precision loss. Claims
 are cumulative lifetime **atomic share amounts**: `settledTotal - distributedTotal`
@@ -728,12 +761,13 @@ All builders are on `client.tx`:
 | Builder                         | Program instruction                                   | Typical signer        |
 | ------------------------------- | ----------------------------------------------------- | --------------------- |
 | `createVault`                   | `create_vault`                                        | Curator               |
-| `createIncentive`               | `create_incentive`                                    | Curator               |
-| `addIncentiveRecipient`         | `add_incentive_recipient`                             | Curator               |
+| `claimIncentive`                | `claim_incentive`                                     | Recipient             |
+| `createIncentive`               | `create_incentive`                                    | Either reporting oracle |
+| `addIncentiveRecipient`         | `add_incentive_recipient`                             | Either reporting oracle |
 | `setIncentiveLimits`            | `set_incentive_limits`                                | Curator               |
 | `submitIncentive`               | `submit_incentive`                                    | First two oracle slots |
 | `cancelIncentiveProposal`       | `cancel_incentive_proposal`                           | Curator, or anyone after expiry |
-| `distributeIncentive`           | `distribute_incentive`                                | Anyone                |
+| `distributeIncentive`           | `distribute_incentive`                                | Cranker + every paid recipient |
 | `createAssetHolding`            | `create_asset_holding`                                | HW manager            |
 | `removeAssetHolding`            | `remove_asset_holding`                                | HW manager            |
 | `updateConsensusSigners`        | `update_consensus_signers`                            | Curator               |