@perena/vault-sdk 1.0.38 → 1.0.41

package/README.md

@@ -125,6 +125,101 @@ for NAV accounts backed only by a current-price API. NAV cashflows have no
 `date` or `fundingNextDay` parameter: they execute immediately at the price the
 tracker fetches during submission.
 
+## Incentive campaigns
+
+All seven incentive instructions have exported `getTx` / `getIx` builders on
+`client.tx`: `createIncentive`, `addIncentiveRecipient`, `setIncentiveLimits`,
+`submitIncentive`, `cancelIncentiveProposal`, `distributeIncentive`, and
+`claimIncentive`. Their
+argument types are exported from `@perena/vault-sdk` alongside the builders.
+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.
+const campaigns = await client.account.fetchAllIncentivesForVault(vault);
+// Each result: { publicKey: Address, account: VaultIncentiveAccountData }.
+const maybeCampaign = await client.account.fetchIncentiveNullable(incentive);
+const batch = await client.account.fetchIncentives([incentive]);
+// Batch preserves input order, duplicates, and nulls for missing accounts.
+
+// Needed only for custom instruction composition; getTx derives these itself.
+const recipientAtas = getIncentiveRecipientShareAtas(data, shareMint, shareTokenProgram);
+
+// Prepare this payload once and share the SAME values with both oracle signers.
+const proposal = {
+  vault,
+  incentive,
+  roundId: BigInt(data.roundId.toString()),
+  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 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`
+is currently payable, and unfinished oracle reports are excluded. Up to
+`MAX_INCENTIVE_RECIPIENTS` (five) wallets may be registered. `maxSurplusValue` and
+`minSurplusReserve` use vault accounting units, rather than share units.
+
+Use the live clock helper for deadlines; historical block timestamps can lag
+execution time after validator time travel. Keep the round, expiry, surplus debit
+limit and totals identical across the two oracle submissions. The program still
+enforces authorization, campaign caps and available funding when agreement occurs.
+
+For instruction semantics and the full accounting model, see
+[`docs/incentives.md`](../../docs/incentives.md).
+
 ## Creating transactions
 
 ### The builder pattern
@@ -666,6 +761,13 @@ All builders are on `client.tx`:
 | Builder                         | Program instruction                                   | Typical signer        |
 | ------------------------------- | ----------------------------------------------------- | --------------------- |
 | `createVault`                   | `create_vault`                                        | 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`                                | Cranker + every paid recipient |
 | `createAssetHolding`            | `create_asset_holding`                                | HW manager            |
 | `removeAssetHolding`            | `remove_asset_holding`                                | HW manager            |
 | `updateConsensusSigners`        | `update_consensus_signers`                            | Curator               |