doc: add comments related to actor code review

chain/state/statetree.go

@@ -21,10 +21,12 @@ import (
 
 var log = logging.Logger("statetree")
 
+// Stores actors state by their ID.
 type StateTree struct {
 	root  *hamt.Node
 	Store cbor.IpldStore
 
+	// Maps ID addresses to actors.
 	actorcache map[address.Address]*types.Actor
 	snapshots  []cid.Cid
 }
@@ -70,6 +72,7 @@ func (st *StateTree) SetActor(addr address.Address, act *types.Actor) error {
 	return st.root.Set(context.TODO(), string(addr.Bytes()), act)
 }
 
+// `LookupID` gets the ID address of this actor's `addr` stored in the `InitActor`.
 func (st *StateTree) LookupID(addr address.Address) (address.Address, error) {
 	if addr.Protocol() == address.ID {
 		return addr, nil
@@ -92,11 +95,13 @@ func (st *StateTree) LookupID(addr address.Address) (address.Address, error) {
 	return a, nil
 }
 
+// GetActor returns the actor from any type of `addr` provided.
 func (st *StateTree) GetActor(addr address.Address) (*types.Actor, error) {
 	if addr == address.Undef {
 		return nil, fmt.Errorf("GetActor called on undefined address")
 	}
 
+	// Transform `addr` to its ID format.
 	iaddr, err := st.LookupID(addr)
 	if err != nil {
 		if xerrors.Is(err, init_.ErrAddressNotFound) {

chain/stmgr/stmgr.go

@@ -429,6 +429,8 @@ func (sm *StateManager) LoadActorStateRaw(ctx context.Context, a address.Address
 	return act, nil
 }
 
+// Similar to `vm.ResolveToKeyAddr` but does not allow `Actor` type of addresses. Uses the `TipSet` `ts`
+// to generate the VM state.
 func (sm *StateManager) ResolveToKeyAddress(ctx context.Context, addr address.Address, ts *types.TipSet) (address.Address, error) {
 	switch addr.Protocol() {
 	case address.BLS, address.SECP256K1:

chain/sync.go

@@ -789,6 +789,7 @@ func (syncer *Syncer) checkBlockMessages(ctx context.Context, b *types.FullBlock
 		}
 
 		if _, ok := nonces[m.From]; !ok {
+			// `GetActor` does not validate that this is an account actor.
 			act, err := st.GetActor(m.From)
 			if err != nil {
 				return xerrors.Errorf("failed to get actor: %w", err)
@@ -827,6 +828,8 @@ func (syncer *Syncer) checkBlockMessages(ctx context.Context, b *types.FullBlock
 			return xerrors.Errorf("block had invalid secpk message at index %d: %w", i, err)
 		}
 
+		// `From` being an account actor is only validated inside the `vm.ResolveToKeyAddr` call
+		// in `StateManager.ResolveToKeyAddress` here (and not in `checkMsg`).
 		kaddr, err := syncer.sm.ResolveToKeyAddress(ctx, m.Message.From, baseTs)
 		if err != nil {
 			return xerrors.Errorf("failed to resolve key addr: %w", err)

chain/types/actor.go

@@ -9,6 +9,7 @@ import (
 var ErrActorNotFound = init_.ErrAddressNotFound
 
 type Actor struct {
+	// Identifies the type of actor (string coded as a CID), see `chain/actors/actors.go`.
 	Code    cid.Cid
 	Head    cid.Cid
 	Nonce   uint64

chain/types/vmcontext.go

@@ -21,6 +21,7 @@ type Storage interface {
 
 type StateTree interface {
 	SetActor(addr address.Address, act *Actor) error
+	// GetActor returns the actor from any type of `addr` provided.
 	GetActor(addr address.Address) (*Actor, error)
 }
 

chain/vm/mkactor.go

@@ -26,6 +26,7 @@ func init() {
 
 var EmptyObjectCid cid.Cid
 
+// Creates account actors from only BLS/SECP256K1 addresses.
 func TryCreateAccountActor(st *state.StateTree, addr address.Address) (*types.Actor, aerrors.ActorError) {
 	act, err := makeActor(st, addr)
 	if err != nil {

chain/vm/vm.go

@@ -66,6 +66,7 @@ type ExecutionResult struct {
 
 // Send allows the current execution context to invoke methods on other actors in the system
 
+// ResolveToKeyAddr returns the public key type of address (`BLS`/`SECP256K1`) of an account actor identified by `addr`.
 func ResolveToKeyAddr(state types.StateTree, cst cbor.IpldStore, addr address.Address) (address.Address, aerrors.ActorError) {
 	if addr.Protocol() == address.BLS || addr.Protocol() == address.SECP256K1 {
 		return addr, nil