docs: document enhanced redeem behavior and issuer authorization (#1649)

Signed-off-by: Flamki <9833ayush@gmail.com>

Author: Flamki

docs/services/ttx.md

@@ -178,11 +178,17 @@ Enables the transfer of token ownership. The service:
 ### Redeem
 A specialized transfer where the recipient is "hidden" or "empty," effectively removing the tokens from circulation on the ledger.
 
+Redeem supports an enhanced flow where an issuer signature is required as part of transfer validation:
+1. Add the redeem action with `tx.Redeem(...)`.
+2. If the issuer endpoint cannot be resolved automatically, pass `ttx.WithFSCIssuerIdentity(...)` so the initiator can contact the issuer for endorsement.
+3. Optionally pass `ttx.WithIssuerPublicParamsPublicKey(...)` to pin which issuer public-parameters signing key must authorize the redeem.
+4. Run `CollectEndorsementsView` to collect owner, auditor (if configured), and issuer signatures.
+
 ## Collecting Endorsements
 
 The `CollectEndorsementsView` is responsible for gathering all signatures required to make a transaction valid:
 *   **Owner Signatures**: For every token spent, the service requests a signature from the node that owns the corresponding identity.
-*   **Issuer Signatures**: For transactions involving token issuance.
+*   **Issuer Signatures**: For transactions involving token issuance and enhanced redeem flows that require issuer authorization.
 *   **Auditor Signatures**: If the TMS is configured with an auditor, the transaction must be approved via the `AuditApproveView`.
 *   **Network Endorsements**: The service delegates to the **Network Service** to obtain backend-specific endorsements (e.g., Fabric chaincode endorsements).
 

docs/token_sdk_usage.md

@@ -143,13 +143,15 @@ if err != nil {
 }
 
 // 2. Add Redeem Action
-// If the issuer is not automatically resolvable, provide their identity.
+// If the issuer is not automatically resolvable, provide their FSC identity.
+// If needed, also pin the issuer signing key expected by public parameters.
 senderWallet := ttx.GetWallet(context, senderWalletID)
 err = tx.Redeem(
     senderWallet,
     tokenType,
     amount,
-    ttx.WithFSCIssuerIdentity(issuerIdentity), // Contact issuer for approval
+    ttx.WithFSCIssuerIdentity(issuerIdentity),                     // Contact issuer for approval
+    ttx.WithIssuerPublicParamsPublicKey(issuerPublicParamsPubKey), // Optional key pinning
 )
 if err != nil {
     return nil, err
@@ -168,6 +170,9 @@ if err != nil {
 }
 ```
 
+Use `ttx.WithFSCIssuerIdentity(...)` when your app cannot resolve the issuer endpoint automatically.
+Use `ttx.WithIssuerPublicParamsPublicKey(...)` when you want redeem authorization to be verified against a specific issuer key from public parameters.
+
 ---
 
 ## 5. Atomic Swap ([`swap.go`](../integration/token/fungible/views/swap.go))

docs/tokenapi.md

@@ -59,7 +59,7 @@ A [Request](../token/request.go) is a ledger-agnostic blueprint for a token tran
 
 ### Core Actions
 *   **Issue**: Minting new tokens into the system.
-*   **Transfer**: Reassigning ownership of existing tokens (includes **Redeem** by transferring to a null owner).
+*   **Transfer**: Reassigning ownership of existing tokens (includes **Redeem** by transferring to a null owner; enhanced redeem flows can additionally require issuer authorization/signature).
 
 ### The Request Lifecycle
 1.  **Assemble**: Add actions to the `Request` using a TMS.