token: introduce policy-based identity (#1586) (#1597)

Signed-off-by: Siddhi Khandelwal <siddhi.200727@gmail.com>

Author: sid200727

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:

docs/services/ttx.md

@@ -115,6 +115,16 @@ var _ = Describe("EndToEnd", func() {
 			It("succeeded", Label("T12"), func() { fungible.TestMultiSig(ts.II, selector) })
 		})
 
+		Describe("PolicyIdentity", t.Label, func() {
+			ts, selector := newTestSuite(t.CommType, Aries, t.ReplicationFactor, "", "alice", "bob", "charlie")
+			BeforeEach(ts.Setup)
+			AfterEach(ts.TearDown)
+			It("OR and AND succeeded", Label("T14", "T15"), func() {
+				fungible.TestPolicyOR(ts.II, selector)
+				fungible.TestPolicyAND(ts.II, selector)
+			})
+		})
+
 		Describe("Redeem to yourself", t.Label, func() {
 			ts, selector := newTestSuite(t.CommType, Aries, t.ReplicationFactor, "", "alice", "bob", "charlie")
 			BeforeEach(ts.Setup)

integration/token/fungible/dlog/dlog_test.go

@@ -14,6 +14,7 @@ import (
 	"github.com/hyperledger-labs/fabric-smart-client/platform/view/services/view"
 	views1 "github.com/hyperledger-labs/fabric-token-sdk/integration/token/common/views"
 	"github.com/hyperledger-labs/fabric-token-sdk/integration/token/fungible/views"
+	"github.com/hyperledger-labs/fabric-token-sdk/token/services/ttx/boolpolicy"
 	"github.com/hyperledger-labs/fabric-token-sdk/token/services/ttx/multisig"
 )
 
@@ -74,9 +75,15 @@ func (p *SDK) Install() error {
 			registry.RegisterResponder(&views.AcceptCashView{}, &views.TransferView{}),
 			registry.RegisterResponder(&views.AcceptCashView{}, &views.TransferWithSelectorView{}),
 			registry.RegisterResponder(&views.AcceptPreparedCashView{}, &views.PrepareTransferView{}),
+			registry.RegisterFactory("PolicyLock", &views.PolicyLockViewFactory{}),
+			registry.RegisterFactory("PolicySpend", &views.PolicySpendViewFactory{}),
+			registry.RegisterFactory("PolicyOwnedBalance", &views.PolicyOwnedBalanceViewFactory{}),
 			registry.RegisterResponder(&views.AcceptCashView{}, &views.MultiSigLockView{}),
 			registry.RegisterResponder(&views.AcceptCashView{}, &views.MultiSigSpendView{}),
 			registry.RegisterResponder(&views.MultiSigAcceptSpendView{}, &multisig.RequestSpendView{}),
+			registry.RegisterResponder(&views.AcceptCashView{}, &views.PolicyLockView{}),
+			registry.RegisterResponder(&views.AcceptCashView{}, &views.PolicySpendView{}),
+			registry.RegisterResponder(&views.PolicyAcceptSpendView{}, &boolpolicy.RequestSpendView{}),
 			registry.RegisterResponder(&views.SwapResponderView{}, &views.SwapInitiatorView{}),
 			registry.RegisterResponder(&views.AcceptCashView{}, &views.MaliciousTransferView{}),
 		)

integration/token/fungible/sdk/party/sdk.go

@@ -301,6 +301,26 @@ func CheckBalanceForTMSID(network *integration.Infrastructure, ref *token3.NodeR
 	}).WithArguments(network, ref, wallet, typ, expected, tmsID).WithTimeout(eventualCheckTimeout).WithPolling(eventualCheckPolling).Should(gomega.Succeed())
 }
 
+func CheckPolicyOwnedBalance(network *integration.Infrastructure, ref *token3.NodeReference, wallet string, typ token.Type, expected uint64) {
+	CheckPolicyOwnedBalanceForTMSID(network, ref, wallet, typ, expected, nil)
+}
+
+func CheckPolicyOwnedBalanceForTMSID(network *integration.Infrastructure, ref *token3.NodeReference, wallet string, typ token.Type, expected uint64, tmsID *token2.TMSID) {
+	res, err := network.Client(ref.ReplicaName()).CallView("PolicyOwnedBalance", common.JSONMarshall(&views.PolicyOwnedBalanceQuery{
+		Wallet: wallet,
+		Type:   typ,
+		TMSID:  tmsID,
+	}))
+	gomega.Expect(err).NotTo(gomega.HaveOccurred())
+	b := &views.Balance{}
+	common.JSONUnmarshal(res.([]byte), b)
+	gomega.Expect(b.Type).To(gomega.BeEquivalentTo(typ))
+	q, err := token.ToQuantity(b.Quantity, 64)
+	gomega.Expect(err).NotTo(gomega.HaveOccurred())
+	expectedQ := token.NewQuantityFromUInt64(expected)
+	gomega.Expect(expectedQ.Cmp(q)).To(gomega.BeEquivalentTo(0), "[%s]!=[%s]", expected, q)
+}
+
 func CheckCoOwnedBalance(network *integration.Infrastructure, ref *token3.NodeReference, wallet string, typ token.Type, expected uint64) {
 	CheckCoOwnedBalanceForTMSID(network, ref, wallet, typ, expected, nil)
 }
@@ -1490,6 +1510,74 @@ func MultiSigSpendCashForTMSID(network *integration.Infrastructure, sender *toke
 	return txID
 }
 
+// PolicyLockCash locks amount tokens of the given type into a policy identity
+// composed of the given receivers and governed by the boolean policy expression.
+func PolicyLockCash(network *integration.Infrastructure, sender *token3.NodeReference, wallet string, typ token.Type, amount uint64, policy string, receivers []*token3.NodeReference, auditor *token3.NodeReference) string {
+	return PolicyLockCashForTMSID(network, sender, wallet, typ, amount, policy, receivers, auditor, nil)
+}
+
+// PolicyLockCashForTMSID is like PolicyLockCash but pins a specific TMSID.
+func PolicyLockCashForTMSID(network *integration.Infrastructure, sender *token3.NodeReference, wallet string, typ token.Type, amount uint64, policy string, receivers []*token3.NodeReference, auditor *token3.NodeReference, tmsID *token2.TMSID) string {
+	parties := make([]view.Identity, len(receivers))
+	for i, r := range receivers {
+		parties[i] = network.Identity(r.Id())
+	}
+	txidBoxed, err := network.Client(sender.ReplicaName()).CallView("PolicyLock", common.JSONMarshall(&views.PolicyLock{
+		Auditor:       auditor.Id(),
+		Wallet:        wallet,
+		Type:          typ,
+		Amount:        amount,
+		Policy:        policy,
+		PolicyParties: parties,
+		TMSID:         tmsID,
+	}))
+	gomega.Expect(err).NotTo(gomega.HaveOccurred())
+
+	return common.JSONUnmarshalString(txidBoxed)
+}
+
+// PolicySpendCashOR spends a policy token using only the sender as the signing
+// component identity (OR-policy optimisation: no co-owner coordination needed).
+func PolicySpendCashOR(network *integration.Infrastructure, sender *token3.NodeReference, wallet string, typ token.Type, receiver *token3.NodeReference, auditor *token3.NodeReference) string {
+	return PolicySpendCashORForTMSID(network, sender, wallet, typ, receiver, auditor, nil)
+}
+
+// PolicySpendCashORForTMSID is like PolicySpendCashOR but pins a specific TMSID.
+func PolicySpendCashORForTMSID(network *integration.Infrastructure, sender *token3.NodeReference, wallet string, typ token.Type, receiver *token3.NodeReference, auditor *token3.NodeReference, tmsID *token2.TMSID) string {
+	txidBoxed, err := network.Client(sender.ReplicaName()).CallView("PolicySpend", common.JSONMarshall(&views.PolicySpend{
+		Auditor:   auditor.Id(),
+		Wallet:    wallet,
+		TMSID:     tmsID,
+		Recipient: network.Identity(receiver.Id()),
+		TokenType: typ,
+		Signers:   []view.Identity{network.Identity(sender.Id())},
+	}))
+	gomega.Expect(err).NotTo(gomega.HaveOccurred())
+
+	return common.JSONUnmarshalString(txidBoxed)
+}
+
+// PolicySpendCashAND spends a policy token that requires all co-owners to sign,
+// coordinating with them via RequestSpendView before collecting endorsements.
+func PolicySpendCashAND(network *integration.Infrastructure, sender *token3.NodeReference, wallet string, typ token.Type, receiver *token3.NodeReference, auditor *token3.NodeReference) string {
+	return PolicySpendCashANDForTMSID(network, sender, wallet, typ, receiver, auditor, nil)
+}
+
+// PolicySpendCashANDForTMSID is like PolicySpendCashAND but pins a specific TMSID.
+func PolicySpendCashANDForTMSID(network *integration.Infrastructure, sender *token3.NodeReference, wallet string, typ token.Type, receiver *token3.NodeReference, auditor *token3.NodeReference, tmsID *token2.TMSID) string {
+	txidBoxed, err := network.Client(sender.ReplicaName()).CallView("PolicySpend", common.JSONMarshall(&views.PolicySpend{
+		Auditor:   auditor.Id(),
+		Wallet:    wallet,
+		TMSID:     tmsID,
+		Recipient: network.Identity(receiver.Id()),
+		TokenType: typ,
+		// Signers is nil: all co-owners are contacted and must sign.
+	}))
+	gomega.Expect(err).NotTo(gomega.HaveOccurred())
+
+	return common.JSONUnmarshalString(txidBoxed)
+}
+
 func BindIssuerNetworkAndSigningIdentities(network *integration.Infrastructure, issuer *token3.NodeReference, issuerPublicKey []byte, onNodes ...*token3.NodeReference) {
 	for _, node := range onNodes {
 		for _, nodeReplica := range node.AllNames() {