Address nkcr's comments

blockchain/mod.go

@@ -15,7 +15,7 @@ type Block interface {
 	// GetIndex returns the index since the genesis block.
 	GetIndex() uint64
 
-	// GetHash returns the footprint of the block.
+	// GetHash returns the fingerprint of the block.
 	GetHash() []byte
 
 	// GetPayload returns the payload of the block.

docs/introduction.md

@@ -25,7 +25,7 @@ definitions of modular pieces that build a blockchain.
   of signature from multiple key pairs and it can be verified by the
   corresponding aggregate of public keys.
 
-- **footprint** - Footprint defines a digest commonly produced by a hash
+- **fingerprint** - Fingerprint defines a digest commonly produced by a hash
   algorithm that can be used to verify the integrity of some data. One example
   is the inventory page integrity to prove which instances are stored.
 
@@ -66,3 +66,6 @@ definitions of modular pieces that build a blockchain.
 
 - **skipchain** - A skipchain is a specific implementation of the blockchain
   that is using collective signings to create shortcuts between blocks.
+
+- **task** - A task is an order of execution that is stored inside a
+  transaction. It will define how the transaction will update the inventory.

internal/testing/fake/mod.go

@@ -514,10 +514,7 @@ type Counter struct {
 
 // Done returns true when the counter reached zero.
 func (c *Counter) Done() bool {
-	if c == nil {
-		return true
-	}
-	return c.Value <= 0
+	return c == nil || c.Value <= 0
 }
 
 // Decrease decrements the counter.

ledger/arc/darc/task.go

@@ -18,6 +18,8 @@ const (
 
 // clientTask is the client task of a transaction that will allow an authorized
 // identity to create or update a DARC.
+//
+// - implements basic.ClientTask
 type clientTask struct {
 	key    []byte
 	access Access
@@ -68,6 +70,8 @@ func (act clientTask) Fingerprint(w io.Writer, enc encoding.ProtoMarshaler) erro
 }
 
 // serverTask is the server task for a DARC transaction.
+//
+// - implements basic.ServerTask
 type serverTask struct {
 	clientTask
 	encoder     encoding.ProtoMarshaler
@@ -119,6 +123,10 @@ func (act serverTask) Consume(ctx basic.Context, page inventory.WritablePage) er
 	return nil
 }
 
+// taskFactory is a factory to instantiate darc server tasks from protobuf
+// messages.
+//
+// - implements basic.TaskFactory
 type taskFactory struct {
 	encoder     encoding.ProtoMarshaler
 	darcFactory arc.AccessControlFactory

ledger/byzcoin/contract/task.go

@@ -14,12 +14,15 @@ import (
 )
 
 // SpawnTask is a client task of a transaction to create a new instance.
+//
+// - implements basic.ClientTask
 type SpawnTask struct {
 	ContractID string
 	Argument   proto.Message
 }
 
-// Pack implements encoding.Packable.
+// Pack implements encoding.Packable. It returns the protobuf message of the
+// task.
 func (act SpawnTask) Pack(enc encoding.ProtoMarshaler) (proto.Message, error) {
 	argument, err := enc.MarshalAny(act.Argument)
 	if err != nil {
@@ -34,7 +37,8 @@ func (act SpawnTask) Pack(enc encoding.ProtoMarshaler) (proto.Message, error) {
 	return pb, nil
 }
 
-// Fingerprint implements encoding.Fingerprinter.
+// Fingerprint implements encoding.Fingerprinter. It serializes the task into
+// the writer in a deterministic way.
 func (act SpawnTask) Fingerprint(w io.Writer, e encoding.ProtoMarshaler) error {
 	_, err := w.Write([]byte(act.ContractID))
 	if err != nil {
@@ -51,12 +55,15 @@ func (act SpawnTask) Fingerprint(w io.Writer, e encoding.ProtoMarshaler) error {
 
 // InvokeTask is a client task of a transaction to update an existing instance
 // if the access rights control allows it.
+//
+// - implements basic.ClientTask
 type InvokeTask struct {
 	Key      []byte
 	Argument proto.Message
 }
 
-// Pack implements encoding.Packable.
+// Pack implements encoding.Packable. It returns the protobuf message of the
+// task.
 func (act InvokeTask) Pack(e encoding.ProtoMarshaler) (proto.Message, error) {
 	argument, err := e.MarshalAny(act.Argument)
 	if err != nil {
@@ -71,7 +78,8 @@ func (act InvokeTask) Pack(e encoding.ProtoMarshaler) (proto.Message, error) {
 	return pb, nil
 }
 
-// Fingerprint implements encoding.Fingeprinter.
+// Fingerprint implements encoding.Fingeprinter. It serializes the task into the
+// writer in a deterministic way.
 func (act InvokeTask) Fingerprint(w io.Writer, e encoding.ProtoMarshaler) error {
 	_, err := w.Write(act.Key)
 	if err != nil {
@@ -88,16 +96,20 @@ func (act InvokeTask) Fingerprint(w io.Writer, e encoding.ProtoMarshaler) error
 
 // DeleteTask is a client task of a transaction to mark an instance as deleted
 // so that it cannot be updated anymore.
+//
+// - implements basic.ClientTask
 type DeleteTask struct {
 	Key []byte
 }
 
-// Pack implements encoding.Packable.
+// Pack implements encoding.Packable. It returns the protobuf message of the
+// task.
 func (a DeleteTask) Pack(encoding.ProtoMarshaler) (proto.Message, error) {
 	return &DeleteTaskProto{Key: a.Key}, nil
 }
 
-// Fingerprint implements encoding.Fingerprinter.
+// Fingerprint implements encoding.Fingerprinter. It serializes the task into
+// the writer in a deterministic way.
 func (a DeleteTask) Fingerprint(w io.Writer, e encoding.ProtoMarshaler) error {
 	_, err := w.Write(a.Key)
 	if err != nil {
@@ -107,13 +119,19 @@ func (a DeleteTask) Fingerprint(w io.Writer, e encoding.ProtoMarshaler) error {
 	return nil
 }
 
+// serverTask is a contract task that can be consumed to update an inventory
+// page.
+//
+// - implements basic.ServerTask
 type serverTask struct {
 	basic.ClientTask
 	contracts  map[string]Contract
 	arcFactory arc.AccessControlFactory
 	encoder    encoding.ProtoMarshaler
 }
 
+// Consume implements basic.ServerTask. It updates the page according to the
+// task definition.
 func (act serverTask) Consume(ctx basic.Context, page inventory.WritablePage) error {
 	txCtx := taskContext{
 		Context:    ctx,
@@ -256,6 +274,8 @@ func (act serverTask) hasAccess(ctx Context, key []byte, rule string) error {
 
 // TaskFactory is a factory to decode protobuf messages into transaction tasks
 // and register static contracts.
+//
+// - implements basic.TaskFactory
 type TaskFactory struct {
 	contracts  map[string]Contract
 	arcFactory arc.AccessControlFactory

ledger/byzcoin/messages.proto

@@ -11,17 +11,17 @@ message GenesisPayload {
     // transactions.
     roster.Roster roster = 1;
 
-    // Footprint is an integrity check of the final state of the inventory after
+    // Fingerprint is an integrity check of the final state of the inventory after
     // applying the genesis payload.
-    bytes footprint = 2;
+    bytes fingerprint = 2;
 }
 
 // BlockPayload is the message that will be stored in the blocks. It is composed
-// of the transactions and the footprint of the new inventory.
+// of the transactions and the fingerprint of the new inventory.
 message BlockPayload {
     repeated google.protobuf.Any transactions = 1;
 
-    // Footprint is an integrity check of the final state of the inventory after
+    // Fingerprint is an integrity check of the final state of the inventory after
     // applying the transactions.
-    bytes footprint = 2;
+    bytes fingerprint = 2;
 }

ledger/byzcoin/mod.go

@@ -274,7 +274,7 @@ func (ldgr *Ledger) stagePayload(txs []transactions.ClientTransaction) (*BlockPa
 		return nil, xerrors.Errorf("couldn't process the txs: %v", err)
 	}
 
-	payload.Footprint = page.GetFootprint()
+	payload.Fingerprint = page.GetFingerprint()
 
 	return payload, nil
 }
@@ -349,7 +349,7 @@ func (a actorLedger) Setup(players mino.Players) error {
 		return xerrors.Errorf("couldn't store genesis payload: %v", err)
 	}
 
-	payload.Footprint = page.GetFootprint()
+	payload.Fingerprint = page.GetFingerprint()
 
 	err = a.bcActor.InitChain(payload, authority)
 	if err != nil {

ledger/byzcoin/mod_test.go

@@ -75,6 +75,8 @@ func TestLedger_Basic(t *testing.T) {
 
 	roster, err := ledgers[2].(*Ledger).governance.GetAuthority(1)
 	require.NoError(t, err)
+	// The last participant over 20 should have been removed from the current
+	// chain roster.
 	require.Equal(t, 19, roster.Len())
 
 	// Try to create a DARC.

ledger/byzcoin/roster/task.go

@@ -30,6 +30,8 @@ var rosterChangeSetKey = []byte(RosterChangeSetKey)
 
 // clientTask is the client task implementation to update the roster of a
 // consensus using the transactions for access rights control.
+//
+// - implements basic.ClientTask
 type clientTask struct {
 	remove []uint32
 }
@@ -78,6 +80,8 @@ func (t clientTask) Fingerprint(w io.Writer, e encoding.ProtoMarshaler) error {
 
 // serverTask is the extension of the client task to consume the task and update
 // the inventory page accordingly.
+//
+// - implements basic.ServerTask
 type serverTask struct {
 	clientTask
 	encoder       encoding.ProtoMarshaler

ledger/byzcoin/task.go

@@ -16,7 +16,7 @@ import (
 	"golang.org/x/xerrors"
 )
 
-// taskFactory is an task factory that can process several types of tasks.
+// taskFactory is a task factory that can process several types of tasks.
 //
 // - implements basic.TaskFactory
 type taskFactory struct {

ledger/byzcoin/txproc.go

@@ -42,7 +42,7 @@ func (proc *txProcessor) Validate(index uint64, data proto.Message) error {
 		}
 	case *BlockPayload:
 		fabric.Logger.Trace().
-			Hex("footprint", payload.GetFootprint()).
+			Hex("fingerprint", payload.GetFingerprint()).
 			Msgf("validating block payload")
 
 		page, err := proc.process(payload)
@@ -54,9 +54,9 @@ func (proc *txProcessor) Validate(index uint64, data proto.Message) error {
 			return xerrors.Errorf("invalid index %d != %d", page.GetIndex(), index)
 		}
 
-		if !bytes.Equal(page.GetFootprint(), payload.GetFootprint()) {
-			return xerrors.Errorf("mismatch payload footprint '%#x' != '%#x'",
-				page.GetFootprint(), payload.GetFootprint())
+		if !bytes.Equal(page.GetFingerprint(), payload.GetFingerprint()) {
+			return xerrors.Errorf("mismatch payload fingerprint '%#x' != '%#x'",
+				page.GetFingerprint(), payload.GetFingerprint())
 		}
 	default:
 		return xerrors.Errorf("invalid message type '%T'", data)
@@ -82,7 +82,7 @@ func (proc *txProcessor) setup(payload *GenesisPayload) (inventory.Page, error)
 }
 
 func (proc *txProcessor) process(payload *BlockPayload) (inventory.Page, error) {
-	page := proc.inventory.GetStagingPage(payload.GetFootprint())
+	page := proc.inventory.GetStagingPage(payload.GetFingerprint())
 	if page != nil {
 		// Page has already been processed previously.
 		return page, nil
@@ -109,28 +109,28 @@ func (proc *txProcessor) process(payload *BlockPayload) (inventory.Page, error)
 		return nil, xerrors.Errorf("couldn't stage new page: %v", err)
 	}
 
-	fabric.Logger.Trace().Msgf("staging new inventory %#x", page.GetFootprint())
+	fabric.Logger.Trace().Msgf("staging new inventory %#x", page.GetFingerprint())
 	return page, err
 }
 
 // Commit implements blockchain.PayloadProcessor. It tries to commit to the
 // payload as it should have previously been processed. It returns nil if the
 // commit is a success, otherwise an error.
 func (proc *txProcessor) Commit(data proto.Message) error {
-	var footprint []byte
+	var fingerprint []byte
 
 	switch payload := data.(type) {
 	case *GenesisPayload:
-		footprint = payload.GetFootprint()
+		fingerprint = payload.GetFingerprint()
 	case *BlockPayload:
-		footprint = payload.GetFootprint()
+		fingerprint = payload.GetFingerprint()
 	default:
 		return xerrors.Errorf("invalid message type '%T'", data)
 	}
 
-	err := proc.inventory.Commit(footprint)
+	err := proc.inventory.Commit(fingerprint)
 	if err != nil {
-		return xerrors.Errorf("couldn't commit to page '%#x': %v", footprint, err)
+		return xerrors.Errorf("couldn't commit to page '%#x': %v", fingerprint, err)
 	}
 
 	return nil