@perena/vault-sdk 1.0.66 → 1.0.68

package/README.md

@@ -663,6 +663,109 @@ const plan = await client.tx.executeTrancheDeposit.getTx({
 await client.sendTransaction(payer, plan);
 ```
 
+### Example: async regular-share redemption
+
+Regular shares default to synchronous redemption. The curator can set
+`redemptionMode: { asyncOnly: {} }` through `setVaultConfig` (or restore
+`{ synchronous: {} }`). Configure `fulfiller` using the existing role timelock
+before processing requests. Async-only mode blocks direct regular withdrawals,
+including fee-exempt/external variants, and regular-to-tranche share swaps.
+Junior and senior tranche redemption policies are unchanged.
+
+```typescript
+await client.sendTransaction(curator, await client.tx.setVaultConfig.getTx({
+  curator: fromWeb3Pk(curator.publicKey),
+  vault,
+  redemptionMode: { asyncOnly: {} },
+}));
+
+await client.sendTransaction(user, await client.tx.requestAsyncWithdraw.getTx({
+  user: fromWeb3Pk(user.publicKey),
+  vault,
+  assetMint,
+  queueId: 0,
+  shareAmount: 100_000n,
+}));
+
+const pending = await client.account.fetchPendingRedemptionQueues(vault);
+// Optional second argument restricts the results to one owner.
+
+// Optional: the HW manager locks the current net output-token payout once.
+await client.sendTransaction(hwManager, await client.tx.priceAsyncWithdraw.getTx({
+  hwManager: fromWeb3Pk(hwManager.publicKey),
+  vault,
+  withdrawalQueue: pending[0].publicKey,
+}));
+
+await client.sendTransaction(fulfiller, await client.tx.fulfillAsyncWithdraw.getTx({
+  signer: fromWeb3Pk(fulfiller.publicKey),
+  owner: fromWeb3Pk(user.publicKey),
+  vault,
+  assetMint,
+  queueId: 0,
+}));
+```
+
+Requests escrow shares without changing supply or NAV. Only the configured
+fulfiller can settle regular requests, with no minimum settlement delay.
+Unpriced requests use current NAV, asset prices, and burn fees. The HW manager
+can price a request once, recording `request.outputAmount` in output-token
+atomic units, `pricedTs`, and `feeShareAmount`. A positive `pricedTs` marks a
+locked quote, even when its payout is zero. Pricing uses fresh oracle state and
+regular-share backing (excluding tranches), applies the owner's fee exemption,
+and does not require liquidity, burn shares, reserve assets, or change NAV.
+Repricing is rejected.
+
+Priced requests settle the recorded net tokens and fee shares. NAV is debited
+by the locked tokens' value at the current output asset price, so settlement
+still requires fresh oracle state. Current withdrawal limits apply to both
+paths. Settlement is all-or-nothing,
+burns the requested shares, pays the owner's asset ATA, returns surplus escrow
+shares, and refunds queue/escrow rent to the original payer. The builder creates
+missing owner ATAs and resolves the recorded rent payer. Settlement uses the
+vault's local token balance first and pulls only the net payout's shortfall from
+external liquidity. The builder reads the queue fresh and compares its locked
+payout (or a current quote when unpriced) against the live local balance.
+When local funds cover the payout, it omits external
+CPI accounts and lookups. Otherwise it prepares the same single-source external
+resolution as junior queue fulfillment. Explicit CPI refs remain caller-controlled.
+Insufficient combined liquidity leaves the request pending. If liquidity or
+pricing changes after building a local-only transaction, rebuild it to resolve
+any newly required external accounts; the fulfiller does this on its next run.
+
+Both share classes share the existing `VaultWithdrawalQueue` layout and the
+256 queue IDs per owner/vault. `fetchAllWithdrawalQueues` supports vault, owner,
+and input-mint filters; `fetchPendingRedemptionQueues` selects regular shares.
+`WithdrawalQueueService` routes by input mint, so previously accepted requests
+remain fulfillable after switching back to synchronous mode. Service snapshots
+include nullable `outputAmount` and `pricedTs`; fulfillment always refreshes
+the queue before building its instruction.
+
+Only the request owner can cancel a regular-share request, and only when chain
+time is **strictly more than 30 days** after `requestTs`, whether priced or
+unpriced. `cancelAsyncWithdraw.getTx({ user, vault, queueId })` recreates a
+missing owner share ATA, returns all escrow shares (including surplus), and
+refunds queue/escrow rent to the recorded payer without charging redemption fees.
+The legacy `cancelJuniorTrancheWithdraw` route enforces the same delay for
+regular shares; junior queue cancellation retains its existing behavior.
+
+The curator console's **Redemptions** tab shows pending regular-share requests,
+their locked payouts and pricing timestamps, and owner cancellation eligibility.
+**Price all unpriced** packs instructions up to the transaction size limit and
+uses the HW-manager wallet's `signAllTransactions` where supported. Each request
+is priced when its transaction executes; separate transactions are not a single
+atomic snapshot. Failed batches remain pending and can be refreshed and retried.
+
+The redemption mode occupies an existing zeroed vault padding byte, preserving
+account size and offsets. Pricing fields reuse three words of queue padding:
+existing queues decode as unpriced, and queue accounts remain 296 bytes including
+the discriminator. No account migration is needed. Deploy the updated program
+and publish a new SDK release, then update and rebuild the backend fulfiller
+with that release (including its package lock) before enabling manager pricing.
+SDK 1.0.67 predates the pricing fields and cannot reliably prepare liquidity
+accounts for a locked payout. Existing config payloads that omit the trailing
+mode option remain valid.
+
 ### Example: junior withdrawal queue
 
 ```typescript
@@ -875,7 +978,7 @@ Argument shapes for each builder: [`src/client/builders/args.ts`](src/client/bui
 For recurring backend work, prefer the services layer over reimplementing
 discovery logic in your app:
 
-- **`WithdrawalQueueService`** — scan and fulfill eligible junior withdrawal
+- **`WithdrawalQueueService`** — scan and fulfill regular and eligible junior withdrawal
   queues (`src/services/withdrawalQueueService.ts`)
 - **`OracleService`** — consensus oracle / asset price updates
   (`src/services/oracleService.ts`)