flip/dcrd
1
0
Fork 0
mirror of https://github.com/FlipsideCrypto/dcrd.git synced 2026-02-06 10:56:47 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

gcs: Improve package documentation.

Browse Source
This commit is contained in:
Dave Collins 2019-10-07 12:28:47 -05:00
parent abe43b0928
commit 8e258be2f3
No known key found for this signature in database
GPG Key ID: B8904D9D9C93D1F2
2 changed files with 83 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
gcs/README.md
View File

@ -1,9 +1,52 @@
gcs
==========
===
[![GoDoc](https://godoc.org/github.com/decred/dcrd/gcs?status.png)](https://godoc.org/github.com/decred/dcrd/gcs)
[![Build Status](https://github.com/decred/dcrd/workflows/Build%20and%20Test/badge.svg)](https://github.com/decred/dcrd/actions)
[![ISC License](https://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org)
[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://godoc.org/github.com/decred/dcrd/gcs)
Package gcs provides an API for building and using a Golomb-coded set filter
similar to that described [here](https://giovanni.bajo.it/post/47119962313/golomb-coded-sets-smaller-than-bloom-filters).
Package gcs provides an API for building and using Golomb-coded sets.
A Golomb-Coded Set (GCS) is a space-efficient probabilistic data structure that
is used to test set membership with a tunable false positive rate while
simultaneously preventing false negatives. In other words, items that are in
the set will always match, but items that are not in the set will also sometimes
match with the chosen false positive rate.
This package currently implements two different versions for backwards
compatibility. Version 1 is deprecated and therefore should no longer be used.
Version 2 is the GCS variation that follows the specification details in
[DCP0005](https://github.com/decred/dcps/blob/master/dcp-0005/dcp-0005.mediawiki#golomb-coded-sets).
Version 2 sets do not permit empty items (data of zero length) to be added and
are parameterized by the following:
* A parameter `B` that defines the remainder code bit size
* A parameter `M` that defines the false positive rate as `1/M`
* A key for the SipHash-2-4 function
* The items to include in the set
A comprehensive suite of tests is provided to ensure proper functionality.
## GCS use in Decred
GCS is used as a mechanism for storing, transmitting, and committing to
per-block filters. Consensus-validating full nodes commit to a single filter
for every block and serve the filter to SPV clients that match against the
filter locally to determine if the block is potentially relevant. The required
parameters for Decred are defined by the blockcf2 package.
For more details, see the [Block Filters section of
DCP0005](https://github.com/decred/dcps/blob/master/dcp-0005/dcp-0005.mediawiki#block-filters).
## Installation and Updating
```bash
$ go get -u github.com/decred/dcrd/gcs
```
## License
Package blockchain is licensed under the [copyfree](http://copyfree.org) ISC
License.

50
gcs/doc.go
View File

@ -1,26 +1,48 @@
// Copyright (c) 2016-2017 The btcsuite developers
// Copyright (c) 2016-2017 The Lightning Network Developers
// Copyright (c) 2018 The Decred developers
// Copyright (c) 2018-2019 The Decred developers
// Use of this source code is governed by an ISC
// license that can be found in the LICENSE file.
/*
Package gcs provides an API for building and using a Golomb-coded set filter.
Golomb-Coded Set
A Golomb-Coded Set (GCS) is a space-efficient probabilistic data structure that
is used to test set membership with a tunable false positive rate while
simultaneously preventing false negatives. In other words, items that are in
the set will always match, but items that are not in the set will also sometimes
match with the chosen false positive rate.
A Golomb-coded set is a probabilistic data structure used similarly to a Bloom
filter. A filter uses constant-size overhead plus on average n+2 bits per item
added to the filter, where 2^-n is the desired false positive (collision)
probability.
This package currently implements two different versions for backwards
compatibility. Version 1 is deprecated and therefore should no longer be used.
Version 2 is the GCS variation that follows the specification details in
DCP0005: https://github.com/decred/dcps/blob/master/dcp-0005/dcp-0005.mediawiki#golomb-coded-sets.
Version 2 sets do not permit empty items (data of zero length) to be added and
are parameterized by the following:
* A parameter `B` that defines the remainder code bit size
* A parameter `M` that defines the false positive rate as `1/M`
* A key for the SipHash-2-4 function
* The items to include in the set
Errors
Errors returned by this package are of type gcs.Error. This allows the caller
to programmatically determine the specific error by examining the ErrorCode
field of the type asserted gcs.Error while still providing rich error messages
with contextual information. A convenience function named IsErrorCode is also
provided to allow callers to easily check for a specific error code. See
ErrorCode in the package documentation for a full list.
GCS use in Decred
GCS filters are a mechanism for storing and transmitting per-block filters. The
usage is intended to be the inverse of Bloom filters: a consensus-validating
full node commits to a single filter for every block and serves the filter to
SPV clients that match against the filter locally to determine if the block is
potentially relevant. The suggested collision probability for Decred use is
2^-20.
GCS is used as a mechanism for storing, transmitting, and committing to
per-block filters. Consensus-validating full nodes commit to a single filter
for every block and serve the filter to SPV clients that match against the
filter locally to determine if the block is potentially relevant. The required
parameters for Decred are defined by the blockcf2 package.
For more details, see the the Block Filters section of DCP0005:
https://github.com/decred/dcps/blob/master/dcp-0005/dcp-0005.mediawiki#block-filters
*/
package gcs