Merge branch 'main' into Soumya8898/extend-issuer-wallet

Author: Soumya8898

Makefile

@@ -231,3 +231,11 @@ install-linter-tool:
 fmt: ## Run gofmt on the entire project
 	@echo "Running gofmt..."
 	@gofmt -l -s -w .
+
+.PHONY: update-all-deps-latest
+update-all-deps-latest: ## Update all dependencies in all Go modules to their latest version
+	@echo "Updating all dependencies to @latest..."
+	@for dir in $$(find . -name "go.mod" -exec dirname {} \;); do \
+		echo "=> Updating dependencies in $$dir"; \
+		(cd $$dir && go get ./...@latest && go mod tidy); \
+	done

cmd/tokengen/testdata/zkatdlognoghv1_pp.json

@@ -232,6 +232,24 @@ Located in `token/services/identity/multisig`.
 *   **Usage**: Useful for requiring multiple signatures or representing a group of parties.
 *   **Auditability**: Aggregates audit information for all underlying identities.
 
+#### PolicyIdentity (Boolean-Expression-Governed Ownership)
+Located in `token/services/identity/boolpolicy`.
+*   **Concept**: An identity whose ownership is governed by a boolean expression over a set of component identities, enabling OR-style (any one signer suffices) and AND-style (all signers required) multi-party control without a fixed M-of-N scheme.
+*   **Policy Expression Syntax**: A string using `$N` slot references and the operators `AND`, `OR`, and parentheses:
+    - `$0 OR $1` — either component identity 0 or 1 can satisfy ownership alone.
+    - `$0 AND $1` — both component identity 0 and 1 must sign.
+    - `($0 OR $1) AND $2` — one of the first two parties plus the third must sign.
+*   **Identity (Payload)**: An ASN.1-encoded `PolicyIdentity` sequence:
+    - `policy` (UTF8String): the boolean expression, e.g. `"$0 OR $1"`.
+    - `identities` (SEQUENCE OF OCTET STRING): ordered list of raw component identity bytes; `$N` indexes into this list.
+*   **Audit Info**: JSON-encoded `AuditInfo` structure.
+    - `IdentityAuditInfos` (array of `IdentityAuditInfo`): per-component audit info blobs in the same order as `identities`.
+*   **Encoding**:
+    - `TypedIdentity` payload: ASN.1 DER.
+    - Audit Info: JSON.
+*   **Signature Representation**: An ASN.1 `PolicySignature` (`SEQUENCE OF OCTET STRING`) where each slot corresponds to one component identity. A slot may be nil/empty when that component does not need to sign (valid for OR branches).
+*   **Implementation**: `token/services/identity/boolpolicy`.
+
 #### HTLC (Hashed Time Lock Contract)
 Located in `token/services/identity/interop/htlc`.
 *   **Concept**: A script-based identity used primarily for interoperability mechanisms like atomic swaps.
@@ -258,3 +276,111 @@ Typical extension scenarios include:
 - Supporting a new identity type by implementing a custom `KeyManager`
 - Customizing signature generation or verification logic within a `KeyManager`
 - Providing a custom `KeyManagerProvider` to plug new identity mechanisms into `LocalMembership`
+
+### Step-by-Step Guide: Introducing a New Identity Type
+
+The steps below describe how to add a new composite identity type end-to-end, based on the pattern used for **PolicyIdentity** (`token/services/identity/boolpolicy`).
+
+#### Step 1 — Reserve a type tag
+
+Add a new constant to `token/driver/wallet.go` alongside the existing tags:
+
+```go
+const (
+    // ...existing tags...
+    MyNewIdentityType       IdentityType = 7
+    MyNewIdentityTypeString              = "mynew"
+)
+```
+
+The integer must be unique across all registered identity types.
+
+#### Step 2 — Define the wire format
+
+Create a package (e.g. `token/services/identity/mynew/`) and define the identity struct. Use ASN.1 DER for structured binary data (as PolicyIdentity does) or JSON for human-readable payloads (as HTLC does):
+
+```go
+type MyNewIdentity struct {
+    SomeField string `asn1:"utf8"`
+    Parts     [][]byte
+}
+
+func (m *MyNewIdentity) Serialize() ([]byte, error) { return asn1.Marshal(*m) }
+func (m *MyNewIdentity) Deserialize(raw []byte) error {
+    _, err := asn1.Unmarshal(raw, m)
+    return err
+}
+```
+
+Expose `Wrap` / `Unwrap` helpers (see `boolpolicy.WrapPolicyIdentity` / `boolpolicy.Unwrap`) that embed the serialized struct inside a `TypedIdentity` envelope with the new type tag.
+
+#### Step 3 — Implement signature verification
+
+Add a `Verifier` that accepts the new signature format and a `Deserializer` that reconstructs a `Verifier` from raw identity bytes.  Register the deserializer via `des.AddTypedVerifierDeserializer(mynew.MyNewIdentityType, ...)` in each driver's `NewTokenService` (see `token/core/fabtoken/v1/driver/driver.go` and the zkatdlog equivalent).
+
+#### Step 4 — Define the signature format
+
+Define a struct for the signature produced over the token request (analogous to `PolicySignature` in `boolpolicy/sig.go`). Include ASN.1 or JSON encoding helpers and a `JoinSignatures` function if multiple parties contribute partial signatures.
+
+#### Step 5 — Implement the `Authorization` checker
+
+Create an `EscrowAuth` struct (see `token/services/ttx/boolpolicy/auth.go`) that implements the `Authorization` interface:
+
+```go
+type EscrowAuth struct{ WalletService driver.WalletService }
+func (a *EscrowAuth) AmIAnAuditor() bool                                  { return false }
+func (a *EscrowAuth) IsMine(ctx context.Context, tok *token.Token) (string, []string, bool) { ... }
+func (a *EscrowAuth) Issued(_ context.Context, _ driver.Identity, _ *token.Token) bool { return false }
+func (a *EscrowAuth) OwnerType(raw []byte) (driver.IdentityType, []byte, error)        { ... }
+```
+
+Register it in **both** driver files inside `NewAuthorizationMultiplexer`:
+
+```go
+// token/core/fabtoken/v1/driver/driver.go  (and the zkatdlog equivalent)
+authorization := common.NewAuthorizationMultiplexer(
+    common.NewTMSAuthorization(...),
+    htlc.NewScriptAuth(ws),
+    multisig.NewEscrowAuth(ws),
+    boolpolicy.NewEscrowAuth(ws),
+    mynew.NewEscrowAuth(ws),   // ← add here
+)
+```
+
+#### Step 6 — Add a wallet wrapper
+
+Create an `OwnerWallet` wrapper (see `token/services/ttx/boolpolicy/wallet.go`) that filters the unspent token list to tokens whose owner is the new identity type, and exposes domain-specific helpers (e.g. `VerifyApprover`).
+
+#### Step 7 — Wire the recipient-negotiation protocol
+
+If the new identity requires interactive negotiation between parties to assemble the composite identity before a transfer, add a `RequestMyNewIdentity` function following the pattern of `ttx.RequestPolicyIdentity` (`token/services/ttx/recipients.go`).  The function sends a typed request, each counterparty responds with its component data, and the initiator assembles the final composite identity.
+
+#### Step 8 — Add integration views
+
+Create initiator and responder views in the integration layer (e.g. `integration/token/fungible/views/mynew.go`) following the pattern in `boolpolicy.go`:
+
+- **Lock view** — transfers tokens to a recipient with the new composite identity.
+- **Spend view** — spends those tokens, optionally with restricted signer sets.
+- **Balance view** — queries the policy-owned token balance (modelled on `PolicyOwnedBalanceView`).
+- **Responder views** — ACK and endorse spend requests for AND-style policies.
+
+Register all view factories and responders in the integration SDK (`integration/token/fungible/sdk/party/sdk.go`).
+
+#### Step 9 — Add tests
+
+- **Unit tests** for the verifier (`sig_test.go` pattern) and for `EscrowAuth.IsMine` (`auth_test.go` pattern).
+- **Integration tests** in `integration/token/fungible/tests.go` + the relevant `dlog_test.go` `Describe` block, following `TestPolicyOR` / `TestPolicyAND`.
+
+#### Summary checklist
+
+| # | What | Where |
+|:--|:-----|:------|
+| 1 | Reserve type tag | `token/driver/wallet.go` |
+| 2 | Wire format + Wrap/Unwrap | `token/services/identity/mynew/` |
+| 3 | Verifier + Deserializer | same package; register in both drivers |
+| 4 | Signature format + JoinSignatures | same package |
+| 5 | EscrowAuth + register in drivers | `token/services/ttx/mynew/auth.go` |
+| 6 | OwnerWallet wrapper | `token/services/ttx/mynew/wallet.go` |
+| 7 | Recipient-negotiation protocol | `token/services/ttx/recipients.go` |
+| 8 | Integration views + SDK registration | `integration/token/fungible/views/mynew.go` |
+| 9 | Unit + integration tests | alongside each new file |

docs/services/identity.md

@@ -159,6 +159,61 @@ sequenceDiagram
     Note over I,R: Full RecipientData on wire today (responder sends local wallet RecipientData)
 ```
 
+### PolicyIdentity — Boolean-Expression-Governed Ownership
+
+The TTX service supports **PolicyIdentity** owners: tokens whose spending requires satisfying a boolean expression over a set of component identities.  This enables richer access-control than simple multisig (M-of-N) — for example, an OR clause where any single co-owner may spend unilaterally, or complex nested expressions.
+
+#### Creating a PolicyIdentity
+
+Call `RequestPolicyIdentity` (in `token/services/ttx/recipients.go`) to negotiate a composite identity from all co-owners before building the transfer:
+
+```go
+recipient, err := bptx.RequestRecipientIdentity(ctx, "$0 OR $1",
+    []view.Identity{bobFSCIdentity, charlieFSCIdentity},
+    token.WithTMSIDPointer(tmsID),
+)
+```
+
+Each co-owner's node responds with its component identity; the SDK assembles the `PolicyIdentity` envelope automatically.
+
+#### Policy Expression Syntax
+
+| Expression | Meaning |
+|:-----------|:--------|
+| `$0 OR $1` | Either component 0 **or** component 1 can spend alone. |
+| `$0 AND $1` | Both component 0 **and** component 1 must sign. |
+| `($0 OR $1) AND $2` | One of the first two parties plus party 2 must sign. |
+
+`$N` is a zero-based index into the ordered component identity list supplied when creating the token.
+
+#### Spending — OR Policy
+
+For an OR policy the initiator alone can satisfy the policy.  Pass `WithPolicySigners` to restrict signature collection to only the signing party's slot; the remaining slots are left nil (which is valid for OR branches):
+
+```go
+_, err = context.RunView(ttx.NewCollectEndorsementsView(tx,
+    ttx.WithPolicySigners(myComponentIdentity),
+))
+```
+
+#### Spending — AND Policy
+
+For an AND policy all co-owners must endorse.  Use `RequestSpendView` (in `token/services/ttx/boolpolicy/spend.go`) to notify co-owners before assembling the transaction, then collect endorsements from all components without restriction:
+
+```go
+_, err = context.RunView(bptx.NewRequestSpendView(unspentToken, serviceOpts...))
+// ... build tx ...
+_, err = context.RunView(ttx.NewCollectEndorsementsView(tx))
+```
+
+Co-owners run `EndorseSpendView` (via `EndorseSpend`) on their side, which ACKs the spend request and then endorses the assembled transaction.
+
+#### Wallet and Authorization
+
+The `boolpolicy.OwnerWallet` (in `token/services/ttx/boolpolicy/wallet.go`) wraps a standard owner wallet and filters the token list to policy-type tokens.  `VerifyApprover` can be used to assert that a given identity is one of the named component identities before allowing a spend.
+
+The `EscrowAuth` struct (in `token/services/ttx/boolpolicy/auth.go`) implements the `Authorization` interface: `IsMine` returns true if any component identity of the policy token belongs to one of the node's owner wallets.
+
 ## Token Operations
 
 The TTX service supports three primary operations through the `TokenRequest` API:
@@ -178,11 +233,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/services/ttx.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/token_sdk_usage.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.

docs/tokenapi.md

@@ -10,7 +10,7 @@ require (
 	github.com/consensys/gnark-crypto v0.20.1
 	github.com/dgraph-io/ristretto/v2 v2.4.0
 	github.com/gin-gonic/gin v1.12.0
-	github.com/go-co-op/gocron/v2 v2.19.1
+	github.com/go-co-op/gocron/v2 v2.21.1
 	github.com/google/pprof v0.0.0-20260402051712-545e8a4df936
 	github.com/hashicorp/go-uuid v1.0.3
 	github.com/hyperledger-labs/fabric-smart-client v0.10.2-0.20260428094934-a70a13e26c74
@@ -30,17 +30,16 @@ require (
 	github.com/spf13/viper v1.21.0
 	github.com/stretchr/testify v1.11.1
 	github.com/tedsuo/ifrit v0.0.0-20230516164442-7862c310ad26
-	github.com/test-go/testify v1.1.4
 	github.com/thedevsaddam/gojsonq v2.3.0+incompatible
 	go.opentelemetry.io/otel/trace v1.43.0
 	go.uber.org/dig v1.19.0
 	go.uber.org/zap v1.27.1
-	golang.org/x/crypto v0.49.0
-	golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90
+	golang.org/x/crypto v0.50.0
+	golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f
 	golang.org/x/sync v0.20.0
 	google.golang.org/protobuf v1.36.11
 	gopkg.in/yaml.v2 v2.4.0
-	modernc.org/sqlite v1.48.0
+	modernc.org/sqlite v1.49.1
 )
 
 require (
@@ -284,14 +283,14 @@ require (
 	go.yaml.in/yaml/v2 v2.4.4 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	golang.org/x/arch v0.22.0 // indirect
-	golang.org/x/mod v0.34.0 // indirect
-	golang.org/x/net v0.52.0 // indirect
+	golang.org/x/mod v0.35.0 // indirect
+	golang.org/x/net v0.53.0 // indirect
 	golang.org/x/oauth2 v0.35.0 // indirect
-	golang.org/x/sys v0.42.0 // indirect
-	golang.org/x/telemetry v0.0.0-20260311193753-579e4da9a98c // indirect
-	golang.org/x/text v0.35.0 // indirect
+	golang.org/x/sys v0.43.0 // indirect
+	golang.org/x/telemetry v0.0.0-20260409153401-be6f6cb8b1fa // indirect
+	golang.org/x/text v0.36.0 // indirect
 	golang.org/x/time v0.14.0 // indirect
-	golang.org/x/tools v0.43.0 // indirect
+	golang.org/x/tools v0.44.0 // indirect
 	gonum.org/v1/gonum v0.17.0 // indirect
 	google.golang.org/api v0.215.0 // indirect
 	google.golang.org/genproto v0.0.0-20241118233622-e639e219e697 // indirect
@@ -300,7 +299,7 @@ require (
 	google.golang.org/grpc v1.79.3 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 	lukechampine.com/blake3 v1.4.1 // indirect
-	modernc.org/libc v1.70.0 // indirect
+	modernc.org/libc v1.72.0 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.11.0 // indirect
 )