From 4fb4313ee7588309d3a1b5d37dd53141935ebb55 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Magiera?= Date: Thu, 18 Mar 2021 18:17:46 +0100 Subject: [PATCH 1/4] api: Document StateSearchMsg replaced message behavior --- api/api_full.go | 50 ++++++++++++++++++++++++++++++++- documentation/en/api-methods.md | 50 ++++++++++++++++++++++++++++++++- 2 files changed, 98 insertions(+), 2 deletions(-) diff --git a/api/api_full.go b/api/api_full.go index ca3a02c747e..4a31fe5373d 100644 --- a/api/api_full.go +++ b/api/api_full.go @@ -404,13 +404,55 @@ type FullNode interface { // StateSearchMsg searches for a message in the chain, and returns its receipt and the tipset where it was executed 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 + // + // 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.) StateSearchMsgLimited(ctx context.Context, msg cid.Cid, limit abi.ChainEpoch) (*MsgLookup, error) // StateWaitMsg looks back in the chain for a message. If not found, it blocks until the // message arrives on chain, and gets to the indicated confidence depth. + // + // 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.) StateWaitMsg(ctx context.Context, cid cid.Cid, confidence uint64) (*MsgLookup, error) // StateWaitMsgLimited looks back up to limit epochs in the chain for a message. // If not found, it blocks until the message arrives on chain, and gets to the // indicated confidence depth. + // + // 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.) StateWaitMsgLimited(ctx context.Context, cid cid.Cid, confidence uint64, limit abi.ChainEpoch) (*MsgLookup, error) // StateListMiners returns the addresses of every miner that has claimed power in the Power Actor StateListMiners(context.Context, types.TipSetKey) ([]address.Address, error) @@ -431,7 +473,13 @@ type FullNode interface { // StateChangedActors returns all the actors whose states change between the two given state CIDs // TODO: Should this take tipset keys instead? StateChangedActors(context.Context, cid.Cid, cid.Cid) (map[string]types.Actor, error) - // StateGetReceipt returns the message receipt for the given message + // StateGetReceipt returns the message receipt for the given message or for a + // matching gas-repriced replacing message + // + // NOTE: If the requested message was replaced, this method will return the receipt + // 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 StateGetReceipt(context.Context, cid.Cid, types.TipSetKey) (*types.MessageReceipt, error) // StateMinerSectorCount returns the number of sectors in a miner's sector set and proving set StateMinerSectorCount(context.Context, address.Address, types.TipSetKey) (MinerSectors, error) diff --git a/documentation/en/api-methods.md b/documentation/en/api-methods.md index 49afeeb1a0a..84ac018a88f 100644 --- a/documentation/en/api-methods.md +++ b/documentation/en/api-methods.md @@ -3686,7 +3686,13 @@ Response: ``` ### StateGetReceipt -StateGetReceipt returns the message receipt for the given message +StateGetReceipt returns the message receipt for the given message or for a +matching gas-repriced replacing message + +NOTE: If the requested message was replaced, this method will return the receipt +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 Perms: read @@ -4583,6 +4589,20 @@ Response: ### StateSearchMsgLimited StateSearchMsgLimited looks back up to limit epochs in the chain for a message, 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 @@ -4877,6 +4897,20 @@ Response: `"0"` StateWaitMsg looks back in the chain for a message. If not found, it blocks until the message arrives on chain, and gets to the indicated confidence depth. +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 @@ -4919,6 +4953,20 @@ StateWaitMsgLimited looks back up to limit epochs in the chain for a message. If not found, it blocks until the message arrives on chain, and gets to the indicated confidence depth. +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 From ce127ec5415ae7790354902f7a166770d997f695 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Magiera?= Date: Thu, 18 Mar 2021 18:17:46 +0100 Subject: [PATCH 2/4] api: Document StateSearchMsg replaced message behavior --- api/api_full.go | 52 ++++++++++++++++++++++++++++++++- documentation/en/api-methods.md | 50 ++++++++++++++++++++++++++++++- 2 files changed, 100 insertions(+), 2 deletions(-) diff --git a/api/api_full.go b/api/api_full.go index ca3a02c747e..25dd9652ae3 100644 --- a/api/api_full.go +++ b/api/api_full.go @@ -404,13 +404,55 @@ type FullNode interface { // StateSearchMsg searches for a message in the chain, and returns its receipt and the tipset where it was executed 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 + // + // 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.) StateSearchMsgLimited(ctx context.Context, msg cid.Cid, limit abi.ChainEpoch) (*MsgLookup, error) // StateWaitMsg looks back in the chain for a message. If not found, it blocks until the // message arrives on chain, and gets to the indicated confidence depth. + // + // 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.) StateWaitMsg(ctx context.Context, cid cid.Cid, confidence uint64) (*MsgLookup, error) // StateWaitMsgLimited looks back up to limit epochs in the chain for a message. // If not found, it blocks until the message arrives on chain, and gets to the // indicated confidence depth. + // + // 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.) StateWaitMsgLimited(ctx context.Context, cid cid.Cid, confidence uint64, limit abi.ChainEpoch) (*MsgLookup, error) // StateListMiners returns the addresses of every miner that has claimed power in the Power Actor StateListMiners(context.Context, types.TipSetKey) ([]address.Address, error) @@ -431,7 +473,15 @@ type FullNode interface { // StateChangedActors returns all the actors whose states change between the two given state CIDs // TODO: Should this take tipset keys instead? StateChangedActors(context.Context, cid.Cid, cid.Cid) (map[string]types.Actor, error) - // StateGetReceipt returns the message receipt for the given message + // StateGetReceipt returns the message receipt for the given message or for a + // matching gas-repriced replacing message + // + // NOTE: If the requested message was replaced, this method will return the receipt + // 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 StateGetReceipt(context.Context, cid.Cid, types.TipSetKey) (*types.MessageReceipt, error) // StateMinerSectorCount returns the number of sectors in a miner's sector set and proving set StateMinerSectorCount(context.Context, address.Address, types.TipSetKey) (MinerSectors, error) diff --git a/documentation/en/api-methods.md b/documentation/en/api-methods.md index 49afeeb1a0a..84ac018a88f 100644 --- a/documentation/en/api-methods.md +++ b/documentation/en/api-methods.md @@ -3686,7 +3686,13 @@ Response: ``` ### StateGetReceipt -StateGetReceipt returns the message receipt for the given message +StateGetReceipt returns the message receipt for the given message or for a +matching gas-repriced replacing message + +NOTE: If the requested message was replaced, this method will return the receipt +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 Perms: read @@ -4583,6 +4589,20 @@ Response: ### StateSearchMsgLimited StateSearchMsgLimited looks back up to limit epochs in the chain for a message, 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 @@ -4877,6 +4897,20 @@ Response: `"0"` StateWaitMsg looks back in the chain for a message. If not found, it blocks until the message arrives on chain, and gets to the indicated confidence depth. +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 @@ -4919,6 +4953,20 @@ StateWaitMsgLimited looks back up to limit epochs in the chain for a message. If not found, it blocks until the message arrives on chain, and gets to the indicated confidence depth. +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 From a0a4d3c462f56e787c81a072e25580faef4ae71e Mon Sep 17 00:00:00 2001 From: Aayush Rajasekaran Date: Thu, 18 Mar 2021 14:35:32 -0400 Subject: [PATCH 3/4] Add a note to ChainGetParentReceipts --- api/api_full.go | 3 ++- documentation/en/api-methods.md | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/api/api_full.go b/api/api_full.go index 4a31fe5373d..2ce7edb9bb3 100644 --- a/api/api_full.go +++ b/api/api_full.go @@ -70,7 +70,8 @@ type FullNode interface { ChainGetBlockMessages(ctx context.Context, blockCid cid.Cid) (*BlockMessages, error) // ChainGetParentReceipts returns receipts for messages in parent tipset of - // the specified block. + // the specified block. The receipts in the list returned is one-to-one with the + // messages returned by a call to ChainGetParentMessages with the same blockCid. ChainGetParentReceipts(ctx context.Context, blockCid cid.Cid) ([]*types.MessageReceipt, error) // ChainGetParentMessages returns messages stored in parent tipset of the diff --git a/documentation/en/api-methods.md b/documentation/en/api-methods.md index 84ac018a88f..79aec713d94 100644 --- a/documentation/en/api-methods.md +++ b/documentation/en/api-methods.md @@ -540,7 +540,8 @@ Response: `null` ### ChainGetParentReceipts ChainGetParentReceipts returns receipts for messages in parent tipset of -the specified block. +the specified block. The receipts in the list returned is one-to-one with the +messages returned by a call to ChainGetParentMessages with the same blockCid. Perms: read From c5ba875fe3efcf67fae3fed4b83cf046c77d9d66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Magiera?= Date: Thu, 18 Mar 2021 19:46:26 +0100 Subject: [PATCH 4/4] api: Add replaced msg note on StateSearchMsg --- api/api_full.go | 14 ++++++++++++++ documentation/en/api-methods.md | 16 ++++++++++++++++ 2 files changed, 30 insertions(+) diff --git a/api/api_full.go b/api/api_full.go index 231586f543b..cbd23564616 100644 --- 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 index 79aec713d94..34b94ff4403 100644 --- 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