Qortal/altcoinj
3
0
Fork 0
mirror of https://github.com/Qortal/altcoinj.git synced 2025-01-30 23:02:15 +00:00
Code Issues Projects Releases Wiki Activity

JavaDoc improvements and other minor tweaks. Remove a few things that are not really meant to be public APIs.

Browse Source
This commit is contained in:
Mike Hearn 2012-08-30 23:46:54 +02:00
parent 2961f65594
commit 38aabdfa24
18 changed files with 75 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
core/src/main/java/com/google/bitcoin/core/Address.java
View File

@ -17,8 +17,9 @@
package com.google.bitcoin.core;
/**
* A Bitcoin address is derived from an elliptic curve public key and a set of network parameters.
* It has several possible representations:<p>
* <p>A Bitcoin address is derived from an elliptic curve public key and a set of network parameters. Not to be confused
* with a {@link PeerAddress} or {@link AddressMessage} which are about network (TCP) addresses.
* It has several possible representations:</p>
*
* <ol>
* <li>The raw public key bytes themselves.

5
core/src/main/java/com/google/bitcoin/core/AddressMessage.java
View File

@ -6,6 +6,11 @@ import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* Represents an "addr" message on the P2P network, which contains broadcast advertisements of other peers. This is
* one of the ways peers can find each other without using the DNS or IRC discovery mechansisms. However storing and
* using addr messages is not presently implemented.
*/
public class AddressMessage extends Message {
private static final long serialVersionUID = 8058283864924679460L;
private static final long MAX_ADDRESSES = 1024;

8
core/src/main/java/com/google/bitcoin/core/Base58.java
View File

@ -21,14 +21,14 @@ import java.math.BigInteger;
import java.util.Arrays;
/**
* A custom form of base58 is used to encode BitCoin addresses. Note that this is not the same base58 as used by
* Flickr, which you may see reference to around the internet.<p>
* <p>Base58 is a way to encode Bitcoin addresses as numbers and letters. Note that this is not the same base58 as used by
* Flickr, which you may see reference to around the internet.</p>
*
* Satoshi says: why base-58 instead of standard base-64 encoding?<p>
* <p>Satoshi says: why base-58 instead of standard base-64 encoding?<p>
*
* <ul>
* <li>Don't want 0OIl characters that look the same in some fonts and
* could be used to create visually identical looking account numbers.</li>
* could be used to create visually identical looking account numbers.</li>
* <li>A string with non-alphanumeric characters is not as easily accepted as an account number.</li>
* <li>E-mail usually won't line-break if there's no punctuation to break at.</li>
* <li>Doubleclicking selects the whole number as one word if it's all alphanumeric.</li>

8
core/src/main/java/com/google/bitcoin/core/Block.java
View File

@ -34,9 +34,11 @@ import static com.google.bitcoin.core.Utils.doubleDigest;
import static com.google.bitcoin.core.Utils.doubleDigestTwoBuffers;
/**
* A block is the foundation of the BitCoin system. It records a set of {@link Transaction}s together with some data
* that links it into a place in the global block chain, and proves that a difficult calculation was done over its
* contents. See the BitCoin technical paper for more detail on blocks. <p/>
* <p>A block is a group of transactions, and is one of the fundamental data structures of the Bitcoin system.
* It records a set of {@link Transaction}s together with some data that links it into a place in the global block
* chain, and proves that a difficult calculation was done over its contents. See
* <a href="http://www.bitcoin.org/bitcoin.pdf">the Bitcoin technical paper</a> for
* more detail on blocks. <p/>
*
* To get a block, you can either build one from the raw bytes you can get from another implementation, or request one
* specifically using {@link Peer#getBlock(Sha256Hash)}, or grab one from a downloaded {@link BlockChain}.

4
core/src/main/java/com/google/bitcoin/core/GetAddrMessage.java
View File

@ -16,6 +16,10 @@
package com.google.bitcoin.core;
/**
* Represents the "getaddr" P2P protocol message, which requests network {@link AddressMessage}s from a peer. Not to
* be confused with {@link Address} which is sort of like an account number.
*/
public class GetAddrMessage extends EmptyMessage {
private static final long serialVersionUID = 6204437624599661503L;

4
core/src/main/java/com/google/bitcoin/core/GetBlocksMessage.java
View File

@ -21,6 +21,10 @@ import java.io.OutputStream;
import java.util.ArrayList;
import java.util.List;
/**
* Represents the "getblocks" P2P network message, which requests the hashes of the parts of the block chain we're
* missing. Those blocks can then be downloaded with a {@link GetDataMessage}.
*/
public class GetBlocksMessage extends Message {
private static final long serialVersionUID = 3479412877853645644L;
protected long version;

4
core/src/main/java/com/google/bitcoin/core/GetDataMessage.java
View File

@ -16,6 +16,10 @@
package com.google.bitcoin.core;
/**
* Represents the "getdata" P2P network message, which requests the contents of blocks or transactions given their
* hashes.
*/
public class GetDataMessage extends ListMessage {
private static final long serialVersionUID = 2754681589501709887L;

6
core/src/main/java/com/google/bitcoin/core/InventoryMessage.java
View File

@ -16,6 +16,12 @@
package com.google.bitcoin.core;
/**
* <p>Represents the "inv" P2P network message. An inv contains a list of hashes of either blocks or transactions. It's
* a bandwidth optimization - on receiving some data, a (fully validating) peer sends every connected peer an inv
* containing the hash of what it saw. It'll only transmit the full thing if a peer asks for it with a
* {@link GetDataMessage}.</p>
*/
public class InventoryMessage extends ListMessage {
private static final long serialVersionUID = -7050246551646107066L;

2
core/src/main/java/com/google/bitcoin/core/ListMessage.java
View File

@ -23,7 +23,7 @@ import java.util.Collections;
import java.util.List;
/**
* Abstract superclass of classes with list based payload, i.e. InventoryMessage and GetDataMessage.
* Abstract superclass of classes with list based payload, ie InventoryMessage and GetDataMessage.
*/
public abstract class ListMessage extends Message {
private static final long serialVersionUID = -4275896329391143643L;

16
core/src/main/java/com/google/bitcoin/core/MemoryPool.java
View File

@ -29,15 +29,15 @@ import java.util.Map;
import java.util.Set;
/**
* Tracks transactions that are being announced across the network. Typically one is created for you by a PeerGroup
* and then given to each Peer to update. The current purpose is to let Peers update the confidence (number of peers
* broadcasting). It helps address an attack scenario in which a malicious remote peer (or several) feeds you
* invalid transactions, eg, ones that spend coins which don't exist. If you don't see most of the peers announce the
* transaction within a reasonable time, it may be that the TX is not valid. Alternatively, an attacker may control
* your entire internet connection: in this scenario counting broadcasting peers does not help you.<p>
* <p>Tracks transactions that are being announced across the network. Typically one is created for you by a
* {@link PeerGroup} and then given to each Peer to update. The current purpose is to let Peers update the confidence
* (number of peers broadcasting). It helps address an attack scenario in which a malicious remote peer (or several)
* feeds you invalid transactions, eg, ones that spend coins which don't exist. If you don't see most of the peers
* announce the transaction within a reasonable time, it may be that the TX is not valid. Alternatively, an attacker
* may control your entire internet connection: in this scenario counting broadcasting peers does not help you.</p>
*
* It is <b>not</b> at this time directly equivalent to the Satoshi clients memory pool, which tracks
* all transactions not currently included in the best chain - it's simply a cache.
* <p>It is <b>not</b> at this time directly equivalent to the Satoshi clients memory pool, which tracks
* all transactions not currently included in the best chain - it's simply a cache.</p>
*/
public class MemoryPool {
private static final Logger log = LoggerFactory.getLogger(MemoryPool.class);

6
core/src/main/java/com/google/bitcoin/core/Message.java
View File

@ -26,11 +26,9 @@ import java.util.Arrays;
import static com.google.common.base.Preconditions.checkState;
/**
* A Message is a data structure that can be serialized/deserialized using both the BitCoin proprietary serialization
* <p>A Message is a data structure that can be serialized/deserialized using both the Bitcoin proprietary serialization
* format and built-in Java object serialization. Specific types of messages that are used both in the block chain,
* and on the wire, are derived from this class.
* <p/>
* This class is not useful for library users. If you want to talk to the network see the {@link Peer} class.
* and on the wire, are derived from this class.</p>
*/
public abstract class Message implements Serializable {
private static final Logger log = LoggerFactory.getLogger(Message.class);

7
core/src/main/java/com/google/bitcoin/core/Peer.java
View File

@ -37,7 +37,7 @@ import java.util.concurrent.*;
* <p>{@link Peer#getHandler()} is part of a Netty Pipeline with a Bitcoin serializer downstream of it.
*/
public class Peer {
public interface PeerLifecycleListener {
interface PeerLifecycleListener {
/** Called when the peer is connected */
public void onPeerConnected(Peer peer);
/** Called when the peer is disconnected */
@ -45,7 +45,6 @@ public class Peer {
}
private static final Logger log = LoggerFactory.getLogger(Peer.class);
public static final int CONNECT_TIMEOUT_MSEC = 60000;
private final NetworkParameters params;
private final BlockChain blockChain;
@ -118,11 +117,11 @@ public class Peer {
return eventListeners.remove(listener);
}
public synchronized void addLifecycleListener(PeerLifecycleListener listener) {
synchronized void addLifecycleListener(PeerLifecycleListener listener) {
lifecycleListeners.add(listener);
}
public synchronized boolean removeLifecycleListener(PeerLifecycleListener listener) {
synchronized boolean removeLifecycleListener(PeerLifecycleListener listener) {
return lifecycleListeners.remove(listener);
}

2
core/src/main/java/com/google/bitcoin/core/PeerAddress.java
View File

@ -28,7 +28,7 @@ import static com.google.bitcoin.core.Utils.uint64ToByteStreamLE;
/**
* A PeerAddress holds an IP address and port number representing the network location of
* a peer in the BitCoin P2P network. It exists primarily for serialization purposes.
* a peer in the Bitcoin P2P network. It exists primarily for serialization purposes.
*/
public class PeerAddress extends ChildMessage {
private static final long serialVersionUID = 7501293709324197411L;

12
core/src/main/java/com/google/bitcoin/core/Script.java
View File

@ -42,14 +42,16 @@ class ScriptChunk {
}
/**
* Bitcoin transactions don't specify what they do directly. Instead <a href="https://en.bitcoin.it/wiki/Script">a
* small binary stack language</a> is used to define programs that when evaluated return whether the transaction
* "accepts" or rejects the other transactions connected to it.<p>
* Instructions for redeeming a payment.
*
* BitcoinJ does not evaluate/run scripts. The reason is that doing so requires the connected transactions, ie, all
* <p>Bitcoin transactions don't specify what they do directly. Instead <a href="https://en.bitcoin.it/wiki/Script">a
* small binary stack language</a> is used to define programs that when evaluated return whether the transaction
* "accepts" or rejects the other transactions connected to it.</p>
*
* <p>bitcoinj does not evaluate/run scripts. The reason is that doing so requires the connected transactions, ie, all
* transactions, and as a lightweight/SPV client we don't store them all. Instead tx validity is decided by miners
* and we rely purely on the majority consensus to determine if the scripts are valid. This class therefore just lets
* you manipulate and parse them.
* you manipulate and parse them.</p>
*/
public class Script {
// Some constants used for decoding the scripts, copied from the reference client

17
core/src/main/java/com/google/bitcoin/core/Transaction.java
View File

@ -28,19 +28,18 @@ import java.util.*;
import static com.google.bitcoin.core.Utils.*;
/**
* A transaction represents the movement of coins from some addresses to some other addresses. It can also represent
* the minting of new coins. A Transaction object corresponds to the equivalent in the BitCoin C++ implementation.<p>
* <p>A transaction represents the movement of coins from some addresses to some other addresses. It can also represent
* the minting of new coins. A Transaction object corresponds to the equivalent in the Bitcoin C++ implementation.</p>
*
* It implements TWO serialization protocols - the Bitcoin proprietary format which is identical to the C++
* implementation and is used for reading/writing transactions to the wire and for hashing. It also implements Java
* serialization which is used for the wallet. This allows us to easily add extra fields used for our own accounting
* or UI purposes.<p>
*
* All Bitcoin transactions are at risk of being reversed, though the risk is much less than with traditional payment
* <p>Transactions are the fundamental atoms of Bitcoin and have many powerful features. Read
* <a href="http://code.google.com/p/bitcoinj/wiki/WorkingWithTransactions">"Working with transactions"</a> in the
* documentation to learn more about how to use this class.</p>
*
* <p>All Bitcoin transactions are at risk of being reversed, though the risk is much less than with traditional payment
* systems. Transactions have <i>confidence levels</i>, which help you decide whether to trust a transaction or not.
* Whether to trust a transaction is something that needs to be decided on a case by case basis - a rule that makes
* sense for selling MP3s might not make sense for selling cars, or accepting payments from a family member. If you
* are building a wallet, how to present confidence to your users is something to consider carefully.
* are building a wallet, how to present confidence to your users is something to consider carefully.</p>
*/
public class Transaction extends ChildMessage implements Serializable {
private static final Logger log = LoggerFactory.getLogger(Transaction.class);

9
core/src/main/java/com/google/bitcoin/core/TransactionConfidence.java
View File

@ -161,10 +161,13 @@ public class TransactionConfidence implements Serializable {
};
/**
* A confidence listener is informed when the level of confidence in a transaction is updated by something, like
* <p>A confidence listener is informed when the level of {@link TransactionConfidence} is updated by something, like
* for example a {@link Wallet}. You can add listeners to update your user interface or manage your order tracking
* system when confidence levels pass a certain threshold. <b>Note that confidence can go down as well as up.</b>.
* During listener execution, it's safe to remove the current listener but not others.
* system when confidence levels pass a certain threshold. <b>Note that confidence can go down as well as up.</b>
* For example, this can happen if somebody is doing a double-spend attack against you. Whilst it's unlikely, your
* code should be able to handle that in order to be correct.</p>
*
* <p>During listener execution, it's safe to remove the current listener but not others.</p>
*/
public interface Listener {
public void onConfidenceChanged(Transaction tx);

6
core/src/main/java/com/google/bitcoin/core/Wallet.java
View File

@ -40,6 +40,9 @@ import static com.google.common.base.Preconditions.*;
* it is able to create new transactions that spend the recorded transactions, and this is the fundamental operation
* of the Bitcoin protocol.</p>
*
* <p>To learn more about this class, read <b><a href="http://code.google.com/p/bitcoinj/wiki/WorkingWithTheWallet">
* working with the wallet.</a></b></p>
*
* <p>To fill up a Wallet with transactions, you need to use it in combination with a {@link BlockChain} and various
* other objects, see the <a href="http://code.google.com/p/bitcoinj/wiki/GettingStarted">Getting started</a> tutorial
* on the website to learn more about how to set everything up.</p>
@ -51,9 +54,6 @@ import static com.google.common.base.Preconditions.*;
* the wallet is changing very fast (eg due to a block chain sync). See
* {@link Wallet#autosaveToFile(java.io.File, long, java.util.concurrent.TimeUnit, com.google.bitcoin.core.Wallet.AutosaveEventListener)}
* for more information about this.</p>
*
* <p><a href="http://code.google.com/p/bitcoinj/wiki/WorkingWithTheWallet">Learn more about working with the wallet.
* </a></p>
*/
public class Wallet implements Serializable {
private static final Logger log = LoggerFactory.getLogger(Wallet.class);

6
core/src/main/java/com/google/bitcoin/core/WalletEventListener.java
View File

@ -92,17 +92,13 @@ public interface WalletEventListener {
* </ol><p>
*
* To find if the transaction is dead, you can use <tt>tx.getConfidence().getConfidenceType() ==
* TransactionConfidence.ConfidenceType.OVERRIDDEN_BY_DOUBLE_SPEND</tt>. If it is, you should notify the user
* TransactionConfidence.ConfidenceType.DEAD</tt>. If it is, you should notify the user
* in some way so they know the thing they bought may not arrive/the thing they sold should not be dispatched.
*
* @param wallet
* @param tx
*/
void onTransactionConfidenceChanged(Wallet wallet, Transaction tx);
/**
* Called by the {@link Wallet#addKey(ECKey)} method on whatever the calling thread was.
* @param key
*/
void onKeyAdded(ECKey key);
}