/bitcoin.org

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Dev Docs: Detail Transaction Format #631

Merged
merged 2 commits into from Nov 7, 2014

Conversation

Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
3 participants
@harding @saivann @ysangkok
@harding
Contributor

harding commented Nov 3, 2014

Preview: http://dg0.dtrt.org/en/developer-reference#raw-transaction-format

Provides a detailed description of the transaction format, replacing an
example hexdump taken from the wiki.

I'm putting this in the transaction section as the format is necessary
for the creation of txids, which are used as merkle leaves (so are
covered by consensus rules). However, this is also the format used by
several P2P network messages to transmit transactions, so I'll be
linking back to it from there as I document those messages.
@harding
Dev Docs: Detail Transaction Format 
Provides a detailed description of the transaction format, replacing an
example hexdump taken from the wiki.

I'm putting this in the transaction section as the format is necessary
for the creation of txids, which are used as merkle leaves (so are
covered by consensus rules).  However, this is also the format used by
several P2P network messages to transmit transactions, so I'll be
linking back to it from there as I document those messages.
This commit was signed with a verified signature.
@harding harding David A. Harding
GPG key ID: 4B29C30FF29EC4B7 Learn about signing commits
0af6ef0

@saivann saivann commented on an outdated diff Nov 4, 2014

View full outdated diff
_includes/ref_transactions.md
-A sample raw transaction is the first non-coinbase transaction, made in
-[block 170][block170]. To get the transaction, use the `getrawtransaction` RPC with
-that transaction's txid (provided below):
+As of Bitcoin Core 0.9.3 (October 2014), all transactions use the
+version 1 format described below. (Note: transactions in the block chain
+are allowed to list a higher version number to permit soft forks, but
+they are treated as version 1 transactions by current software.)
+
+A raw transaction has the following top-level format:
+
+| Bytes | Name | Data Type | Description
+|----------|--------------|---------------------|-------------
+| 4 | version | uint32_t | Transaction version number; currently version 1. Programs creating transactions using newer consensus rules may use higher version numbers.
+| *Varies* | tx_in count | compactSize uint | Number of inputs in this transaction.
+| *Varies* | tx_in | *See TxIn Below* | Transaction inputs.
+| *Varies* | tx_out count | compactSize uint | Number outputs in this transaction
@saivann

saivann Nov 4, 2014

Contributor

@harding Just found a dot is missing here (or maybe it's more appropriate to only use dots with complete sentences containing a verb?)

@saivann saivann and 1 other commented on an outdated diff Nov 4, 2014

View full outdated diff
_includes/ref_transactions.md
-A sample raw transaction is the first non-coinbase transaction, made in
-[block 170][block170]. To get the transaction, use the `getrawtransaction` RPC with
-that transaction's txid (provided below):
+As of Bitcoin Core 0.9.3 (October 2014), all transactions use the
+version 1 format described below. (Note: transactions in the block chain
+are allowed to list a higher version number to permit soft forks, but
+they are treated as version 1 transactions by current software.)
+
+A raw transaction has the following top-level format:
+
+| Bytes | Name | Data Type | Description
+|----------|--------------|---------------------|-------------
+| 4 | version | uint32_t | Transaction version number; currently version 1. Programs creating transactions using newer consensus rules may use higher version numbers.
+| *Varies* | tx_in count | compactSize uint | Number of inputs in this transaction.
+| *Varies* | tx_in | *See TxIn Below* | Transaction inputs.
@saivann

saivann Nov 4, 2014

Contributor

@harding One suggestion; maybe we can only link to the subsection and keep tables short and concise by avoiding "See ... Below" for TxIn, TxOut and Outpoint?

@harding

harding Nov 4, 2014

Contributor

Links are always good; I'll add those.

I like the See Below phrasing because it maybe tells the first-time reader that they only need to continue reading this section in order and they'll get the relevant information. They don't need to click a link to what might be a completely different part of the docs, read the entry, and then come back to the table.

I don't know if it actually works that way---do you recall what you thought as you read the See Below entries versus the compactSize entries which use only links?

@saivann

saivann Nov 4, 2014

Contributor

@harding Anyway not a big deal and maybe it's just me. I just realized that I would find it clearer or more readable with a simple change;

TxIn
(See below)

Instead of:

See TxIn
Below

I expect only the Data Type information to be in the table, so when the instructions (See below) follows what I expect to find here, it's a bit easier and straightfoward IMO. Maybe we don't need a link here (or maybe a crosslink consistently with other terms?). Anyway, just a suggestion :) .
@saivann
Contributor

saivann commented Nov 4, 2014

@harding Very useful addition, thanks!
@harding
Contributor

harding commented Nov 4, 2014

@saivann thanks for the review! I meant to ask you: do you mind if I change the CSS to make all tables in the dev docs left-aligned instead of the default justified? Justified (especially in non-auto-hyphen HTML) doesn't seem to work that well in tight spaces like tables.

If you agree, I'll make that change as part of this pull and also check the preexisting tables in the docs to make sure they still look good.
@saivann
Contributor

saivann commented Nov 4, 2014

@harding I was actually about to suggest we use text-align:left; on the whole devel-docs layout (.toccontent) :) . Yes I think it is a good idea!
@harding
Change Text Alignment & Fix Some Typos 
* Replaced text justification with left-align (raggedright) for all text
  in dev docs.

    * Removed previous manual left-align in RPC byte order table

* Changed placement of See Below text partly based on a suggestion by
  @saivann (thanks!)

* Normalized capitialization of special structures (e.g. s/TxIn/txIn/)
  to be consistent with some other parts of the docs. (I don't think
  we're fully consistent on this in all parts of the docs. I'll put a
  rule in the style guide today and then we can make changes on the next
  global proofread.)

* Fixed missing period found by @saivann (thanks!) and a related missing
  preposition.
This commit was signed with a verified signature.
@harding harding David A. Harding
GPG key ID: 4B29C30FF29EC4B7 Learn about signing commits
6ae3342
@harding
Contributor

harding commented Nov 4, 2014

Made all discussed changes and updated the preview:

  • Replaced text justification with left-align (raggedright) for all text
    in dev docs.
    • Removed previous manual left-align in RPC byte order table
  • Changed placement of See Below text partly based on a suggestion by
    @saivann (thanks!)
  • Normalized capitialization of special structures (e.g. s/TxIn/txIn/)
    to be consistent with some other parts of the docs. (I don't think
    we're fully consistent on this in all parts of the docs. I'll put a
    rule in the style guide today and then we can make changes on the next
    global proofread.)
  • Fixed missing period found by @saivann (thanks!) and a related missing
    preposition.
@saivann
Contributor

saivann commented Nov 4, 2014

Thanks! I haven't researched enough to proofread the accuracy of the changes, but I couldn't find any part that raised doubts on my side, and transaction examples are very clear.

So, LGTM, as always!

I'll fix the inconsistent line-height in tables a bit later.
@harding
Contributor

harding commented Nov 6, 2014

@saivann thanks!

In the absence of critical feedback, I'll merge this pull around Friday morning UTC.

@harding harding merged commit 6ae3342 into bitcoin-dot-org:master Nov 7, 2014

harding added a commit that referenced this pull request Nov 7, 2014

@harding
Merge branch 'tx-format' (pull #631)
This commit was signed with a verified signature.
@harding harding David A. Harding
GPG key ID: 4B29C30FF29EC4B7 Learn about signing commits
fbf5448

@harding harding referenced this pull request Nov 8, 2014

Merged

Dev Docs: Describe Serialized Block Header And Block Format #638

@harding harding deleted the harding:tx-format branch Feb 25, 2015

@ysangkok

ysangkok commented on _includes/ref_transactions.md in 0af6ef0 Jun 24, 2017

why is this signed? it is non-negative according to 'Transaction' in the wiki
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment