|
| 1 | +# Extending a Validator Driver |
| 2 | + |
| 3 | +This guide explains how to extend an existing token validator driver with custom validation functions. |
| 4 | +This is useful when you need to enforce additional business rules or compliance checks beyond the default logic provided by the token drivers (e.g., `FabToken` or `ZKAT-DLog`). |
| 5 | + |
| 6 | +## Overview |
| 7 | + |
| 8 | +The Token SDK uses a `ValidatorDriverService` to manage factories for creating `driver.Validator` instances. |
| 9 | +Each driver version is identified by a unique string (e.g., `zkatdlognogh.v1`). |
| 10 | + |
| 11 | +To extend a validator, you typically: |
| 12 | +1. Implement a custom `driver.ValidatorDriver` that wraps an existing one. |
| 13 | +2. Override the `NewValidator` method to inject additional validation logic. |
| 14 | +3. Register your custom driver factory in the SDK's dependency injection container. |
| 15 | + |
| 16 | +## Architecture |
| 17 | + |
| 18 | +The `ValidatorDriverService` (found in `token/core/service.go`) maintains a map of driver identifiers to `driver.ValidatorDriver` implementations. |
| 19 | + |
| 20 | +```go |
| 21 | +type ValidatorDriverService struct { |
| 22 | + *factoryDirectory[driver.ValidatorDriver] |
| 23 | +} |
| 24 | + |
| 25 | +func (s *ValidatorDriverService) NewValidator(pp driver.PublicParameters) (driver.Validator, error) { |
| 26 | + if driver, ok := s.factories[DriverIdentifierFromPP(pp)]; ok { |
| 27 | + return driver.NewValidator(pp) |
| 28 | + } |
| 29 | + return nil, errors.Errorf("no validator found for token driver [%s]", DriverIdentifierFromPP(pp)) |
| 30 | +} |
| 31 | +``` |
| 32 | + |
| 33 | +By providing a custom factory with the same identifier as an existing driver, you can effectively "hijack" the validator creation process. |
| 34 | + |
| 35 | +## Example: Extending the ZKAT-DLog Validator |
| 36 | + |
| 37 | +Suppose you want to add a custom check to all transfer operations in a `ZKAT-DLog` system. |
| 38 | + |
| 39 | +### 1. Define your custom validation function |
| 40 | + |
| 41 | +First, define a function that matches the signature expected by the validator. For `ZKAT-DLog` (NOGH v1), this is `ValidateTransferFunc`. |
| 42 | + |
| 43 | +```go |
| 44 | +package myextension |
| 45 | + |
| 46 | +import ( |
| 47 | + v1 "github.com/hyperledger-labs/fabric-token-sdk/token/core/zkatdlog/nogh/v1/setup" |
| 48 | + "github.com/hyperledger-labs/fabric-token-sdk/token/core/zkatdlog/nogh/v1/token" |
| 49 | + "github.com/hyperledger-labs/fabric-token-sdk/token/core/zkatdlog/nogh/v1/transfer" |
| 50 | + "github.com/hyperledger-labs/fabric-token-sdk/token/core/zkatdlog/nogh/v1/validator" |
| 51 | + "github.com/hyperledger-labs/fabric-token-sdk/token/driver" |
| 52 | +) |
| 53 | + |
| 54 | +func MyCustomTransferValidation(ctx validator.Context, tr *transfer.Action) error { |
| 55 | + // Perform your custom validation logic here. |
| 56 | + // For example, check if the transfer metadata contains a specific attribute. |
| 57 | + if len(tr.Metadata) == 0 { |
| 58 | + return errors.New("transfer metadata is missing") |
| 59 | + } |
| 60 | + return nil |
| 61 | +} |
| 62 | +``` |
| 63 | + |
| 64 | +### 2. Create a custom Validator Driver |
| 65 | + |
| 66 | +Implement the `driver.ValidatorDriver` interface by wrapping the standard one. |
| 67 | + |
| 68 | +```go |
| 69 | +type MyValidatorDriver struct { |
| 70 | + driver.ValidatorDriver // Wrap the existing driver |
| 71 | +} |
| 72 | + |
| 73 | +func (d *MyValidatorDriver) NewValidator(pp driver.PublicParameters) (driver.Validator, error) { |
| 74 | + // We can't easily use the wrapped driver's NewValidator if we want to |
| 75 | + // inject functions into its internal pipeline, so we replicate its logic. |
| 76 | + |
| 77 | + ppp, ok := pp.(*v1.PublicParams) |
| 78 | + if !ok { |
| 79 | + return nil, errors.Errorf("invalid public parameters type [%T]", pp) |
| 80 | + } |
| 81 | + |
| 82 | + deserializer, err := driver.NewDeserializer(ppp) // Assume driver is the zkatdlog driver package |
| 83 | + if err != nil { |
| 84 | + return nil, err |
| 85 | + } |
| 86 | + |
| 87 | + logger := logging.DriverLoggerFromPP("token-sdk.driver.myextension", string(pp.TokenDriverName())) |
| 88 | + |
| 89 | + // Instantiate the validator with your custom function |
| 90 | + return validator.New( |
| 91 | + logger, |
| 92 | + ppp, |
| 93 | + deserializer, |
| 94 | + []validator.ValidateTransferFunc{MyCustomTransferValidation}, // Extra transfer validators |
| 95 | + nil, // Extra issuer validators |
| 96 | + nil, // Extra auditor validators |
| 97 | + ), nil |
| 98 | +} |
| 99 | +``` |
| 100 | + |
| 101 | +### 3. Register the extension |
| 102 | + |
| 103 | +Register your custom factory using the SDK's registration mechanism. If you are using the `dig` container (standard in FSC-based applications), you can provide it to the `token-validator-drivers` group. |
| 104 | + |
| 105 | +```go |
| 106 | +func NewMyValidatorDriver() core.NamedFactory[driver.ValidatorDriver] { |
| 107 | + return core.NamedFactory[driver.ValidatorDriver]{ |
| 108 | + Name: core.DriverIdentifier(v1.DLogNoGHDriverName, v1.ProtocolV1), |
| 109 | + Driver: &MyValidatorDriver{ |
| 110 | + // You might need to initialize the wrapped driver here |
| 111 | + }, |
| 112 | + } |
| 113 | +} |
| 114 | +``` |
| 115 | + |
| 116 | +By using the same `Name` as the original driver, the `ValidatorDriverService` will use your factory instead of the default one. |
| 117 | + |
| 118 | +## Alternative: Generic Validator Wrapping |
| 119 | + |
| 120 | +If you want to add validation that is independent of the driver's internal implementation, you can wrap the `driver.Validator` interface directly. |
| 121 | + |
| 122 | +```go |
| 123 | +type WrappedValidator struct { |
| 124 | + driver.Validator |
| 125 | +} |
| 126 | + |
| 127 | +func (v *WrappedValidator) VerifyTokenRequestFromRaw(ctx context.Context, getState driver.GetStateFnc, anchor driver.TokenRequestAnchor, raw []byte) ([]interface{}, driver.ValidationAttributes, error) { |
| 128 | + // Call the original validator first |
| 129 | + actions, attrs, err := v.Validator.VerifyTokenRequestFromRaw(ctx, getState, anchor, raw) |
| 130 | + if err != nil { |
| 131 | + return nil, nil, err |
| 132 | + } |
| 133 | + |
| 134 | + // Perform post-validation |
| 135 | + for _, action := range actions { |
| 136 | + if err := myGlobalCheck(action); err != nil { |
| 137 | + return nil, nil, err |
| 138 | + } |
| 139 | + } |
| 140 | + |
| 141 | + return actions, attrs, nil |
| 142 | +} |
| 143 | +``` |
| 144 | + |
| 145 | +This approach is highly portable and works across all token drivers. |
0 commit comments