Make bls a module

scripts/build_spec.py

@@ -24,12 +24,7 @@ from eth2spec.utils.ssz.ssz_typing import (
     boolean, Container, List, Vector, uint64, SSZType,
     Bytes1, Bytes4, Bytes8, Bytes32, Bytes48, Bytes96, Bitlist, Bitvector,
 )
-from eth2spec.utils.bls import (
+from eth2spec.utils import bls
-    Sign,
-    Verify,
-    Aggregate,
-    FastAggregateVerify,
-)
 
 from eth2spec.utils.hash_function import hash
 
@@ -57,12 +52,7 @@ from eth2spec.utils.ssz.ssz_typing import (
     Bytes1, Bytes4, Bytes8, Bytes32, Bytes48, Bytes96,
     uint64, bit, boolean, byte,
 )
-from eth2spec.utils.bls import (
+from eth2spec.utils import bls
-    Verify,
-    AggregateVerify,
-    FastAggregateVerify,
-    bls_signature_to_G2,
-)
 
 from eth2spec.utils.hash_function import hash
 

specs/core/0_beacon-chain.md

@@ -584,15 +584,15 @@ def bytes_to_int(data: bytes) -> uint64:
 
 #### BLS Signatures
 
-Eth2 makes use of BLS signatures as specified in the [IETF draft BLS specification](https://tools.ietf.org/html/draft-irtf-cfrg-bls-signature-00).
+Eth2 makes use of BLS signatures as specified in the [IETF draft BLS specification](https://tools.ietf.org/html/draft-irtf-cfrg-bls-signature-00). Specifically, eth2 uses the `BLS_SIG_BLS12381G2-SHA256-SSWU-RO-_POP_` ciphersuite which implements the following interfaces:
-
-Specifically, eth2 uses the `BLS_SIG_BLS12381G2-SHA256-SSWU-RO-_POP_` ciphersuite where it makes use of the following functions:
 
 * `def Sign(SK: int, message: Bytes) -> BLSSignature`
 * `def Verify(PK: BLSPubkey, message: Bytes, signature: BLSSignature) -> bool`
 * `def Aggregate(signatures: Sequence[BLSSignature]) -> BLSSignature`
 * `def FastAggregateVerify(PKs: Sequence[BLSSignature], message: Bytes, signature: BLSSignature) -> bool`
 
+Within these specifications, BLS signatures are treated as a module for notational clarity, thus to verify a signature `bls.Verify(...)` is used.
+
 ### Predicates
 
 #### `is_active_validator`
@@ -677,7 +677,7 @@ def is_valid_indexed_attestation(state: BeaconState, indexed_attestation: Indexe
     pubkeys = [state.validators[i].pubkey for i in indices]
     domain = get_domain(state, DOMAIN_BEACON_ATTESTER, indexed_attestation.data.target.epoch)
     message = compute_domain_wrapper_root(indexed_attestation.data, domain)
-    return FastAggregateVerify(pubkeys, message, indexed_attestation.signature)
+    return bls.FastAggregateVerify(pubkeys, message, indexed_attestation.signature)
 ```
 
 #### `is_valid_merkle_branch`
@@ -1149,7 +1149,7 @@ def state_transition(state: BeaconState, signed_block: SignedBeaconBlock, valida
 def verify_block_signature(state: BeaconState, signed_block: SignedBeaconBlock) -> bool:
     proposer = state.validators[get_beacon_proposer_index(state)]
     message = compute_domain_wrapper_root(signed_block.message, get_domain(state, DOMAIN_BEACON_PROPOSER))
-    return Verify(proposer.pubkey, message, signed_block.signature)
+    return bls.Verify(proposer.pubkey, message, signed_block.signature)
 ```
 
 ```python
@@ -1449,7 +1449,7 @@ def process_randao(state: BeaconState, body: BeaconBlockBody) -> None:
     # Verify RANDAO reveal
     proposer = state.validators[get_beacon_proposer_index(state)]
     message = compute_domain_wrapper_root(epoch, get_domain(state, DOMAIN_RANDAO))
-    assert Verify(proposer.pubkey, message, body.randao_reveal)
+    assert bls.Verify(proposer.pubkey, message, body.randao_reveal)
     # Mix in RANDAO reveal
     mix = xor(get_randao_mix(state, epoch), hash(body.randao_reveal))
     state.randao_mixes[epoch % EPOCHS_PER_HISTORICAL_VECTOR] = mix
@@ -1498,7 +1498,7 @@ def process_proposer_slashing(state: BeaconState, proposer_slashing: ProposerSla
     for signed_header in (proposer_slashing.signed_header_1, proposer_slashing.signed_header_2):
         domain = get_domain(state, DOMAIN_BEACON_PROPOSER, compute_epoch_at_slot(signed_header.message.slot))
         message = compute_domain_wrapper_root(signed_header.message, domain)
-        assert Verify(proposer.pubkey, message, signed_header.signature)
+        assert bls.Verify(proposer.pubkey, message, signed_header.signature)
 
     slash_validator(state, proposer_slashing.proposer_index)
 ```
@@ -1581,7 +1581,7 @@ def process_deposit(state: BeaconState, deposit: Deposit) -> None:
             withdrawal_credentials=deposit.data.withdrawal_credentials,
             amount=deposit.data.amount)
         message = compute_domain_wrapper_root(deposit_message, compute_domain(DOMAIN_DEPOSIT))
-        if not Verify(pubkey, message, deposit.data.signature):
+        if not bls.Verify(pubkey, message, deposit.data.signature):
             return
 
         # Add validator and balance entries
@@ -1618,7 +1618,7 @@ def process_voluntary_exit(state: BeaconState, signed_voluntary_exit: SignedVolu
     # Verify signature
     domain = get_domain(state, DOMAIN_VOLUNTARY_EXIT, voluntary_exit.epoch)
     message = compute_domain_wrapper_root(voluntary_exit, domain)
-    assert Verify(validator.pubkey, message, signed_voluntary_exit.signature)
+    assert bls.Verify(validator.pubkey, message, signed_voluntary_exit.signature)
     # Initiate exit
     initiate_validator_exit(state, voluntary_exit.validator_index)
 ```

specs/core/1_custody-game.md

@@ -353,7 +353,7 @@ def custody_subchunkify(bytez: bytes) -> Sequence[bytes]:
 
 ```python
 def get_custody_chunk_bit(key: BLSSignature, chunk: bytes) -> bool:
-    full_G2_element = bls_signature_to_G2(key)
+    full_G2_element = bls.signature_to_G2(key)
     s = full_G2_element[0].coeffs
     bits = [legendre_bit((i + 1) * s[i % 2] + int.from_bytes(subchunk, "little"), BLS12_381_Q)
             for i, subchunk in enumerate(custody_subchunkify(chunk))]
@@ -431,7 +431,7 @@ def process_custody_key_reveal(state: BeaconState, reveal: CustodyKeyReveal) ->
     # Verify signature
     domain = get_domain(state, DOMAIN_RANDAO, epoch_to_sign)
     message = compute_domain_wrapper_root(epoch_to_sign, domain)
-    assert Verify(revealer.pubkey, message, reveal.reveal)
+    assert bls.Verify(revealer.pubkey, message, reveal.reveal)
 
     # Decrement max reveal lateness if response is timely
     if epoch_to_sign + EPOCHS_PER_CUSTODY_PERIOD >= get_current_epoch(state):
@@ -485,7 +485,7 @@ def process_early_derived_secret_reveal(state: BeaconState, reveal: EarlyDerived
     messages = [compute_domain_wrapper_root(message, domain)
                 for message in [hash_tree_root(reveal.epoch), reveal.mask]]
 
-    assert AggregateVerify(pubkeys, messages, reveal.reveal)
+    assert bls.AggregateVerify(pubkeys, messages, reveal.reveal)
 
     if reveal.epoch >= get_current_epoch(state) + CUSTODY_PERIOD_TO_RANDAO_PADDING:
         # Full slashing when the secret was revealed so early it may be a valid custody
@@ -582,7 +582,7 @@ def process_bit_challenge(state: BeaconState, challenge: CustodyBitChallenge) ->
     challenger = state.validators[challenge.challenger_index]
     domain = get_domain(state, DOMAIN_CUSTODY_BIT_CHALLENGE, get_current_epoch(state))
     # TODO incorrect hash-tree-root, but this changes with phase 1 PR #1483
-    assert Verify(challenger.pubkey, compute_domain_wrapper_root(challenge, domain), challenge.signature)
+    assert bls.Verify(challenger.pubkey, compute_domain_wrapper_root(challenge, domain), challenge.signature)
     # Verify challenger is slashable
     assert is_slashable_validator(challenger, get_current_epoch(state))
     # Verify attestation
@@ -606,7 +606,7 @@ def process_bit_challenge(state: BeaconState, challenge: CustodyBitChallenge) ->
         challenge.responder_index,
     )
     domain = get_domain(state, DOMAIN_RANDAO, epoch_to_sign)
-    assert Verify(responder.pubkey, compute_domain_wrapper_root(epoch_to_sign, domain), challenge.responder_key)
+    assert bls.Verify(responder.pubkey, compute_domain_wrapper_root(epoch_to_sign, domain), challenge.responder_key)
     # Verify the chunk count
     chunk_count = get_custody_chunk_count(attestation.data.crosslink)
     assert chunk_count == len(challenge.chunk_bits)

specs/core/1_shard-data-chains.md

@@ -386,7 +386,7 @@ def process_shard_block_header(beacon_state: BeaconState, shard_state: ShardStat
     assert not proposer.slashed
     # Verify proposer signature
     domain = get_domain(beacon_state, DOMAIN_SHARD_PROPOSER, compute_epoch_of_shard_slot(block.slot))
-    assert Verify(proposer.pubkey, compute_domain_wrapper_root(block, domain), block.signature)
+    assert bls.Verify(proposer.pubkey, compute_domain_wrapper_root(block, domain), block.signature)
 ```
 
 #### Attestations
@@ -408,7 +408,7 @@ def process_shard_attestations(beacon_state: BeaconState, shard_state: ShardStat
     domain = get_domain(beacon_state, DOMAIN_SHARD_ATTESTER, compute_epoch_of_shard_slot(block.slot))
     shard_attestation_data = ShardAttestationData(slot=shard_state.slot, parent_root=block.parent_root)
     message = compute_domain_wrapper_root(shard_attestation_data, domain)
-    assert FastAggregateVerify(pubkeys, message, block.attestations)
+    assert bls.FastAggregateVerify(pubkeys, message, block.attestations)
     # Proposer micro-reward
     proposer_index = get_shard_proposer_index(beacon_state, shard_state.shard, block.slot)
     reward = attestation_count * get_base_reward(beacon_state, proposer_index) // PROPOSER_REWARD_QUOTIENT

specs/light_client/sync_protocol.md

@@ -138,7 +138,7 @@ def update_memory(memory: LightClientMemory, update: LightClientUpdate) -> None:
     pubkeys = filter(lambda i: update.aggregation_bits[i], pubkeys)
     domain = compute_domain(DOMAIN_SHARD_ATTESTER, update.fork_version)
     message = compute_domain_wrapper_root(update.shard_block_root, domain)
-    assert FastAggregateVerify(pubkeys, message, update.signature)
+    assert bls.FastAggregateVerify(pubkeys, message, update.signature)
 
     # Update period committees if entering a new period
     if next_period == current_period + 1:

specs/validator/0_beacon-chain-validator.md

@@ -235,7 +235,7 @@ Set `block.body.randao_reveal = epoch_signature` where `epoch_signature` is obta
 def get_epoch_signature(state: BeaconState, block: BeaconBlock, privkey: int) -> BLSSignature:
     domain = get_domain(state, DOMAIN_RANDAO, compute_epoch_at_slot(block.slot))
     message = compute_domain_wrapper_root(compute_epoch_at_slot(block.slot), domain)
-    return Sign(privkey, message)
+    return bls.Sign(privkey, message)
 ```
 
 ##### Eth1 Data
@@ -313,7 +313,7 @@ def compute_new_state_root(state: BeaconState, block: BeaconBlock) -> Root:
 def get_block_signature(state: BeaconState, header: BeaconBlockHeader, privkey: int) -> BLSSignature:
     domain = get_domain(state, DOMAIN_BEACON_PROPOSER, compute_epoch_at_slot(header.slot))
     message = compute_domain_wrapper_root(header, domain)
-    return Sign(privkey, message)
+    return bls.Sign(privkey, message)
 ```
 
 ### Attesting
@@ -372,7 +372,7 @@ Set `attestation.signature = signed_attestation_data` where `signed_attestation_
 def get_signed_attestation_data(state: BeaconState, attestation: IndexedAttestation, privkey: int) -> BLSSignature:
     domain = get_domain(state, DOMAIN_BEACON_ATTESTER, attestation.data.target.epoch)
     message = compute_domain_wrapper_root(attestation.data, domain)
-    return Sign(privkey, message)
+    return bls.Sign(privkey, message)
 ```
 
 #### Broadcast attestation
@@ -391,7 +391,7 @@ A validator is selected to aggregate based upon the return value of `is_aggregat
 def get_slot_signature(state: BeaconState, slot: Slot, privkey: int) -> BLSSignature:
     domain = get_domain(state, DOMAIN_BEACON_ATTESTER, compute_epoch_at_slot(slot))
     message = compute_domain_wrapper_root(slot, domain)
-    return Sign(privkey, message)
+    return bls.Sign(privkey, message)
 ```
 
 ```python
@@ -422,7 +422,7 @@ Set `aggregate_attestation.signature = aggregate_signature` where `aggregate_sig
 ```python
 def get_aggregate_signature(attestations: Sequence[Attestation]) -> BLSSignature:
     signatures = [attestation.signature for attestation in attestations]
-    return Aggregate(signatures)
+    return bls.Aggregate(signatures)
 ```
 
 #### Broadcast aggregate

test_libs/pyspec/eth2spec/test/helpers/attestations.py

@@ -3,7 +3,7 @@ from typing import List
 from eth2spec.test.helpers.block import build_empty_block_for_next_slot, transition_unsigned_block, \
     build_empty_block
 from eth2spec.test.helpers.keys import privkeys
-from eth2spec.utils.bls import Sign, Aggregate
+from eth2spec.utils import bls
 from eth2spec.utils.ssz.ssz_typing import Bitlist
 
 
@@ -77,7 +77,7 @@ def sign_aggregate_attestation(spec, state, attestation_data, participants: List
                 privkey
             )
         )
-    return Aggregate(signatures)
+    return bls.Aggregate(signatures)
 
 
 def sign_indexed_attestation(spec, state, indexed_attestation):
@@ -98,7 +98,7 @@ def sign_attestation(spec, state, attestation):
 def get_attestation_signature(spec, state, attestation_data, privkey):
     domain = spec.get_domain(state, spec.DOMAIN_BEACON_ATTESTER, attestation_data.target.epoch)
     message = spec.compute_domain_wrapper_root(attestation_data, domain)
-    return Sign(privkey, message)
+    return bls.Sign(privkey, message)
 
 
 def fill_aggregate_attestation(spec, state, attestation, signed=False):

test_libs/pyspec/eth2spec/test/helpers/block.py

@@ -1,7 +1,8 @@
 from copy import deepcopy
 
 from eth2spec.test.helpers.keys import privkeys
-from eth2spec.utils.bls import Sign, only_with_bls
+from eth2spec.utils import bls
+from eth2spec.utils.bls import only_with_bls
 from eth2spec.utils.ssz.ssz_impl import hash_tree_root
 
 
@@ -30,7 +31,7 @@ def apply_randao_reveal(spec, state, block, proposer_index=None):
 
     domain = spec.get_domain(state, spec.DOMAIN_RANDAO, spec.compute_epoch_at_slot(block.slot))
     message = spec.compute_domain_wrapper_root(spec.compute_epoch_at_slot(block.slot), domain)
-    block.body.randao_reveal = Sign(privkey, message)
+    block.body.randao_reveal = bls.Sign(privkey, message)
 
 
 # Fully ignore the function if BLS is off, beacon-proposer index calculation is slow.
@@ -43,7 +44,7 @@ def apply_sig(spec, state, signed_block, proposer_index=None):
     domain = spec.get_domain(state, spec.DOMAIN_BEACON_PROPOSER, spec.compute_epoch_at_slot(block.slot))
     message = spec.compute_domain_wrapper_root(block, domain)
 
-    signed_block.signature = Sign(privkey, message)
+    signed_block.signature = bls.Sign(privkey, message)
 
 
 def sign_block(spec, state, block, proposer_index=None):

test_libs/pyspec/eth2spec/test/helpers/block_header.py

@@ -1,4 +1,4 @@
-from eth2spec.utils.bls import Sign
+from eth2spec.utils import bls
 
 
 def sign_block_header(spec, state, header, privkey):
@@ -7,5 +7,5 @@ def sign_block_header(spec, state, header, privkey):
         domain_type=spec.DOMAIN_BEACON_PROPOSER,
     )
     message = spec.compute_domain_wrapper_root(header, domain)
-    signature = Sign(privkey, message)
+    signature = bls.Sign(privkey, message)
     return spec.SignedBeaconBlockHeader(message=header, signature=signature)

test_libs/pyspec/eth2spec/test/helpers/custody.py

@@ -1,5 +1,5 @@
 from eth2spec.test.helpers.keys import privkeys
-from eth2spec.utils.bls import Sign, Aggregate
+from eth2spec.utils import bls
 from eth2spec.utils.hash_function import hash
 from eth2spec.utils.ssz.ssz_typing import Bitlist, ByteVector, Bitvector
 from eth2spec.utils.ssz.ssz_impl import chunkify, pack, hash_tree_root
@@ -19,13 +19,13 @@ def get_valid_early_derived_secret_reveal(spec, state, epoch=None):
     # Generate the secret that is being revealed
     domain = spec.get_domain(state, spec.DOMAIN_RANDAO, epoch)
     message = spec.compute_domain_wrapper_root(spec.Epoch(epoch), domain)
-    reveal = Sign(privkeys[revealed_index], message)
+    reveal = bls.Sign(privkeys[revealed_index], message)
     # Generate the mask (any random 32 bytes that don't reveal the masker's secret will do)
     mask = hash(reveal)
     # Generate masker's signature on the mask
     message = spec.compute_domain_wrapper_root(mask, domain)
-    masker_signature = Sign(privkeys[masker_index], message)
+    masker_signature = bls.Sign(privkeys[masker_index], message)
-    masked_reveal = Aggregate([reveal, masker_signature])
+    masked_reveal = bls.Aggregate([reveal, masker_signature])
 
     return spec.EarlyDerivedSecretReveal(
         revealed_index=revealed_index,
@@ -49,7 +49,7 @@ def get_valid_custody_key_reveal(spec, state, period=None):
     # Generate the secret that is being revealed
     domain = spec.get_domain(state, spec.DOMAIN_RANDAO, epoch_to_sign)
     message = spec.compute_domain_wrapper_root(spec.Epoch(epoch_to_sign), domain)
-    reveal = Sign(privkeys[revealer_index], message)
+    reveal = bls.Sign(privkeys[revealer_index], message)
     return spec.CustodyKeyReveal(
         revealer_index=revealer_index,
         reveal=reveal,
@@ -75,7 +75,7 @@ def get_valid_bit_challenge(spec, state, attestation, invalid_custody_bit=False)
     # Generate the responder key
     domain = spec.get_domain(state, spec.DOMAIN_RANDAO, epoch)
     message = spec.compute_domain_wrapper_root(spec.compute_domain_wrapper_root, domain)
-    responder_key = Sign(privkeys[responder_index], message)
+    responder_key = bls.Sign(privkeys[responder_index], message)
 
     chunk_count = spec.get_custody_chunk_count(attestation.data.crosslink)
 

test_libs/pyspec/eth2spec/test/helpers/deposits.py

@@ -1,5 +1,5 @@
 from eth2spec.test.helpers.keys import pubkeys, privkeys
-from eth2spec.utils.bls import Sign
+from eth2spec.utils import bls
 from eth2spec.utils.merkle_minimal import calc_merkle_tree_from_leaves, get_merkle_proof
 from eth2spec.utils.ssz.ssz_impl import hash_tree_root
 from eth2spec.utils.ssz.ssz_typing import List
@@ -31,7 +31,7 @@ def sign_deposit_data(spec, deposit_data, privkey, state=None):
         withdrawal_credentials=deposit_data.withdrawal_credentials,
         amount=deposit_data.amount)
     message = spec.compute_domain_wrapper_root(deposit_message, domain)
-    deposit_data.signature = Sign(privkey, message)
+    deposit_data.signature = bls.Sign(privkey, message)
 
 
 def build_deposit(spec,

test_libs/pyspec/eth2spec/test/helpers/phase1/attestations.py

@@ -1,8 +1,5 @@
 from eth2spec.test.helpers.keys import privkeys
-from eth2spec.utils.bls import (
+from eth2spec.utils import bls
-    Aggregate,
-    Sign,
-)
 
 
 def sign_shard_attestation(spec, beacon_state, shard_state, block, participants):
@@ -24,10 +21,10 @@ def sign_shard_attestation(spec, beacon_state, shard_state, block, participants)
                 privkey,
             )
         )
-    return Aggregate(signatures)
+    return bls.Aggregate(signatures)
 
 
 def get_attestation_signature(spec, beacon_state, shard_state, message_hash, block_epoch, privkey):
     domain = spec.get_domain(beacon_state, spec.DOMAIN_SHARD_ATTESTER, block_epoch)
     message = spec.compute_domain_wrapper(message_hash, domain)
-    return Sign(privkey, message)
+    return bls.Sign(privkey, message)

test_libs/pyspec/eth2spec/test/helpers/phase1/shard_block.py

@@ -1,10 +1,8 @@
 from copy import deepcopy
 
 from eth2spec.test.helpers.keys import privkeys
-from eth2spec.utils.bls import (
+from eth2spec.utils import bls
-    Sign,
+from eth2spec.utils.bls import only_with_bls
-    only_with_bls,
-)
 from eth2spec.utils.ssz.ssz_impl import (
     hash_tree_root,
 )
@@ -22,7 +20,7 @@ def sign_shard_block(spec, beacon_state, shard_state, block, proposer_index=None
     privkey = privkeys[proposer_index]
     domain = spec.get_domain(beacon_state, spec.DOMAIN_SHARD_PROPOSER, spec.compute_epoch_of_shard_slot(block.slot))
     message = spec.compute_domain_wrapper(block, domain)
-    block.signature = Sign(privkey, message)
+    block.signature = bls.Sign(privkey, message)
 
 
 def build_empty_shard_block(spec,

test_libs/pyspec/eth2spec/test/helpers/voluntary_exits.py

@@ -1,4 +1,4 @@
-from eth2spec.utils.bls import Sign
+from eth2spec.utils import bls
 
 
 def sign_voluntary_exit(spec, state, voluntary_exit, privkey):
@@ -6,5 +6,5 @@ def sign_voluntary_exit(spec, state, voluntary_exit, privkey):
     message = spec.compute_domain_wrapper_root(voluntary_exit, domain)
     return spec.SignedVoluntaryExit(
         message=voluntary_exit,
-        signature=Sign(privkey, message)
+        signature=bls.Sign(privkey, message)
     )

test_libs/pyspec/eth2spec/test/sanity/test_blocks.py

@@ -1,6 +1,6 @@
 from copy import deepcopy
 
-from eth2spec.utils.bls import Sign
+from eth2spec.utils import bls
 
 from eth2spec.test.helpers.state import get_balance, state_transition_and_sign_block, next_slot
 from eth2spec.test.helpers.block import build_empty_block_for_next_slot, build_empty_block, sign_block, \
@@ -107,7 +107,7 @@ def test_invalid_block_sig(spec, state):
     message = spec.compute_domain_wrapper_root(block, domain)
     invalid_signed_block = spec.SignedBeaconBlock(
         message=block,
-        signature=Sign(123456, message)
+        signature=bls.Sign(123456, message)
     )
     expect_assertion_error(lambda: spec.state_transition(state, invalid_signed_block))
 
@@ -416,7 +416,7 @@ def test_voluntary_exit(spec, state):
     message = spec.compute_domain_wrapper_root(voluntary_exit, domain)
     signed_voluntary_exit = spec.SignedVoluntaryExit(
         message=voluntary_exit,
-        signature=Sign(privkeys[validator_index], message)
+        signature=bls.Sign(privkeys[validator_index], message)
     )
 
     # Add to state via block transition

test_libs/pyspec/eth2spec/utils/bls.py

@@ -49,5 +49,5 @@ def Sign(SK, message):
 
 
 @only_with_bls(alt_return=STUB_COORDINATES)
-def bls_signature_to_G2(signature):
+def signature_to_G2(signature):
     return bls.api.signature_to_G2(signature)