s4

README

S4: Simple Shared Storage Service

See the corresponding CLIP describing the proposal.

Documentation

Index

• Variables
• type Constraints
• type Envelope
  • func NewEnvelopeFromRecord(key *Key, record *Record) *Envelope
  • func (e Envelope) GetSignerAddress(signature []byte) (address common.Address, err error)
  • func (e Envelope) Sign(privateKey *ecdsa.PrivateKey) (signature []byte, err error)
  • func (e Envelope) ToJson() ([]byte, error)
• type Key
• type Metadata
• type ORM
  • func NewInMemoryORM() ORM
• type Record
• type Row
  • func (r Row) Clone() *Row
• type Storage
  • func NewStorage(lggr logger.Logger, contraints Constraints, orm ORM) Storage

Variables

var (
	ErrNotFound       = errors.New("not found")
	ErrWrongSignature = errors.New("wrong signature")
	ErrSlotIdTooBig   = errors.New("slot id is too big")
	ErrPayloadTooBig  = errors.New("payload is too big")
	ErrPastExpiration = errors.New("past expiration")
	ErrVersionTooLow  = errors.New("version too low")
)

Types

type Constraints

type Constraints struct {
	MaxPayloadSizeBytes uint
	MaxSlotsPerUser     uint
}

Constraints specifies the global storage constraints.

type Envelope

type Envelope struct {
	Address    []byte `json:"address"`
	SlotID     uint   `json:"slotid"`
	Payload    []byte `json:"payload"`
	Version    uint64 `json:"version"`
	Expiration int64  `json:"expiration"`
}

Envelope represents a JSON object that is signed for address verification. All []byte values are encoded as base64 (default JSON behavior). Hex is not used to avoid confusion due to case-sensivity and 0x prefix. A signer is responsible for generating a JSON that has no whitespace and the keys appear in this exact order: {"address":base64,"slotid":int,"payload":base64,"version":int,"expiration":int}

func NewEnvelopeFromRecord

func NewEnvelopeFromRecord(key *Key, record *Record) *Envelope

func (Envelope) GetSignerAddress

func (e Envelope) GetSignerAddress(signature []byte) (address common.Address, err error)

GetSignerAddress verifies the signature and returns the signing address.

func (Envelope) Sign

func (e Envelope) Sign(privateKey *ecdsa.PrivateKey) (signature []byte, err error)

Sign calculates signature for the serialized envelope data.

func (Envelope) ToJson

func (e Envelope) ToJson() ([]byte, error)

type Key

type Key struct {
	// Address is a user address
	Address common.Address
	// SlotId is a slot number
	SlotId uint
	// Version is a data version
	Version uint64
}

Key identifies a versioned user record.

type Metadata

type Metadata struct {
	// Confirmed turns true once consensus is reached.
	Confirmed bool
	// Signature contains the original user signature.
	Signature []byte
}

Metadata is the internal S4 data associated with a Record

type ORM

type ORM interface {
	// Get reads a row for the given address and slotId.
	// If a row is missing, ErrNotFound is returned.
	// Returned row is a clone, safe to modify.
	Get(address common.Address, slotId uint, qopts ...pg.QOpt) (*Row, error)

	// Put inserts (or updates) a row identified by the specified address and slotId.
	// No validation is applied for signature, version, etc.
	// Implementation clones the given Row when persisting.
	Upsert(address common.Address, slotId uint, row *Row, qopts ...pg.QOpt) error

	// DeleteExpired deletes any entries having HighestExpiration < now().
	// The function can be called by OCR plugin on every round.
	// (shall be cheap for postgres implementation, given the right columns are indexed).
	DeleteExpired(qopts ...pg.QOpt) error
}

ORM represents S4 persistence layer. All functions are thread-safe.

func NewInMemoryORM

func NewInMemoryORM() ORM

type Record

type Record struct {
	// Arbitrary user data
	Payload []byte
	// Expiration timestamp assigned by user (unix time in milliseconds)
	Expiration int64
}

Record represents a user record persisted by S4.

type Row

type Row struct {
	Payload    []byte
	Version    uint64
	Expiration int64
	Confirmed  bool
	Signature  []byte
}

Row represents a data row persisted by ORM.

func (Row) Clone

func (r Row) Clone() *Row

type Storage

type Storage interface {
	// Constraints returns a copy of Constraints struct specified during service creation.
	// The implementation is thread-safe.
	Constraints() Constraints

	// Get returns a copy of record (with metadata) associated with the specified key.
	// The returned Record & Metadata are always a copy.
	Get(ctx context.Context, key *Key) (*Record, *Metadata, error)

	// Put creates (or updates) a record identified by the specified key.
	// For signature calculation see envelope.go
	Put(ctx context.Context, key *Key, record *Record, signature []byte) error
}

Storage represents S4 storage access interface. All functions are thread-safe.

func NewStorage

func NewStorage(lggr logger.Logger, contraints Constraints, orm ORM) Storage