infra-sdk-typescript 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -352,8 +352,27 @@ declare class WalletResource extends APIResource {
 
 type TokenType = "ASSET" | "YIELD_BEARING";
 type TokenStatus = LooseUnion<"PENDING" | "ACTIVE" | "PAUSED" | "RETIRED">;
-type TokenTransactionType = LooseUnion<"MINT" | "BURN" | "TRANSFER" | "DEPLOY" | "REDEEM" | "SNAPSHOT">;
+type TokenTransactionType = LooseUnion<"MINT" | "BURN" | "TRANSFER" | "DEPLOY" | "REDEEM" | "SNAPSHOT" | "FORCED_TRANSFER" | "CLAIM" | "RECLAIM">;
 type TokenTransactionStatus = LooseUnion<"PENDING" | "CONFIRMED" | "FAILED">;
+/**
+ * Where pushing a distribution's yield to investors stands, on a `SNAPSHOT` transaction created
+ * with `pushYield: true`.
+ *
+ * - `PENDING` — requested; the push runs once the snapshot confirms.
+ * - `SUBMITTED` — the push transaction was sent but hasn't settled yet.
+ * - `PUSHED` — the push transaction was mined and succeeded.
+ * - `FAILED` — the push failed; see `pushFailureReason`.
+ */
+type YieldPushStatus = LooseUnion<"PENDING" | "SUBMITTED" | "PUSHED" | "FAILED">;
+/**
+ * Outcome of a yield claim or reclaim when the call returns.
+ *
+ * - `COMPLETED` — the transaction was mined and succeeded.
+ * - `SUBMITTED` — the transaction was sent but hasn't settled yet. Poll
+ *   {@link TokenizationResource.getTokenTransaction} with the result's `operationRef`; its `status`
+ *   becomes `CONFIRMED` or `FAILED`.
+ */
+type YieldSettlementStatus = LooseUnion<"COMPLETED" | "SUBMITTED">;
 /**
  * Chain id a token is deployed on, e.g. `84532` (Base Sepolia). The API accepts it as a number
  * or a numeric string; responses always return it as a string.
@@ -522,6 +541,11 @@ interface TokenOperationResult {
 /** Result of {@link TokenizationResource.transferToken}. */
 interface TokenTransferResult {
     tokenId: string;
+    /**
+     * `CONFIRMED` once mined. `FAILED` when the transfer was rejected or reverted on-chain; the call
+     * still resolves in that case, so check this rather than relying on an error. `txHash` is set
+     * when the failed transfer was mined.
+     */
     status: TokenTransactionStatus;
     transactionId: string;
     fromAddressIndex: number;
@@ -567,6 +591,24 @@ interface TokenWalletBalance {
     balance: string;
     decimals: number;
 }
+interface GetPayoutBalanceParams {
+    chainId: TokenChainId;
+    walletAddress: string;
+}
+/**
+ * A wallet's balance of the chain's payout token, returned by
+ * {@link TokenizationResource.getPayoutBalance}. Coupons, yield and principal are all paid in it.
+ */
+interface PayoutBalance {
+    chainId: string;
+    walletAddress: string;
+    payoutToken: YieldPayoutToken;
+    /** The payout token's contract address on this chain. */
+    tokenAddress: string;
+    /** Balance in payout-token units, as a decimal string, e.g. `"1234.56"`. */
+    balance: string;
+    decimals: number;
+}
 interface ListTokenTransactionsParams {
     tokenId?: string;
     chainId?: TokenChainId;
@@ -579,7 +621,10 @@ interface ListTokenTransactionsParams {
     txHash?: string;
     operationRef?: string;
 }
-/** A recorded on-chain operation against a token (mint, burn, or transfer). */
+/**
+ * A recorded on-chain operation against a token: a mint, burn or transfer, a deployment, a yield
+ * distribution (`SNAPSHOT`), or a yield claim (`CLAIM`) or reclaim (`RECLAIM`).
+ */
 interface TokenTransactionRecord {
     id: string;
     tokenId: string;
@@ -600,8 +645,18 @@ interface TokenTransactionRecord {
     memo?: string;
     createdAt?: string;
     confirmedAt?: string;
-    /** Distribution snapshot id, set on `SNAPSHOT` transactions. */
+    /** Distribution snapshot id, set on `SNAPSHOT`, `CLAIM` and `RECLAIM` transactions. */
     snapshotId?: number;
+    /** Why the transaction failed, when `status` is `FAILED`. */
+    failureReason?: string;
+    /** Whether the distribution pushes yield to investors. Set on `SNAPSHOT` transactions. */
+    pushYield?: boolean;
+    /** Progress of the push, on `SNAPSHOT` transactions with `pushYield`. Absent when no push was requested or made. */
+    pushStatus?: YieldPushStatus;
+    /** Hash of the push transaction, once sent. */
+    pushTxHash?: string;
+    /** Why the push failed, when `pushStatus` is `FAILED`. */
+    pushFailureReason?: string;
 }
 interface UpdateTokenYieldParams {
     /** Yield-bearing token id. */
@@ -616,6 +671,7 @@ interface UpdateYieldResult {
     currentRate: number;
     /** Annual rate after the update, as a percentage. */
     newRate: number;
+    operationRef: string;
     txHash: string;
 }
 interface DistributeYieldParams {
@@ -654,12 +710,89 @@ interface RedeemPrincipalParams {
     tokenId: string;
     chainId: TokenChainId;
 }
-/** Result of {@link TokenizationResource.redeemPrincipal} — one transaction per redemption payout. */
+/**
+ * Why a holder was left out of a redemption. Their principal is still owed once the cause is resolved.
+ *
+ * - `NOT_VERIFIED` — not KYC-verified in the token's identity registry.
+ * - `FROZEN` — the wallet is frozen.
+ * - `NOT_ALLOWLISTED` — removed from the compliance allowlist.
+ * - `SKIPPED_BY_CONTRACT` — eligible when read, but the contract skipped it when the batch executed
+ *   (e.g. it became ineligible in between).
+ */
+type RedemptionSkipReason = LooseUnion<"NOT_VERIFIED" | "FROZEN" | "NOT_ALLOWLISTED" | "SKIPPED_BY_CONTRACT">;
+/** A holder {@link TokenizationResource.redeemPrincipal} did not redeem. */
+interface RedemptionSkippedHolder {
+    address: string;
+    /** Unredeemed balance in the token's smallest unit, as an integer string. */
+    balance: string;
+    reasons: RedemptionSkipReason[];
+}
+/** Result of {@link TokenizationResource.redeemPrincipal}. */
 interface RedeemPrincipalResult {
     tokenId: string;
     operationRef: string;
+    /** Transaction records created by this run: the issuer-token burn (if any), then one per redemption batch. */
     transactionIds: string[];
+    /** Hashes in send order: the burn, each batch, then the seal that marks the principal repaid (if one was needed). */
     txHashes: string[];
+    /** Holders actually paid, from the contract's `PrincipalRedeemed` events. */
+    redeemedHolders: number;
+    /** Principal actually paid, in cNGN base units (6 decimals), as an integer string. */
+    paidPrincipal: string;
+    /** {@link paidPrincipal} as a decimal cNGN string, e.g. `"100000.0"`. */
+    paidPrincipalFormatted: string;
+    /**
+     * Indexes of batches whose receipt couldn't be read. Their transactions landed, but their paid amounts
+     * are the pre-transaction estimate rather than the on-chain events.
+     */
+    unreconciledBatches: number[];
+    /** Holders that were not redeemed, with their balances and why. */
+    skipped: RedemptionSkippedHolder[];
+    /** Issuer-held (treasury) tokens burned without a payout, or `null` when there were none. Frozen tokens are never burned. */
+    treasuryBurned: {
+        amount: string;
+        txHash: string;
+    } | null;
+    /** Supply left after the run, in the token's smallest unit, as an integer string. */
+    outstandingSupply: string;
+    /**
+     * `true` once supply is zero and the bond is marked principal-repaid. While `false`, the remaining
+     * supply belongs to {@link skipped} holders, frozen issuer tokens or the yield distributor.
+     */
+    closed: boolean;
+}
+interface GetNextCouponParams {
+    tokenId: string;
+    chainId: TokenChainId;
+}
+/**
+ * Where a bond stands on its coupon schedule.
+ *
+ * - `SCHEDULED` — the next coupon isn't due yet.
+ * - `DUE` — the coupon can be paid now with {@link TokenizationResource.payCoupon}.
+ * - `GRACE_EXPIRED` — the coupon was missed and its grace period has passed; it is still payable,
+ *   but anyone can now flag the bond as defaulted.
+ * - `DEFAULTED` — the bond is in default; no further coupons can be scheduled.
+ * - `NO_MORE_COUPONS` — the schedule has run past maturity; only principal redemption remains.
+ * - `CLOSED` — principal has been repaid and the bond is closed.
+ */
+type NextCouponStatus = LooseUnion<"SCHEDULED" | "DUE" | "GRACE_EXPIRED" | "DEFAULTED" | "NO_MORE_COUPONS" | "CLOSED">;
+/** Result of {@link TokenizationResource.getNextCoupon}. Dates are ISO 8601 strings in UTC. */
+interface NextCoupon {
+    tokenId: string;
+    chainId: string;
+    status: NextCouponStatus;
+    /** When the next coupon falls due. `null` once there are no more coupons (`NO_MORE_COUPONS` or `CLOSED`). */
+    nextCouponDate: string | null;
+    /** `nextCouponDate` plus the bond's grace period; after this a missed coupon allows a default. `null` with it. */
+    graceEndsAt: string | null;
+    /** `true` when a coupon can be paid now (`DUE` or `GRACE_EXPIRED`). */
+    isDue: boolean;
+    /** Seconds between coupons. */
+    couponPeriodSeconds: number;
+    maturityDate: string;
+    /** Coupon paid per whole token, in cNGN, as a decimal string. */
+    couponPerToken: string;
 }
 interface ReclaimUnclaimedYieldParams {
     tokenId: string;
@@ -670,16 +803,22 @@ interface ReclaimUnclaimedYieldParams {
 /** Result of {@link TokenizationResource.reclaimUnclaimedYield}. */
 interface ReclaimUnclaimedYieldResult {
     tokenId: string;
-    /** Snapshot id, as a numeric string. */
-    snapshotId: string;
-    /** Amount reclaimed, as a decimal string. */
+    snapshotId: number;
+    /** Amount reclaimed, in cNGN base units (6 decimals), as an integer string. */
     reclaimed: string;
     operationRef: string;
+    /** Id of the `RECLAIM` transaction record. */
+    transactionId: string;
     txHash: string;
+    status: YieldSettlementStatus;
 }
 /** Result of {@link TokenizationResource.claimYield}. */
 interface YieldTxResult {
+    operationRef: string;
+    /** Id of the `CLAIM` transaction record. */
+    transactionId: string;
     txHash: string;
+    status: YieldSettlementStatus;
 }
 /** Result of {@link TokenizationResource.distributeYield} / {@link TokenizationResource.payCoupon}. */
 interface YieldOperationResult {
@@ -718,7 +857,10 @@ declare class TokenizationResource extends APIResource {
     mintToken(params: MintTokenParams, overrides?: IdempotentRequestOverrides): Promise<TokenOperationResult>;
     /** Burns units of a token from a holder address. */
     burnToken(params: BurnTokenParams, overrides?: IdempotentRequestOverrides): Promise<TokenOperationResult>;
-    /** Transfers token units between holder addresses. */
+    /**
+     * Transfers token units between holder addresses. A transfer that is rejected or reverts
+     * on-chain still resolves, with `status: "FAILED"`, so check `status` rather than relying on an error.
+     */
     transferToken(params: TransferTokenParams, overrides?: IdempotentRequestOverrides): Promise<TokenTransferResult>;
     /**
      * Force-transfers token units out of a holder's address without the holder's signature
@@ -730,25 +872,57 @@ declare class TokenizationResource extends APIResource {
     registerWallet(params: RegisterTokenWalletParams, overrides?: IdempotentRequestOverrides): Promise<RegisterTokenWalletResult>;
     /** Returns the paginated list of holder wallet addresses and balances for a token on a chain. */
     getTokenHolders(params: GetTokenHoldersParams, overrides?: RequestOverrides): Promise<Page<TokenHolder>>;
-    /** Returns a single wallet's balance of a token on a chain. */
+    /** Returns a single wallet's balance of a token on a chain. For its cNGN balance, use {@link getPayoutBalance}. */
     getWalletBalance(params: GetWalletBalanceParams, overrides?: RequestOverrides): Promise<TokenWalletBalance>;
+    /**
+     * Returns a wallet's balance of the chain's payout token (cNGN), in which coupons, yield and
+     * principal are paid. It depends only on the chain and wallet, so no token is needed.
+     */
+    getPayoutBalance(params: GetPayoutBalanceParams, overrides?: RequestOverrides): Promise<PayoutBalance>;
     /** Fetches a single token transaction by its reference. */
     getTokenTransaction(ref: string, overrides?: RequestOverrides): Promise<TokenTransactionRecord>;
     /** Returns token transactions, optionally filtered by token. */
     listTokenTransactions(params?: ListTokenTransactionsParams, overrides?: RequestOverrides): Promise<Page<TokenTransactionRecord>>;
-    /** Updates the annual yield rate for a yield-bearing token. */
-    updateYield(params: UpdateTokenYieldParams, overrides?: RequestOverrides): Promise<UpdateYieldResult>;
+    /**
+     * Updates the annual yield rate for a yield-bearing token. An `Idempotency-Key` is generated
+     * per call unless you pass your own.
+     */
+    updateYield(params: UpdateTokenYieldParams, overrides?: IdempotentRequestOverrides): Promise<UpdateYieldResult>;
     /** Funds and distributes a yield payout to holders. Unclaimed funds may be reclaimed after `reclaimAfter`. */
     distributeYield(params: DistributeYieldParams, overrides?: IdempotentRequestOverrides): Promise<YieldOperationResult>;
     /** Pays the scheduled coupon for a yield-bearing token. Set `pushYield` to push funds rather than let investors claim. */
     payCoupon(params: PayCouponParams, overrides?: IdempotentRequestOverrides): Promise<YieldOperationResult>;
-    /** Claims an investor's yield for a given distribution snapshot. */
+    /**
+     * Claims an investor's yield for a given distribution snapshot. `status` is `COMPLETED` once the
+     * claim is mined. If it's `SUBMITTED`, the outcome isn't known yet: poll
+     * {@link getTokenTransaction} with the result's `operationRef` until its `status` is `CONFIRMED` or `FAILED`.
+     */
     claimYield(params: ClaimYieldParams, overrides?: IdempotentRequestOverrides): Promise<YieldTxResult>;
-    /** Redeems principal to holders at maturity. */
+    /**
+     * Returns the bond's next coupon date and where it stands on its schedule. Whether a coupon is
+     * due is decided by the chain's clock, not yours, so check `status` (or `isDue`) rather than
+     * comparing `nextCouponDate` with local time. Works for paused tokens too.
+     *
+     * ```ts
+     * const next = await client.tokenization.getNextCoupon({ tokenId, chainId: "84532" });
+     * if (next.status === "DUE") await client.tokenization.payCoupon({ tokenId, chainId: "84532", ... });
+     * ```
+     */
+    getNextCoupon(params: GetNextCouponParams, overrides?: RequestOverrides): Promise<NextCoupon>;
+    /**
+     * Redeems principal to holders at maturity, paying from the cNGN deposited in the token contract.
+     * Issuer-held tokens are burned without a payout so the supply can reach zero and the bond close.
+     * Holders that can't be redeemed (frozen, unverified, not allowlisted) are left alone and listed in
+     * `skipped`; check `closed` to see whether the bond is done.
+     *
+     * If a run fails part-way, call it again: holders already redeemed are skipped, so it carries on
+     * where it stopped. Reusing the same `idempotencyKey` only replays the earlier response.
+     */
     redeemPrincipal(params: RedeemPrincipalParams, overrides?: IdempotentRequestOverrides): Promise<RedeemPrincipalResult>;
     /**
      * Returns a snapshot's unclaimed yield to the issuer once its `reclaimAfter` window has
-     * passed. An `Idempotency-Key` is generated per call unless you pass your own.
+     * passed. An `Idempotency-Key` is generated per call unless you pass your own. As with
+     * {@link claimYield}, a `SUBMITTED` status means the outcome should be polled by `operationRef`.
      */
     reclaimUnclaimedYield(params: ReclaimUnclaimedYieldParams, overrides?: IdempotentRequestOverrides): Promise<ReclaimUnclaimedYieldResult>;
 }
@@ -1005,4 +1179,4 @@ declare function verifyIndexerWebhookSignature(options: VerifyIndexerWebhookOpti
 /** Generates a UUIDv4 suitable for use as an `Idempotency-Key` header value. */
 declare function generateIdempotencyKey(): string;
 
-export { type AssetClass, AuthenticationError, BadRequestError, type BurnTokenParams, type Chain, type ChainType, type ClaimYieldParams, ConflictError, type CreateSubscriptionParams, type CreateTokenParams, type DeactivateWalletParams, type DistributeYieldParams, type EventCatalogEntry, type EventFamily, type EventKind, type FlatPaginatedResponse, type ForcedTransferTokenParams, type GenerateWalletsParams, type GeneratedWallet, type GetTokenHoldersParams, type GetTransactionHistoryParams, type GetWalletBalanceParams, type GetWalletByAddressIndexParams, type GetWalletByAddressParams, type GetWalletCountParams, type HdEnabledStatus, type HttpMethod, type IdempotentRequestOverrides, IndexerResource, type IndexerSubscription, type IndexerSubscriptionWithSecret, InfraAPIError, InfraAuthTokenError, InfraClient, type InfraClientOptions, InfraConnectionError, InfraConnectionTimeoutError, InfraError, type InitiateTransferParams, InternalServerError, type ListEventCatalogParams, type ListSubscriptionsParams, type ListTokenTransactionsParams, type ListTokensParams, type ListWalletsParams, type LooseUnion, type MetaPaginatedResponse, type MintTokenParams, type Network, NotFoundError, type OffsetPaginatedResponse, Page, type PayCouponParams, PaymentRequiredError, PermissionDeniedError, type QueryValue, RateLimitError, type ReclaimUnclaimedYieldParams, type ReclaimUnclaimedYieldResult, type RedeemPrincipalParams, type RedeemPrincipalResult, type RegisterTokenWalletParams, type RegisterTokenWalletResult, type RequestOptions, type RequestOverrides, ServiceUnavailableError, type SignTransactionParams, type SignTransactionRequest, type SignedTransactionResult, type SubscriptionStatus, type SupportedChain, type TokenChainDeployment, type TokenChainId, type TokenDeploymentResult, type TokenDetail, type TokenHolder, type TokenOperationResult, type TokenStatus, type TokenSummary, type TokenTransactionRecord, type TokenTransactionStatus, type TokenTransactionType, type TokenTransferResult, type TokenType, type TokenWalletBalance, TokenizationResource, type TransactionStatus, type TransferTokenParams, UnknownAPIError, UnprocessableEntityError, type UpdateSubscriptionParams, type UpdateTokenYieldParams, type UpdateYieldResult, type VerifyIndexerWebhookOptions, type VerifyWalletWebhookOptions, type Wallet, type WalletBalance, type WalletCount, WalletResource, type WalletTransaction, WebhookSignatureVerificationError, type YieldDayCount, type YieldOperationResult, type YieldParams, type YieldPayoutToken, type YieldTxResult, generateIdempotencyKey, verifyIndexerWebhookSignature, verifyWalletWebhookSignature };
+export { type AssetClass, AuthenticationError, BadRequestError, type BurnTokenParams, type Chain, type ChainType, type ClaimYieldParams, ConflictError, type CreateSubscriptionParams, type CreateTokenParams, type DeactivateWalletParams, type DistributeYieldParams, type EventCatalogEntry, type EventFamily, type EventKind, type FlatPaginatedResponse, type ForcedTransferTokenParams, type GenerateWalletsParams, type GeneratedWallet, type GetNextCouponParams, type GetPayoutBalanceParams, type GetTokenHoldersParams, type GetTransactionHistoryParams, type GetWalletBalanceParams, type GetWalletByAddressIndexParams, type GetWalletByAddressParams, type GetWalletCountParams, type HdEnabledStatus, type HttpMethod, type IdempotentRequestOverrides, IndexerResource, type IndexerSubscription, type IndexerSubscriptionWithSecret, InfraAPIError, InfraAuthTokenError, InfraClient, type InfraClientOptions, InfraConnectionError, InfraConnectionTimeoutError, InfraError, type InitiateTransferParams, InternalServerError, type ListEventCatalogParams, type ListSubscriptionsParams, type ListTokenTransactionsParams, type ListTokensParams, type ListWalletsParams, type LooseUnion, type MetaPaginatedResponse, type MintTokenParams, type Network, type NextCoupon, type NextCouponStatus, NotFoundError, type OffsetPaginatedResponse, Page, type PayCouponParams, PaymentRequiredError, type PayoutBalance, PermissionDeniedError, type QueryValue, RateLimitError, type ReclaimUnclaimedYieldParams, type ReclaimUnclaimedYieldResult, type RedeemPrincipalParams, type RedeemPrincipalResult, type RedemptionSkipReason, type RedemptionSkippedHolder, type RegisterTokenWalletParams, type RegisterTokenWalletResult, type RequestOptions, type RequestOverrides, ServiceUnavailableError, type SignTransactionParams, type SignTransactionRequest, type SignedTransactionResult, type SubscriptionStatus, type SupportedChain, type TokenChainDeployment, type TokenChainId, type TokenDeploymentResult, type TokenDetail, type TokenHolder, type TokenOperationResult, type TokenStatus, type TokenSummary, type TokenTransactionRecord, type TokenTransactionStatus, type TokenTransactionType, type TokenTransferResult, type TokenType, type TokenWalletBalance, TokenizationResource, type TransactionStatus, type TransferTokenParams, UnknownAPIError, UnprocessableEntityError, type UpdateSubscriptionParams, type UpdateTokenYieldParams, type UpdateYieldResult, type VerifyIndexerWebhookOptions, type VerifyWalletWebhookOptions, type Wallet, type WalletBalance, type WalletCount, WalletResource, type WalletTransaction, WebhookSignatureVerificationError, type YieldDayCount, type YieldOperationResult, type YieldParams, type YieldPayoutToken, type YieldPushStatus, type YieldSettlementStatus, type YieldTxResult, generateIdempotencyKey, verifyIndexerWebhookSignature, verifyWalletWebhookSignature };

package/dist/index.d.ts

@@ -352,8 +352,27 @@ declare class WalletResource extends APIResource {
 
 type TokenType = "ASSET" | "YIELD_BEARING";
 type TokenStatus = LooseUnion<"PENDING" | "ACTIVE" | "PAUSED" | "RETIRED">;
-type TokenTransactionType = LooseUnion<"MINT" | "BURN" | "TRANSFER" | "DEPLOY" | "REDEEM" | "SNAPSHOT">;
+type TokenTransactionType = LooseUnion<"MINT" | "BURN" | "TRANSFER" | "DEPLOY" | "REDEEM" | "SNAPSHOT" | "FORCED_TRANSFER" | "CLAIM" | "RECLAIM">;
 type TokenTransactionStatus = LooseUnion<"PENDING" | "CONFIRMED" | "FAILED">;
+/**
+ * Where pushing a distribution's yield to investors stands, on a `SNAPSHOT` transaction created
+ * with `pushYield: true`.
+ *
+ * - `PENDING` — requested; the push runs once the snapshot confirms.
+ * - `SUBMITTED` — the push transaction was sent but hasn't settled yet.
+ * - `PUSHED` — the push transaction was mined and succeeded.
+ * - `FAILED` — the push failed; see `pushFailureReason`.
+ */
+type YieldPushStatus = LooseUnion<"PENDING" | "SUBMITTED" | "PUSHED" | "FAILED">;
+/**
+ * Outcome of a yield claim or reclaim when the call returns.
+ *
+ * - `COMPLETED` — the transaction was mined and succeeded.
+ * - `SUBMITTED` — the transaction was sent but hasn't settled yet. Poll
+ *   {@link TokenizationResource.getTokenTransaction} with the result's `operationRef`; its `status`
+ *   becomes `CONFIRMED` or `FAILED`.
+ */
+type YieldSettlementStatus = LooseUnion<"COMPLETED" | "SUBMITTED">;
 /**
  * Chain id a token is deployed on, e.g. `84532` (Base Sepolia). The API accepts it as a number
  * or a numeric string; responses always return it as a string.
@@ -522,6 +541,11 @@ interface TokenOperationResult {
 /** Result of {@link TokenizationResource.transferToken}. */
 interface TokenTransferResult {
     tokenId: string;
+    /**
+     * `CONFIRMED` once mined. `FAILED` when the transfer was rejected or reverted on-chain; the call
+     * still resolves in that case, so check this rather than relying on an error. `txHash` is set
+     * when the failed transfer was mined.
+     */
     status: TokenTransactionStatus;
     transactionId: string;
     fromAddressIndex: number;
@@ -567,6 +591,24 @@ interface TokenWalletBalance {
     balance: string;
     decimals: number;
 }
+interface GetPayoutBalanceParams {
+    chainId: TokenChainId;
+    walletAddress: string;
+}
+/**
+ * A wallet's balance of the chain's payout token, returned by
+ * {@link TokenizationResource.getPayoutBalance}. Coupons, yield and principal are all paid in it.
+ */
+interface PayoutBalance {
+    chainId: string;
+    walletAddress: string;
+    payoutToken: YieldPayoutToken;
+    /** The payout token's contract address on this chain. */
+    tokenAddress: string;
+    /** Balance in payout-token units, as a decimal string, e.g. `"1234.56"`. */
+    balance: string;
+    decimals: number;
+}
 interface ListTokenTransactionsParams {
     tokenId?: string;
     chainId?: TokenChainId;
@@ -579,7 +621,10 @@ interface ListTokenTransactionsParams {
     txHash?: string;
     operationRef?: string;
 }
-/** A recorded on-chain operation against a token (mint, burn, or transfer). */
+/**
+ * A recorded on-chain operation against a token: a mint, burn or transfer, a deployment, a yield
+ * distribution (`SNAPSHOT`), or a yield claim (`CLAIM`) or reclaim (`RECLAIM`).
+ */
 interface TokenTransactionRecord {
     id: string;
     tokenId: string;
@@ -600,8 +645,18 @@ interface TokenTransactionRecord {
     memo?: string;
     createdAt?: string;
     confirmedAt?: string;
-    /** Distribution snapshot id, set on `SNAPSHOT` transactions. */
+    /** Distribution snapshot id, set on `SNAPSHOT`, `CLAIM` and `RECLAIM` transactions. */
     snapshotId?: number;
+    /** Why the transaction failed, when `status` is `FAILED`. */
+    failureReason?: string;
+    /** Whether the distribution pushes yield to investors. Set on `SNAPSHOT` transactions. */
+    pushYield?: boolean;
+    /** Progress of the push, on `SNAPSHOT` transactions with `pushYield`. Absent when no push was requested or made. */
+    pushStatus?: YieldPushStatus;
+    /** Hash of the push transaction, once sent. */
+    pushTxHash?: string;
+    /** Why the push failed, when `pushStatus` is `FAILED`. */
+    pushFailureReason?: string;
 }
 interface UpdateTokenYieldParams {
     /** Yield-bearing token id. */
@@ -616,6 +671,7 @@ interface UpdateYieldResult {
     currentRate: number;
     /** Annual rate after the update, as a percentage. */
     newRate: number;
+    operationRef: string;
     txHash: string;
 }
 interface DistributeYieldParams {
@@ -654,12 +710,89 @@ interface RedeemPrincipalParams {
     tokenId: string;
     chainId: TokenChainId;
 }
-/** Result of {@link TokenizationResource.redeemPrincipal} — one transaction per redemption payout. */
+/**
+ * Why a holder was left out of a redemption. Their principal is still owed once the cause is resolved.
+ *
+ * - `NOT_VERIFIED` — not KYC-verified in the token's identity registry.
+ * - `FROZEN` — the wallet is frozen.
+ * - `NOT_ALLOWLISTED` — removed from the compliance allowlist.
+ * - `SKIPPED_BY_CONTRACT` — eligible when read, but the contract skipped it when the batch executed
+ *   (e.g. it became ineligible in between).
+ */
+type RedemptionSkipReason = LooseUnion<"NOT_VERIFIED" | "FROZEN" | "NOT_ALLOWLISTED" | "SKIPPED_BY_CONTRACT">;
+/** A holder {@link TokenizationResource.redeemPrincipal} did not redeem. */
+interface RedemptionSkippedHolder {
+    address: string;
+    /** Unredeemed balance in the token's smallest unit, as an integer string. */
+    balance: string;
+    reasons: RedemptionSkipReason[];
+}
+/** Result of {@link TokenizationResource.redeemPrincipal}. */
 interface RedeemPrincipalResult {
     tokenId: string;
     operationRef: string;
+    /** Transaction records created by this run: the issuer-token burn (if any), then one per redemption batch. */
     transactionIds: string[];
+    /** Hashes in send order: the burn, each batch, then the seal that marks the principal repaid (if one was needed). */
     txHashes: string[];
+    /** Holders actually paid, from the contract's `PrincipalRedeemed` events. */
+    redeemedHolders: number;
+    /** Principal actually paid, in cNGN base units (6 decimals), as an integer string. */
+    paidPrincipal: string;
+    /** {@link paidPrincipal} as a decimal cNGN string, e.g. `"100000.0"`. */
+    paidPrincipalFormatted: string;
+    /**
+     * Indexes of batches whose receipt couldn't be read. Their transactions landed, but their paid amounts
+     * are the pre-transaction estimate rather than the on-chain events.
+     */
+    unreconciledBatches: number[];
+    /** Holders that were not redeemed, with their balances and why. */
+    skipped: RedemptionSkippedHolder[];
+    /** Issuer-held (treasury) tokens burned without a payout, or `null` when there were none. Frozen tokens are never burned. */
+    treasuryBurned: {
+        amount: string;
+        txHash: string;
+    } | null;
+    /** Supply left after the run, in the token's smallest unit, as an integer string. */
+    outstandingSupply: string;
+    /**
+     * `true` once supply is zero and the bond is marked principal-repaid. While `false`, the remaining
+     * supply belongs to {@link skipped} holders, frozen issuer tokens or the yield distributor.
+     */
+    closed: boolean;
+}
+interface GetNextCouponParams {
+    tokenId: string;
+    chainId: TokenChainId;
+}
+/**
+ * Where a bond stands on its coupon schedule.
+ *
+ * - `SCHEDULED` — the next coupon isn't due yet.
+ * - `DUE` — the coupon can be paid now with {@link TokenizationResource.payCoupon}.
+ * - `GRACE_EXPIRED` — the coupon was missed and its grace period has passed; it is still payable,
+ *   but anyone can now flag the bond as defaulted.
+ * - `DEFAULTED` — the bond is in default; no further coupons can be scheduled.
+ * - `NO_MORE_COUPONS` — the schedule has run past maturity; only principal redemption remains.
+ * - `CLOSED` — principal has been repaid and the bond is closed.
+ */
+type NextCouponStatus = LooseUnion<"SCHEDULED" | "DUE" | "GRACE_EXPIRED" | "DEFAULTED" | "NO_MORE_COUPONS" | "CLOSED">;
+/** Result of {@link TokenizationResource.getNextCoupon}. Dates are ISO 8601 strings in UTC. */
+interface NextCoupon {
+    tokenId: string;
+    chainId: string;
+    status: NextCouponStatus;
+    /** When the next coupon falls due. `null` once there are no more coupons (`NO_MORE_COUPONS` or `CLOSED`). */
+    nextCouponDate: string | null;
+    /** `nextCouponDate` plus the bond's grace period; after this a missed coupon allows a default. `null` with it. */
+    graceEndsAt: string | null;
+    /** `true` when a coupon can be paid now (`DUE` or `GRACE_EXPIRED`). */
+    isDue: boolean;
+    /** Seconds between coupons. */
+    couponPeriodSeconds: number;
+    maturityDate: string;
+    /** Coupon paid per whole token, in cNGN, as a decimal string. */
+    couponPerToken: string;
 }
 interface ReclaimUnclaimedYieldParams {
     tokenId: string;
@@ -670,16 +803,22 @@ interface ReclaimUnclaimedYieldParams {
 /** Result of {@link TokenizationResource.reclaimUnclaimedYield}. */
 interface ReclaimUnclaimedYieldResult {
     tokenId: string;
-    /** Snapshot id, as a numeric string. */
-    snapshotId: string;
-    /** Amount reclaimed, as a decimal string. */
+    snapshotId: number;
+    /** Amount reclaimed, in cNGN base units (6 decimals), as an integer string. */
     reclaimed: string;
     operationRef: string;
+    /** Id of the `RECLAIM` transaction record. */
+    transactionId: string;
     txHash: string;
+    status: YieldSettlementStatus;
 }
 /** Result of {@link TokenizationResource.claimYield}. */
 interface YieldTxResult {
+    operationRef: string;
+    /** Id of the `CLAIM` transaction record. */
+    transactionId: string;
     txHash: string;
+    status: YieldSettlementStatus;
 }
 /** Result of {@link TokenizationResource.distributeYield} / {@link TokenizationResource.payCoupon}. */
 interface YieldOperationResult {
@@ -718,7 +857,10 @@ declare class TokenizationResource extends APIResource {
     mintToken(params: MintTokenParams, overrides?: IdempotentRequestOverrides): Promise<TokenOperationResult>;
     /** Burns units of a token from a holder address. */
     burnToken(params: BurnTokenParams, overrides?: IdempotentRequestOverrides): Promise<TokenOperationResult>;
-    /** Transfers token units between holder addresses. */
+    /**
+     * Transfers token units between holder addresses. A transfer that is rejected or reverts
+     * on-chain still resolves, with `status: "FAILED"`, so check `status` rather than relying on an error.
+     */
     transferToken(params: TransferTokenParams, overrides?: IdempotentRequestOverrides): Promise<TokenTransferResult>;
     /**
      * Force-transfers token units out of a holder's address without the holder's signature
@@ -730,25 +872,57 @@ declare class TokenizationResource extends APIResource {
     registerWallet(params: RegisterTokenWalletParams, overrides?: IdempotentRequestOverrides): Promise<RegisterTokenWalletResult>;
     /** Returns the paginated list of holder wallet addresses and balances for a token on a chain. */
     getTokenHolders(params: GetTokenHoldersParams, overrides?: RequestOverrides): Promise<Page<TokenHolder>>;
-    /** Returns a single wallet's balance of a token on a chain. */
+    /** Returns a single wallet's balance of a token on a chain. For its cNGN balance, use {@link getPayoutBalance}. */
     getWalletBalance(params: GetWalletBalanceParams, overrides?: RequestOverrides): Promise<TokenWalletBalance>;
+    /**
+     * Returns a wallet's balance of the chain's payout token (cNGN), in which coupons, yield and
+     * principal are paid. It depends only on the chain and wallet, so no token is needed.
+     */
+    getPayoutBalance(params: GetPayoutBalanceParams, overrides?: RequestOverrides): Promise<PayoutBalance>;
     /** Fetches a single token transaction by its reference. */
     getTokenTransaction(ref: string, overrides?: RequestOverrides): Promise<TokenTransactionRecord>;
     /** Returns token transactions, optionally filtered by token. */
     listTokenTransactions(params?: ListTokenTransactionsParams, overrides?: RequestOverrides): Promise<Page<TokenTransactionRecord>>;
-    /** Updates the annual yield rate for a yield-bearing token. */
-    updateYield(params: UpdateTokenYieldParams, overrides?: RequestOverrides): Promise<UpdateYieldResult>;
+    /**
+     * Updates the annual yield rate for a yield-bearing token. An `Idempotency-Key` is generated
+     * per call unless you pass your own.
+     */
+    updateYield(params: UpdateTokenYieldParams, overrides?: IdempotentRequestOverrides): Promise<UpdateYieldResult>;
     /** Funds and distributes a yield payout to holders. Unclaimed funds may be reclaimed after `reclaimAfter`. */
     distributeYield(params: DistributeYieldParams, overrides?: IdempotentRequestOverrides): Promise<YieldOperationResult>;
     /** Pays the scheduled coupon for a yield-bearing token. Set `pushYield` to push funds rather than let investors claim. */
     payCoupon(params: PayCouponParams, overrides?: IdempotentRequestOverrides): Promise<YieldOperationResult>;
-    /** Claims an investor's yield for a given distribution snapshot. */
+    /**
+     * Claims an investor's yield for a given distribution snapshot. `status` is `COMPLETED` once the
+     * claim is mined. If it's `SUBMITTED`, the outcome isn't known yet: poll
+     * {@link getTokenTransaction} with the result's `operationRef` until its `status` is `CONFIRMED` or `FAILED`.
+     */
     claimYield(params: ClaimYieldParams, overrides?: IdempotentRequestOverrides): Promise<YieldTxResult>;
-    /** Redeems principal to holders at maturity. */
+    /**
+     * Returns the bond's next coupon date and where it stands on its schedule. Whether a coupon is
+     * due is decided by the chain's clock, not yours, so check `status` (or `isDue`) rather than
+     * comparing `nextCouponDate` with local time. Works for paused tokens too.
+     *
+     * ```ts
+     * const next = await client.tokenization.getNextCoupon({ tokenId, chainId: "84532" });
+     * if (next.status === "DUE") await client.tokenization.payCoupon({ tokenId, chainId: "84532", ... });
+     * ```
+     */
+    getNextCoupon(params: GetNextCouponParams, overrides?: RequestOverrides): Promise<NextCoupon>;
+    /**
+     * Redeems principal to holders at maturity, paying from the cNGN deposited in the token contract.
+     * Issuer-held tokens are burned without a payout so the supply can reach zero and the bond close.
+     * Holders that can't be redeemed (frozen, unverified, not allowlisted) are left alone and listed in
+     * `skipped`; check `closed` to see whether the bond is done.
+     *
+     * If a run fails part-way, call it again: holders already redeemed are skipped, so it carries on
+     * where it stopped. Reusing the same `idempotencyKey` only replays the earlier response.
+     */
     redeemPrincipal(params: RedeemPrincipalParams, overrides?: IdempotentRequestOverrides): Promise<RedeemPrincipalResult>;
     /**
      * Returns a snapshot's unclaimed yield to the issuer once its `reclaimAfter` window has
-     * passed. An `Idempotency-Key` is generated per call unless you pass your own.
+     * passed. An `Idempotency-Key` is generated per call unless you pass your own. As with
+     * {@link claimYield}, a `SUBMITTED` status means the outcome should be polled by `operationRef`.
      */
     reclaimUnclaimedYield(params: ReclaimUnclaimedYieldParams, overrides?: IdempotentRequestOverrides): Promise<ReclaimUnclaimedYieldResult>;
 }
@@ -1005,4 +1179,4 @@ declare function verifyIndexerWebhookSignature(options: VerifyIndexerWebhookOpti
 /** Generates a UUIDv4 suitable for use as an `Idempotency-Key` header value. */
 declare function generateIdempotencyKey(): string;
 
-export { type AssetClass, AuthenticationError, BadRequestError, type BurnTokenParams, type Chain, type ChainType, type ClaimYieldParams, ConflictError, type CreateSubscriptionParams, type CreateTokenParams, type DeactivateWalletParams, type DistributeYieldParams, type EventCatalogEntry, type EventFamily, type EventKind, type FlatPaginatedResponse, type ForcedTransferTokenParams, type GenerateWalletsParams, type GeneratedWallet, type GetTokenHoldersParams, type GetTransactionHistoryParams, type GetWalletBalanceParams, type GetWalletByAddressIndexParams, type GetWalletByAddressParams, type GetWalletCountParams, type HdEnabledStatus, type HttpMethod, type IdempotentRequestOverrides, IndexerResource, type IndexerSubscription, type IndexerSubscriptionWithSecret, InfraAPIError, InfraAuthTokenError, InfraClient, type InfraClientOptions, InfraConnectionError, InfraConnectionTimeoutError, InfraError, type InitiateTransferParams, InternalServerError, type ListEventCatalogParams, type ListSubscriptionsParams, type ListTokenTransactionsParams, type ListTokensParams, type ListWalletsParams, type LooseUnion, type MetaPaginatedResponse, type MintTokenParams, type Network, NotFoundError, type OffsetPaginatedResponse, Page, type PayCouponParams, PaymentRequiredError, PermissionDeniedError, type QueryValue, RateLimitError, type ReclaimUnclaimedYieldParams, type ReclaimUnclaimedYieldResult, type RedeemPrincipalParams, type RedeemPrincipalResult, type RegisterTokenWalletParams, type RegisterTokenWalletResult, type RequestOptions, type RequestOverrides, ServiceUnavailableError, type SignTransactionParams, type SignTransactionRequest, type SignedTransactionResult, type SubscriptionStatus, type SupportedChain, type TokenChainDeployment, type TokenChainId, type TokenDeploymentResult, type TokenDetail, type TokenHolder, type TokenOperationResult, type TokenStatus, type TokenSummary, type TokenTransactionRecord, type TokenTransactionStatus, type TokenTransactionType, type TokenTransferResult, type TokenType, type TokenWalletBalance, TokenizationResource, type TransactionStatus, type TransferTokenParams, UnknownAPIError, UnprocessableEntityError, type UpdateSubscriptionParams, type UpdateTokenYieldParams, type UpdateYieldResult, type VerifyIndexerWebhookOptions, type VerifyWalletWebhookOptions, type Wallet, type WalletBalance, type WalletCount, WalletResource, type WalletTransaction, WebhookSignatureVerificationError, type YieldDayCount, type YieldOperationResult, type YieldParams, type YieldPayoutToken, type YieldTxResult, generateIdempotencyKey, verifyIndexerWebhookSignature, verifyWalletWebhookSignature };
+export { type AssetClass, AuthenticationError, BadRequestError, type BurnTokenParams, type Chain, type ChainType, type ClaimYieldParams, ConflictError, type CreateSubscriptionParams, type CreateTokenParams, type DeactivateWalletParams, type DistributeYieldParams, type EventCatalogEntry, type EventFamily, type EventKind, type FlatPaginatedResponse, type ForcedTransferTokenParams, type GenerateWalletsParams, type GeneratedWallet, type GetNextCouponParams, type GetPayoutBalanceParams, type GetTokenHoldersParams, type GetTransactionHistoryParams, type GetWalletBalanceParams, type GetWalletByAddressIndexParams, type GetWalletByAddressParams, type GetWalletCountParams, type HdEnabledStatus, type HttpMethod, type IdempotentRequestOverrides, IndexerResource, type IndexerSubscription, type IndexerSubscriptionWithSecret, InfraAPIError, InfraAuthTokenError, InfraClient, type InfraClientOptions, InfraConnectionError, InfraConnectionTimeoutError, InfraError, type InitiateTransferParams, InternalServerError, type ListEventCatalogParams, type ListSubscriptionsParams, type ListTokenTransactionsParams, type ListTokensParams, type ListWalletsParams, type LooseUnion, type MetaPaginatedResponse, type MintTokenParams, type Network, type NextCoupon, type NextCouponStatus, NotFoundError, type OffsetPaginatedResponse, Page, type PayCouponParams, PaymentRequiredError, type PayoutBalance, PermissionDeniedError, type QueryValue, RateLimitError, type ReclaimUnclaimedYieldParams, type ReclaimUnclaimedYieldResult, type RedeemPrincipalParams, type RedeemPrincipalResult, type RedemptionSkipReason, type RedemptionSkippedHolder, type RegisterTokenWalletParams, type RegisterTokenWalletResult, type RequestOptions, type RequestOverrides, ServiceUnavailableError, type SignTransactionParams, type SignTransactionRequest, type SignedTransactionResult, type SubscriptionStatus, type SupportedChain, type TokenChainDeployment, type TokenChainId, type TokenDeploymentResult, type TokenDetail, type TokenHolder, type TokenOperationResult, type TokenStatus, type TokenSummary, type TokenTransactionRecord, type TokenTransactionStatus, type TokenTransactionType, type TokenTransferResult, type TokenType, type TokenWalletBalance, TokenizationResource, type TransactionStatus, type TransferTokenParams, UnknownAPIError, UnprocessableEntityError, type UpdateSubscriptionParams, type UpdateTokenYieldParams, type UpdateYieldResult, type VerifyIndexerWebhookOptions, type VerifyWalletWebhookOptions, type Wallet, type WalletBalance, type WalletCount, WalletResource, type WalletTransaction, WebhookSignatureVerificationError, type YieldDayCount, type YieldOperationResult, type YieldParams, type YieldPayoutToken, type YieldPushStatus, type YieldSettlementStatus, type YieldTxResult, generateIdempotencyKey, verifyIndexerWebhookSignature, verifyWalletWebhookSignature };