From 605e9bbbd7bb3a53d495d515cce3a38726946b94 Mon Sep 17 00:00:00 2001 From: Aayush Rajasekaran Date: Tue, 30 Jun 2020 18:28:49 -0400 Subject: [PATCH] Add docs comments to API --- api/api_full.go | 146 ++++++++++++++++++++++++++++++++----------- chain/stmgr/utils.go | 2 +- 2 files changed, 112 insertions(+), 36 deletions(-) diff --git a/api/api_full.go b/api/api_full.go index d5a256bd6..784651466 100644 --- a/api/api_full.go +++ b/api/api_full.go @@ -30,58 +30,59 @@ type FullNode interface { // MethodGroup: Chain // The Chain method group contains methods for interacting with the - // blockchain, but that do not require any form of state computation + // blockchain, but that do not require any form of state computation. - // ChainNotify returns channel with chain head updates - // First message is guaranteed to be of len == 1, and type == 'current' + // ChainNotify returns channel with chain head updates. + // First message is guaranteed to be of len == 1, and type == 'current'. ChainNotify(context.Context) (<-chan []*HeadChange, error) - // ChainHead returns the current head of the chain + // ChainHead returns the current head of the chain. ChainHead(context.Context) (*types.TipSet, error) - // ChainGetRandomness is used to sample the chain for randomness + // ChainGetRandomness is used to sample the chain for randomness. ChainGetRandomness(ctx context.Context, tsk types.TipSetKey, personalization crypto.DomainSeparationTag, randEpoch abi.ChainEpoch, entropy []byte) (abi.Randomness, error) - // ChainGetBlock returns the block specified by the given CID + // ChainGetBlock returns the block specified by the given CID. ChainGetBlock(context.Context, cid.Cid) (*types.BlockHeader, error) + // ChainGetTipSet returns the tipset specified by the given TipSetKey. ChainGetTipSet(context.Context, types.TipSetKey) (*types.TipSet, error) - // ChainGetBlockMessages returns messages stored in the specified block + // ChainGetBlockMessages returns messages stored in the specified block. ChainGetBlockMessages(ctx context.Context, blockCid cid.Cid) (*BlockMessages, error) // ChainGetParentReceipts returns receipts for messages in parent tipset of - // the specified block + // the specified block. ChainGetParentReceipts(ctx context.Context, blockCid cid.Cid) ([]*types.MessageReceipt, error) // ChainGetParentReceipts returns messages stored in parent tipset of the - // specified block + // specified block. ChainGetParentMessages(ctx context.Context, blockCid cid.Cid) ([]Message, error) // ChainGetTipSetByHeight looks back for a tipset at the specified epoch. // If there are no blocks at the specified epoch, a tipset at higher epoch - // will be returned + // will be returned. ChainGetTipSetByHeight(context.Context, abi.ChainEpoch, types.TipSetKey) (*types.TipSet, error) // ChainReadObj reads ipld nodes referenced by the specified CID from chain - // blockstore and returns raw bytes + // blockstore and returns raw bytes. ChainReadObj(context.Context, cid.Cid) ([]byte, error) - // ChainHasObj checks if a given CID exists in the chain blockstore + // ChainHasObj checks if a given CID exists in the chain blockstore. ChainHasObj(context.Context, cid.Cid) (bool, error) ChainStatObj(context.Context, cid.Cid, cid.Cid) (ObjStat, error) - // ChainSetHead forcefully sets current chain head. Use with caution + // ChainSetHead forcefully sets current chain head. Use with caution. ChainSetHead(context.Context, types.TipSetKey) error - // ChainGetGenesis returns the genesis tipset + // ChainGetGenesis returns the genesis tipset. ChainGetGenesis(context.Context) (*types.TipSet, error) - // ChainTipSetWeight computes weight for the specified tipset + // ChainTipSetWeight computes weight for the specified tipset. ChainTipSetWeight(context.Context, types.TipSetKey) (types.BigInt, error) ChainGetNode(ctx context.Context, p string) (*IpldObject, error) // ChainGetMessage reads a message referenced by the specified CID from the - // chain blockstore + // chain blockstore. ChainGetMessage(context.Context, cid.Cid) (*types.Message, error) // ChainGetPath returns a set of revert/apply operations needed to get from @@ -99,17 +100,17 @@ type FullNode interface { // Would return `[revert(tBA), apply(tAB), apply(tAA)]` ChainGetPath(ctx context.Context, from types.TipSetKey, to types.TipSetKey) ([]*HeadChange, error) - // ChainExport returns a stream of bytes with CAR dump of chain data + // ChainExport returns a stream of bytes with CAR dump of chain data. ChainExport(context.Context, types.TipSetKey) (<-chan []byte, error) // MethodGroup: Sync // The Sync method group contains methods for interacting with and - // observing the lotus sync service + // observing the lotus sync service. - // SyncState returns the current status of the lotus sync system + // SyncState returns the current status of the lotus sync system. SyncState(context.Context) (*SyncState, error) - // SyncSubmitBlock can be used to submit a newly created block to the + // SyncSubmitBlock can be used to submit a newly created block to the. // network through this node SyncSubmitBlock(ctx context.Context, blk *types.BlockMsg) error @@ -118,34 +119,34 @@ type FullNode interface { SyncIncomingBlocks(ctx context.Context) (<-chan *types.BlockHeader, error) // SyncMarkBad marks a blocks as bad, meaning that it won't ever by synced. - // Use with extreme caution + // Use with extreme caution. SyncMarkBad(ctx context.Context, bcid cid.Cid) error // SyncCheckBad checks if a block was marked as bad, and if it was, returns - // the reason + // the reason. SyncCheckBad(ctx context.Context, bcid cid.Cid) (string, error) // MethodGroup: Mpool // The Mpool methods are for interacting with the message pool. The message pool // manages all incoming and outgoing 'messages' going over the network. - // MpoolPending returns pending mempool messages + // MpoolPending returns pending mempool messages. MpoolPending(context.Context, types.TipSetKey) ([]*types.SignedMessage, error) - // MpoolPush pushes a signed message to mempool + // MpoolPush pushes a signed message to mempool. MpoolPush(context.Context, *types.SignedMessage) (cid.Cid, error) // MpoolPushMessage atomically assigns a nonce, signs, and pushes a message - // to mempool + // to mempool. MpoolPushMessage(context.Context, *types.Message) (*types.SignedMessage, error) // MpoolGetNonce gets next nonce for the specified sender. - // Note that this method may not be atomic. Use MpoolPushMessage instead + // Note that this method may not be atomic. Use MpoolPushMessage instead. MpoolGetNonce(context.Context, address.Address) (uint64, error) MpoolSub(context.Context) (<-chan MpoolUpdate, error) // MpoolEstimateGasPrice estimates what gas price should be used for a - // message to have high likelihood of inclusion in `nblocksincl` epochs + // message to have high likelihood of inclusion in `nblocksincl` epochs. MpoolEstimateGasPrice(ctx context.Context, nblocksincl uint64, sender address.Address, gaslimit int64, tsk types.TipSetKey) (types.BigInt, error) // MethodGroup: Miner @@ -157,17 +158,30 @@ type FullNode interface { // MethodGroup: Wallet + // WalletNew creates a new address in the wallet with the given sigType. WalletNew(context.Context, crypto.SigType) (address.Address, error) + // WalletHas indicates whether the given address is in the wallet. WalletHas(context.Context, address.Address) (bool, error) + // WalletHas indicates whether the given address is in the wallet. WalletList(context.Context) ([]address.Address, error) + // WalletBalance returns the balance of the given address at the current head of the chain. WalletBalance(context.Context, address.Address) (types.BigInt, error) + // WalletSign signs the given bytes using the given address. WalletSign(context.Context, address.Address, []byte) (*crypto.Signature, error) + // WalletSignMessage signs the given message using the given address. WalletSignMessage(context.Context, address.Address, *types.Message) (*types.SignedMessage, error) + // WalletVerify takes an address, a signature, and some bytes, and indicates whether the signature is valid. + // The address does not have to be in the wallet. WalletVerify(context.Context, address.Address, []byte, *crypto.Signature) bool + // WalletDefaultAddress returns the address marked as default in the wallet. WalletDefaultAddress(context.Context) (address.Address, error) + // WalletSetDefault marks the given address as as the default one. WalletSetDefault(context.Context, address.Address) error + // WalletExport returns the private key of an address in the wallet. WalletExport(context.Context, address.Address) (*types.KeyInfo, error) + // WalletImport receives a KeyInfo, which includes a private key, and imports it into the wallet. WalletImport(context.Context, *types.KeyInfo) (address.Address, error) + // WalletDelete deletes an address from the wallet. WalletDelete(context.Context, address.Address) error // Other @@ -176,19 +190,27 @@ type FullNode interface { // The Client methods all have to do with interacting with the storage and // retrieval markets as a client - // ClientImport imports file under the specified path into filestore + // ClientImport imports file under the specified path into filestore. ClientImport(ctx context.Context, ref FileRef) (cid.Cid, error) - // ClientStartDeal proposes a deal with a miner + // ClientStartDeal proposes a deal with a miner. ClientStartDeal(ctx context.Context, params *StartDealParams) (*cid.Cid, error) - // ClientGetDeal info returns the latest information about a given deal + // ClientGetDealInfo returns the latest information about a given deal. ClientGetDealInfo(context.Context, cid.Cid) (*DealInfo, error) + // ClientListDeals returns information about the deals made by the local client. ClientListDeals(ctx context.Context) ([]DealInfo, error) + // ClientHasLocal indicates whether a certain CID is locally stored. ClientHasLocal(ctx context.Context, root cid.Cid) (bool, error) + // ClientFindData identifies peers that have a certain file, and returns QueryOffers (one per peer). ClientFindData(ctx context.Context, root cid.Cid) ([]QueryOffer, error) + // ClientMinerQueryOffer returns a QueryOffer for the specific miner and file. ClientMinerQueryOffer(ctx context.Context, root cid.Cid, miner address.Address) (QueryOffer, error) + // ClientRetrieve initiates the retrieval of a file, as specified in the order. ClientRetrieve(ctx context.Context, order RetrievalOrder, ref *FileRef) error + // ClientQueryAsk returns a signed StorageAsk from the specified miner. ClientQueryAsk(ctx context.Context, p peer.ID, miner address.Address) (*storagemarket.SignedStorageAsk, error) + // ClientCalcCommP calculates the CommP for a specified file, based on the sector size of the provided miner. ClientCalcCommP(ctx context.Context, inpath string, miner address.Address) (*CommPRet, error) + // ClientGenCar generates a CAR file for the specified file. ClientGenCar(ctx context.Context, ref FileRef, outpath string) error // ClientUnimport removes references to the specified file from filestore @@ -200,54 +222,107 @@ type FullNode interface { //ClientListAsks() []Ask // MethodGroup: State - // The State methods are used to query, inspect, and interact with chain state + // The State methods are used to query, inspect, and interact with chain state. + // All methods take a TipSetKey as a parameter. The state looked up is the state at that tipset. + // A nil TipSetKey can be provided as a param, this will cause the heaviest tipset in the chain to be used. - // if tipset is nil, we'll use heaviest + // StateCall runs the given message and returns its result without any persisted changes. StateCall(context.Context, *types.Message, types.TipSetKey) (*InvocResult, error) + // StateReplay returns the result of executing the indicated message, assuming it was executed in the indicated tipset. StateReplay(context.Context, types.TipSetKey, cid.Cid) (*InvocResult, error) + // StateGetActor returns the indicated actor's nonce and balance. StateGetActor(ctx context.Context, actor address.Address, tsk types.TipSetKey) (*types.Actor, error) + // StateReadState returns the indicated actor's state. StateReadState(ctx context.Context, actor address.Address, tsk types.TipSetKey) (*ActorState, error) + // StateListMessages looks back and returns all messages with a matching to or from address, stopping at the given height. StateListMessages(ctx context.Context, match *types.Message, tsk types.TipSetKey, toht abi.ChainEpoch) ([]cid.Cid, error) + // StateNetworkName returns the name of the network the node is synced to StateNetworkName(context.Context) (dtypes.NetworkName, error) + // StateMinerSectors returns info about the given miner's sectors. If the filter bitfield is nil, all sectors are included. + // If the filterOut boolean is set to true, any sectors in the filter are excluded. + // If false, only those sectors in the filter are included. StateMinerSectors(context.Context, address.Address, *abi.BitField, bool, types.TipSetKey) ([]*ChainSectorInfo, error) + // StateMinerProvingSet returns info about those sectors that a given miner is actively proving. StateMinerProvingSet(context.Context, address.Address, types.TipSetKey) ([]*ChainSectorInfo, error) + // StateMinerProvingDeadline calculates the deadline at some epoch for a proving period + // and returns the deadline-related calculations. StateMinerProvingDeadline(context.Context, address.Address, types.TipSetKey) (*miner.DeadlineInfo, error) + // StateMinerPower returns the power of the indicated miner StateMinerPower(context.Context, address.Address, types.TipSetKey) (*MinerPower, error) + // StateMinerInfo returns info about the indicated miner StateMinerInfo(context.Context, address.Address, types.TipSetKey) (MinerInfo, error) + // StateMinerDeadlines returns all the proving deadlines for the given miner StateMinerDeadlines(context.Context, address.Address, types.TipSetKey) (*miner.Deadlines, error) + // StateMinerFaults returns a bitfield indicating the faulty sectors of the given miner StateMinerFaults(context.Context, address.Address, types.TipSetKey) (*abi.BitField, error) - // Returns all non-expired Faults that occur within lookback epochs of the given tipset + // StateAllMinerFaults returns all non-expired Faults that occur within lookback epochs of the given tipset StateAllMinerFaults(ctx context.Context, lookback abi.ChainEpoch, ts types.TipSetKey) ([]*Fault, error) + // StateMinerRecoveries returns a bitfield indicating the recovering sectors of the given miner StateMinerRecoveries(context.Context, address.Address, types.TipSetKey) (*abi.BitField, error) + // StateMinerInitialPledgeCollateral returns the initial pledge collateral for the specified miner's sector StateMinerInitialPledgeCollateral(context.Context, address.Address, abi.SectorNumber, types.TipSetKey) (types.BigInt, error) + // StateMinerAvailableBalance returns the portion of a miner's balance that can be withdrawn or spent StateMinerAvailableBalance(context.Context, address.Address, types.TipSetKey) (types.BigInt, error) + // StateSectorPreCommitInfo returns the PreCommit info for the specified miner's sector StateSectorPreCommitInfo(context.Context, address.Address, abi.SectorNumber, types.TipSetKey) (miner.SectorPreCommitOnChainInfo, error) + // StateSectorGetInfo returns the on-chain info for the specified miner's sector StateSectorGetInfo(context.Context, address.Address, abi.SectorNumber, types.TipSetKey) (*miner.SectorOnChainInfo, error) StatePledgeCollateral(context.Context, types.TipSetKey) (types.BigInt, error) - StateWaitMsg(ctx context.Context, cid cid.Cid, confidence uint64) (*MsgLookup, error) + // 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) + // 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. + StateWaitMsg(ctx context.Context, cid cid.Cid, confidence uint64) (*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) + // StateListActors returns the addresses of every actor in the state StateListActors(context.Context, types.TipSetKey) ([]address.Address, error) + // StateMarketBalance looks up the Escrow and Locked balances of the given address in the Storage Market StateMarketBalance(context.Context, address.Address, types.TipSetKey) (MarketBalance, error) + // StateMarketParticipants returns the Escrow and Locked balances of every participant in the Storage Market StateMarketParticipants(context.Context, types.TipSetKey) (map[string]MarketBalance, error) + // StateMarketDeals returns information about every deal in the Storage Market StateMarketDeals(context.Context, types.TipSetKey) (map[string]MarketDeal, error) + // StateMarketStorageDeal returns information about the indicated deal StateMarketStorageDeal(context.Context, abi.DealID, types.TipSetKey) (*MarketDeal, error) + // StateLookupID retrieves the ID address of the given address StateLookupID(context.Context, address.Address, types.TipSetKey) (address.Address, error) + // StateAccountKey returns the public key address of the given ID address StateAccountKey(context.Context, address.Address, types.TipSetKey) (address.Address, error) + // 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(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) + // StateCompute is a flexible command that applies the given messages on the given tipset. + // The messages are run as though the VM were at the provided height. StateCompute(context.Context, abi.ChainEpoch, []*types.Message, types.TipSetKey) (*ComputeStateOutput, error) // MethodGroup: Msig // The Msig methods are used to interact with multisig wallets on the // filecoin network + // MsigGetAvailableBalance returns the portion of a multisig's balance that can be withdrawn or spent MsigGetAvailableBalance(context.Context, address.Address, types.TipSetKey) (types.BigInt, error) + // MsigGetAvailableBalance creates a multisig wallet + // It takes the following params: , , , + // , MsigCreate(context.Context, int64, []address.Address, types.BigInt, address.Address, types.BigInt) (cid.Cid, error) + // MsigPropose proposes a multisig message + // It takes the following params: , , , + // , , MsigPropose(context.Context, address.Address, address.Address, types.BigInt, address.Address, uint64, []byte) (cid.Cid, error) + // MsigApprove approves a previously-proposed multisig message + // It takes the following params: , , , , , + // , , MsigApprove(context.Context, address.Address, uint64, address.Address, address.Address, types.BigInt, address.Address, uint64, []byte) (cid.Cid, error) + // MsigCancel cancels a previously-proposed multisig message + // It takes the following params: , , , , , + // , , + // TODO: You can't cancel someone else's proposed message, so "src" and "proposer" here are redundant MsigCancel(context.Context, address.Address, uint64, address.Address, address.Address, types.BigInt, address.Address, uint64, []byte) (cid.Cid, error) MarketEnsureAvailable(context.Context, address.Address, address.Address, types.BigInt) (cid.Cid, error) @@ -304,7 +379,8 @@ type DealInfo struct { type MsgLookup struct { Receipt types.MessageReceipt - TipSet *types.TipSet + // TODO: This should probably a tipsetkey? + TipSet *types.TipSet } type BlockMessages struct { diff --git a/chain/stmgr/utils.go b/chain/stmgr/utils.go index 1901c79eb..fd99deef1 100644 --- a/chain/stmgr/utils.go +++ b/chain/stmgr/utils.go @@ -38,7 +38,7 @@ func GetNetworkName(ctx context.Context, sm *StateManager, st cid.Cid) (dtypes.N var state init_.State _, err := sm.LoadActorStateRaw(ctx, builtin.InitActorAddr, &state, st) if err != nil { - return "", xerrors.Errorf("(get sset) failed to load miner actor state: %w", err) + return "", xerrors.Errorf("(get sset) failed to load init actor state: %w", err) } return dtypes.NetworkName(state.NetworkName), nil