@perena/vault-sdk 1.0.37 → 1.0.40

package/README.md

@@ -125,6 +125,68 @@ 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 six incentive instructions have exported `getTx` / `getIx` builders on
+`client.tx`: `createIncentive`, `addIncentiveRecipient`, `setIncentiveLimits`,
+`submitIncentive`, `cancelIncentiveProposal`, and `distributeIncentive`. 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.
+
+```typescript
+import {
+  getIncentiveRecipients,
+  getIncentiveTotals,
+  getIncentiveRecipientShareAtas,
+  MAX_INCENTIVE_RECIPIENTS,
+} from "@perena/vault-sdk";
+
+const [incentive] = await client.pda.deriveIncentivePda(vault, 1n);
+const data = await client.account.fetchIncentiveForVault(vault, 1n);
+const recipients = getIncentiveRecipients(data); // registration order, bigint amounts
+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: recipients.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:
+const payout = await client.tx.distributeIncentive.getTx({ cranker, vault, incentive });
+```
+
+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 +728,12 @@ All builders are on `client.tx`:
 | Builder                         | Program instruction                                   | Typical signer        |
 | ------------------------------- | ----------------------------------------------------- | --------------------- |
 | `createVault`                   | `create_vault`                                        | Curator               |
+| `createIncentive`               | `create_incentive`                                    | Curator               |
+| `addIncentiveRecipient`         | `add_incentive_recipient`                             | Curator               |
+| `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                |
 | `createAssetHolding`            | `create_asset_holding`                                | HW manager            |
 | `removeAssetHolding`            | `remove_asset_holding`                                | HW manager            |
 | `updateConsensusSigners`        | `update_consensus_signers`                            | Curator               |
@@ -692,7 +760,6 @@ All builders are on `client.tx`:
 | `updateAssetPrice`              | `update_asset_price`                                  | Oracle keeper         |
 | `vaultReallocation`             | `vault_reallocation`                                  | HW manager            |
 | `withdrawProtocolFees`          | `withdraw_protocol_fees`                              | Curator               |
-| `withdrawTrancheFees`           | `withdraw_tranche_fees`                               | Curator               |
 
 Argument shapes for each builder: [`src/client/builders/args.ts`](src/client/builders/args.ts).