@perena/vault-sdk 1.0.65 → 1.0.67

package/README.md

@@ -663,6 +663,72 @@ 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.
+
+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. There is no fixed lockup:
+only the configured fulfiller can settle regular requests, using current NAV,
+asset prices, burn fees, and withdrawal limits. 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 checks fresh pricing, the queued share amount,
+and 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. The existing
+`cancelJuniorTrancheWithdraw` on-chain instruction also accepts regular queues;
+its SDK builder can be used with the regular mint as `juniorShareMint` and an
+explicit `shareTokenProgram` until a generic cancellation name is introduced.
+
+The redemption mode occupies an existing zeroed vault padding byte, preserving
+account size and offsets. Deploy the updated program and publish SDK 1.0.67
+before rebuilding the backend fulfiller pinned to that version. Existing config
+payloads that omit the trailing mode option remain valid.
+Use the refreshed IDL/SDK to set the new policy.
+
 ### Example: junior withdrawal queue
 
 ```typescript
@@ -875,7 +941,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`)