Skip to content

Commit

Permalink
Update docs and ReadMe
Browse files Browse the repository at this point in the history
  • Loading branch information
@AustEcon
AustEcon committed Jun 14, 2019
1 parent b06fb68 commit 915b950
Show file tree
Hide file tree
Showing 3 changed files with 120 additions and 114 deletions.
51 changes: 12 additions & 39 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,73 +36,46 @@ the **bitsv.PrivateKey** class such as checking balance, unspends, sending payme
>>> import polyglot
>>> uploader = polyglot.Upload('your private key goes here in WIF format')
>>> file = "C:/Users/username/Pictures/Ludwig_von_Mises.jpg"
>>> media_type = uploader.get_media_type_for_file_name(file) # 'image/jpeg'
>>> encoding = uploader.get_encoding_for_file_name(file) # 'binary'
>>> file_name = uploader.get_filename(file)
>>>
>>> uploader.b_send_from_file(file, media_type, encoding, file_name=file_name)
'252ea6d5a4a4bfc956518403f6e5aa2ced1c2590d1120cd75341e0233d1b06e3'
>>> # Optional parameters shown for completeness are populated from the file path by default
>>> uploader.upload_b(file, media_type=None, encoding=None, file_name=None)
See image here: https://bico.media/252ea6d5a4a4bfc956518403f6e5aa2ced1c2590d1120cd75341e0233d1b06e3

This works for a wide range of media types.

In the next release, this will be done simply with:

.. code-block:: python
>>> file = "C:/Users/username/Pictures/BSV_banner.jpg""
>>> uploader.upload_b(file)
2. Upload large multimedia > 100kb with bcat:// protocol (https://bcat.bico.media/):

.. code-block:: python
>>> file = "C:/Users/username/Pictures/BSV_banner.jpg""
>>> file_name = uploader.get_filename(file)
>>>
>>> txids = uploader.bcat_parts_send_from_file(file)
>>> txid = uploader.bcat_linker_send_from_txids(
txids=txids,
media_type=uploader.get_media_type_for_file_name(file),
encoding=uploader.get_encoding_for_file_name(file),
file_name=file
)
'be8b6a79e66934d3419265fbf3295d03e331a4c08098ae7f817a7592ffaedd2b'
>>> uploader.upload_bcat(file)
See image here: https://bico.media/be8b6a79e66934d3419265fbf3295d03e331a4c08098ae7f817a7592ffaedd2b

In the next release, this will be done simply with:

.. code-block:: python
>>> uploader.upload_bcat(file)
Please note: For BCAT protocol, it is very important to have an adequate number of "fresh" utxos with 1 confirmation to generate the parts. To do this see #3 Utilities (next).

3. Basic Utilities

Some basic utilities are included for working with utxo splitting and predicting the media type / handling of the file based on the filename.

Already shown:
Some basic utilities are included for working with utxo splitting and manually extracting the media type / handling of the file based on the file path (with extension) - to cover some potentially more advanced useage patterns of the B and BCAT protocols.

.. code-block:: python
>>> get_media_type_for_file_name(file) #--> media_type
>>> get_encoding_for_file_name(file) #--> encoding,
>>> get_filename(path) #--> file_name.ext)
>>> uploader.get_media_type_for_file_name(file) #--> media_type
>>> uploader.get_encoding_for_file_name(file) #--> encoding,
>>> uploader.get_filename(path) #--> file_name.ext)
But additionally:

.. code-block:: python
>>> Upload.get_largest_utxo(self) #--> largest utxo (for splitting)
>>> Upload.split_biggest_utxo(self) #--> splits utxo into 100000 satoshi amounts
>>> Upload.filter_utxos_for_bcat(self) #-- > filters utxos with 0 conf or too low amount to handle a 100kb tx
>>> uploader.get_largest_utxo(self) #--> largest utxo (for splitting)
>>> uploader.split_biggest_utxo(self) #--> splits utxo into 100000 satoshi amounts
>>> uploader.filter_utxos_for_bcat(self) #-- > filters utxos with 0 conf or too low amount to handle a 100kb tx
>>> get_file_ext(file) #--> .ext
>>> calculate_txid(rawtx) #--> txid
Features
--------

Expand Down
70 changes: 54 additions & 16 deletions docs/source/guide/intro.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,37 +50,75 @@ Lower barriers to entry for novice programmers and make metanet FUN!

* A PyQt5 GUI will accompany this library to lower barriers to entry even further to non-technical folk https://github.com/AustEcon/polyglotGUI

Features
--------

Features (Planned)
------------------
Currently Working:
~~~~~~~~~~~~~~~~~~

1. Uploading
~~~~~~~~~~~~
- B:// (for multimedia up to 100kb) - https://github.com/unwriter/B
- BCAT:// (for multimedia up to 310mb uncompressed, 110GB with nested gzip) - https://bcat.bico.media/
- Bottle (https://bottle.bitdb.network/) (native metanet) refs and mainstream urls for:

- B:// (ref. by txid)
- C:// (ref. by sha256 hash of content)
- D:// (ref. by dynamic state - linked to identity system)
2. UTXO management
~~~~~~~~~~~~~~~~~~
- Utilities for splitting / selecting UTXOs for a single private key - especially for use in BCAT protocol.
- Bip32 level UTXO management is also planned

Planned:
~~~~~~~~

1. HTML reference converter
~~~~~~~~~~~~~~~~~~~~~~~~~~~

A Class that will allow for easy conversion of metanet style referencing:

- B:// (ref. by txid)
- C:// (ref. by sha256 hash of content)
- D:// (ref. by dynamic state - linked to identity system)

To localhost paths or mainstream internet urls as well as toggling it all back and forth.

This will allow quick iteration of building a web application on the local machine but also rapid conversion to b://, c:// d:// etc. referencing styles for deployment to the blockchain.

Would just need a dictionary of {path : B:// reference} pairs for example to be swapped back and forth. Many other features in mind (possibly for another repository).

2. Downloading
~~~~~~~~~~~~~~
Should be able to specify content by:

- B:// (ref. by txid)
- C:// (ref. by sha256 hash of content)
- D:// (ref. by dynamic state - linked to identity system)
- Should work for content uploaded via BCAT

And have it be downloaded.

If it is a static html page then should optionally allow retreival of all referenced content to reconstruct the entire webpage on the local machine.

3. Identity protocols (Money Button, AIP etc.):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
I would like to add a very simple interface for interacting with
- AIP (https://github.com/BitcoinFiles/AUTHOR_IDENTITY_PROTOCOL)
- other ID protocols (e.g. Ryan X. Charles of Money Button has been working hard on this area)

4. "Linking / mapping / database functions":
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- MAP protocol for linking all kinds of different protocols together (powerful)
- A.N.N.E. protocol by Mr Scatmann - https://medium.com/@bsmith12251960/a-n-n-e-the-alpha-testing-begins-545f809c6129
- (maybe) A.N.N.E. protocol by Mr Scatmann - https://medium.com/@bsmith12251960/a-n-n-e-the-alpha-testing-begins-545f809c6129


Installation
------------

Polyglot *will be* distributed on `PyPI` as a universal wheel and is available on Linux/macOS
and Windows and supports Python 3.5+. ``pip`` >= 8.1.2 is required.
Polyglot is distributed on `PyPI` as a universal wheel and is available on Linux/macOS
and Windows and supports Python 3.6+. ``pip`` >= 8.1.2 is required.

.. code-block:: bash
$ pip install polyglot # pip3 if pip is Python 2 on your system.
In the meantime - you can simply clone the repository and run:

.. code-block:: bash
$ pip install polyglot-bitcoin # pip3 if pip is Python 2 on your system.
$ python setup.py install
License
-------
Expand All @@ -89,7 +127,7 @@ Polyglot is licensed under terms of the `MIT License`_.

Credits
-------
- CoinGeek for putting on an amazing hackathon from which this project was born!
- CoinGeek / nChain / Bitcoin Association for putting on an amazing hackathon from which this project was born!

Donate
--------
Expand Down
113 changes: 54 additions & 59 deletions docs/source/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,117 +34,112 @@ the **bitsv.PrivateKey** class such as checking balance, unspends, sending payme
>>> import polyglot
>>> uploader = polyglot.Upload('your private key goes here in WIF format')
>>> file = "C:/Users/username/Pictures/Ludwig_von_Mises.jpg"
>>> media_type = uploader.get_media_type_for_file_name(file) # 'image/jpeg'
>>> encoding = uploader.get_encoding_for_file_name(file) # 'binary'
>>> file_name = uploader.get_filename(file)
>>>
>>> uploader.b_send_from_file(file, media_type, encoding, file_name=file_name)
>>> # Optional parameters shown for completeness are populated from the file path by default
>>> uploader.upload_b(file, media_type=None, encoding=None, file_name=None)
See image here: https://bico.media/252ea6d5a4a4bfc956518403f6e5aa2ced1c2590d1120cd75341e0233d1b06e3

This works for a wide range of media types.

In the next release, this will be done simply with:

.. code-block:: python
>>> file = "C:/Users/username/Pictures/BSV_banner.jpg""
>>> uploader.upload_b(file)
2. Upload large multimedia > 100kb with bcat:// protocol (https://bcat.bico.media/):

.. code-block:: python
>>> file = "C:/Users/username/Pictures/BSV_banner.jpg""
>>> file_name = uploader.get_filename(file)
>>>
>>> txids = uploader.bcat_parts_send_from_file(file)
>>> txid = uploader.bcat_linker_send_from_txids(
txids=txids,
media_type=uploader.get_media_type_for_file_name(file),
encoding=uploader.get_encoding_for_file_name(file),
file_name=file
)
>>> uploader.upload_bcat(file)
See image here: https://bico.media/be8b6a79e66934d3419265fbf3295d03e331a4c08098ae7f817a7592ffaedd2b

In the next release, this will be done simply with:

.. code-block:: python
>>> uploader.upload_bcat(file)
Please note: For BCAT protocol, it is very important to have an adequate number of "fresh" utxos with 1 confirmation to generate the parts. To do this see #3 Utilities (next).

3. Basic Utilities

Some basic utilities are included for working with utxo splitting and predicting the media type / handling of the file based on the filename.

Already shown:
Some basic utilities are included for working with utxo splitting and manually extracting the media type / handling of the file based on the file path (with extension) - to cover some potentially more advanced useage patterns of the B and BCAT protocols.

.. code-block:: python
>>> get_media_type_for_file_name(file) #--> media_type
>>> get_encoding_for_file_name(file) #--> encoding,
>>> get_filename(path) #--> file_name.ext)
>>> uploader.get_media_type_for_file_name(file) #--> media_type
>>> uploader.get_encoding_for_file_name(file) #--> encoding,
>>> uploader.get_filename(path) #--> file_name.ext)
But additionally:

.. code-block:: python
>>> Upload.get_largest_utxo(self) #--> largest utxo (for splitting)
>>> Upload.split_biggest_utxo(self) #--> splits utxo into 100000 satoshi amounts
>>> Upload.filter_utxos_for_bcat(self) #-- > filters utxos with 0 conf or too low amount to handle a 100kb tx
>>> uploader.get_largest_utxo(self) #--> largest utxo (for splitting)
>>> uploader.split_biggest_utxo(self) #--> splits utxo into 100000 satoshi amounts
>>> uploader.filter_utxos_for_bcat(self) #-- > filters utxos with 0 conf or too low amount to handle a 100kb tx
>>> get_file_ext(file) #--> .ext
>>> calculate_txid(rawtx) #--> txid
Features (Planned)
------------------
Features
--------

Operational:
~~~~~~~~~~~~
Currently Working:
~~~~~~~~~~~~~~~~~~

1. Uploading
~~~~~~~~~~~~
- B:// (for multimedia up to 100kb) - https://github.com/unwriter/B
- BCAT:// (for multimedia up to 310mb uncompressed, 110GB with nested gzip) - https://bcat.bico.media/

Bottle (metanet native browser) related:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2. UTXO management
~~~~~~~~~~~~~~~~~~
- Utilities for splitting / selecting UTXOs for a single private key - especially for use in BCAT protocol.
- Bip32 level UTXO management is also planned

Bottle (https://bottle.bitdb.network/) (native metanet) refs and mainstream urls for:
Planned:
~~~~~~~~

1. HTML reference converter
~~~~~~~~~~~~~~~~~~~~~~~~~~~

A Class that will allow for easy conversion of metanet style referencing:

- B:// (ref. by txid)
- C:// (ref. by sha256 hash of content)
- D:// (ref. by dynamic state - linked to identity system)

Would like to make scripts for re-translating html document links to any of these three bitcoin resource links, so that one can quickly iterate building a web application on the local machine (and swap back and forth between local paths versus b://, c:// d:// etc. referencing style for deployment to the blockchain. (would just need a dictionary of {path : txid} pairs to be swapped back and forth. Many other features in mind (possibly for another repository).
To localhost paths or mainstream internet urls as well as toggling it all back and forth.

This will allow quick iteration of building a web application on the local machine but also rapid conversion to b://, c:// d:// etc. referencing styles for deployment to the blockchain.

Would just need a dictionary of {path : B:// reference} pairs for example to be swapped back and forth. Many other features in mind (possibly for another repository).

Identity protocols (Money Button, AIP etc.):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2. Downloading
~~~~~~~~~~~~~~
Should be able to specify content by:

- B:// (ref. by txid)
- C:// (ref. by sha256 hash of content)
- D:// (ref. by dynamic state - linked to identity system)
- Should work for content uploaded via BCAT

And have it be downloaded.

If it is a static html page then should optionally allow retreival of all referenced content to reconstruct the entire webpage on the local machine.

3. Identity protocols (Money Button, AIP etc.):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
I would like to add a very simple interface for interacting with
- AIP (https://github.com/BitcoinFiles/AUTHOR_IDENTITY_PROTOCOL)
- other ID protocols (e.g. Ryan X. Charles of Money Button has been working hard on this area)

"Linking / mapping / database functions":
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4. "Linking / mapping / database functions":
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- MAP protocol for linking all kinds of different protocols together (powerful)
- A.N.N.E. protocol by Mr Scatmann - https://medium.com/@bsmith12251960/a-n-n-e-the-alpha-testing-begins-545f809c6129
- (maybe) A.N.N.E. protocol by Mr Scatmann - https://medium.com/@bsmith12251960/a-n-n-e-the-alpha-testing-begins-545f809c6129

Installation
------------

Polyglot *will be* distributed on `PyPI` as a universal wheel and is available on Linux/macOS
and Windows and supports Python 3.5+. ``pip`` >= 8.1.2 is required.

.. code-block:: bash
$ pip install polyglot # pip3 if pip is Python 2 on your system.
In the meantime - you can simply clone the repository and run:
Polyglot is distributed on `PyPI` as a universal wheel and is available on Linux/macOS
and Windows and supports Python 3.6+. ``pip`` >= 8.1.2 is required.

.. code-block:: bash
$ python setup.py install
$ pip install polyglot-bitcoin # pip3 if pip is Python 2 on your system.
User Guide
Expand Down

0 comments on commit 915b950

Please sign in to comment.