code review changes from Aga

Author: snedamle

Features/encumbrance-avatar/README.md

@@ -58,12 +58,18 @@ Create the Avatar on PartyA node
 
 Sell the Avatar to PartyB node from PartyA node
 
-      start SellAvatarFlow avatarId : 1, buyer : PartyB , includeEncumbrance : true
+      start SellAvatarFlow avatarId : 1, buyer : PartyB
 
 Confirm if PartyB owns the Avatar
 
       run vaultQuery contractStateType : com.template.states.Avatar
 
+Note
+As you can see in both the flows, Avatar is encumbered by Expiry. But Encumbrances should form a complete directed cycle, 
+otherwise one can spend the "encumbrance" (Expiry) state, which would freeze the "encumbered" (Avatar) state for ever.
+That's why we also make Expiry dependent on Avatar. (See how we have added encumbrance index's to the output states in 
+both the flows.)
+
 ## Reminder
 
 This project is open source under an Apache 2.0 licence. That means you

Features/encumbrance-avatar/contracts/build.gradle

@@ -19,5 +19,7 @@ dependencies {
     // Corda dependencies.
     cordaCompile "$corda_release_group:corda-core:$corda_release_version"
     cordaRuntime "$corda_release_group:corda:$corda_release_version"
-    testCompile "$corda_release_group:corda-node-driver:$corda_release_version"
+    cordaCompile "$corda_release_group:corda-node-driver:$corda_release_version"
+
+    testCompile "junit:junit:$junit_version"
 }

Features/encumbrance-avatar/contracts/src/main/java/com/template/contracts/ExpiryContract.java

@@ -10,6 +10,7 @@
 import java.time.LocalDateTime;
 import java.time.ZoneId;
 
+//ExpiryContract is also run when Avatar's contract is run
 public class ExpiryContract implements Contract {
 
     public static final String EXPIRY_CONTRACT_ID = "com.template.contracts.ExpiryContract";
@@ -26,6 +27,9 @@ public void verify(@NotNull LedgerTransaction tx) throws IllegalArgumentExceptio
         if (timeWindow == null || timeWindow.getUntilTime() == null) {
             throw new IllegalArgumentException("Make sure you specify the time window for the Avatar transaction.");
         }
+
+        //Expiry time should be after the time window, if the avatar expires before the time window, then the avatar
+        //cannot be sold
         if (timeWindow.getUntilTime().isAfter(expiry.getExpiry())) {
             throw new IllegalArgumentException("Avatar transfer time has expired! Expiry date & time was: " + LocalDateTime.ofInstant(expiry.getExpiry(), ZoneId.systemDefault()));
         }

Features/encumbrance-avatar/contracts/src/main/java/com/template/states/Avatar.java

@@ -10,6 +10,8 @@
 import java.util.List;
 import java.util.Objects;
 
+//Avatar can be thought of as any metaverse avatar which needs to be created and sold on at an exchange. This entity
+//has an id and owner associated with it. We will see how this avatar can only be sold within a certain time limit.
 @BelongsToContract(AvatarContract.class)
 public class Avatar implements ContractState {
     private final AbstractParty owner;

Features/encumbrance-avatar/contracts/src/main/java/com/template/states/Expiry.java

@@ -11,6 +11,8 @@
 import java.util.List;
 import java.util.Objects;
 
+//Expiry represents an expiry date beyond which the avatar cannot be sold. This is the encumbrance state which encumbers
+//the Avatar state.
 @BelongsToContract(ExpiryContract.class)
 public class Expiry implements ContractState {
 

Features/encumbrance-avatar/workflows/src/main/java/com/template/flows/CreateAvatarFlow.java

@@ -37,9 +37,10 @@ public SignedTransaction call() throws FlowException {
         Avatar avatar = new Avatar(this.getOurIdentity(), avatarId);
         Expiry expiry = new Expiry(Instant.now().plus(expiryAfterMinutes, ChronoUnit.MINUTES), avatarId, avatar.getOwner());
 
+        //add expiry and avatar as outputs by specifying encumbrance as index. add time window
         TransactionBuilder txBuilder = new TransactionBuilder(notary)
-                .addOutputState(avatar, AvatarContract.AVATAR_CONTRACT_ID, notary, 1)
-                .addOutputState(expiry, ExpiryContract.EXPIRY_CONTRACT_ID, notary, 0)
+                .addOutputState(avatar, AvatarContract.AVATAR_CONTRACT_ID, notary, 1) //specify the encumbrance as the 3rd parameter
+                .addOutputState(expiry, ExpiryContract.EXPIRY_CONTRACT_ID, notary, 0) //specify the encumbrance as the 3rd parameter
                 .addCommand(new AvatarContract.Commands.Create(), avatar.getOwner().getOwningKey())
                 .addCommand(new ExpiryContract.Commands.Create(), expiry.getOwner().getOwningKey())
                 .setTimeWindow(Instant.now(), Duration.ofSeconds(10));

Features/encumbrance-avatar/workflows/src/main/java/com/template/flows/SellAvatarFlow.java

@@ -36,21 +36,25 @@ public SignedTransaction call() throws FlowException {
 
         Party buyerParty = getServiceHub().getIdentityService().partiesFromName(buyer, true).iterator().next();
 
-                Party notary = getServiceHub().getNetworkMapCache().getNotaryIdentities().get(0);
+        Party notary = getServiceHub().getNetworkMapCache().getNotaryIdentities().get(0);
 
+        //get avatar from db
         Vault.Page<Avatar> avatarPage = getServiceHub().getVaultService().queryBy(Avatar.class);
         StateAndRef<Avatar> avatarStateAndRef = avatarPage.getStates().stream().filter(i ->
                 i.getState().getData().getAvatarId().equalsIgnoreCase(avatarId)).findAny().orElseThrow(() ->
                 new CordaRuntimeException("No avatar found with avatar id as : " + avatarId));;
 
+        //get expiry from db
         Vault.Page<Expiry> expiryPage = getServiceHub().getVaultService().queryBy(Expiry.class);
         StateAndRef<Expiry> expiryStateAndRef = expiryPage.getStates().stream().filter(i ->
                 i.getState().getData().getAvatarId().equalsIgnoreCase(avatarId)).findAny().orElseThrow(() ->
                 new CordaRuntimeException("No expiry found with avatar id as " + avatarId));
 
+        //change owner
         Avatar avatar = new Avatar(buyerParty, avatarId);
-        Expiry expiry = new Expiry(expiryStateAndRef.getState().getData().getExpiry(), avatarId, avatar.getOwner());
+        Expiry expiry = new Expiry(expiryStateAndRef.getState().getData().getExpiry(), avatarId, buyerParty);
 
+        //consume existing states, encumbering states will trigger the expiry contract to run
         TransactionBuilder transactionBuilder = new TransactionBuilder(notary)
                 .addInputState(avatarStateAndRef)
                 .addInputState(expiryStateAndRef)

Features/encumbrance-avatar/workflows/src/test/java/com/template/ContractTests.java

@@ -1,13 +1,94 @@
 package com.template;
 
+import com.google.common.collect.ImmutableList;
+import com.template.contracts.AvatarContract;
+import com.template.contracts.ExpiryContract;
+import com.template.states.Avatar;
+import com.template.states.Expiry;
+import net.corda.core.identity.CordaX500Name;
+import net.corda.testing.core.TestIdentity;
 import net.corda.testing.node.MockServices;
 import org.junit.Test;
 
+import java.time.Duration;
+import java.time.Instant;
+import java.time.temporal.ChronoUnit;
+
+import static net.corda.testing.node.NodeTestUtils.ledger;
+
 public class ContractTests {
-    private final MockServices ledgerServices = new MockServices();
 
+    static private final MockServices ledgerServices = new MockServices();
+    static private final TestIdentity seller = new TestIdentity(new CordaX500Name("MegaCorp", "London", "GB"));
+    static private final TestIdentity buyer = new TestIdentity(new CordaX500Name("MiniCorp", "London", "GB"));
+
+
+    //Both the encumbrance and the encumbered state must be added to the transaction
+    @Test
+    public void thereMustBeTwoOutputs() {
+        ledger(ledgerServices, (ledger -> {
+            ledger.transaction(tx -> {
+                tx.output(AvatarContract.AVATAR_CONTRACT_ID, new Avatar(seller.getParty(), "1"));
+                tx.command(ImmutableList.of(seller.getPublicKey()), new AvatarContract.Commands.Create());
+                tx.fails();
+                return null;
+            });
+            return null;
+        }));
+    }
+
+    //Specifying time window is mandatory. This is checked in the encumbrance Expiry state.
+    @Test
+    public void specifyTimeWindow() {
+        ledger(ledgerServices, (ledger -> {
+            ledger.transaction(tx -> {
+                //this fails as time window is not specified
+                tx.output(AvatarContract.AVATAR_CONTRACT_ID, new Avatar(seller.getParty(), "1"));
+                tx.output(ExpiryContract.EXPIRY_CONTRACT_ID,
+                        new Expiry(Instant.now().plus(2, ChronoUnit.MINUTES), "1", seller.getParty()));
+                tx.command(ImmutableList.of(seller.getPublicKey()), new AvatarContract.Commands.Create());
+                tx.fails();
+
+                //this will pass once we specify time window
+                tx.timeWindow(Instant.now(), Duration.ofMinutes(1));
+                return tx.verifies();
+            });
+            return null;
+        }));
+    }
+
+    //For selling, the Expiry of avatar must be greater than the time window
+    @Test
+    public void avatarIsRejectedIfItIsExpired() {
+        ledger(ledgerServices, (ledger -> {
+            ledger.transaction(tx -> {
+                tx.output(AvatarContract.AVATAR_CONTRACT_ID, new Avatar(seller.getParty(), "1"));
+                tx.output(ExpiryContract.EXPIRY_CONTRACT_ID,
+                        new Expiry(Instant.now().plus(2, ChronoUnit.MINUTES), "1", seller.getParty()));
+                tx.command(ImmutableList.of(seller.getPublicKey()), new AvatarContract.Commands.Create());
+                tx.timeWindow(Instant.now(), Duration.ofMinutes(3));
+                tx.fails();
+                return null;
+            });
+            return null;
+        }));
+    }
+
+    //For selling, the Expiry of avatar must be greater than the time window
     @Test
-    public void dummyTest() {
+    public void expirationDateShouldBeAfterTheTimeWindow() {
+        ledger(ledgerServices, (ledger -> {
+            ledger.transaction(tx -> {
+                tx.output(AvatarContract.AVATAR_CONTRACT_ID, new Avatar(seller.getParty(), "1"));
+                tx.output(ExpiryContract.EXPIRY_CONTRACT_ID,
+                        new Expiry(Instant.now().plus(3, ChronoUnit.MINUTES), "1", seller.getParty()));
+                tx.command(ImmutableList.of(seller.getPublicKey()), new AvatarContract.Commands.Create());
+                tx.timeWindow(Instant.now(), Duration.ofMinutes(2));
+                tx.verifies();
+                return null;
+            });
+            return null;
+        }));
 
     }
 }