documenting and removing no-need function

README.md

@@ -3,4 +3,11 @@
 This is the Invitation Chain, which is the Go package and CLI tool for building
 invitation and reputation chains. Later we might offer gRPC API as well.
 
+### Design
 
+- use case driven approach.
+- test driven approach
+- algorithm first
+- then input and output 
+  - network transport
+- last the persistence 

chain/chain.go

@@ -125,12 +125,11 @@ func (c Chain) Bytes() []byte {
 	return buf.Bytes()
 }
 
-// todo: should we refactor to immutable which returns a new chain?
-func (c *Chain) addBlock(
+func (c Chain) Invite(
 	invitersKey *crypto.Key,
 	inviteesPubKey crypto.PubKey,
 	position int,
-) {
+) (nc Chain) {
 	assert.D.True(invitersKey.PubKeyEqual(c.LeafPubKey()))
 
 	newBlock := Block{
@@ -140,7 +139,9 @@ func (c *Chain) addBlock(
 	}
 	newBlock.InvitersSignature = invitersKey.Sign(newBlock.Bytes())
 
-	c.Blocks = append(c.Blocks, newBlock)
+	nc = c.Clone()
+	nc.Blocks = append(nc.Blocks, newBlock)
+	return nc
 }
 
 func (c Chain) LeafPubKey() crypto.PubKey {
@@ -178,18 +179,6 @@ func (c Chain) Clone() Chain {
 	return NewChainFromData(c.Bytes())
 }
 
-func (c Chain) Invite(
-	invitersKey *crypto.Key,
-	inviteesPubKey crypto.PubKey,
-	level int,
-) Chain {
-	assert.D.True(len(c.Blocks) > 0, "root must exist")
-
-	nc := c.Clone()
-	nc.addBlock(invitersKey, inviteesPubKey, level)
-	return nc
-}
-
 func (c Chain) IsInviterFor(invitee Chain) bool {
 	if !invitee.Verify() {
 		return false

chain/chain_test.go

@@ -33,7 +33,7 @@ func setup() {
 	c = NewChain(rootKey.PubKey)
 	inviteeKey = crypto.NewKey()
 	level := 1
-	c.addBlock(rootKey, inviteeKey.PubKey, level)
+	c = c.Invite(rootKey, inviteeKey.PubKey, level)
 
 	// root, alice, bob setup
 	root.Key = crypto.NewKey()
@@ -74,7 +74,7 @@ func TestVerifyChain(t *testing.T) {
 
 	newInvitee := crypto.NewKey()
 	level := 3
-	c.addBlock(inviteeKey, newInvitee.PubKey, level)
+	c = c.Invite(inviteeKey, newInvitee.PubKey, level)
 
 	assert.Len(t, c.Blocks, 3)
 	assert.True(t, c.Verify())
@@ -101,7 +101,7 @@ func TestInvitation(t *testing.T) {
 
 // common root : my distance, her distance
 
-// common inviter
+// TestCommonInviter tests that Chain owners have one common inviter
 func TestCommonInviter(t *testing.T) {
 	// alice and bod have common root
 	cecilia := struct {