CR doc changes and rename fromCache => cacheOnly

4 files changed, 34 insertions, 28 deletions

diff --git a/ledger/internal/appcow_test.go b/ledger/internal/appcow_test.go
index 54101952d..cc23663b2 100644
--- a/ledger/internal/appcow_test.go
+++ b/ledger/internal/appcow_test.go
@@ -47,19 +47,19 @@ func (ml *emptyLedger) lookup(addr basics.Address) (ledgercore.AccountData, erro
 	return ledgercore.AccountData{}, nil
 }
 
-func (ml *emptyLedger) lookupAppParams(addr basics.Address, aidx basics.AppIndex, fromCache bool) (ledgercore.AppParamsDelta, bool, error) {
+func (ml *emptyLedger) lookupAppParams(addr basics.Address, aidx basics.AppIndex, cacheOnly bool) (ledgercore.AppParamsDelta, bool, error) {
 	return ledgercore.AppParamsDelta{}, true, nil
 }
 
-func (ml *emptyLedger) lookupAssetParams(addr basics.Address, aidx basics.AssetIndex, fromCache bool) (ledgercore.AssetParamsDelta, bool, error) {
+func (ml *emptyLedger) lookupAssetParams(addr basics.Address, aidx basics.AssetIndex, cacheOnly bool) (ledgercore.AssetParamsDelta, bool, error) {
 	return ledgercore.AssetParamsDelta{}, true, nil
 }
 
-func (ml *emptyLedger) lookupAppLocalState(addr basics.Address, aidx basics.AppIndex, fromCache bool) (ledgercore.AppLocalStateDelta, bool, error) {
+func (ml *emptyLedger) lookupAppLocalState(addr basics.Address, aidx basics.AppIndex, cacheOnly bool) (ledgercore.AppLocalStateDelta, bool, error) {
 	return ledgercore.AppLocalStateDelta{}, true, nil
 }
 
-func (ml *emptyLedger) lookupAssetHolding(addr basics.Address, aidx basics.AssetIndex, fromCache bool) (ledgercore.AssetHoldingDelta, bool, error) {
+func (ml *emptyLedger) lookupAssetHolding(addr basics.Address, aidx basics.AssetIndex, cacheOnly bool) (ledgercore.AssetHoldingDelta, bool, error) {
 	return ledgercore.AssetHoldingDelta{}, true, nil
 }
 
diff --git a/ledger/internal/cow.go b/ledger/internal/cow.go
index 2b437ffc8..f371bade7 100644
--- a/ledger/internal/cow.go
+++ b/ledger/internal/cow.go
@@ -38,11 +38,17 @@ import (
 //                  ||     ||
 
 type roundCowParent interface {
+	// lookup retrieves data about an address, eventually querying the ledger if the address was not found in cache.
 	lookup(basics.Address) (ledgercore.AccountData, error)
-	lookupAppParams(addr basics.Address, aidx basics.AppIndex, fromCache bool) (ledgercore.AppParamsDelta, bool, error)
-	lookupAssetParams(addr basics.Address, aidx basics.AssetIndex, fromCache bool) (ledgercore.AssetParamsDelta, bool, error)
-	lookupAppLocalState(addr basics.Address, aidx basics.AppIndex, fromCache bool) (ledgercore.AppLocalStateDelta, bool, error)
-	lookupAssetHolding(addr basics.Address, aidx basics.AssetIndex, fromCache bool) (ledgercore.AssetHoldingDelta, bool, error)
+
+	// lookupAppParams, lookupAssetParams, lookupAppLocalState, and lookupAssetHolding retrieve data for a given address and ID.
+	// If cacheOnly is set, the ledger DB will not be queried, and only the cache will be consulted.
+	// This is used when we know a given value is already in cache (from a previous query for that same address and ID),
+	// and would rather have an error returned if that assumption is wrong, rather than hit the ledger.
+	lookupAppParams(addr basics.Address, aidx basics.AppIndex, cacheOnly bool) (ledgercore.AppParamsDelta, bool, error)
+	lookupAssetParams(addr basics.Address, aidx basics.AssetIndex, cacheOnly bool) (ledgercore.AssetParamsDelta, bool, error)
+	lookupAppLocalState(addr basics.Address, aidx basics.AppIndex, cacheOnly bool) (ledgercore.AppLocalStateDelta, bool, error)
+	lookupAssetHolding(addr basics.Address, aidx basics.AssetIndex, cacheOnly bool) (ledgercore.AssetHoldingDelta, bool, error)
 
 	checkDup(basics.Round, basics.Round, transactions.Txid, ledgercore.Txlease) error
 	txnCounter() uint64
@@ -154,40 +160,40 @@ func (cb *roundCowState) lookup(addr basics.Address) (data ledgercore.AccountDat
 	return cb.lookupParent.lookup(addr)
 }
 
-func (cb *roundCowState) lookupAppParams(addr basics.Address, aidx basics.AppIndex, fromCache bool) (ledgercore.AppParamsDelta, bool, error) {
+func (cb *roundCowState) lookupAppParams(addr basics.Address, aidx basics.AppIndex, cacheOnly bool) (ledgercore.AppParamsDelta, bool, error) {
 	params, ok := cb.mods.Accts.GetAppParams(addr, aidx)
 	if ok {
 		return params, ok, nil
 	}
 
-	return cb.lookupParent.lookupAppParams(addr, aidx, fromCache)
+	return cb.lookupParent.lookupAppParams(addr, aidx, cacheOnly)
 }
 
-func (cb *roundCowState) lookupAssetParams(addr basics.Address, aidx basics.AssetIndex, fromCache bool) (ledgercore.AssetParamsDelta, bool, error) {
+func (cb *roundCowState) lookupAssetParams(addr basics.Address, aidx basics.AssetIndex, cacheOnly bool) (ledgercore.AssetParamsDelta, bool, error) {
 	params, ok := cb.mods.Accts.GetAssetParams(addr, aidx)
 	if ok {
 		return params, ok, nil
 	}
 
-	return cb.lookupParent.lookupAssetParams(addr, aidx, fromCache)
+	return cb.lookupParent.lookupAssetParams(addr, aidx, cacheOnly)
 }
 
-func (cb *roundCowState) lookupAppLocalState(addr basics.Address, aidx basics.AppIndex, fromCache bool) (ledgercore.AppLocalStateDelta, bool, error) {
+func (cb *roundCowState) lookupAppLocalState(addr basics.Address, aidx basics.AppIndex, cacheOnly bool) (ledgercore.AppLocalStateDelta, bool, error) {
 	state, ok := cb.mods.Accts.GetAppLocalState(addr, aidx)
 	if ok {
 		return state, ok, nil
 	}
 
-	return cb.lookupParent.lookupAppLocalState(addr, aidx, fromCache)
+	return cb.lookupParent.lookupAppLocalState(addr, aidx, cacheOnly)
 }
 
-func (cb *roundCowState) lookupAssetHolding(addr basics.Address, aidx basics.AssetIndex, fromCache bool) (ledgercore.AssetHoldingDelta, bool, error) {
+func (cb *roundCowState) lookupAssetHolding(addr basics.Address, aidx basics.AssetIndex, cacheOnly bool) (ledgercore.AssetHoldingDelta, bool, error) {
 	holding, ok := cb.mods.Accts.GetAssetHolding(addr, aidx)
 	if ok {
 		return holding, ok, nil
 	}
 
-	return cb.lookupParent.lookupAssetHolding(addr, aidx, fromCache)
+	return cb.lookupParent.lookupAssetHolding(addr, aidx, cacheOnly)
 }
 
 func (cb *roundCowState) checkDup(firstValid, lastValid basics.Round, txid transactions.Txid, txl ledgercore.Txlease) error {
diff --git a/ledger/internal/cow_test.go b/ledger/internal/cow_test.go
index deb49d787..9c5ffcafb 100644
--- a/ledger/internal/cow_test.go
+++ b/ledger/internal/cow_test.go
@@ -41,22 +41,22 @@ func (ml *mockLedger) lookup(addr basics.Address) (ledgercore.AccountData, error
 	return ledgercore.ToAccountData(ml.balanceMap[addr]), nil
 }
 
-func (ml *mockLedger) lookupAppParams(addr basics.Address, aidx basics.AppIndex, fromCache bool) (ledgercore.AppParamsDelta, bool, error) {
+func (ml *mockLedger) lookupAppParams(addr basics.Address, aidx basics.AppIndex, cacheOnly bool) (ledgercore.AppParamsDelta, bool, error) {
 	params, ok := ml.balanceMap[addr].AppParams[aidx]
 	return ledgercore.AppParamsDelta{Params: &params}, ok, nil // XXX make a copy?
 }
 
-func (ml *mockLedger) lookupAssetParams(addr basics.Address, aidx basics.AssetIndex, fromCache bool) (ledgercore.AssetParamsDelta, bool, error) {
+func (ml *mockLedger) lookupAssetParams(addr basics.Address, aidx basics.AssetIndex, cacheOnly bool) (ledgercore.AssetParamsDelta, bool, error) {
 	params, ok := ml.balanceMap[addr].AssetParams[aidx]
 	return ledgercore.AssetParamsDelta{Params: &params}, ok, nil
 }
 
-func (ml *mockLedger) lookupAppLocalState(addr basics.Address, aidx basics.AppIndex, fromCache bool) (ledgercore.AppLocalStateDelta, bool, error) {
+func (ml *mockLedger) lookupAppLocalState(addr basics.Address, aidx basics.AppIndex, cacheOnly bool) (ledgercore.AppLocalStateDelta, bool, error) {
 	params, ok := ml.balanceMap[addr].AppLocalStates[aidx]
 	return ledgercore.AppLocalStateDelta{LocalState: &params}, ok, nil
 }
 
-func (ml *mockLedger) lookupAssetHolding(addr basics.Address, aidx basics.AssetIndex, fromCache bool) (ledgercore.AssetHoldingDelta, bool, error) {
+func (ml *mockLedger) lookupAssetHolding(addr basics.Address, aidx basics.AssetIndex, cacheOnly bool) (ledgercore.AssetHoldingDelta, bool, error) {
 	params, ok := ml.balanceMap[addr].Assets[aidx]
 	return ledgercore.AssetHoldingDelta{Holding: &params}, ok, nil
 }
diff --git a/ledger/internal/eval.go b/ledger/internal/eval.go
index 51a97a9aa..e8fb7b85c 100644
--- a/ledger/internal/eval.go
+++ b/ledger/internal/eval.go
@@ -213,7 +213,7 @@ func (x *roundCowBase) updateAppResourceCache(aa ledgercore.AccountApp, r ledger
 	}
 }
 
-func (x *roundCowBase) lookupAppParams(addr basics.Address, aidx basics.AppIndex, fromCache bool) (ledgercore.AppParamsDelta, bool, error) {
+func (x *roundCowBase) lookupAppParams(addr basics.Address, aidx basics.AppIndex, cacheOnly bool) (ledgercore.AppParamsDelta, bool, error) {
 	aa := ledgercore.AccountApp{Address: addr, App: aidx}
 	if result, ok := x.appParams[aa]; ok {
 		if !result.exists {
@@ -222,7 +222,7 @@ func (x *roundCowBase) lookupAppParams(addr basics.Address, aidx basics.AppIndex
 		return ledgercore.AppParamsDelta{Params: &result.value}, true, nil
 	}
 
-	if fromCache { // hasn't been found yet; we were asked not to query DB
+	if cacheOnly { // hasn't been found yet; we were asked not to query DB
 		return ledgercore.AppParamsDelta{}, false, fmt.Errorf("lookupAppParams couldn't find addr %s aidx %d in cache: %w", addr.String(), aidx, ErrNotInCowCache)
 	}
 
@@ -239,7 +239,7 @@ func (x *roundCowBase) lookupAppParams(addr basics.Address, aidx basics.AppIndex
 	return ledgercore.AppParamsDelta{Params: resourceData.AppParams}, true, nil
 }
 
-func (x *roundCowBase) lookupAssetParams(addr basics.Address, aidx basics.AssetIndex, fromCache bool) (ledgercore.AssetParamsDelta, bool, error) {
+func (x *roundCowBase) lookupAssetParams(addr basics.Address, aidx basics.AssetIndex, cacheOnly bool) (ledgercore.AssetParamsDelta, bool, error) {
 	aa := ledgercore.AccountAsset{Address: addr, Asset: aidx}
 	if result, ok := x.assetParams[aa]; ok {
 		if !result.exists {
@@ -248,7 +248,7 @@ func (x *roundCowBase) lookupAssetParams(addr basics.Address, aidx basics.AssetI
 		return ledgercore.AssetParamsDelta{Params: &result.value}, true, nil
 	}
 
-	if fromCache { // hasn't been found yet; we were asked not to query DB
+	if cacheOnly { // hasn't been found yet; we were asked not to query DB
 		return ledgercore.AssetParamsDelta{}, false, fmt.Errorf("lookupAssetParams couldn't find addr %s aidx %d in cache: %w", addr.String(), aidx, ErrNotInCowCache)
 	}
 
@@ -265,7 +265,7 @@ func (x *roundCowBase) lookupAssetParams(addr basics.Address, aidx basics.AssetI
 	return ledgercore.AssetParamsDelta{Params: resourceData.AssetParams}, true, nil
 }
 
-func (x *roundCowBase) lookupAppLocalState(addr basics.Address, aidx basics.AppIndex, fromCache bool) (ledgercore.AppLocalStateDelta, bool, error) {
+func (x *roundCowBase) lookupAppLocalState(addr basics.Address, aidx basics.AppIndex, cacheOnly bool) (ledgercore.AppLocalStateDelta, bool, error) {
 	aa := ledgercore.AccountApp{Address: addr, App: aidx}
 	if result, ok := x.appLocalStates[aa]; ok {
 		if !result.exists {
@@ -274,7 +274,7 @@ func (x *roundCowBase) lookupAppLocalState(addr basics.Address, aidx basics.AppI
 		return ledgercore.AppLocalStateDelta{LocalState: &result.value}, true, nil
 	}
 
-	if fromCache { // hasn't been found yet; we were asked not to query DB
+	if cacheOnly { // hasn't been found yet; we were asked not to query DB
 		return ledgercore.AppLocalStateDelta{}, false, fmt.Errorf("lookupAppLocalState couldn't find addr %s aidx %d in cache: %w", addr.String(), aidx, ErrNotInCowCache)
 	}
 
@@ -291,7 +291,7 @@ func (x *roundCowBase) lookupAppLocalState(addr basics.Address, aidx basics.AppI
 	return ledgercore.AppLocalStateDelta{LocalState: resourceData.AppLocalState}, true, nil
 }
 
-func (x *roundCowBase) lookupAssetHolding(addr basics.Address, aidx basics.AssetIndex, fromCache bool) (ledgercore.AssetHoldingDelta, bool, error) {
+func (x *roundCowBase) lookupAssetHolding(addr basics.Address, aidx basics.AssetIndex, cacheOnly bool) (ledgercore.AssetHoldingDelta, bool, error) {
 	aa := ledgercore.AccountAsset{Address: addr, Asset: aidx}
 	if result, ok := x.assets[aa]; ok {
 		if !result.exists {
@@ -300,7 +300,7 @@ func (x *roundCowBase) lookupAssetHolding(addr basics.Address, aidx basics.Asset
 		return ledgercore.AssetHoldingDelta{Holding: &result.value}, true, nil
 	}
 
-	if fromCache { // hasn't been found yet; we were asked not to query DB
+	if cacheOnly { // hasn't been found yet; we were asked not to query DB
 		return ledgercore.AssetHoldingDelta{}, false, fmt.Errorf("lookupAssetHolding couldn't find addr %s aidx %d in cache: %w", addr.String(), aidx, ErrNotInCowCache)
 	}