[FAB-11671] Token client: redeem function

- add RequestRedeem to Prover interface
- add Redeem to client API

Change-Id: Iad6c0d0fb54633bb8ac8955a94ab825c5aa6d5e8
Signed-off-by: Wenjian Qiao <wenjianq@gmail.com>

Author: wenjianqiao

token/client/client.go

@@ -31,6 +31,12 @@ type Prover interface {
 	// request fails
 	RequestTransfer(tokenIDs [][]byte, shares []*token.RecipientTransferShare, signingIdentity tk.SigningIdentity) ([]byte, error)
 
+	// RequestRedeem allows the redemption of the tokens in the input tokenIDs
+	// It queries the ledger to read detail for each token id.
+	// It creates a token transaction with an output for redeemed tokens and
+	// possibly another output to transfer the remaining tokens, if any, to the same user
+	RequestRedeem(tokenIDs [][]byte, quantity uint64, signingIdentity tk.SigningIdentity) ([]byte, error)
+
 	// ListTokens allows the client to submit a list request to a prover peer service;
 	// it returns a list of TokenOutput and an error message in the case the request fails
 	ListTokens(signingIdentity tk.SigningIdentity) ([]*token.TokenOutput, error)
@@ -139,6 +145,31 @@ func (c *Client) Transfer(tokenIDs [][]byte, shares []*token.RecipientTransferSh
 	return txEnvelope, txid, ordererStatus, committed, err
 }
 
+// Redeem allows the redemption of the tokens in the input tokenIDs
+// The 'waitTimeout' parameter defines the time to wait for the transaction to be committed.
+// If it is 0, the function will return immediately after receiving a response from the orderer
+// without waiting for the transaction to be committed.
+// If it is greater than 0, the function will wait until the transaction commit event is received or wait timed out, whichever is earlier.
+// This API submits the transaction to the orderer and returns envelope, transaction id, orderer status, committed boolean, and error.
+// When an error is returned, check the orderer status.
+// If it is SUCCESS (200), the transaction has been successfully submitted regardless of the error.
+// The application must analyze the error and get the transaction status to make sure the transaction is either committed or invalidated.
+// If the transaction is invalidated, the application may call the API again after fixing the error.
+func (c *Client) Redeem(tokenIDs [][]byte, quantity uint64, waitTimeout time.Duration) (*common.Envelope, string, *common.Status, bool, error) {
+	serializedTokenTx, err := c.Prover.RequestRedeem(tokenIDs, quantity, c.SigningIdentity)
+	if err != nil {
+		return nil, "", nil, false, err
+	}
+
+	txEnvelope, txid, err := c.TxSubmitter.CreateTxEnvelope(serializedTokenTx)
+	if err != nil {
+		return nil, "", nil, false, err
+	}
+
+	ordererStatus, committed, err := c.TxSubmitter.Submit(txEnvelope, waitTimeout)
+	return txEnvelope, txid, ordererStatus, committed, err
+}
+
 // ListTokens allows the client to submit a list request to a prover peer service;
 // it returns a list of TokenOutput and an error in the case the request fails
 func (c *Client) ListTokens() ([]*token.TokenOutput, error) {

token/client/client_test.go

@@ -44,6 +44,7 @@ var _ = Describe("Client", func() {
 		fakeProver = &mock.Prover{}
 		fakeProver.RequestImportReturns(payload.Data, nil) // same data as payload
 		fakeProver.RequestTransferReturns(payload.Data, nil)
+		fakeProver.RequestRedeemReturns(payload.Data, nil)
 
 		fakeSigningIdentity = &mock.SigningIdentity{}
 		fakeSigningIdentity.SerializeReturns([]byte("creator"), nil) // same signature as envelope
@@ -256,6 +257,100 @@ var _ = Describe("Client", func() {
 		})
 	})
 
+	Describe("Redeem", func() {
+		var (
+			tokenIDs [][]byte
+			quantity uint64
+		)
+
+		BeforeEach(func() {
+			// input data for redeem
+			tokenIDs = [][]byte{[]byte("id1"), []byte("id2")}
+			quantity = 100
+		})
+
+		It("returns tx envelope without error", func() {
+			txEnvelope, txid, ordererStatus, committed, err := tokenClient.Redeem(tokenIDs, quantity, 10*time.Second)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(txEnvelope).To(Equal(envelope))
+			Expect(txid).To(Equal(expectedTxid))
+			Expect(*ordererStatus).To(Equal(common.Status_SUCCESS))
+			Expect(committed).To(Equal(true))
+
+			Expect(fakeProver.RequestRedeemCallCount()).To(Equal(1))
+			ids, num, signingIdentity := fakeProver.RequestRedeemArgsForCall(0)
+			Expect(ids).To(Equal(tokenIDs))
+			Expect(num).To(Equal(quantity))
+			Expect(signingIdentity).To(Equal(fakeSigningIdentity))
+
+			Expect(fakeTxSubmitter.CreateTxEnvelopeCallCount()).To(Equal(1))
+			txBytes := fakeTxSubmitter.CreateTxEnvelopeArgsForCall(0)
+			Expect(txBytes).To(Equal(payload.Data))
+
+			Expect(fakeTxSubmitter.SubmitCallCount()).To(Equal(1))
+			txEnvelope, waitTime := fakeTxSubmitter.SubmitArgsForCall(0)
+			Expect(txEnvelope).To(Equal(envelope))
+			Expect(waitTime).To(Equal(10 * time.Second))
+		})
+
+		Context("when prover.RequestRedeem fails", func() {
+			BeforeEach(func() {
+				fakeProver.RequestRedeemReturns(nil, errors.New("wild-banana"))
+			})
+
+			It("returns an error", func() {
+				envelope, txid, ordererStatus, committed, err := tokenClient.Redeem(tokenIDs, quantity, 0)
+				Expect(err).To(MatchError("wild-banana"))
+				Expect(envelope).To(BeNil())
+				Expect(txid).To(Equal(""))
+				Expect(ordererStatus).To(BeNil())
+				Expect(committed).To(Equal(false))
+
+				Expect(fakeProver.RequestRedeemCallCount()).To(Equal(1))
+				Expect(fakeTxSubmitter.CreateTxEnvelopeCallCount()).To(Equal(0))
+				Expect(fakeTxSubmitter.SubmitCallCount()).To(Equal(0))
+			})
+		})
+
+		Context("when TxSubmitter CreateTxEnvelope fails", func() {
+			BeforeEach(func() {
+				fakeTxSubmitter.CreateTxEnvelopeReturns(nil, "", errors.New("wild-banana"))
+			})
+
+			It("returns an error", func() {
+				envelope, txid, ordererStatus, committed, err := tokenClient.Redeem(tokenIDs, quantity, 0)
+				Expect(err).To(MatchError("wild-banana"))
+				Expect(envelope).To(BeNil())
+				Expect(txid).To(Equal(""))
+				Expect(ordererStatus).To(BeNil())
+				Expect(committed).To(Equal(false))
+
+				Expect(fakeProver.RequestRedeemCallCount()).To(Equal(1))
+				Expect(fakeTxSubmitter.CreateTxEnvelopeCallCount()).To(Equal(1))
+				Expect(fakeTxSubmitter.SubmitCallCount()).To(Equal(0))
+			})
+		})
+
+		Context("when TxSubmitter Submit fails", func() {
+			BeforeEach(func() {
+				fakeTxSubmitter.SubmitReturns(nil, false, errors.New("wild-banana"))
+			})
+
+			It("returns an error", func() {
+				txEnvelope, txid, ordererStatus, committed, err := tokenClient.Redeem(tokenIDs, quantity, 0)
+				Expect(err).To(MatchError("wild-banana"))
+				Expect(txEnvelope).To(Equal(envelope))
+				Expect(txid).To(Equal(expectedTxid))
+				Expect(ordererStatus).To(BeNil())
+				Expect(committed).To(Equal(false))
+
+				Expect(fakeProver.RequestRedeemCallCount()).To(Equal(1))
+				Expect(fakeTxSubmitter.CreateTxEnvelopeCallCount()).To(Equal(1))
+				Expect(fakeTxSubmitter.SubmitCallCount()).To(Equal(1))
+			})
+		})
+	})
+
 	Describe("ListTokens", func() {
 		var (
 			expectedTokens []*token.TokenOutput

token/client/mock/prover.go

@@ -123,6 +123,25 @@ func (prover *ProverPeer) RequestTransfer(
 	return prover.SendCommand(context.Background(), sc)
 }
 
+// RequestRedeem allows the redemption of the tokens in the input tokenIDs
+// It queries the ledger to read detail for each token id.
+// It creates a token transaction with an output for redeemed tokens and
+// possibly another output to transfer the remaining tokens, if any, to the same user
+func (prover *ProverPeer) RequestRedeem(tokenIDs [][]byte, quantity uint64, signingIdentity tk.SigningIdentity) ([]byte, error) {
+	rr := &token.RedeemRequest{
+		QuantityToRedeem: quantity,
+		TokenIds:         tokenIDs,
+	}
+	payload := &token.Command_RedeemRequest{RedeemRequest: rr}
+
+	sc, err := prover.CreateSignedCommand(payload, signingIdentity)
+	if err != nil {
+		return nil, err
+	}
+
+	return prover.SendCommand(context.Background(), sc)
+}
+
 // ListTokens allows the client to submit a list request to a prover peer service;
 // it returns a list of TokenOutput and an error message in the case the request fails
 func (prover *ProverPeer) ListTokens(signingIdentity tk.SigningIdentity) ([]*token.TokenOutput, error) {
@@ -241,6 +260,8 @@ func commandFromPayload(payload interface{}) (*token.Command, error) {
 	switch t := payload.(type) {
 	case *token.Command_ImportRequest:
 		return &token.Command{Payload: t}, nil
+	case *token.Command_RedeemRequest:
+		return &token.Command{Payload: t}, nil
 	case *token.Command_TransferRequest:
 		return &token.Command{Payload: t}, nil
 	case *token.Command_ListRequest: