* Scaladoc formatting

* Adds sbt-api-mappings plugin
This commit is contained in:
Torkel Rogstad 2019-01-21 13:36:39 +01:00 committed by Chris Stewart
parent 4761679b45
commit dec5bf0c14
12 changed files with 105 additions and 62 deletions

View file

@ -137,7 +137,8 @@ sealed abstract class WitnessTxSigComponentRebuilt extends TxSigComponent {
override def scriptPubKey: ScriptPubKey = output.scriptPubKey
/** The [[WitnessScriptPubKey]] we used to rebuild the scriptPubKey above */
/** The [[org.bitcoins.core.protocol.script.WitnessScriptPubKey WitnessScriptPubKey]] we used to
* rebuild the scriptPubKey above */
def witnessScriptPubKey: WitnessScriptPubKey
override def sigVersion = SigVersionWitnessV0

View file

@ -15,42 +15,55 @@ import scodec.bits.ByteVector
/**
* Created by chris on 5/22/16.
* CChainParams defines various tweakable parameters of a given instance of the
* `ChainParams` defines various tweakable parameters of a given instance of the
* Bitcoin system. There are three: the main network on which people trade goods
* and services, the public test network which gets reset from time to time and
* a regression test mode which is intended for private networks only. It has
* minimal difficulty to ensure that blocks can be found instantly.
* Mimics this C++ interface
* https://github.com/bitcoin/bitcoin/blob/master/src/chainparams.h#L42
* @see Mimics
* [[https://github.com/bitcoin/bitcoin/blob/master/src/chainparams.h#L42 this C++ interface]]
* in Bitcoin Core
*/
sealed abstract class ChainParams {
/** Return the BIP70 network string ([[MainNetChainParams]], [[TestNetChainParams]] or [[RegTestNetChainParams]].) */
/** Return the BIP70 network string (
* [[org.bitcoins.core.protocol.blockchain.MainNetChainParams MainNetChainParams]],
* [[org.bitcoins.core.protocol.blockchain.MainNetChainParams TestNetChainParams]] or
* [[org.bitcoins.core.protocol.blockchain.MainNetChainParams RegTestNetChainParams]].)
*
* @see [[https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki BIP70]]
* */
def networkId: String
/** The Genesis [[Block]] in the blockchain. */
/** The Genesis [[org.bitcoins.core.protocol.blockchain.Block Block]] in the blockchain. */
def genesisBlock: Block
/**
* Filter transactions that do not match well-defined patterns
* inside of [[org.bitcoins.core.policy.Policy]].
* inside of [[org.bitcoins.core.policy.Policy Policy]].
*/
def requireStandardTransaction: Boolean = true
/** Takes in a [[Base58Type]] and returns its base58 prefix. */
/** Takes in a [[org.bitcoins.core.protocol.blockchain.Base58Type Base58Type]] and returns its base58 prefix. */
def base58Prefix(base58: Base58Type): ByteVector = base58Prefixes(base58)
/**
* The mapping from a [[Base58Type]]to a String.
* The mapping from a [[org.bitcoins.core.protocol.blockchain.Base58Type Base58Type]]to a String.
* Base58 prefixes for various keys/hashes on the network.
* See: [[https://en.bitcoin.it/wiki/List_of_address_prefixes]].
*
* @see Bitcoin wiki
* [[https://en.bitcoin.it/wiki/List_of_address_prefixes article]]
* on address prefixes
*/
def base58Prefixes: Map[Base58Type, ByteVector]
/**
* Creates the Genesis [[Block]] for this blockchain.
* Mimics this function in bitcoin core:
* [[https://github.com/bitcoin/bitcoin/blob/master/src/chainparams.cpp#L51]]
* Creates the Genesis [[org.bitcoins.core.protocol.blockchain.Block Block]] for this blockchain.
*
* @see Mimics
* [[https://github.com/bitcoin/bitcoin/blob/master/src/chainparams.cpp#L51 this function]]
* in Bitcoin Core
*
* @param time the time when the miner started hashing the block header
* @param nonce the nonce to mine the block
* @param nBits An encoded version of the target threshold this blocks header hash must be less than or equal to.

View file

@ -50,7 +50,7 @@ trait ScriptOperationFactory[T <: ScriptOperation] extends BitcoinSLogger {
str.replace("OP_", "")
}
/** Finds a [[org.bitcoins.core.script.ScriptOperation ScriptOperation]] from a given [[Byte]]. */
/** Finds a [[org.bitcoins.core.script.ScriptOperation ScriptOperation]] from a given [[scala.Byte Byte]]. */
def fromByte(byte: Byte): T = {
operations.find(_.toByte == byte).get
}

View file

@ -93,7 +93,7 @@ sealed abstract class ControlOperationsInterpreter {
}
/** Evaluates the [[OP_ELSE]] operator. */
/** Evaluates the [[org.bitcoins.core.script.control.OP_ELSE OP_ELSE]] operator. */
def opElse(program: ScriptProgram): ScriptProgram = {
require(program.script.headOption.contains(OP_ELSE),
"First script opt must be OP_ELSE")
@ -114,7 +114,7 @@ sealed abstract class ControlOperationsInterpreter {
}
}
/** Evaluates an [[OP_ENDIF]] operator. */
/** Evaluates an [[org.bitcoins.core.script.control.OP_ENDIF OP_ENDIF]] operator. */
def opEndIf(program: ScriptProgram): ScriptProgram = {
require(program.script.headOption.contains(OP_ENDIF),
"Script top must be OP_ENDIF")
@ -128,16 +128,20 @@ sealed abstract class ControlOperationsInterpreter {
/**
* Marks transaction as invalid. A standard way of attaching extra data to transactions is to add a zero-value output
* with a [[org.bitcoins.core.protocol.script.ScriptPubKey]] consisting of [[OP_RETURN]] followed by exactly one pushdata op. Such outputs are provably unspendable,
* reducing their cost to the network. Currently it is usually considered non-standard (though valid) for a transaction to
* have more than one OP_RETURN output or an OP_RETURN output with more than one pushdata op.
* with a [[org.bitcoins.core.protocol.script.ScriptPubKey ScriptPubKey]] consisting of
* [[org.bitcoins.core.script.control.OP_RETURN OP_RETURN]] followed by exactly one pushdata op.
* Such outputs are provably unspendable,
* reducing their cost to the network. Currently it is usually considered non-standard (though valid) for
* a transaction to
* have more than one [[org.bitcoins.core.script.control.OP_RETURN OP_RETURN]] output or an
* [[org.bitcoins.core.script.control.OP_RETURN OP_RETURN]] output with more than one pushdata op.
*/
def opReturn(program: ScriptProgram): ScriptProgram = {
require(program.script.headOption.contains(OP_RETURN))
ScriptProgram(program, ScriptErrorOpReturn)
}
/** Marks [[org.bitcoins.core.protocol.transaction.Transaction]] as invalid if top stack value is not true. */
/** Marks [[org.bitcoins.core.protocol.transaction.Transaction Transaction]] as invalid if top stack value is not true. */
def opVerify(program: ScriptProgram): ScriptProgram = {
require(program.script.headOption.contains(OP_VERIFY),
"Script top must be OP_VERIFY")
@ -152,7 +156,8 @@ sealed abstract class ControlOperationsInterpreter {
}
}
/** Parses a list of [[ScriptToken]]s into its corresponding [[BinaryTree]] */
/** Parses a list of [[org.bitcoins.core.script.constant.ScriptToken ScriptToken]]s
* into its corresponding [[org.bitcoins.core.util.BinaryTree BinaryTree]] */
def parseBinaryTree(script: List[ScriptToken]): BinaryTree[ScriptToken] = {
//@tailrec
def loop(
@ -184,7 +189,8 @@ sealed abstract class ControlOperationsInterpreter {
t
}
/** The loop that parses a list of [[ScriptToken]]s into a [[BinaryTree]]. */
/** The loop that parses a list of [[org.bitcoins.core.script.constant.ScriptToken ScriptToken]]s into a
* [[org.bitcoins.core.util.BinaryTree BinaryTree]]. */
private def parse(script: List[ScriptToken], tree: BinaryTree[ScriptToken]): (
BinaryTree[ScriptToken],
List[ScriptToken]) = script match {
@ -239,7 +245,10 @@ sealed abstract class ControlOperationsInterpreter {
Node(node.v, insertSubTree(node.l, subTree), node.r)
}
/** Checks if an [[OP_IF]]/[[OP_NOTIF]] [[ScriptToken]] has a matching [[OP_ENDIF]] */
/** Checks if an [[org.bitcoins.core.script.control.OP_IF OP_IF]]/
* [[org.bitcoins.core.script.control.OP_NOTIF OP_NOTIF]]
* [[org.bitcoins.core.script.constant.ScriptToken ScriptToken]] has a matching
* [[org.bitcoins.core.script.control.OP_ENDIF OP_ENDIF]] */
def checkMatchingOpIfOpNotIfOpEndIf(script: List[ScriptToken]): Boolean = {
@tailrec
def loop(script: List[ScriptToken], counter: Int): Boolean = script match {
@ -253,7 +262,7 @@ sealed abstract class ControlOperationsInterpreter {
loop(script, 0)
}
/** Returns the first index of an [[OP_ENDIF]]. */
/** Returns the first index of an [[org.bitcoins.core.script.control.OP_ENDIF OP_ENDIF]]. */
def findFirstOpEndIf(script: List[ScriptToken]): Option[Int] = {
val index = script.indexOf(OP_ENDIF)
index match {
@ -262,14 +271,14 @@ sealed abstract class ControlOperationsInterpreter {
}
}
/** Finds the last [[OP_ENDIF]] in the given script. */
/** Finds the last [[org.bitcoins.core.script.control.OP_ENDIF OP_ENDIF]] in the given script. */
def findLastOpEndIf(script: List[ScriptToken]): Option[Int] = {
val lastOpEndIf = findFirstOpEndIf(script.reverse)
if (lastOpEndIf.isDefined) Some(script.size - lastOpEndIf.get - 1)
else None
}
/** Returns the first index of an [[OP_ENDIF]]. */
/** Returns the first index of an [[org.bitcoins.core.script.control.OP_ENDIF OP_ENDIF]]. */
def findFirstOpElse(script: List[ScriptToken]): Option[Int] = {
val index = script.indexOf(OP_ELSE)
index match {
@ -278,12 +287,13 @@ sealed abstract class ControlOperationsInterpreter {
}
}
/** Removes the first [[OP_ELSE]] expression encountered in the script. */
/** Removes the first [[org.bitcoins.core.script.control.OP_ELSE OP_ELSE]] expression encountered in the script. */
def removeFirstOpElse(script: List[ScriptToken]): List[ScriptToken] = {
removeFirstOpElse(parseBinaryTree(script)).toList
}
/** Removes the first [[OP_ELSE]] in a [[BinaryTree]]. */
/** Removes the first [[org.bitcoins.core.script.control.OP_ELSE OP_ELSE]] in a
* [[org.bitcoins.core.util.BinaryTree BinaryTree]]. */
def removeFirstOpElse(
tree: BinaryTree[ScriptToken]): BinaryTree[ScriptToken] = {
//@tailrec
@ -304,12 +314,14 @@ sealed abstract class ControlOperationsInterpreter {
}
}
/** Removes the first [[OP_IF]] encountered in the script. */
/** Removes the first [[org.bitcoins.core.script.control.OP_IF OP_IF]] encountered in the script. */
def removeFirstOpIf(script: List[ScriptToken]): List[ScriptToken] = {
removeFirstOpIf(parseBinaryTree(script)).toList
}
/** Removes the first occurrence of [[OP_IF]] or [[OP_NOTIF]] in the [[BinaryTree]]. */
/** Removes the first occurrence of [[org.bitcoins.core.script.control.OP_IF OP_IF]] or
* [[org.bitcoins.core.script.control.OP_NOTIF OP_NOTIF]] in the
* [[org.bitcoins.core.util.BinaryTree BinaryTree]]. */
def removeFirstOpIf(
tree: BinaryTree[ScriptToken]): BinaryTree[ScriptToken] = {
require(
@ -318,7 +330,9 @@ sealed abstract class ControlOperationsInterpreter {
tree.right.getOrElse(Empty)
}
/** Finds the indexes of our [[OP_ELSE]] (if it exists) and our [[OP_ENDIF]]. */
/** Finds the indexes of our
* [[org.bitcoins.core.script.control.OP_ELSE OP_ELSE]] (if it exists) and our
* [[org.bitcoins.core.script.control.OP_ENDIF OP_ENDIF]]. */
def findFirstIndexesOpElseOpEndIf(
script: List[ScriptToken]): (Option[Int], Option[Int]) = {
val indexOpElse = findFirstOpElse(script)
@ -326,7 +340,8 @@ sealed abstract class ControlOperationsInterpreter {
(indexOpElse, indexOpEndIf)
}
/** Returns the index of the matching [[OP_ENDIF]] for the [[OP_IF]] statement. */
/** Returns the index of the matching [[org.bitcoins.core.script.control.OP_ENDIF OP_ENDIF]] for the
* [[org.bitcoins.core.script.control.OP_IF OP_IF]] statement. */
def findMatchingOpEndIf(script: List[ScriptToken]): Int = {
val matchingOpEndIfIndex = findLastOpEndIf(script)
require(matchingOpEndIfIndex.isDefined,

View file

@ -45,7 +45,8 @@ sealed abstract class ScriptInterpreter {
/**
* Runs an entire script though our script programming language and
* returns a [[ScriptResult]] indicating if the script was valid, or if not what error it encountered
* returns a [[org.bitcoins.core.script.result.ScriptResult ScriptResult]]
* indicating if the script was valid, or if not what error it encountered
*/
def run(program: PreExecutionScriptProgram): ScriptResult = {
val scriptSig = program.txSignatureComponent.scriptSignature
@ -118,7 +119,7 @@ sealed abstract class ScriptInterpreter {
}
/**
* Runs the given [[org.bitcoins.core.script.PreExecutionScriptProgram]] and
* Runs the given [[org.bitcoins.core.script.PreExecutionScriptProgram PreExecutionScriptProgram]] and
* return if that script was valid or not
*/
def runVerify(p: PreExecutionScriptProgram): Boolean = {
@ -126,15 +127,15 @@ sealed abstract class ScriptInterpreter {
}
/**
* Every given [[org.bitcoins.core.script.PreExecutionScriptProgram]] and returns
* it's [[org.bitcoins.core.script.result.ScriptResult]]
* Every given [[org.bitcoins.core.script.PreExecutionScriptProgram PreExecutionScriptProgram]] and returns
* it's [[org.bitcoins.core.script.result.ScriptResult ScriptResult]]
*/
def runAll(programs: Seq[PreExecutionScriptProgram]): Seq[ScriptResult] = {
programs.map(p => ScriptInterpreter.run(p))
}
/**
* Runs all the given [[org.bitcoins.core.script.ScriptProgram]] and return
* Runs all the given [[org.bitcoins.core.script.ScriptProgram ScriptProgram]] and return
* if it is valid or not
*/
def runAllVerify(programs: Seq[PreExecutionScriptProgram]): Boolean = {
@ -277,8 +278,8 @@ sealed abstract class ScriptInterpreter {
/**
* Runs a segwit script through our interpreter, mimics this functionality in bitcoin core:
* [[https://github.com/bitcoin/bitcoin/blob/528472111b4965b1a99c4bcf08ac5ec93d87f10f/src/script/interpreter.cpp#L1441-L1452]]
* @param scriptPubKeyExecutedProgram the program with the [[ScriptPubKey]] executed
* @return
* @param scriptPubKeyExecutedProgram the program with the
* [[org.bitcoins.core.protocol.script.ScriptPubKey ScriptPubKey]] executed
*/
private def executeSegWitScript(
scriptPubKeyExecutedProgram: ExecutedScriptProgram,
@ -798,7 +799,8 @@ sealed abstract class ScriptInterpreter {
currencyUnit >= CurrencyUnits.zero && currencyUnit <= Consensus.maxMoney
}
/** Calculates the new op count after the execution of the given [[ScriptToken]] */
/** Calculates the new op count after the execution of the given
* [[org.bitcoins.core.script.constant.ScriptToken ScriptToken]] */
private def calcOpCount(oldOpCount: Int, token: ScriptToken): Int =
BitcoinScriptUtil.countsTowardsScriptOpLimit(token) match {
case true => oldOpCount + 1
@ -839,8 +841,10 @@ sealed abstract class ScriptInterpreter {
}
/**
* Helper function used to rebuild a [[WitnessTxSigComponentRebuilt]]
* this converts a [[WitnessScriptPubKey]] into it's corresponding [[ScriptPubKey]]
* Helper function used to rebuild a
* [[org.bitcoins.core.crypto.WitnessTxSigComponentRebuilt WitnessTxSigComponentRebuilt]]
* this converts a [[org.bitcoins.core.protocol.script.WitnessScriptPubKey WitnessScriptPubKey]]
* into it's corresponding [[org.bitcoins.core.protocol.script.ScriptPubKey ScriptPubKey]]
*/
private def rebuildWTxSigComponent(
old: WitnessTxSigComponent,

View file

@ -146,9 +146,12 @@ sealed abstract class LockTimeInterpreter {
}
/**
* Mimics this function inside of bitcoin core
* [[https://github.com/bitcoin/bitcoin/blob/e26b62093ae21e89ed7d36a24a6b863f38ec631d/src/script/interpreter.cpp#L1196]]
* [[https://github.com/bitcoin/bips/blob/master/bip-0068.mediawiki#specification]]
* @see Mimics
* [[https://github.com/bitcoin/bitcoin/blob/e26b62093ae21e89ed7d36a24a6b863f38ec631d/src/script/interpreter.cpp#L1196 this function]]
* inside of Bitcoin Core
*
* @see [[https://github.com/bitcoin/bips/blob/master/bip-0068.mediawiki#specification BIP68]]
*
* @param program the program whose transaction input's sequence is being compared
* @param nSequence the script number on the stack top to compare to the input's sequence number
* @return if the given script number is valid or not
@ -269,8 +272,10 @@ sealed abstract class LockTimeInterpreter {
}
/**
* Mimics this function inside of bitcoin core for checking the locktime of a transaction
* [[https://github.com/bitcoin/bitcoin/blob/master/src/script/interpreter.cpp#L1160]].
* Checks the locktime of a transaction.
* @see Mimics
* [[https://github.com/bitcoin/bitcoin/blob/master/src/script/interpreter.cpp#L1160 this function]]
* inside of Bitcoin Core
*/
private def checkLockTime(
program: ScriptProgram,

View file

@ -64,12 +64,13 @@ sealed abstract class Base58 {
encode(bytes)
}
/** Encodes a [[Byte]] to its [[org.bitcoins.core.protocol.blockchain.Base58Type Base58Type]] representation. */
/** Encodes a [[scala.Byte Byte]] to its
* [[org.bitcoins.core.protocol.blockchain.Base58Type Base58Type]] representation. */
def encode(byte: Byte): String = encode(ByteVector.fromByte(byte))
/**
* Takes in [[org.bitcoins.core.protocol.blockchain.Base58Type Base58Type]]
* string and returns sequence of [[Byte]]s.
* string and returns sequence of [[scala.Byte Byte]]s.
* [[https://github.com/ACINQ/bitcoin-lib/blob/master/src/main/scala/fr/acinq/bitcoin/Base58.scala]]
*/
def decode(input: String): ByteVector = {

View file

@ -79,7 +79,7 @@ trait BinaryTree[+T] {
/**
* Inserts an element into one of the two branches in a [[org.bitcoins.core.util.BinaryTree BinaryTree]].
* If it cannot insert it because the branches are not empty,
* it throws a [[RuntimeException]].
* it throws a [[scala.RuntimeException RuntimeException]].
*/
def insert[T](t: T)(implicit tree: BinaryTree[T] = this): BinaryTree[T] = {
insert(Leaf(t))(tree)
@ -88,7 +88,7 @@ trait BinaryTree[+T] {
/**
* Inserts a tree into one of the two branches in a [[org.bitcoins.core.util.BinaryTree BinaryTree]]
* If it cannot insert it because the branches are not empty,
* it throws a [[RuntimeException]].
* it throws a [[scala.RuntimeException RuntimeException]].
*/
def insert[T](subTree: BinaryTree[T])(
implicit parentTree: BinaryTree[T]): BinaryTree[T] = parentTree match {

View file

@ -49,16 +49,16 @@ trait NumberUtil extends BitcoinSLogger {
}
}
/** Converts a sequence of [[Byte]] to a [[scala.Int Int]]. */
/** Converts a sequence of [[scala.Byte Byte]] to a [[scala.Int Int]]. */
def toInt(bytes: ByteVector): Int = toBigInt(bytes).toInt
/** Converts a hex string to a [[scala.Int Int]]. */
def toInt(hex: String): Int = toInt(BitcoinSUtil.decodeHex(hex))
/** Converts a sequence of [[Byte]] to a [[Long]]. */
/** Converts a sequence of [[scala.Byte Byte]] to a [[scala.Long Long]]. */
def toLong(bytes: ByteVector): Long = toBigInt(bytes).toLong
/** Converts a hex string to a [[Long]]. */
/** Converts a hex string to a [[scala.Long Long]]. */
def toLong(hex: String): Long = toLong(BitcoinSUtil.decodeHex(hex))
/**

View file

@ -22,3 +22,7 @@ addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "1.3.2")
// publish said site to GitHub pages
addSbtPlugin("com.typesafe.sbt" % "sbt-ghpages" % "0.6.2")
// ensure proper linkage across libraries in Scaladoc
addSbtPlugin(
"com.thoughtworks.sbt-api-mappings" % "sbt-api-mappings" % "latest.release")

View file

@ -39,8 +39,8 @@ sealed abstract class CryptoGenerators {
}
/**
* Generates a random number of private keys less than the max public keys setting in [[ScriptSettings]]
* also generates a random 'requiredSigs' number that a transaction needs to be signed with
* Generates a random number of private keys less than 15.
* Also generates a random 'requiredSigs' number that a transaction needs to be signed with
*/
def privateKeySeqWithRequiredSigs: Gen[(Seq[ECPrivateKey], Int)] =
for {
@ -74,7 +74,7 @@ sealed abstract class CryptoGenerators {
digest = CryptoUtil.sha256(hex)
} yield digest
/** Generates a random [[DoubleSha256Digest]] */
/** Generates a random [[org.bitcoins.core.crypto.DoubleSha256Digest DoubleSha256Digest]] */
def doubleSha256Digest: Gen[DoubleSha256Digest] =
for {
hex <- StringGenerators.hexString
@ -82,21 +82,21 @@ sealed abstract class CryptoGenerators {
} yield digest
/**
* Generates a sequence of [[DoubleSha256Digest]]
* Generates a sequence of [[org.bitcoins.core.crypto.DoubleSha256Digest DoubleSha256Digest]]
* @param num the number of digets to generate
* @return
*/
def doubleSha256DigestSeq(num: Int): Gen[Seq[DoubleSha256Digest]] =
Gen.listOfN(num, doubleSha256Digest)
/** Generates a random [[org.bitcoins.core.crypto.Sha256Hash160Digest]] */
/** Generates a random [[org.bitcoins.core.crypto.Sha256Hash160Digest Sha256Hash160Digest]] */
def sha256Hash160Digest: Gen[Sha256Hash160Digest] =
for {
pubKey <- publicKey
hash = CryptoUtil.sha256Hash160(pubKey.bytes)
} yield hash
/** Generates a random [[HashType]] */
/** Generates a random [[org.bitcoins.core.script.crypto.HashType HashType]] */
def hashType: Gen[HashType] =
Gen.oneOf(
HashType.sigHashAll,
@ -111,7 +111,7 @@ sealed abstract class CryptoGenerators {
def extVersion: Gen[ExtKeyVersion] =
Gen.oneOf(MainNetPriv, MainNetPub, TestNet3Priv, TestNet3Pub)
/** Generates an [[org.bitcoins.core.crypto.ExtPrivateKey]] */
/** Generates an [[org.bitcoins.core.crypto.ExtPrivateKey ExtPrivateKey]] */
def extPrivateKey: Gen[ExtPrivateKey] =
for {
version <- Gen.oneOf(MainNetPriv, TestNet3Priv)

View file

@ -77,7 +77,7 @@ trait NumberGenerator {
def compactSizeUInts: Gen[CompactSizeUInt] = uInt64s.map(CompactSizeUInt(_))
/** Generates an arbitrary [[Byte]] in Scala */
/** Generates an arbitrary [[scala.Byte Byte]] in Scala */
def byte: Gen[Byte] = arbitrary[Byte]
/** Generates a 100 byte sequence */