/// \mainpage Brief introduction into cryptocondition contracts
/// There are only a very few types in bitcoin: pay to pubkey, pay to pubkey hash and pay to script hash (p2pk, p2pkh, p2sh).
/// There are actually more that are possible, but those three are 99%+ of bitcoin transactions.
/// So you can pay to a pubkey, or to its hash or to a script's hash. The last is how most of the more complex scripts are invoked. To spend a p2sh vout, you need to provide the redeemscript,
/// this script's hash is what the p2sh address was.
/// All of the above are the standard bitcoin vout types and there should be plenty of materials about it.
/// Cryptoconditions (CC) contracts created a fourth type of vout, the CC vout. This is using the cryptoconditions standard and it is even a different signature mechanism,
/// ed25519 instead of secp256k1. It is basically a big extension to the bitcoin script. There is a special opcode that is added that says it is a CC script.
///
/// But it gets more interesting. Each CC script has an evalcode.
/// This is just an arbitrary number but what it does is allows to create a self-contained universe of CC utxo that all have the same evalcode and that is
/// how a faucet CC contract differentiates itself from a dice CC contract, the eval code is different.
///
/// One effect from using a different eval code is that even if the rest of the CC script is the same, the bitcoin address that is calculated is different.
/// What this means is that for each pubkey, there is a unique address for each different eval code!
/// And this allows efficient segregation of one CC contracts transactions from another.
/// The final part that will make it all clear how the funds can be locked inside the contract.
/// This is what makes a contract, a contract.
/// I put both the privkey and pubkey for a randomly chosen address and associate it with each CC contract.
/// That means anybody can sign outputs for that privkey.
/// However, it is a CC output, so in addition to the signature, whatever constraints a CC contract implements must also be satistifed.
/// This allows funds to be locked and yet anybody is able to spend it, assuming they satisfy the CC's rules.
/// so it can lookup directly all transactions to any address.
/// This is a key performance boosting thing as if it wasnt there, trying to get all the utxo for an address not in the wallet is quite time consuming.
#define CC_BURNPUBKEY "02deaddeaddeaddeaddeaddeaddeaddeaddeaddeaddeaddeaddeaddeaddeaddead" //!< 'dead' pubkey in hex for burning tokens (if tokens are sent to it, they become 'burned')
#define CC_REQUIREMENTS_MSG (HUSH_NSPV_SUPERLITE?"to use CC contracts you need to nspv_login first\n":"to use CC contracts, you need to launch daemon with valid -pubkey= for an address in your wallet\n")
/// CC contract (Antara module) info structure that contains data used for signing and validation of cc contract transactions
structCCcontract_info
{
uint8_tevalcode;//!< cc contract eval code, set by CCinit function
uint8_tadditionalTokensEvalcode2;//!< additional eval code for spending from three-eval-code vouts with EVAL_TOKENS, evalcode, additionalTokensEvalcode2
//!< or vouts with two evalcodes: EVAL_TOKENS, additionalTokensEvalcode2.
//!< Set by AddTokenCCInputs function
charunspendableCCaddr[64];//!< global contract cryptocondition address, set by CCinit function
charCChexstr[72];//!< global contract pubkey in hex, set by CCinit function
charnormaladdr[64];//!< global contract normal address, set by CCinit function
uint8_tCCpriv[32];//!< global contract private key, set by CCinit function
/// vars for spending from 1of2 cc.
/// NOTE: the value of 'evalcode' member variable will be used for constructing 1of2 cryptocondition
charcoins1of2addr[64];//!< address of 1of2 cryptocondition, set by CCaddr1of2set function
CPubKeycoins1of2pk[2];//!< two pubkeys of 1of2 cryptocondition, set by CCaddr1of2set function
uint8_tcoins1of2priv[32];//!< privkey for the one of two pubkeys of 1of2 cryptocondition, set by CCaddr1of2set function
/// vars for spending from 1of2 token cc.
/// NOTE: the value of 'evalcode' member variable will be used for constructing 1of2 token cryptocondition
chartokens1of2addr[64];//!< address of 1of2 token cryptocondition set by CCaddrTokens1of2set function
CPubKeytokens1of2pk[2];//!< two pubkeys of 1of2 token cryptocondition set by CCaddrTokens1of2set function
uint8_ttokens1of2priv[32];//!< privkey for the one of two pubkeys of 1of2 token cryptocondition set by CCaddrTokens1of2set function
/// vars for spending from two additional global CC addresses of other contracts with their own eval codes
uint8_tunspendableEvalcode2;//!< other contract eval code, set by CCaddr2set function
uint8_tunspendableEvalcode3;//!< yet another other contract eval code, set by CCaddr3set function
charunspendableaddr2[64];//!< other contract global cc address, set by CCaddr2set function
charunspendableaddr3[64];//!< yet another contract global cc address, set by CCaddr3set function
uint8_tunspendablepriv2[32];//!< other contract private key for the global cc address, set by CCaddr2set function
uint8_tunspendablepriv3[32];//!< yet another contract private key for the global cc address, set by CCaddr3set function
CPubKeyunspendablepk2;//!< other contract global public key, set by CCaddr2set function
CPubKeyunspendablepk3;//!< yet another contract global public key, set by CCaddr3set function
/// cc contract transaction validation callback that enforces the contract consensus rules
/// @param cp CCcontract_info structure with initialzed with CCinit
/// @param eval object of Eval type, used to report validation error like eval->Invalid("some error");
/// CCgetspenttxid finds the txid of the transaction which spends a transaction output. The function does this without loading transactions from the chain, by using spent index
/// @param[out] spenttxid transaction id of the spending transaction
/// @param[out] vini order number of input of the spending transaction
/// @param[out] height block height where spending transaction is located
/// @param txid id of the transaction for which spending tx is searched
/// @param vout output number of the transaction for which spending transaction is searched
/// @returns 0 if spending tx is found or -1 if not
/// Adds token inputs to transaction object. If tokenid is a non-fungible token then the function will set additionalTokensEvalcode2 variable in the cp object to the eval code from NFT data to spend NFT outputs properly
/// @param cp CCcontract_info structure
/// @param mtx mutable transaction object
/// @param pk pubkey for whose token inputs to add
/// @param tokenid id of token which inputs to add
/// @param total amount to add (if total==0 no inputs are added and all available amount is returned)
/// @param maxinputs maximum number of inputs to add. If 0 then CC_MAXVINS define is used
/// Checks if a transaction vout is true token vout, for this check pubkeys and eval code in token opreturn are used to recreate vout and compare it with the checked vout.
/// Verifies that the transaction total token inputs value equals to total token outputs (that is, token balance is not changed in this transaction)
/// @param goDeeper also recursively checks the previous token transactions (or the creation transaction) and ensures token balance is not changed for them too
/// @param checkPubkeys always true
/// @param cp CCcontract_info structure initialized for EVAL_TOKENS eval code
/// @param eval could be NULL, if not NULL then the eval parameter is used to report validation error
/// @param tx transaction object to check
/// @param v vout number (starting from 0)
/// @param reftokenid id of the token. The vout is checked if it has this tokenid
/// @returns true if vout is true token with the reftokenid id
/// Makes opreturn scriptPubKey for token creation transaction. Normally this function is called internally by the tokencreate rpc. You might need to call this function to create a customized token.
/// The total opreturn length should not exceed 10001 byte
/// @param funcid should be set to 'c' character
/// @param origpubkey token creator pubkey as byte array
/// @param name token name (no more than 32 char)
/// @param description token description (no more than 4096 char)
/// @param vopretNonfungible NFT data, could be empty. If not empty, NFT will be created, the first byte if the NFT data should be set to the eval code of the contract validating this NFT data
/// Makes opreturn scriptPubKey for token creation transaction. Normally this function is called internally by the tokencreate rpc. You might need to call it to create a customized token.
/// The total opreturn length should not exceed 10001 byte
/// @param funcid should be set to 'c' character
/// @param origpubkey token creator pubkey as byte array
/// @param name token name (no more than 32 char)
/// @param description token description (no more than 4096 char)
/// @param oprets vector of pairs of additional data added to the token opret. The first element in the pair is opretid enum, the second is the data as byte array
/// Makes opreturn scriptPubKey for token transaction. Normally this function is called internally by the token rpcs. You might call this function if your module should create a customized token.
/// The total opreturn length should not exceed 10001 byte
/// @param tokenid id of the token
/// @param voutPubkeys vector of pubkeys used to make the token vout in the same transaction that the created opreturn is for, the pubkeys are used for token vout validation
/// @param opretWithId a pair of additional opreturn data added to the token opret. Could be empty. The first element in the pair is opretid enum, the second is the data as byte array
/// An overload to make opreturn scriptPubKey for token transaction. Normally this function is called internally by the token rpcs. You might call this function if your module should create a customized token.
/// The total opreturn length should not exceed 10001 byte
/// @param tokenid id of the token
/// @param voutPubkeys vector of pubkeys used to make the token vout in the same transaction that the created opreturn is for, the pubkeys are used for token vout validation
/// @param oprets vector of pairs of additional opreturn data added to the token opret. Could be empty. The first element in the pair is opretid enum, the second is the data as byte array
/// Decodes opreturn scriptPubKey of token creation transaction. Normally this function is called internally by the token rpcs. You might call this function if your module should create a customized token.
/// @param scriptPubKey OP_RETURN script to decode
/// @param[out] origpubkey creator public key as a byte array
/// Overload that decodes opreturn scriptPubKey of token creation transaction and also returns additional data blobs.
/// Normally this function is called internally by the token rpcs. You might want to call this function if your module should create a customized token.
/// @param scriptPubKey OP_RETURN script to decode
/// @param[out] origpubkey creator public key as a byte array
/// @param[out] name token name
/// @param[out] description token description
/// @param[out] oprets vector of pairs of additional opreturn data added to the token opret. Could be empty if not set. The first element in the pair is opretid enum, the second is the data as byte array
/// Decodes opreturn scriptPubKey of token transaction, also returns additional data blobs.
/// Normally this function is called internally by different token rpc. You might want to call if your module created a customized token.
/// @param scriptPubKey OP_RETURN script to decode
/// @param[out] evalCodeTokens should be EVAL_TOKENS
/// @param[out] tokenid id of token
/// @param[out] voutPubkeys vector of token output validation pubkeys from the opreturn
/// @param[out] oprets vector of pairs of additional opreturn data added to the token opret. Could be empty if not set. The first element in the pair is opretid enum, the second is the data as byte array
/// @returns funcid ('c' if creation tx or 't' if token transfer tx) or NULL if errors
/// MakeCC1vout creates a transaction output with a cryptocondition that allows to spend it by one key. The returned output should be added to a transaction vout array.
/// @param evalcode cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// @param nValue value of the output in satoshi
/// @param pk pubkey to spend the cc
/// @param vData pointer to vector of vectors of unsigned char data to be added to the created vout for application needs
/// MakeCC1of2vout creates creates a transaction output with a 1of2 cryptocondition that allows to spend it by either of two keys. The returned output should be added to a transaction vout array.
/// @param evalcode cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// @param nValue value of the output in satoshi
/// @param pk one of two pubkeys to spend the cc
/// @param pk2 second of two pubkeys to spend the cc
/// @param vData pointer to vector of vectors of unsigned char data to be added to the created vout for application needs
/// MakeCCcond1 creates a cryptocondition that allows to spend it by one key
/// @param evalcode cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// @param pk pubkey to spend the cc
/// @returns cryptocondition object. Must be disposed with cc_free function when not used any more
/// MakeCCcond1of2 creates new 1of2 cryptocondition that allows to spend it by either of two keys
/// @param evalcode cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// @param pk1 one of two pubkeys to spend the cc
/// @param pk2 second of two pubkeys to spend the cc
/// @returns cryptocondition object. Must be disposed with cc_free function when not used any more
/// CCaddr2set sets private key for yet another eval code global address.
/// This allows to spend from three cc global addresses in one transaction (the first one is set in cp object by CCinit function, the second is set by CCaddr2set function).
/// @param cp contract info structure where the private key is set
/// @param evalcode eval code of the other contract
/// @param pk global public key of the other contract
/// @param priv private key for the global public key of the other contract
/// @param coinaddr the cc address obtained for this global pubkey and eval code with _GetCCaddress
/// Creates a token cryptocondition that allows to spend it by one key
/// The resulting cc will have two eval codes (EVAL_TOKENS and evalcode parameter value).
/// @param evalcode cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// @param pk pubkey to spend the cc
/// @returns cryptocondition object. Must be disposed with cc_free function when not used any more
/// Overloaded function that creates a token cryptocondition that allows to spend it by one key
/// The resulting cc will have two eval codes (EVAL_TOKENS and evalcode parameter value).
/// @param evalcode cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// @param evalcode2 yet another cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// @param pk pubkey to spend the cc
/// @returns cryptocondition object. Must be disposed with cc_free function when not used any more
/// Creates new 1of2 token cryptocondition that allows to spend it by either of two keys
/// Resulting vout will have three eval codes (EVAL_TOKENS, evalcode and evalcode2 parameter values).
/// @param evalcode cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// @param pk1 one of two pubkeys to spend the cc
/// @param pk2 second of two pubkeys to spend the cc
/// @returns cryptocondition object. Must be disposed with cc_free function when not used any more
/// Creates new 1of2 token cryptocondition that allows to spend it by either of two keys
/// The resulting cc will have two eval codes (EVAL_TOKENS and evalcode parameter value).
/// @param evalcode cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// @param evalcode2 yet another cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// @param pk1 one of two pubkeys to spend the cc
/// @param pk2 second of two pubkeys to spend the cc
/// @returns cryptocondition object. Must be disposed with cc_free function when not used any more
/// Creates a token transaction output with a cryptocondition that allows to spend it by one key.
/// The resulting vout will have two eval codes (EVAL_TOKENS and evalcode parameter value).
/// The returned output should be added to a transaction vout array.
/// @param evalcode cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// Another MakeTokensCC1vout overloaded function that creates a token transaction output with a cryptocondition with two eval codes that allows to spend it by one key.
/// Resulting vout will have three eval codes (EVAL_TOKENS, evalcode and evalcode2 parameter values).
/// The returned output should be added to a transaction vout array.
/// @param evalcode cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// @param evalcode2 yet another cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// MakeTokensCC1of2vout creates a token transaction output with a 1of2 cryptocondition that allows to spend it by either of two keys.
/// The resulting vout will have two eval codes (EVAL_TOKENS and evalcode parameter value).
/// The returned output should be added to a transaction vout array.
/// @param evalcode cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// @param nValue value of the output in satoshi
/// @param pk1 one of two pubkeys to spend the cc
/// @param pk2 second of two pubkeys to spend the cc
/// Another overload of MakeTokensCC1of2vout creates a token transaction output with a 1of2 cryptocondition with two eval codes that allows to spend it by either of two keys.
/// The resulting vout will have three eval codes (EVAL_TOKENS, evalcode and evalcode2 parameter values).
/// The returned output should be added to a transaction vout array.
/// @param evalcode cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// @param evalcode2 yet another cryptocondition eval code (transactions with this eval code in cc inputs will be forwarded to the contract associated with this eval code)
/// @param nValue value of the output in satoshi
/// @param pk1 one of two pubkeys to spend the cc
/// @param pk2 second of two pubkeys to spend the cc
externstd::vector<CPubKey>NULL_pubkeys;//!< constant value for use in functions where such value might be passed @see FinalizeCCTx
/// overload old-style FinalizeCCTx for compatibility
/// @param skipmask parameter is not used
/// @param cp contract info structure with cc eval code, module's global address and privkey. It also could have a vector of probe cryptoconditions created by CCAddVintxCond
/// @param mtx prepared transaction to sign
/// @param mypk my pubkey to sign
/// @param txfee transaction fee
/// @param opret opreturn vout which function will add if it is not empty
/// @param pubkeys array of pubkeys to make multiple probe 1of2 cc's with the call Make1of2cond(cp->evalcode, globalpk, pubkeys[i])
/// FinalizeCCTx is a very useful function that will properly sign both CC and normal inputs, adds normal change and might add an opreturn output.
/// This allows for Antara module transaction creation rpc functions to create an CMutableTransaction object, add the appropriate vins and vouts to it and use FinalizeCCTx to properly sign the transaction.
/// For signing the vins the function builds several default probe scriptPubKeys and checks them against the referred previous transactions (vintx) vouts.
/// For cryptocondition vins the function creates a basic set of probe cryptconditions with mypk and module global pubkey, both for coins and tokens cases.
/// For signing 1of2 cryptocondition it is needed to use CCaddr1of2set function to set both pubkeys in cp object before calling FinalizeCCtx.
/// For a set of 1of2 cc with pairs of module globalpk and some other pk, spending with global pk, pass a vector with pubkeys as 'pubkeys' parameter.
/// For any other cc case use CCAddVintxCond function to add any possible probe cryptoconditions to the cp opbject.
/// @param remote true if the caller is in remote nspv mode
/// @param skipmask parameter is not used
/// @param cp contract info structure with cc eval code, module's global address and privkey. It also could have a vector of probe cryptoconditions created by CCAddVintxCond
/// @param mtx prepared transaction to sign
/// @param mypk my pubkey to sign
/// @param txfee transaction fee
/// @param opret opreturn vout which function will add if it is not empty
/// @param pubkeys array of pubkeys to make multiple probe 1of2 cc's with the call Make1of2cond(cp->evalcode, globalpk, pubkeys[i])
/// In NSPV mode adds normal (not cc) inputs to the transaction object vin array for the specified total amount using available utxos on mypk's TX_PUBKEY address
/// @param mtx mutable transaction object
/// @param mypk pubkey to make TX_PUBKEY address from
/// @param total amount of inputs to add. If total equals to 0 the function does not add inputs but returns amount of all available normal inputs in the wallet
/// @param maxinputs maximum number of inputs to add
/// @param[out] ptr pointer to NSPV_CCmtxinfo structure with the info about the added utxo
/// @returns amount of added normal inputs or amount of all normal inputs in the wallet
/// AddNormalinputs wrapper for calling either AddNormalinputsLocal or AddNormalinputsRemote
/// @param mtx mutable transaction object
/// @param mypk not used
/// @param total amount of inputs to add. If total equals to 0 the function does not add inputs but returns amount of all available normal inputs in the wallet
/// @param maxinputs maximum number of inputs to add
/// @param remote true if running in remote nspv mode (default false)
/// @returns amount of added normal inputs or amount of all normal inputs in the wallet
/// Local version for cc runnnig on the same node, adds normal (not cc) inputs to the transaction object vin array for the specified total amount using available utxos in the wallet, to fund the transaction
/// @param mtx mutable transaction object
/// @param mypk not used
/// @param total amount of inputs to add. If total equals to 0 the function does not add inputs but returns amount of all available normal inputs in the wallet
/// @param maxinputs maximum number of inputs to add
/// @returns amount of added normal inputs or amount of all normal inputs in the wallet
/// AddNormalinputs2 adds normal (not cc) inputs to the transaction object vin array for the specified total amount using utxos on my pubkey's TX_PUBKEY address (my pubkey is set by -pubkey command line parameter), to fund the transaction.
/// @param total amount of inputs to add. If total equals to 0 the function does not add inputs but returns amount of all available normal inputs in the wallet
/// @param maxinputs maximum number of inputs to add
/// @returns amount of added normal inputs or amount of all normal inputs on my pubkey's address
/// Remote version, does not use local wallet, adds normal (not cc) inputs to the transaction object vin array for the specified total amount using available utxos on mypk, to fund the transaction
/// @param mtx mutable transaction object
/// @param mypk pubkey on which utxo's are searched
/// @param total amount of inputs to add. If total equals to 0 the function does not add inputs but returns amount of all available normal inputs in the wallet
/// @param maxinputs maximum number of inputs to add
/// @returns amount of added normal inputs or amount of all normal inputs in the wallet
/// To set debug level pass -debug=category-1, -debug=category-2 or -debug=category-3 param. If some level is enabled lower level messages also will be printed.
/// To print info-level messages pass just -debug=category parameter, with no level.
/// Error-level messages will always be printed, even if -debug parameter is not set
/// @param category category of message, for example Antara module name
/// @param level debug-level, use defines CCLOG_ERROR, CCLOG_INFO, CCLOG_DEBUGN
/// @param logoperator to form the log message (the 'stream' name is mandatory)
/// LOGSTREAMFN is a version of LOGSTREAM macro which adds calling function name with the standard define \_\_func\_\_ at the beginning of the printed string.
/// LOGSTREAMFN parameters are the same as in LOGSTREAM