Contract Shim API Document

用户合约Shim API说明

Shim接口用于合约内部调用底层的相关资源。

文档中*这种字体*的表示系统合约调用接口。

1. 合约调用参数获取的Shim接口

stub.GetArgs

API 说明获取合约调用时的参数列表，以序列值返回。包括函数名和参数。
函数定义

  GetArgs() [][]byte

参数说明

无

返回值说明

- 将所有合约调用参数以字节数组类型形式返回，返回值依次是：nil，nil，nil，函数名，传给函数的参数。通过string()接口转换为string类型，比如下面是转换后的数据：
[u'', u'', u'', u'testGetInvokeInfo', u'arg1', u'arg2']

stub.GetStringArgs

API 说明

获取合约调用参数，以string类型返回。
函数定义

GetStringArgs() []string

参数说明

无

返回值说明

- 将所有合约调用参数以string类型形式返回，返回值依次是：nil，nil，nil，函数名，传给函数的参数。返回数据示例如下：
[u'', u'', u'', u'testGetInvokeInfo', u'arg1', u'arg2']

stub.GetFunctionAndParameters

API 说明

获取调用合约的函数名和参数列表。

函数定义：

GetFunctionAndParameters() (string, []string)

参数说明

无

返回值说明

- 返回值1：调用的合约函数名。
- 返回值2：传递给该函数的参数列表，以string类型返回。

stub.GetArgsSlice

API 说明

获取合约调用函数名和参数的序列信息。
函数定义

GetArgsSlice() ([]byte, error)

参数说明

无

返回值说明

- 返回值1：将函数名和传递给函数的参数都序列化，参数与GetArgs的参数相同：
[u'', u'', u'', u't', u'e', u's', u't', u'G', u'e', u't', u'I', u'n', u'v', u'o', u'k', u'e', u'I', u'n', u'f', u'o', u'a', u'r', u'g', u'1', u'a', u'r', u'g', u'2']
- 执行成功返回nil，否则返回错误信息。

stub.GetTxID

API 说明

返回当前调用合约的交易ID。
函数定义

GetTxID() string

参数说明

无

返回值说明

- 交易ID的string类型。
示例：0x341a575d11193d1d7399b7113932c6a81c7729c2d80fe66a2f7c7d5615ab9f84

stub.GetChannelID

API 说明

返回当前合约调用通道ID。
函数定义

GetTxID() string

参数说明

无

返回值说明

- 通道ID，string类型。
示例：palletone

stub.GetTxTimestamp

API 说明

获取时间戳，比如某个用户发起了某一种投票并设定一个截止时间点（从当前区块开始的第10个区块）；此时某个用户进行投票，该投票交易中包含一个时间戳，在其他mediator验证的时候，需要验证投票交易的时间是否在截止时间内（10个区块内）。
函数定义

GetTxTimestamp(rangeNumber uint32) (*timestamp.Timestamp, error)

参数说明

- rangeNumber：区块高度，要求取10的倍数的区块，比如10，100，1000 ...

返回值说明

- 未来的区块高度的时间戳。比如上述示例的截止时间点。

stub.GetInvokeAddress

API 说明

获取调用合约的用户地址。
函数定义

GetInvokeAddress() (invokeAddr common.Address, err error)

参数说明

无

返回值说明

- invokeAddr：调用合约的用户地址。
- err：执行成功返回nil；否则返回错误信息。

stub.GetInvokeTokens

API 说明

获取在合约调用时转给其他地址的token信息。目前在保证金合约、投票合约中用到。
函数定义

GetInvokeTokens() (invokeTokens []*modules.InvokeTokens, err error)

参数说明

无

返回值说明

- invokeTokens：token信息，其中InvokeTokens的定义如下：
type InvokeTokens struct {
	Amount  uint64 `json:"amount"`  //数量
	Asset   *Asset `json:"asset"`   //资产
	Address string `json:"address"` //接收地址
}
- err：执行成功返回nil；否则返回错误信息。

stub.GetInvokeFees

API 说明

返回合约调用时的交易费信息。
函数定义

GetInvokeFees() (invokeFees *modules.AmountAsset, err error)

参数说明

无

返回值说明

- invokeFees：交易费信息，其中AmountAsset的定义如下：
type AmountAsset struct {
	Amount uint64 `json:"amount"`
	Asset  *Asset `json:"asset"`
}
- err：执行成功返回nil；否则返回错误信息。

stub.GetContractID

API 说明

获取当前调用合约的ID。
函数定义

GetContractID() ([]byte, string)

参数说明

无

返回值说明

- 返回值1：合约ID，byte数组。
- 返回值2：合约ID，string类型。

stub.GetInvokeParameters

API 说明

获取合约调用的所有信息。
函数定义

GetInvokeParameters() (invokeAddr common.Address, invokeTokens []*modules.InvokeTokens, invokeFees *modules.AmountAsset, funcName string, params []string, err error)

参数说明

无

返回值说明

- invokeAddr：合约地址。
- invokeTokens：与GetInvokeTokens的返回值一致。
- invokeFees：与GetInvokeFees的返回值一致。
- funcName：调用的合约内部的函数名。
- params：传递给调用函数的参数列表。
- err：执行成功返回nil；否则返回错误信息。

2. 状态操作的Shim接口

stub.GetState

API 说明

获取当前合约的某个状态信息。

注意：该状态只读取写入到账本的状态数据，合约交易写集中的状态不会读取。
函数定义：

GetState(key string) ([]byte, error)

参数说明

- key: 合约状态名称。

返回值说明

- 返回值1：合约状态的value，类型为[]byte；如果状态不存在则返回nil。
- 返回值2：始终为nil

stub.GetGlobalState

API 说明

获取系统中零号合约的状态。
函数定义

GetGlobalState(key string) ([]byte, error)

参数说明

- key: 零号合约中的某个状态的名称

返回值说明

- 返回值1：零号合约状态的value，类型为[]byte；如果状态不存在则返回nil。
- 返回值2：始终为nil

stub.GetContractState

API 说明

获取指定合约的某个状态名称对应的状态值。
函数定义

GetContractState(contractAddr common.Address, key string) ([]byte, error)

参数说明

- contractAddr： 合约ID，类型是common.Address。可以使用Address类型对应的SetString()方法将string类型地址转换为Address类型。
- key：某个状态的名称。

返回值说明

- 返回值1：指定合约状态的value，类型为[]byte；如果状态不存在则返回nil。
- 返回值2：始终为nil

stub.GetStateByPrefix

API 说明

通过前缀查询获取当前合约的状态。
函数定义

GetStateByPrefix(prefix string) ([]*modules.KeyValue, error)

参数说明

- prefix： 合约状态名称的前缀。

返回值说明

- 返回值1：所有的状态信息的键值对；如果未查到，则返回nil。
type KeyValue struct {
	Key   string
	Value []byte
}
- 返回值2：始终为nil

stub.GetContractAllState

API 说明

获取指定合约的所有状态信息。
函数定义

GetContractAllState() (states map[string]*modules.ContractStateValue, err error)

参数说明

无

返回值说明

- states：合约的所有状态信息键值对。key-账本中存储的名称，包含一些前缀信息等，value-状态信息的键值对，名称去除了前缀信息。
- err：成功返回nil；错误返回对应的错误信息。

stub.PutState

API 说明

为当前合约添加状态信息。
函数定义

PutState(key string, value []byte) error

参数说明

- key：状态名称
- value：状态值。

返回值说明

- 执行成功返回nil，否则返回错误信息。

stub.DelState

API 说明

删除当前合约给定的状态。
函数定义

DelState(key string) error

参数说明

- key：删除的状态名。

返回值说明

- 执行成功返回nil；否则返回错误信息。

`stub.PutGlobalState`

API 说明

向零号合约中添加全局状态。

系统合约调用接口。
函数定义

PutGlobalState(key string, value []byte) error

参数说明

- key：状态名称
- value：状态值

返回值说明

- 执行成功返回nil；否则返回错误信息。

`stub.DelGlobalState`

API 说明

删除零号合约的全局状态。

系统合约调用接口。
函数定义

DelGlobalState(key string) error

参数说明

- key：需要删除的状态名。

返回值说明

- 执行成功返回nil；否则返回错误信息。

3. Jury操作的Shim接口

stub.SendJury

API 说明

将数据发送给Jury，返回Jury对数据的签名信息。一般和RecvJury配套使用。
函数定义

SendJury(msgType uint32, consultContent []byte, myAnswer []byte) ([]byte, error)

参数说明

- msgType：消息类型，目前未使用。
- consultContent：数据名称
- myAnswer：数据的原始字节序

返回值说明

- 返回值1：Jury签名数据的字节序。
- 返回值2：执行成功返回nil；否则返回错误信息。

stub.RecvJury

API 说明

接收Jury的签名信息，一般和SendJury配套使用。
函数定义

RecvJury(msgType uint32, consultContent []byte, timeout uint32) ([]byte, error)

参数说明

- msgType: 消息类型，与SendJury相同，目前未使用。
- consultContent：数据名称，与SendJury接口中的consultContent对应。

返回值说明

- 返回值1：返回的是Jury的签名结果。结构为JuryMsgAddr，并通过json.Marshal()进行序列化。
type JuryMsgAddr struct {
	Address string
	Answer  []byte
}
- 返回值2：如果成功返回nil；否则返回错误信息。

4. Token操作的Shim接口

`stub.DefineToken`

API 说明

定义某种PalletOne上的Token。

系统合约调用接口。
函数定义

DefineToken(tokenType byte, define []byte, creator string) error

参数说明

- tokenType：token的类型，分别是：0-ERC20  1-ERC721   2-VoteToken
- define：说明token的FungibleToken结构数据。序列化使用的是 json.Marshal()方法。
FungibleToken结构定义如下：
type FungibleToken struct {
    Name     string `json:"name"`
    Symbol   string `json:"symbol"`
    Decimals byte   `json:"decimals"`
    //总发行量
    TotalSupply uint64 `json:"total_supply"`
    //如果允许增发，那么允许哪个地址进行增发，如果为空则不允许增发
    SupplyAddress string `json:"supply_address"`
}
- creator：创币合约调用者地址。

返回值说明

`stub.SupplyToken`

API 说明

增发PalletOne上的某种Token。

系统合约调用接口。
函数定义

SupplyToken(assetId []byte, uniqueId []byte, amt uint64, creator string) error

参数说明

- assetId：Token的同质化ID
- uniqueId：Token的非同质化ID
- amt：增发数量。
- creator：Token的创建者，与DefineToken接口FungibleToken结构体中SupplyAddress地址指定的一致。

返回值说明

- 执行成功返回nil，否则返回错误信息。

stub.PayOutToken

API 说明

通过合约实现对某种token的转账。
函数定义

PayOutToken(addr string, invokeTokens *modules.AmountAsset, lockTime uint32) error

参数说明

- addr： Token接收者。
- invokeTokens：Token的信息。AmountAsset的定义如下，其中Asset通过Token的符号填充；Amount是转账数量。
type AmountAsset struct {
	Amount uint64 `json:"amount"`
	Asset  *Asset `json:"asset"`
}
- lockTime：交易中Token被锁定的时间（或者区块高度），默认是0

返回值说明

- 执行成功返回nil；否则返回错误信息。

stub.GetTokenBalance

API 说明

通过合约获取某个地址的余额信息。
函数定义

GetTokenBalance(address string, token *modules.Asset) ([]*modules.InvokeTokens, error)

参数说明

- address：需要获取余额的账户地址。
- token：获取该地址下某种Token类型的余额。

返回值说明

- 返回值1：InvokeTokens结构的余额信息。InvokeTokens定义如下：
type InvokeTokens struct {
	Amount  uint64 `json:"amount"`  //数量
	Asset   *Asset `json:"asset"`   //资产
	Address string `json:"address"` //接收地址
}
- 返回值2：执行成功返回nil；否则返回错误信息。

5. 数字证书检查的Shim接口

stub.GetRequesterCert

API 说明

通过证书ID获取用户使用证书的字节内容。
函数定义

GetRequesterCert() (certBytes []byte, err error)

参数说明

无

返回值说明

- certBytes：证书的原始内容字节序。
- err：执行成功为nil；否则为错误信息。

stub.IsRequesterCertValid

API 说明

根据证书ID验证用户在合约中使用的证书是否合法。
函数定义

IsRequesterCertValid() (bool, error)

参数说明

无

返回值说明

- 返回值1：证书合法返回true；否则返回false。
- 返回值2：执行成功返回nil；否则返回错误信息。

6. 其他Shim接口

stub.SetEvent

API 说明

与Hyperledger的机制一样，运行合约中设定消息机制。在PalletOne中目前暂未使用。
函数定义

SetEvent(name string, payload []byte) error

参数说明

- name：消息名称
- payload：消息的负载。

返回值说明

- 执行成功返回nil；否则返回错误信息。

stub.GetSystemConfig

API 说明

获取合约的一些配置参数。
函数定义

GetSystemConfig() (cp *core.ChainParameters, err error)

参数说明

无

返回值说明

- cp：合约的配置参数信息。ChainParameters的定义如下：
type ChainParameters struct {
	ChainParametersBase

	// TxCoinYearRate float64 `json:"tx_coin_year_rate"` //交易币天的年利率
	DepositRate   float64 `json:"deposit_rate"`   //保证金的年利率
	DepositPeriod int     `json:"deposit_period"` //保证金周期

	//对启动用户合约容器的相关资源的限制
	UccMemory    int64 `json:"ucc_memory"`
	UccCpuShares int64 `json:"ucc_cpu_shares"`
	UccCpuQuota  int64 `json:"ucc_cpu_quota"`
	UccDisk      int64 `json:"ucc_disk"`
	//对中间容器的相关资源限制
	TempUccMemory    int64 `json:"temp_ucc_memory"`
	TempUccCpuShares int64 `json:"temp_ucc_cpu_shares"`
	TempUccCpuQuota  int64 `json:"temp_ucc_cpu_quota"`

	//contract about
	ContractSignatureNum int `json:"contract_signature_num"`
	ContractElectionNum  int `json:"contract_election_num"`
}

其中 ChainParametersBase的定义如下
type ChainParametersBase struct {
	GenerateUnitReward uint64 `json:"generate_unit_reward"` //每生产一个单元，奖励多少Dao的PTN
	PledgeDailyReward  uint64 `json:"pledge_daily_reward"`  //质押金的日奖励额
	RewardHeight       uint64 `json:"reward_height"`        //每多少高度进行一次奖励的派发
	UnitMaxSize        uint64 `json:"unit_max_size"`        //一个单元最大允许多大
	FoundationAddress  string `json:"foundation_address"`   //基金会地址，该地址具有一些特殊权限，比如发起参数修改的投票，发起罚没保证金等

	DepositAmountForMediator  uint64 `json:"deposit_amount_for_mediator"` //保证金的数量
	DepositAmountForJury      uint64 `json:"deposit_amount_for_jury"`
	DepositAmountForDeveloper uint64 `json:"deposit_amount_for_developer"`

	//UccCpuSetCpus string `json:"ucc_cpu_set_cpus"` //限制使用某些CPUS  "1,3"  "0-2"

	// 活跃mediator的数量。 number of active mediators
	ActiveMediatorCount uint8 `json:"active_mediator_count"`

	// 用户可投票mediator的最大数量。the maximum number of mediator users can vote for
	MaximumMediatorCount uint8 `json:"max_mediator_count"`

	// unit生产之间的间隔时间，以秒为单元。 interval in seconds between Units
	MediatorInterval uint8 `json:"mediator_interval"`

	// 区块链维护事件之间的间隔，以秒为单元。 interval in sections between unit maintenance events
	MaintenanceInterval uint32 `json:"maintenance_interval"`

	// 在维护时跳过的MediatorInterval数量。 number of MediatorInterval to skip at maintenance time
	MaintenanceSkipSlots uint8 `json:"maintenance_skip_slots"`

	// 目前的操作交易费，current schedule of fees
	MediatorCreateFee        uint64 `json:"mediator_create_fee"`
	AccountUpdateFee         uint64 `json:"account_update_fee"`
	TransferPtnBaseFee       uint64 `json:"transfer_ptn_base_fee"`
	TransferPtnPricePerKByte uint64 `json:"transfer_ptn_price_per_KByte"`
	// ContractInvokeFee        uint64 `json:"contract_invoke_fee"`
}
- err：执行成功返回nil；否则返回错误信息。

Home

Getting started

Developer Tools

FAQ

Frequently asked questions

Contract Shim API Document

用户合约Shim API说明

1. 合约调用参数获取的Shim接口

stub.GetArgs

stub.GetStringArgs

stub.GetFunctionAndParameters

stub.GetArgsSlice

stub.GetTxID

stub.GetChannelID

stub.GetTxTimestamp

stub.GetInvokeAddress

stub.GetInvokeTokens

stub.GetInvokeFees

stub.GetContractID

stub.GetInvokeParameters

2. 状态操作的Shim接口

stub.GetState

stub.GetGlobalState

stub.GetContractState

stub.GetStateByPrefix

stub.GetContractAllState

stub.PutState

stub.DelState

stub.PutGlobalState

stub.DelGlobalState

3. Jury操作的Shim接口

stub.SendJury

stub.RecvJury

4. Token操作的Shim接口

stub.DefineToken

stub.SupplyToken

stub.PayOutToken

stub.GetTokenBalance

5. 数字证书检查的Shim接口

stub.GetRequesterCert

stub.IsRequesterCertValid

6. 其他Shim接口

stub.SetEvent

stub.GetSystemConfig

Clone this wiki locally

`stub.PutGlobalState`

`stub.DelGlobalState`

`stub.DefineToken`

`stub.SupplyToken`