oracle

README

Oracle Module

x/oracle provides a way to receive external information(real world price, events from other chains, etc.) with validators' vote. Each validator make transaction which contains those informations, and Oracle aggregates them until the supermajority signed on it. After then, Oracle sends the information to the actual module that processes the information, and prune the votes from the state.

Integration

See x/oracle/oracle_test.go for the code that using Oracle

To use Oracle in your module, first define a payload. It should implement oracle.Payload and contain nessesary information for your module. Including nonce is recommended.

type MyPayload struct {
    Data  int
    Nonce int
}

When you write a payload, its .Route() should return same route with your module is registered on the router. It is because oracle.Msg inherits .Route() from its embedded payload and it should be handled on the user modules.

Then route every incoming oracle.Msg to oracle.Keeper.Handler() with the function that implements oracle.Handler.

func NewHandler(keeper Keeper) sdk.Handler {
    return func(ctx sdk.Context, msg sdk.Msg) sdk.Result {
        switch msg := msg.(type) {
        case oracle.Msg: 
            return keeper.oracle.Handle(ctx sdk.Context, p oracle.Payload) sdk.Error {
                switch p := p.(type) {
                case MyPayload:
                    return handleMyPayload(ctx, keeper, p)
                }
            }
        }
    }
}

In the previous example, the keeper has an oracle.Keeper. oracle.Keepers are generated by NewKeeper.

func NewKeeper(key sdk.StoreKey, cdc *codec.Codec, valset sdk.ValidatorSet, supermaj sdk.Dec, timeout int64) Keeper {
    return Keeper {
        cdc: cdc,
        key: key,
    
        // ValidatorSet to get validators infor
        valset: valset,

        // The keeper will pass payload
        // when more than 2/3 signed on it
        supermaj: supermaj,
        // The keeper will prune votes after 100 blocks from last sign
        timeout: timeout,
    }
}

Now the validators can send oracle.Msgs with MyPayload when they want to witness external events.

Documentation

Index

• Constants
• func ErrAlreadyProcessed(codespace sdk.CodespaceType) sdk.Error
• func ErrAlreadySigned(codespace sdk.CodespaceType) sdk.Error
• func ErrNotValidator(codespace sdk.CodespaceType, address sdk.AccAddress) sdk.Error
• func GetInfoKey(p Payload, cdc *codec.Codec) []byte
• func GetSignKey(p Payload, signer sdk.AccAddress, cdc *codec.Codec) []byte
• func GetSignPrefix(p Payload, cdc *codec.Codec) []byte
• type Handler
• type Info
  • func EmptyInfo(ctx sdk.Context) Info
• type InfoStatus
• type Keeper
  • func NewKeeper(key sdk.StoreKey, cdc *codec.Codec, valset sdk.ValidatorSet, supermaj sdk.Dec, ...) Keeper
  • func (keeper Keeper) Handle(h Handler, ctx sdk.Context, o Msg, codespace sdk.CodespaceType) sdk.Result
  • func (keeper Keeper) Info(ctx sdk.Context, p Payload) (res Info)
• type Msg
  • func (msg Msg) GetSignBytes() []byte
  • func (msg Msg) GetSigners() []sdk.AccAddress
• type Payload

Constants

const (
	CodeNotValidator     sdk.CodeType = 1101
	CodeAlreadyProcessed sdk.CodeType = 1102
	CodeAlreadySigned    sdk.CodeType = 1103
	CodeUnknownRequest   sdk.CodeType = sdk.CodeUnknownRequest
)

Oracle errors reserve 1101-1199

const (
	Pending = InfoStatus(iota)
	Processed
	Timeout
)

Define InfoStatus

Functions

func ErrAlreadyProcessed

func ErrAlreadyProcessed(codespace sdk.CodespaceType) sdk.Error

ErrAlreadyProcessed called when a payload is already processed

func ErrAlreadySigned

func ErrAlreadySigned(codespace sdk.CodespaceType) sdk.Error

ErrAlreadySigned called when the signer is trying to double signing

func ErrNotValidator

func ErrNotValidator(codespace sdk.CodespaceType, address sdk.AccAddress) sdk.Error

ErrNotValidator called when the signer of a Msg is not a validator

func GetInfoKey

func GetInfoKey(p Payload, cdc *codec.Codec) []byte

GetInfoKey returns the key for OracleInfo

func GetSignKey

func GetSignKey(p Payload, signer sdk.AccAddress, cdc *codec.Codec) []byte

GetSignKey returns the key for sign

func GetSignPrefix

func GetSignPrefix(p Payload, cdc *codec.Codec) []byte

GetSignPrefix returns the prefix for signs

Types

type Handler

type Handler func(ctx sdk.Context, p Payload) sdk.Error

Handler handles payload after it passes voting process

type Info

type Info struct {
	Power      sdk.Int
	Hash       []byte
	LastSigned int64
	Status     InfoStatus
}

Info for each payload

func EmptyInfo

func EmptyInfo(ctx sdk.Context) Info

EmptyInfo construct an empty Info

type InfoStatus

type InfoStatus int8

InfoStatus - current status of an Info

type Keeper

type Keeper struct {
	// contains filtered or unexported fields
}

Keeper of the oracle store

func NewKeeper

func NewKeeper(key sdk.StoreKey, cdc *codec.Codec, valset sdk.ValidatorSet, supermaj sdk.Dec, timeout int64) Keeper

NewKeeper constructs a new keeper

func (Keeper) Handle

func (keeper Keeper) Handle(h Handler, ctx sdk.Context, o Msg, codespace sdk.CodespaceType) sdk.Result

Handle is used by other modules to handle Msg

func (Keeper) Info

func (keeper Keeper) Info(ctx sdk.Context, p Payload) (res Info)

Info returns the information about a payload

type Msg

type Msg struct {
	Payload
	Signer sdk.AccAddress
}

Msg - struct for voting on payloads

func (Msg) GetSignBytes

func (msg Msg) GetSignBytes() []byte

GetSignBytes implements sdk.Msg

func (Msg) GetSigners

func (msg Msg) GetSigners() []sdk.AccAddress

GetSigners implements sdk.Msg

type Payload

type Payload interface {
	Route() string
	Type() string
	ValidateBasic() sdk.Error
}

Payload defines inner data for actual execution