github.com/googgoog/go-ethereum@v1.9.7/trie/encoding.go (about)

     1  // Copyright 2014 The go-ethereum Authors
     2  // This file is part of the go-ethereum library.
     3  //
     4  // The go-ethereum library is free software: you can redistribute it and/or modify
     5  // it under the terms of the GNU Lesser General Public License as published by
     6  // the Free Software Foundation, either version 3 of the License, or
     7  // (at your option) any later version.
     8  //
     9  // The go-ethereum library is distributed in the hope that it will be useful,
    10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
    11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    12  // GNU Lesser General Public License for more details.
    13  //
    14  // You should have received a copy of the GNU Lesser General Public License
    15  // along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
    16  
    17  package trie
    18  
    19  // Trie keys are dealt with in three distinct encodings:
    20  //
    21  // KEYBYTES encoding contains the actual key and nothing else. This encoding is the
    22  // input to most API functions.
    23  //
    24  // HEX encoding contains one byte for each nibble of the key and an optional trailing
    25  // 'terminator' byte of value 0x10 which indicates whether or not the node at the key
    26  // contains a value. Hex key encoding is used for nodes loaded in memory because it's
    27  // convenient to access.
    28  //
    29  // COMPACT encoding is defined by the Ethereum Yellow Paper (it's called "hex prefix
    30  // encoding" there) and contains the bytes of the key and a flag. The high nibble of the
    31  // first byte contains the flag; the lowest bit encoding the oddness of the length and
    32  // the second-lowest encoding whether the node at the key is a value node. The low nibble
    33  // of the first byte is zero in the case of an even number of nibbles and the first nibble
    34  // in the case of an odd number. All remaining nibbles (now an even number) fit properly
    35  // into the remaining bytes. Compact encoding is used for nodes stored on disk.
    36  
    37  func hexToCompact(hex []byte) []byte {
    38  	terminator := byte(0)
    39  	if hasTerm(hex) {
    40  		terminator = 1
    41  		hex = hex[:len(hex)-1]
    42  	}
    43  	buf := make([]byte, len(hex)/2+1)
    44  	buf[0] = terminator << 5 // the flag byte
    45  	if len(hex)&1 == 1 {
    46  		buf[0] |= 1 << 4 // odd flag
    47  		buf[0] |= hex[0] // first nibble is contained in the first byte
    48  		hex = hex[1:]
    49  	}
    50  	decodeNibbles(hex, buf[1:])
    51  	return buf
    52  }
    53  
    54  func compactToHex(compact []byte) []byte {
    55  	if len(compact) == 0 {
    56  		return compact
    57  	}
    58  	base := keybytesToHex(compact)
    59  	// delete terminator flag
    60  	if base[0] < 2 {
    61  		base = base[:len(base)-1]
    62  	}
    63  	// apply odd flag
    64  	chop := 2 - base[0]&1
    65  	return base[chop:]
    66  }
    67  
    68  func keybytesToHex(str []byte) []byte {
    69  	l := len(str)*2 + 1
    70  	var nibbles = make([]byte, l)
    71  	for i, b := range str {
    72  		nibbles[i*2] = b / 16
    73  		nibbles[i*2+1] = b % 16
    74  	}
    75  	nibbles[l-1] = 16
    76  	return nibbles
    77  }
    78  
    79  // hexToKeybytes turns hex nibbles into key bytes.
    80  // This can only be used for keys of even length.
    81  func hexToKeybytes(hex []byte) []byte {
    82  	if hasTerm(hex) {
    83  		hex = hex[:len(hex)-1]
    84  	}
    85  	if len(hex)&1 != 0 {
    86  		panic("can't convert hex key of odd length")
    87  	}
    88  	key := make([]byte, len(hex)/2)
    89  	decodeNibbles(hex, key)
    90  	return key
    91  }
    92  
    93  func decodeNibbles(nibbles []byte, bytes []byte) {
    94  	for bi, ni := 0, 0; ni < len(nibbles); bi, ni = bi+1, ni+2 {
    95  		bytes[bi] = nibbles[ni]<<4 | nibbles[ni+1]
    96  	}
    97  }
    98  
    99  // prefixLen returns the length of the common prefix of a and b.
   100  func prefixLen(a, b []byte) int {
   101  	var i, length = 0, len(a)
   102  	if len(b) < length {
   103  		length = len(b)
   104  	}
   105  	for ; i < length; i++ {
   106  		if a[i] != b[i] {
   107  			break
   108  		}
   109  	}
   110  	return i
   111  }
   112  
   113  // hasTerm returns whether a hex key has the terminator flag.
   114  func hasTerm(s []byte) bool {
   115  	return len(s) > 0 && s[len(s)-1] == 16
   116  }