feat: extend informations returned by GET /stamps (#2051)

On top of the current information, the returned data are
extended by: label, depth, amount, bucketDepth,
blockNumber, and immutableFlag.

go.mod

@@ -57,6 +57,7 @@ require (
 	github.com/syndtr/goleveldb v1.0.1-0.20200815110645-5c35d600f0ca
 	github.com/uber/jaeger-client-go v2.24.0+incompatible
 	github.com/uber/jaeger-lib v2.2.0+incompatible // indirect
+	github.com/vmihailenco/msgpack/v5 v5.3.4
 	github.com/wealdtech/go-ens/v3 v3.4.4
 	gitlab.com/nolash/go-mockbytes v0.0.7
 	go.opencensus.io v0.22.5 // indirect

go.sum

@@ -941,6 +941,10 @@ github.com/ugorji/go/codec v0.0.0-20181204163529-d75b2dcb6bc8/go.mod h1:VFNgLljT
 github.com/urfave/cli v1.22.1/go.mod h1:Gos4lmkARVdJ6EkW0WaNv/tZAAMe9V7XWyB60NtXRu0=
 github.com/viant/assertly v0.4.8/go.mod h1:aGifi++jvCrUaklKEKT0BU95igDNaqkvz+49uaYMPRU=
 github.com/viant/toolbox v0.24.0/go.mod h1:OxMCG57V0PXuIP2HNQrtJf2CjqdmbrOx5EkMILuUhzM=
+github.com/vmihailenco/msgpack/v5 v5.3.4 h1:qMKAwOV+meBw2Y8k9cVwAy7qErtYCwBzZ2ellBfvnqc=
+github.com/vmihailenco/msgpack/v5 v5.3.4/go.mod h1:7xyJ9e+0+9SaZT0Wt1RGleJXzli6Q/V5KbhBonMG9jc=
+github.com/vmihailenco/tagparser/v2 v2.0.0 h1:y09buUbR+b5aycVFQs/g70pqKVZNBmxwAhO7/IwNM9g=
+github.com/vmihailenco/tagparser/v2 v2.0.0/go.mod h1:Wri+At7QHww0WTrCBeu4J6bNtoV6mEfg5OIWRZA9qds=
 github.com/wealdtech/go-ens/v3 v3.4.4 h1:rgfjBqKj7L9ipVJOo/9XTQTKMcVERvxJpQBNUcIOnhs=
 github.com/wealdtech/go-ens/v3 v3.4.4/go.mod h1:X1ORiTz78XpHIhDATM1yZR9jxBPnV83mdX5Ty53IRb8=
 github.com/wealdtech/go-multicodec v1.2.0 h1:9AHSxcSE9F9r6ZvQLAO0EXCdM08QfYohaXmW3k6sSh4=

openapi/SwarmCommon.yaml

@@ -321,6 +321,18 @@ components:
           type: integer
         usable:
           type: boolean
+        label:
+          type: string
+        depth:
+          type: integer
+        amount:
+          $ref: "#/components/schemas/BigInt"
+        bucketDepth:
+          type: integer
+        blockNumber:
+          type: integer
+        immutableFlag:
+          type: boolean
 
     Settlement:
       type: object

pkg/api/api_test.go

@@ -11,6 +11,7 @@ import (
 	"errors"
 	"io"
 	"io/ioutil"
+	"math/big"
 	"net/http"
 	"net/http/httptest"
 	"net/url"
@@ -267,7 +268,7 @@ func TestPostageHeaderError(t *testing.T) {
 		mockStorer     = mock.NewStorer()
 		mockStatestore = statestore.NewStateStore()
 		logger         = logging.New(ioutil.Discard, 5)
-		mp             = mockpost.New(mockpost.WithIssuer(postage.NewStampIssuer("", "", batchOk, 11, 10, 1000)))
+		mp             = mockpost.New(mockpost.WithIssuer(postage.NewStampIssuer("", "", batchOk, big.NewInt(3), 11, 10, 1000, true)))
 		client, _, _   = newTestServer(t, testServerOptions{
 			Storer: mockStorer,
 			Tags:   tags.NewTags(mockStatestore, logger),

pkg/api/feed_test.go

@@ -12,6 +12,7 @@ import (
 	"errors"
 	"fmt"
 	"io/ioutil"
+	"math/big"
 	"net/http"
 	"testing"
 
@@ -154,7 +155,7 @@ func TestFeed_Post(t *testing.T) {
 		logger         = logging.New(ioutil.Discard, 0)
 		tag            = tags.NewTags(mockStatestore, logger)
 		topic          = "aabbcc"
-		mp             = mockpost.New(mockpost.WithIssuer(postage.NewStampIssuer("", "", batchOk, 11, 10, 1000)))
+		mp             = mockpost.New(mockpost.WithIssuer(postage.NewStampIssuer("", "", batchOk, big.NewInt(3), 11, 10, 1000, true)))
 		mockStorer     = mock.NewStorer()
 		client, _, _   = newTestServer(t, testServerOptions{
 			Storer: mockStorer,

pkg/api/postage.go

@@ -12,6 +12,7 @@ import (
 	"net/http"
 	"strconv"
 
+	"github.com/ethersphere/bee/pkg/bigint"
 	"github.com/ethersphere/bee/pkg/jsonhttp"
 	"github.com/ethersphere/bee/pkg/postage/postagecontract"
 	"github.com/ethersphere/bee/pkg/sctx"
@@ -100,22 +101,32 @@ type postageStampResponse struct {
 	BatchID       batchID        `json:"batchID"`
 	Utilization   uint32         `json:"utilization"`
 	Usable        bool           `json:"usable"`
+	Label         string         `json:"label"`
+	Depth         uint8          `json:"depth"`
+	Amount        *bigint.BigInt `json:"amount"`
+	BucketDepth   uint8          `json:"bucketDepth"`
+	BlockNumber   uint64         `json:"blockNumber"`
+	ImmutableFlag bool           `json:"immutableFlag"`
 }
 
 type postageStampsResponse struct {
 	Stamps []postageStampResponse `json:"stamps"`
 }
 
-func (s *server) postageGetStampsHandler(w http.ResponseWriter, r *http.Request) {
-	issuers := s.post.StampIssuers()
+func (s *server) postageGetStampsHandler(w http.ResponseWriter, _ *http.Request) {
 	resp := postageStampsResponse{}
-	for _, v := range issuers {
-		issuer := postageStampResponse{
+	for _, v := range s.post.StampIssuers() {
+		resp.Stamps = append(resp.Stamps, postageStampResponse{
 			BatchID:       v.ID(),
 			Utilization:   v.Utilization(),
 			Usable:        s.post.IssuerUsable(v),
-		}
-		resp.Stamps = append(resp.Stamps, issuer)
+			Label:         v.Label(),
+			Depth:         v.Depth(),
+			Amount:        bigint.Wrap(v.Amount()),
+			BucketDepth:   v.BucketDepth(),
+			BlockNumber:   v.BlockNumber(),
+			ImmutableFlag: v.ImmutableFlag(),
+		})
 	}
 	jsonhttp.OK(w, resp)
 }
@@ -146,6 +157,12 @@ func (s *server) postageGetStampHandler(w http.ResponseWriter, r *http.Request)
 		BatchID:       id,
 		Utilization:   issuer.Utilization(),
 		Usable:        s.post.IssuerUsable(issuer),
+		Label:         issuer.Label(),
+		Depth:         issuer.Depth(),
+		Amount:        bigint.Wrap(issuer.Amount()),
+		BucketDepth:   issuer.BucketDepth(),
+		BlockNumber:   issuer.BlockNumber(),
+		ImmutableFlag: issuer.ImmutableFlag(),
 	}
 	jsonhttp.OK(w, &resp)
 }

pkg/api/postage_test.go

@@ -14,6 +14,7 @@ import (
 	"testing"
 
 	"github.com/ethersphere/bee/pkg/api"
+	"github.com/ethersphere/bee/pkg/bigint"
 	"github.com/ethersphere/bee/pkg/jsonhttp"
 	"github.com/ethersphere/bee/pkg/jsonhttp/jsonhttptest"
 	"github.com/ethersphere/bee/pkg/postage"
@@ -192,7 +193,8 @@ func TestPostageCreateStamp(t *testing.T) {
 }
 
 func TestPostageGetStamps(t *testing.T) {
-	mp := mockpost.New(mockpost.WithIssuer(postage.NewStampIssuer("", "", batchOk, 11, 10, 1000)))
+	si := postage.NewStampIssuer("", "", batchOk, big.NewInt(3), 11, 10, 1000, true)
+	mp := mockpost.New(mockpost.WithIssuer(si))
 	client, _, _ := newTestServer(t, testServerOptions{Post: mp})
 
 	jsonhttptest.Request(t, client, http.MethodGet, "/stamps", http.StatusOK,
@@ -200,8 +202,14 @@ func TestPostageGetStamps(t *testing.T) {
 			Stamps: []api.PostageStampResponse{
 				{
 					BatchID:       batchOk,
-					Utilization: 0,
+					Utilization:   si.Utilization(),
 					Usable:        true,
+					Label:         si.Label(),
+					Depth:         si.Depth(),
+					Amount:        bigint.Wrap(si.Amount()),
+					BucketDepth:   si.BucketDepth(),
+					BlockNumber:   si.BlockNumber(),
+					ImmutableFlag: si.ImmutableFlag(),
 				},
 			},
 		}),
@@ -209,15 +217,22 @@ func TestPostageGetStamps(t *testing.T) {
 }
 
 func TestPostageGetStamp(t *testing.T) {
-	mp := mockpost.New(mockpost.WithIssuer(postage.NewStampIssuer("", "", batchOk, 11, 10, 1000)))
+	si := postage.NewStampIssuer("", "", batchOk, big.NewInt(3), 11, 10, 1000, true)
+	mp := mockpost.New(mockpost.WithIssuer(si))
 	client, _, _ := newTestServer(t, testServerOptions{Post: mp})
 
 	t.Run("ok", func(t *testing.T) {
 		jsonhttptest.Request(t, client, http.MethodGet, "/stamps/"+batchOkStr, http.StatusOK,
 			jsonhttptest.WithExpectedJSONResponse(&api.PostageStampResponse{
 				BatchID:       batchOk,
-				Utilization: 0,
+				Utilization:   si.Utilization(),
 				Usable:        true,
+				Label:         si.Label(),
+				Depth:         si.Depth(),
+				Amount:        bigint.Wrap(si.Amount()),
+				BucketDepth:   si.BucketDepth(),
+				BlockNumber:   si.BlockNumber(),
+				ImmutableFlag: si.ImmutableFlag(),
 			}),
 		)
 	})

pkg/api/pss_test.go

@@ -11,6 +11,7 @@ import (
 	"encoding/hex"
 	"fmt"
 	"io/ioutil"
+	"math/big"
 	"net/http"
 	"net/url"
 	"sync"
@@ -185,7 +186,7 @@ func TestPssSend(t *testing.T) {
 			mtx.Unlock()
 			return err
 		}
-		mp           = mockpost.New(mockpost.WithIssuer(postage.NewStampIssuer("", "", batchOk, 11, 10, 1000)))
+		mp           = mockpost.New(mockpost.WithIssuer(postage.NewStampIssuer("", "", batchOk, big.NewInt(3), 11, 10, 1000, true)))
 		p            = newMockPss(sendFn)
 		client, _, _ = newTestServer(t, testServerOptions{
 			Pss:    p,

pkg/api/soc_test.go

@@ -9,6 +9,7 @@ import (
 	"encoding/hex"
 	"fmt"
 	"io/ioutil"
+	"math/big"
 	"net/http"
 	"testing"
 
@@ -32,7 +33,7 @@ func TestSOC(t *testing.T) {
 		mockStatestore = statestore.NewStateStore()
 		logger         = logging.New(ioutil.Discard, 0)
 		tag            = tags.NewTags(mockStatestore, logger)
-		mp             = mockpost.New(mockpost.WithIssuer(postage.NewStampIssuer("", "", batchOk, 11, 10, 1000)))
+		mp             = mockpost.New(mockpost.WithIssuer(postage.NewStampIssuer("", "", batchOk, big.NewInt(3), 11, 10, 1000, true)))
 		mockStorer     = mock.NewStorer()
 		client, _, _   = newTestServer(t, testServerOptions{
 			Storer: mockStorer,

pkg/postage/batch.go

@@ -23,7 +23,7 @@ type Batch struct {
 
 // MarshalBinary implements BinaryMarshaller. It will attempt to serialize the
 // postage batch to a byte slice.
-// serialised as ID(32)|big endian value(32)|start block(8)|owner addr(20)|bucketDepth(1)|depth(1)|immutable(1)
+// serialised as ID(32)|big endian value(32)|start block(8)|owner addr(20)|BucketDepth(1)|depth(1)|immutable(1)
 func (b *Batch) MarshalBinary() ([]byte, error) {
 	out := make([]byte, 95)
 	copy(out, b.ID)

pkg/postage/mock/service.go

@@ -6,6 +6,7 @@ package mock
 
 import (
 	"errors"
+	"math/big"
 
 	"github.com/ethersphere/bee/pkg/postage"
 )
@@ -54,7 +55,7 @@ func (m *mockPostage) StampIssuers() []*postage.StampIssuer {
 
 func (m *mockPostage) GetStampIssuer(id []byte) (*postage.StampIssuer, error) {
 	if m.acceptAll {
-		return postage.NewStampIssuer("test fallback", "test identity", id, 24, 6, 1000), nil
+		return postage.NewStampIssuer("test fallback", "test identity", id, big.NewInt(3), 24, 6, 1000, true), nil
 	}
 
 	if m.i != nil {

pkg/postage/postagecontract/contract.go

@@ -190,9 +190,11 @@ func (c *postageContract) CreateBatch(ctx context.Context, initialBalance *big.I
 				label,
 				c.owner.Hex(),
 				batchID,
-				depth,
+				initialBalance,
+				createdEvent.Depth,
 				createdEvent.BucketDepth,
 				ev.BlockNumber,
+				createdEvent.ImmutableFlag,
 			))
 
 			return createdEvent.BatchId[:], nil

pkg/postage/service.go

@@ -94,7 +94,7 @@ func (ps *service) IssuerUsable(st *StampIssuer) bool {
 	// the batch creation, before we start using a stamp issuer. The threshold
 	// is meant to allow enough time for upstream peers to see the batch and
 	// hence validate the stamps issued
-	if cs.Block < st.blockNumber || (cs.Block-st.blockNumber) < blockThreshold {
+	if cs.Block < st.data.BlockNumber || (cs.Block-st.data.BlockNumber) < blockThreshold {
 		return false
 	}
 	return true
@@ -105,7 +105,7 @@ func (ps *service) GetStampIssuer(batchID []byte) (*StampIssuer, error) {
 	ps.lock.Lock()
 	defer ps.lock.Unlock()
 	for _, st := range ps.issuers {
-		if bytes.Equal(batchID, st.batchID) {
+		if bytes.Equal(batchID, st.data.BatchID) {
 			if !ps.IssuerUsable(st) {
 				return nil, ErrNotUsable
 			}

pkg/postage/service_test.go

@@ -7,6 +7,7 @@ package postage_test
 import (
 	crand "crypto/rand"
 	"io"
+	"math/big"
 	"reflect"
 	"testing"
 
@@ -75,11 +76,12 @@ func TestGetStampIssuer(t *testing.T) {
 		if i == 0 {
 			continue
 		}
-		if i < 4 {
-			ps.Add(postage.NewStampIssuer(string(id), "", id, 16, 8, validBlockNumber))
-		} else {
-			ps.Add(postage.NewStampIssuer(string(id), "", id, 16, 8, validBlockNumber+uint64(i)))
+
+		var shift uint64 = 0
+		if i > 3 {
+			shift = uint64(i)
 		}
+		ps.Add(postage.NewStampIssuer(string(id), "", id, big.NewInt(3), 16, 8, validBlockNumber+shift, true))
 	}
 	t.Run("found", func(t *testing.T) {
 		for _, id := range ids[1:4] {

pkg/postage/stamp_test.go

@@ -6,6 +6,7 @@ package postage_test
 
 import (
 	"bytes"
+	"math/big"
 	"testing"
 
 	"github.com/ethersphere/bee/pkg/crypto"
@@ -74,7 +75,7 @@ func TestValidStamp(t *testing.T) {
 	b := postagetesting.MustNewBatch(postagetesting.WithOwner(owner))
 	bs := mock.New(mock.WithBatch(b))
 	signer := crypto.NewDefaultSigner(privKey)
-	issuer := postage.NewStampIssuer("label", "keyID", b.ID, b.Depth, b.BucketDepth, 1000)
+	issuer := postage.NewStampIssuer("label", "keyID", b.ID, big.NewInt(3), b.Depth, b.BucketDepth, 1000, true)
 	stamper := postage.NewStamper(issuer, signer)
 
 	// this creates a chunk with a mocked stamp. ValidStamp will override this

pkg/postage/stamper.go

@@ -43,7 +43,7 @@ func (st *stamper) Stamp(addr swarm.Address) (*Stamp, error) {
 		return nil, err
 	}
 	ts := timestamp()
-	toSign, err := toSignDigest(addr.Bytes(), st.issuer.batchID, index, ts)
+	toSign, err := toSignDigest(addr.Bytes(), st.issuer.data.BatchID, index, ts)
 	if err != nil {
 		return nil, err
 	}
@@ -51,7 +51,7 @@ func (st *stamper) Stamp(addr swarm.Address) (*Stamp, error) {
 	if err != nil {
 		return nil, err
 	}
-	return NewStamp(st.issuer.batchID, index, ts, sig), nil
+	return NewStamp(st.issuer.data.BatchID, index, ts, sig), nil
 }
 
 func timestamp() []byte {

pkg/postage/stamper_test.go

@@ -8,6 +8,7 @@ import (
 	crand "crypto/rand"
 	"errors"
 	"io"
+	"math/big"
 	"testing"
 
 	"github.com/ethersphere/bee/pkg/crypto"
@@ -90,8 +91,7 @@ func TestStamperStamping(t *testing.T) {
 	// tests that Stamps returns with postage.ErrBucketFull iff
 	// issuer has the corresponding collision bucket filled]
 	t.Run("bucket full", func(t *testing.T) {
-		st := newTestStampIssuer(t, 1000)
-		st = postage.NewStampIssuer("", "", st.ID(), 12, 8, 1000)
+		st := postage.NewStampIssuer("", "", newTestStampIssuer(t, 1000).ID(), big.NewInt(3), 12, 8, 1000, true)
 		stamper := postage.NewStamper(st, signer)
 		// issue 1 stamp
 		chunkAddr, _ := createStamp(t, stamper)

pkg/postage/stampissuer.go

@@ -6,55 +6,71 @@ package postage
 
 import (
 	"encoding/binary"
+	"math/big"
 	"sync"
 
 	"github.com/ethersphere/bee/pkg/swarm"
+	"github.com/vmihailenco/msgpack/v5"
 )
 
+// stampIssuerData groups related StampIssuer data.
+// The data are factored out in order to make
+// serialization/deserialization easier and at the same
+// time not to export the fields outside of the package.
+type stampIssuerData struct {
+	Label          string   `msgpack:"label"`          // Label to identify the batch period/importance.
+	KeyID          string   `msgpack:"keyID"`          // Owner identity.
+	BatchID        []byte   `msgpack:"batchID"`        // The batch stamps are issued from.
+	BatchAmount    *big.Int `msgpack:"batchAmount"`    // Amount paid for the batch.
+	BatchDepth     uint8    `msgpack:"batchDepth"`     // Batch depth: batch size = 2^{depth}.
+	BucketDepth    uint8    `msgpack:"bucketDepth"`    // Bucket depth: the depth of collision Buckets uniformity.
+	Buckets        []uint32 `msgpack:"buckets"`        // Collision Buckets: counts per neighbourhoods (limited to 2^{batchdepth-bucketdepth}).
+	MaxBucketCount uint32   `msgpack:"maxBucketCount"` // the count of the fullest bucket
+	BlockNumber    uint64   `msgpack:"blockNumber"`    // BlockNumber when this batch was created
+	ImmutableFlag  bool     `msgpack:"immutableFlag"`  // Specifies immutability of the created batch.
+}
+
 // StampIssuer is a local extension of a batch issuing stamps for uploads.
 // A StampIssuer instance extends a batch with bucket collision tracking
 // embedded in multiple Stampers, can be used concurrently.
 type StampIssuer struct {
-	label          string     // Label to identify the batch period/importance.
-	keyID          string     // Owner identity.
-	batchID        []byte     // The batch stamps are issued from.
-	batchDepth     uint8      // Batch depth: batch size = 2^{depth}.
-	bucketDepth    uint8      // Bucket depth: the depth of collision buckets uniformity.
-	mu             sync.Mutex // Mutex for buckets.
-	buckets        []uint32   // Collision buckets: counts per neighbourhoods (limited to 2^{batchdepth-bucketdepth}).
-	maxBucketCount uint32     // the count of the fullest bucket
-	blockNumber    uint64     // blockNumber when this batch was created
+	bucketMu sync.Mutex
+	data     stampIssuerData
 }
 
 // NewStampIssuer constructs a StampIssuer as an extension of a batch for local
 // upload.
 //
-// bucketDepth must always be smaller than batchDepth otherwise inc() panics.
-func NewStampIssuer(label, keyID string, batchID []byte, batchDepth, bucketDepth uint8, blockNumber uint64) *StampIssuer {
+// BucketDepth must always be smaller than batchDepth otherwise inc() panics.
+func NewStampIssuer(label, keyID string, batchID []byte, batchAmount *big.Int, batchDepth, bucketDepth uint8, blockNumber uint64, immutableFlag bool) *StampIssuer {
 	return &StampIssuer{
-		label:       label,
-		keyID:       keyID,
-		batchID:     batchID,
-		batchDepth:  batchDepth,
-		bucketDepth: bucketDepth,
-		buckets:     make([]uint32, 1<<bucketDepth),
-		blockNumber: blockNumber,
+		data: stampIssuerData{
+			Label:         label,
+			KeyID:         keyID,
+			BatchID:       batchID,
+			BatchAmount:   batchAmount,
+			BatchDepth:    batchDepth,
+			BucketDepth:   bucketDepth,
+			Buckets:       make([]uint32, 1<<bucketDepth),
+			BlockNumber:   blockNumber,
+			ImmutableFlag: immutableFlag,
+		},
 	}
 }
 
 // inc increments the count in the correct collision bucket for a newly stamped
 // chunk with address addr.
-func (st *StampIssuer) inc(addr swarm.Address) ([]byte, error) {
-	st.mu.Lock()
-	defer st.mu.Unlock()
-	b := toBucket(st.bucketDepth, addr)
-	bucketCount := st.buckets[b]
-	if bucketCount == 1<<(st.batchDepth-st.bucketDepth) {
+func (si *StampIssuer) inc(addr swarm.Address) ([]byte, error) {
+	si.bucketMu.Lock()
+	defer si.bucketMu.Unlock()
+	b := toBucket(si.BucketDepth(), addr)
+	bucketCount := si.data.Buckets[b]
+	if bucketCount == 1<<(si.Depth()-si.BucketDepth()) {
 		return nil, ErrBucketFull
 	}
-	st.buckets[b]++
-	if st.buckets[b] > st.maxBucketCount {
-		st.maxBucketCount = st.buckets[b]
+	si.data.Buckets[b]++
+	if si.data.Buckets[b] > si.data.MaxBucketCount {
+		si.data.MaxBucketCount = si.data.Buckets[b]
 	}
 	return indexToBytes(b, bucketCount), nil
 }
@@ -84,71 +100,57 @@ func bytesToIndex(buf []byte) (bucket, index uint32) {
 }
 
 // Label returns the label of the issuer.
-func (st *StampIssuer) Label() string {
-	return st.label
-}
-
-// MarshalBinary gives the byte slice serialisation of a StampIssuer:
-// = label[32]|keyID[32]|batchID[32]|batchDepth[1]|bucketDepth[1]|blockNumber[8]|size_0[4]|size_1[4]|....
-func (st *StampIssuer) MarshalBinary() ([]byte, error) {
-	buf := make([]byte, 32+32+32+1+1+8+4*(1<<st.bucketDepth))
-	label := []byte(st.label)
-	copy(buf[32-len(label):32], label)
-	keyID := []byte(st.keyID)
-	copy(buf[64-len(keyID):64], keyID)
-	copy(buf[64:96], st.batchID)
-	buf[96] = st.batchDepth
-	buf[97] = st.bucketDepth
-	binary.BigEndian.PutUint64(buf[98:106], st.blockNumber)
-	st.mu.Lock()
-	defer st.mu.Unlock()
-	for i, addr := range st.buckets {
-		offset := 106 + i*4
-		binary.BigEndian.PutUint32(buf[offset:offset+4], addr)
-	}
-	return buf, nil
-}
-
-// UnmarshalBinary parses a serialised StampIssuer into the receiver struct.
-func (st *StampIssuer) UnmarshalBinary(buf []byte) error {
-	st.label = toString(buf[:32])
-	st.keyID = toString(buf[32:64])
-	st.batchID = buf[64:96]
-	st.batchDepth = buf[96]
-	st.bucketDepth = buf[97]
-	st.blockNumber = binary.BigEndian.Uint64(buf[98:106])
-	st.buckets = make([]uint32, 1<<st.bucketDepth)
-	// not using lock as unmarshal is init
-	for i := range st.buckets {
-		offset := 106 + i*4
-		st.buckets[i] = binary.BigEndian.Uint32(buf[offset : offset+4])
-	}
-	return nil
+func (si *StampIssuer) Label() string {
+	return si.data.Label
 }
 
-func toString(buf []byte) string {
-	i := 0
-	var c byte
-	for i, c = range buf {
-		if c != 0 {
-			break
-		}
-	}
-	return string(buf[i:])
+// MarshalBinary implements the encoding.BinaryMarshaler interface.
+func (si *StampIssuer) MarshalBinary() ([]byte, error) {
+	return msgpack.Marshal(si.data)
+}
+
+// UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.
+func (si *StampIssuer) UnmarshalBinary(data []byte) error {
+	return msgpack.Unmarshal(data, &si.data)
 }
 
 // Utilization returns the batch utilization in the form of
 // an integer between 0 and 4294967295. Batch fullness can be
 // calculated with: max_bucket_value / 2 ^ (batch_depth - bucket_depth)
-func (st *StampIssuer) Utilization() uint32 {
-	st.mu.Lock()
-	defer st.mu.Unlock()
-	return st.maxBucketCount
+func (si *StampIssuer) Utilization() uint32 {
+	si.bucketMu.Lock()
+	defer si.bucketMu.Unlock()
+	return si.data.MaxBucketCount
 }
 
 // ID returns the BatchID for this batch.
-func (s *StampIssuer) ID() []byte {
-	id := make([]byte, len(s.batchID))
-	copy(id, s.batchID)
+func (si *StampIssuer) ID() []byte {
+	id := make([]byte, len(si.data.BatchID))
+	copy(id, si.data.BatchID)
 	return id
 }
+
+// Depth represent issued batch depth.
+func (si *StampIssuer) Depth() uint8 {
+	return si.data.BatchDepth
+}
+
+// Amount represent issued batch amount paid.
+func (si *StampIssuer) Amount() *big.Int {
+	return si.data.BatchAmount
+}
+
+// BucketDepth the depth of collision Buckets uniformity.
+func (si *StampIssuer) BucketDepth() uint8 {
+	return si.data.BucketDepth
+}
+
+// BlockNumber when this batch was created.
+func (si *StampIssuer) BlockNumber() uint64 {
+	return si.data.BlockNumber
+}
+
+// ImmutableFlag immutability of the created batch.
+func (si *StampIssuer) ImmutableFlag() bool {
+	return si.data.ImmutableFlag
+}

pkg/postage/stampissuer_test.go

@@ -7,6 +7,7 @@ package postage_test
 import (
 	crand "crypto/rand"
 	"io"
+	"math/big"
 	"reflect"
 	"testing"
 
@@ -37,5 +38,5 @@ func newTestStampIssuer(t *testing.T, block uint64) *postage.StampIssuer {
 	if err != nil {
 		t.Fatal(err)
 	}
-	return postage.NewStampIssuer("label", "keyID", id, 12, 8, block)
+	return postage.NewStampIssuer("label", "keyID", id, big.NewInt(3), 16, 8, block, true)
 }