api: Add replaced msg note on StateSearchMsg

filecoin-project · Mar 18, 2021 · c5ba875 · c5ba875
1 parent 80ecec7
commit c5ba875
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 0 deletions.
diff --git a/api/api_full.go b/api/api_full.go
@@ -403,6 +403,20 @@ type FullNode interface {
 	// StateSectorPartition finds deadline/partition with the specified sector
 	StateSectorPartition(ctx context.Context, maddr address.Address, sectorNumber abi.SectorNumber, tok types.TipSetKey) (*miner.SectorLocation, error)
 	// StateSearchMsg searches for a message in the chain, and returns its receipt and the tipset where it was executed
+	//
+	// NOTE: If a replacing message is found on chain, this method will return
+	// a MsgLookup for the replacing message - the MsgLookup.Message will be a different
+	// CID than the one provided in the 'cid' param, MsgLookup.Receipt will contain the
+	// result of the execution of the replacing message.
+	//
+	// If the caller wants to ensure that exactly the requested message was executed,
+	// they MUST check that MsgLookup.Message is equal to the provided 'cid'.
+	// Without this check both the requested and original message may appear as
+	// successfully executed on-chain, which may look like a double-spend.
+	//
+	// A replacing message is a message with a different CID, any of Gas values, and
+	// different signature, but with all other parameters matching (source/destination,
+	// nonce, params, etc.)
 	StateSearchMsg(context.Context, cid.Cid) (*MsgLookup, error)
 	// StateSearchMsgLimited looks back up to limit epochs in the chain for a message, and returns its receipt and the tipset where it was executed
 	//

diff --git a/documentation/en/api-methods.md b/documentation/en/api-methods.md
@@ -3695,6 +3695,8 @@ for the replacing message - if the caller needs the receipt for exactly the
 requested message, use StateSearchMsg().Receipt, and check that MsgLookup.Message
 is matching the requseted CID
 
+DEPRECATED: Use StateSearchMsg, this method won't be supported in v1 API
+
 
 Perms: read
 
@@ -4551,6 +4553,20 @@ Response:
 ### StateSearchMsg
 StateSearchMsg searches for a message in the chain, and returns its receipt and the tipset where it was executed
 
+NOTE: If a replacing message is found on chain, this method will return
+a MsgLookup for the replacing message - the MsgLookup.Message will be a different
+CID than the one provided in the 'cid' param, MsgLookup.Receipt will contain the
+result of the execution of the replacing message.
+
+If the caller wants to ensure that exactly the requested message was executed,
+they MUST check that MsgLookup.Message is equal to the provided 'cid'.
+Without this check both the requested and original message may appear as
+successfully executed on-chain, which may look like a double-spend.
+
+A replacing message is a message with a different CID, any of Gas values, and
+different signature, but with all other parameters matching (source/destination,
+nonce, params, etc.)
+
 
 Perms: read