ddc-sdk-operator-go

README

DDC-SDK-Go

• DDC-SDK-Go
  • 运营方可调用的如下方法
    • 1.初始化Client (连接测试网)
    • 2.BSN-DDC-权限管理
    • 3.BSN-DDC-费用管理
    • 4.BSN-DDC-721
    • 5.BSN-DDC-1155
    • 6.BSN-DDC-交易查询
    • 7.BSN-DDC-区块查询
    • 8.BSN-DDC-数据解析
    • 9.离线账户创建
  • 基本的工具方法
  • 测试用例

运营方可调用的如下方法：

1.初始化Client (连接测试网)

初始化client时，可设置：签名方法、GasPrice、GatewayUrl以及相关的合约地址等，具体可设置项见以下示例：

    //初始化clientBuilder
    clientBuilder = app.DDCSdkClientBuilder{}
    //可设置项如下：
    client        = clientBuilder.
        SetSignEventListener(new(SignListener)).//注册实现了签名接口的结构体
        SetGasPrice(1e10).//设置gasPrice
        SetGatewayUrl("https://opbtest.bsngate.com:18602/api/[ProjectId]/evmrpc").
        SetGatewayApiKey("x-api-key").
        SetGatewayApiValue("[ProjectKey]").
    	SetAuthorityAddress("0xa7FC5B0F4A0085c5Ce689b919a866675Ce37B66b").
        SetChargeAddress("0x3BBb01B38958d4dbF1e004611EbB3c65979B0511").
        SetDDC721Address("0x3B09b7A00271C5d9AE84593850dE3A526b8BF96e").
        SetDDC1155Address("0xe5d3b9E7D16E03A4A1060c72b5D1cb7806DD9070").
        RegisterLog("./log.log").//设置日志输出的文件路径
        Build()

其中实现签名接口的示例如下：

type SignListener struct {
}

// SignEvent
// @Description: 自定义的签名方法
// @receiver s
// @param sender 调用者的账户地址
// @param tx 待签名的交易
// @return *types.Transaction 签名好的交易
// @return error
func (s *SignListener) SignEvent(sender common.Address, tx *types.Transaction) (*types.Transaction, error) {

	// 提取私钥
	privateKey, err := StringToPrivateKey("sender的私钥")
	if err != nil {
		log.Fatalf("StringToPrivateKey failed:%v", err)
	}
	// 签名
	signTx, err := types.SignTx(tx, types.HomesteadSigner{}, privateKey)

	return signTx, err
}

// StringToPrivateKey
// @Description: 从明文的私钥字符串转换成ECDSA格式的私钥
// @param privateKeyStr 明文的私钥字符串
// @return *ecdsa.PrivateKey
// @return error
func StringToPrivateKey(privateKeyStr string) (*ecdsa.PrivateKey, error) {
	privateKeyByte, err := hexutil.Decode(privateKeyStr)
	if err != nil {
		return nil, err
	}
	privateKey, err := crypto.ToECDSA(privateKeyByte)
	if err != nil {
		return nil, err
	}
	return privateKey, nil
}

2.BSN-DDC-权限管理

在调用权限管理的方法前需要先获取对应的service：

var authorityService = client.GetAuthorityService()

接下来可通过service调用的方法如下：

// AddAccountByOperator
// @Description: 运营方可以通过调用该方法直接对平台方或平台方的终端用户进行创建
// @receiver a
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param account DDC链账户地址
// @param accName DDC账户对应的账户名称
// @param accDID DDC账户对应的DID信息
// @param leaderDID 该账户对应的上级账户的DID
// @return signedTx 签名好的交易
// @return error
AddAccountByOperator(opts *bind.TransactOpts, account, accName, accDID, leaderDID string) (signedTx *types.Transaction, err error)

// GetAccount
// @Description: 运营方、平台方以及终端用户可以通过调用该方法进行DDC账户信息的查询
// @receiver a
// @param account DDC用户的账户地址
// @return *dto.AccountInfo DDC账户信息实体
// @return error
GetAccount(account string) (*dto.AccountInfo, error)

// UpdateAccState
// @Description: 运营方或平台方可以通过调用该方法对终端用户进行DDC账户信息状态的更改
// @receiver a
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param account 要更新的账户地址
// @param state 状态 ：Frozen 0 - 冻结状态 ； Active 1 - 活跃状态
// @param changePlatformState 修改平台方状态标识
// @return signedTx 签名好的交易
// @return error
UpdateAccState(opts *bind.TransactOpts, account string, state uint8, changePlatformState bool) (signedTx *types.Transaction, err error)

// CrossPlatformApproval
// @Description: 运营方可以通过调用该方法对DDC的跨平台操作进行授权
// @receiver a
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param from 授权者账户
// @param to 接收者地址账户
// @param approved 授权标识
// @return signedTx 签名好的交易
// @return error
CrossPlatformApproval(opts *bind.TransactOpts, from, to string, approved bool) (signedTx *types.Transaction, err error)

// AddFunction
// @Description:运营方调用该方法为平台方和终端用户设置调用对应方法的权限
// @receiver a
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param role 目标角色
// @param ctrAddr 目标合约地址
// @param sig 目标方法对应的sig编码
// @return signedTx 签名好的交易
// @return error
AddFunction(opts *bind.TransactOpts, role uint8, ctrAddr string, sig [4]byte) (signedTx *types.Transaction, err error)

// HasFunctionPermission
// @Description: 运营方调用该方法查询平台方和终端用户是否有调用对应方法的权限
// @receiver a
// @param accAddr 账户地址
// @param ctrAddr 合约地址
// @param sig 目标方法对应的sig编码
// @return bool 是否已被授权
// @return error
HasFunctionPermission(accAddr, ctrAddr string, sig [4]byte) (bool, error) 

3.BSN-DDC-费用管理

在调用费用管理的方法前需要先获取对应的service：

var chargeService = client.GetChargeService()

接下来可通过service调用的方法如下：

// Recharge
// @Description:运营方、平台方调用该接口为所属同一方的同一级别账户或者下级账户充值
// @receiver c
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param to 接收者账户
// @param amount 充值金额
// @return signedTx 签名好的交易
// @return error
Recharge(opts *bind.TransactOpts, to string, amount int64) (signedTx *types.Transaction, err error)

// BalanceOf
// @Description: 查询指定账户的余额
// @receiver c
// @param accAddr 要查询的账户地址
// @return uint64 账户所对应的业务费余额
// @return error
BalanceOf(accAddr string) (uint64, error) 

// QueryFee
// @Description: 查询指定的DDC业务方法所对应的业务费用
// @receiver c
// @param contrAddr DDC业务合约地址
// @param sig DDC业务方法对应的sig编码
// @return uint32 业务费用
// @return error
QueryFee(contrAddr string, sig [4]byte) (uint32, error)

// SelfRecharge
// @Description: 运营方调用为自己的账户增加业务费
// @receiver c
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param amount 充值金额
// @return signedTx 签名好的交易
// @return error
SelfRecharge(opts *bind.TransactOpts, amount int64) (signedTx *types.Transaction, err error)

// SetFee
// @Description: 运营方调用接口设置指定的DDC主合约的方法调用费用
// @receiver c
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param contrAddr DDC业务合约地址
// @param sig DDC业务方法对应的sig编码
// @param amount 业务费用
// @return signedTx 签名好的交易
// @return error
SetFee(opts *bind.TransactOpts, contrAddr string, sig [4]byte, amount uint32) (signedTx *types.Transaction, err error) 

// DelFee
// @Description: 运营方调用接口删除指定的DDC业务方法的调用费用
// @receiver c
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param contrAddr DDC业务合约地址
// @param sig DDC业务方法对应的sig编码
// @return signedTx 签名好的交易
// @return error
DelFee(opts *bind.TransactOpts, contrAddr string, sig [4]byte) (signedTx *types.Transaction, err error) 

// DelDDC
// @Description: 运营方调用该接口删除指定的DDC业务主逻辑合约授权
// @receiver c
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param contrAddr DDC业务合约地址
// @return signedTx 签名好的交易
// @return error
DelDDC(opts *bind.TransactOpts, contrAddr string) (signedTx *types.Transaction, err error)

4.BSN-DDC-721

在调用ddc721的方法前需要先获取对应的service：

var ddc721Service = client.GetDDC721Service()

接下来可通过service调用的方法如下：

// Approve
// @Description: DDC拥有者可以通过调用该方法进行DDC的授权，发起者需要是DDC的拥有者
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param to 授权者账户
// @param ddcID DDC唯一标识
// @return signedTx 签名好的交易
// @return error
Approve(opts *bind.TransactOpts, to string, ddcID int64) (signedTx *types.Transaction, err error)

// GetApprove
// @Description: 运营方、平台方或终端用户都可以通过调用该方法查询DDC的授权情况
// @receiver d
// @param ddcID DDC唯一标识
// @return string 授权的账户
// @return error
GetApprove(ddcID int64) (string, error) 

// SetApprovalForAll
// @Description: DDC拥有者可以通过调用该方法进行账户授权，发起者需要是DDC的拥有者
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param operator 授权者账户
// @param approved 授权标识
// @return signedTx 签名好的交易
// @return error
SetApprovalForAll(opts *bind.TransactOpts, operator string, approved bool) (signedTx *types.Transaction, err error)

// IsApprovedForAll
// @Description: 运营方、平台方或终端用户可以通过调用该方法进行账户授权查询
// @receiver d
// @param owner 拥有者账户
// @param operator 授权者账户
// @return bool 授权标识
// @return error
IsApprovedForAll(owner, operator string) (bool, error)

// SafeTransferFrom
// @Description: DDC的拥有者或授权者可以通过调用该方法进行DDC的转移
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param from 拥有者账户
// @param to 接收者账户
// @param ddcID DDC唯一标识
// @param data 附加数据
// @return signedTx 签名好的交易
// @return error
SafeTransferFrom(opts *bind.TransactOpts, from, to string, ddcID int64, data []byte) (signedTx *types.Transaction, err error)

// TransferFrom
// @Description: DDC拥有者或授权者可以通过调用该方法进行DDC的转移
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param from 拥有者账户
// @param to 接收者账户
// @param ddcID ddc唯一标识
// @return signedTx 签名好的交易
// @return error
TransferFrom(opts *bind.TransactOpts, from, to string, ddcID int64) (signedTx *types.Transaction, err error) 

// Freeze
// @Description: 运营方可以通过调用该方法进行DDC的冻结
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param ddcID DDC唯一标识
// @return signedTx 签名好的交易
// @return error
Freeze(opts *bind.TransactOpts, ddcID int64) (signedTx *types.Transaction, err error)

// UnFreeze
// @Description: 运营方可以通过调用该方法进行DDC的解冻
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param ddcID DDC唯一标识
// @return signedTx 签名好的交易
// @return error
UnFreeze(opts *bind.TransactOpts, ddcID int64) (signedTx *types.Transaction, err error)

// Burn
// @Description: DDC拥有者或DDC授权者可以通过调用该方法进行DDC的销毁
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param ddcID DDC唯一标识
// @return signedTx 签名好的交易
// @return error
Burn(opts *bind.TransactOpts, ddcID int64) (signedTx *types.Transaction, err error)

// BalanceOf
// @Description: 运营方、平台方以及终端用户可以通过调用该方法进行查询当前账户拥有的DDC的数量
// @receiver d
// @param owner 拥有者账户
// @return uint64 ddc的数量
// @return error
BalanceOf(owner string) (uint64, error)

// OwnerOf
// @Description: 运营方、平台方以及终端用户可以通过调用该方法查询当前DDC的拥有者
// @receiver d
// @param ddcID ddc唯一标识
// @return string 拥有者账户
// @return error
OwnerOf(ddcID int64) (string, error)

// Name
// @Description: 运营方、平台方以及终端用户可以通过调用该方法查询当前DDC的名称
// @receiver d
// @return string DDC运营方名称
// @return error
Name() (string, error)

// Symbol
// @Description: 运营方、平台方以及终端用户可以通过调用该方法查询当前DDC的符号标识
// @receiver d
// @return string DDC运营方符号
// @return error
Symbol() (string, error)

// DdcURI
// @Description: 运营方、平台方以及终端用户可以通过调用该方法查询当前DDC的资源标识符
// @receiver d
// @param ddcID DDC唯一标识符
// @return string DDC资源标识符
// @return error
DdcURI(ddcID int64) (string, error)

// SetURI
// @Description: DDC拥有者或DDC授权者通过调用该方法对DDC的资源标识符进行设置
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param ddcID DDC唯一标识
// @param ddcURI DDC资源标识符
// @return signedTx 签名好的交易
// @return err
SetURI(opts *bind.TransactOpts, ddcID int64, ddcURI string) (signedTx *types.Transaction, err error)

// SetNameAndSymbol
// @Description: 合约拥有者调用该方法对721的名称及符号进行设置。
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param name 名称
// @param symbol 符号
// @return signedTx 签名好的交易
// @return err
SetNameAndSymbol(opts *bind.TransactOpts, name, symbol string) (signedTx *types.Transaction, err error) 

5.BSN-DDC-1155

在调用ddc1155的方法前需要先获取对应的service：

var ddc1155Service = client.GetDDC1155Service()

接下来可通过service调用的方法如下：

// SetApprovalForAll
// @Description: DDC拥有者可以通过调用该方法进行账户授权，发起者需要是DDC的拥有者
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param operator 授权者账户
// @param approved 授权标识
// @return signedTx 签名好的交易
// @return error
SetApprovalForAll(opts *bind.TransactOpts, operator string, approved bool) (signedTx *types.Transaction, err error)

// IsApprovedForAll
// @Description: 运营方、平台方或终端用户可以通过调用该方法进行账户授权查询
// @receiver d
// @param owner 拥有者账户
// @param operator 授权者账户
// @return bool 授权标识
// @return error
IsApprovedForAll(owner, operator string) (bool, error)

// SafeTransferFrom
// @Description: DDC拥有者或DDC授权者可以通过调用该方法进行DDC的转移
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param from 拥有者账户
// @param to 接收者账户
// @param ddcID DDC唯一标识
// @param amount 需要转移的DDC数量
// @param data 附加数据
// @return signedTx 签名好的交易
// @return error
SafeTransferFrom(opts *bind.TransactOpts, from, to string, ddcID, amount int64, data []byte) (signedTx *types.Transaction, err error)

// SafeBatchTransferFrom
// @Description: DDC拥有者或DDC授权者可以通过调用该方法进行DDC的批量转移
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param from 拥有者账户
// @param to 接收者账户
// @param ddcInfo 要转移的ddc集合（ddcID->amount）
// @param data 附加数据
// @return signedTx 签名好的交易
// @return error
SafeBatchTransferFrom(opts *bind.TransactOpts, from, to string, ddcInfo map[int64]int64, data []byte) (signedTx *types.Transaction, err error)

// Freeze
// @Description: 运营方可以通过调用该方法进行DDC的冻结
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param ddcID DDC唯一标识
// @return signedTx 签名好的交易
// @return error
Freeze(opts *bind.TransactOpts, ddcID int64) (signedTx *types.Transaction, err error)

// UnFreeze
// @Description: 运营方可以通过调用该方法进行DDC的解冻
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param ddcID DDC唯一标识
// @return signedTx 签名好的交易
// @return error
UnFreeze(opts *bind.TransactOpts, ddcID int64) (signedTx *types.Transaction, err error)

// Burn
// @Description: DDC拥有者或DDC授权者可以通过调用该方法进行DDC的销毁
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param ddcID DDC唯一标识
// @return signedTx 签名好的交易
// @return error
Burn(opts *bind.TransactOpts, owner string, ddcID int64) (signedTx *types.Transaction, err error)

// BurnBatch
// @Description: DDC拥用者可以通过调用该方法进行DDC的批量销毁
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param owner 拥有者账户
// @param ddcIds 要销毁的DDC的唯一标识的集合
// @return signedTx 签名好的交易
// @return error
BurnBatch(opts *bind.TransactOpts, owner string, ddcIds []int64) (signedTx *types.Transaction, err error)

// BalanceOf
// @Description: 运营方、平台方以及终端用户可以通过调用该方法进行查询当前账户拥有的对应ddcId的数量
// @receiver d
// @param owner 拥有者账户
// @param ddcID DDC唯一标识
// @return uint64 ddcId对应的数量
// @return error
BalanceOf(owner string, ddcID int64) (uint64, error)

// BalanceOfBatch
// @Description: 运营方、平台方以及终端用户可以通过调用该方法进行批量查询账户拥有的DDC的数量
// @receiver d
// @param owners 要查询的账户地址
// @param ddcIds 要查询的ddcId
// @return []*big.Int ddc数量的集合
// @return error
BalanceOfBatch(owners []common.Address, ddcIds []*big.Int) ([]*big.Int, error)

// DdcURI
// @Description: 运营方、平台方以及终端用户可以通过调用该方法查询当前DDC的资源标识符
// @receiver d
// @param ddcId DDC唯一标识符
// @return string DDC资源标识符
// @return error
DdcURI(ddcId int64) (ddcURI string, err error)

// SetURI
// @Description: DDC拥有者或DDC授权者通过调用该方法对DDC的资源标识符进行设置
// @receiver d
// @param opts opts.Price和opts.Signer为空时，默认使用初始化client时set的price和signer
// @param owner DDC拥有者
// @param ddcId DDC唯一标识
// @param ddcURI DDC资源标识符
// @return signedTx 签名好的交易
// @return error
SetURI(opts *bind.TransactOpts, owner string, ddcId int64, ddcURI string) (signedTx *types.Transaction, err error)

6.BSN-DDC-交易查询

使用client或任意service即可调用以下方法：

// GetTxByHash
// @Description: 运营方或平台方根据交易哈希对交易信息进行查询
// @receiver t
// @param txHash: 交易哈希
// @return *types.Transaction: 交易信息
// @return bool： pending状态
// @return error
GetTxByHash(txHash string) (*types.Transaction, bool, error)

// GetTxReceipt
// @Description: 运营方或平台方根据交易哈希对交易回执信息进行查询。
// @receiver t
// @param txHash: 交易哈希
// @return string： 交易回执
// @return error
GetTxReceipt(txHash string) (*types.Receipt, error)

// GetTxStatus
// @Description: 运营方或平台方根据交易哈希查询交易状态是否成功
// @receiver t
// @param txHash: 交易哈希
// @return bool：交易是否成功
// @return error
GetTxStatus(txHash string) (bool, error)

// GetTimeByTxHash
// @Description: 通过txHash查询所在块的时间
// @receiver t
// @param txHash 交易哈希
// @return uint64 所在块的时间
// @return error
GetTimeByTxHash(txHash string) (uint64, error)

7.BSN-DDC-区块查询

使用client或任意service即可调用以下方法：

// GetBlockByNumber
// @Description: 运营方或平台方根据区块高度对区块信息进行查询，并解析区块数据返回给运营方或平台方
// @receiver b
// @param blockNumber： 区块高度
// @return *types2.Block： 区块信息
// @return error
GetBlockByNumber(blockNumber int64) (*types.Block, error)

8.BSN-DDC-数据解析

使用client或任意service即可调用以下方法：

// GetTxEvents
// @Description: 获取指定交易中的所有events
// @receiver b
// @param txHash 交易哈希
// @return events 查询出的事件
// @return err
GetTxEvents(txHash common.Hash) (events []interface{}, err error)

// GetBlockEvents
// @Description: 获取指定区块内的所有events
// @receiver b
// @param blockNumber 块高
// @return *dto.BlockEventBean 事件和时间戳的实体
// @return error
GetBlockEvents(blockNumber int64) (*dto.BlockEventBean, error)

9.离线账户创建

使用client或任意service即可调用以下方法：

// CreateAccount
// @Description:可以通过此方法生成离线账户
// @receiver b
// @return *dto.Account 返回的账户信息
// @return error
CreateAccount() (*dto.Account, error)

基本工具方法

使用client或任意service即可调用以下方法：

// GetNonce
// @Description:查询对应账户下的最新nonce
// @receiver b
// @param addr 账户地址
// @return uint64 最新nonce
// @return error
func (b Base) GetNonce(addr common.Address) (uint64, error)

// DDCIdByHash
// @Description: 通过交易hash查询相关ddc的ddcId
// @receiver b
// @param hash 交易哈希
// @return []uint64 对应的ddcId的集合
func (b Base) DDCIdByHash(hash string) (res []uint64)

// NewRawTx
// @Description: 组装待签名的交易
// @receiver b
// @param opts
// @param contract 目标合约地址
// @param input 目标方法的字节码
// @return *types.Transaction 待签名的交易
// @return error
func (b Base) NewRawTx(opts *bind.TransactOpts, contract common.Address, input []byte) (*types.Transaction, error)

// Bech32ToHex
// @Description: irita链账户转以太坊账户格式
// @receiver b
// @param addr irita链账户
// @return string 以太坊账户
// @return error
func (b Base) Bech32ToHex(addr string) (string, error)

// HexToBech32
// @Description: 以太坊账户格式转irita链账户
// @receiver b
// @param addr 0x开头的以太坊账户
// @return string irita链账户
// @return error
func (b Base) HexToBech32(addr string) (string, error)

测试用例

AuthorityServiceTest.java

ChargeServiceTest.java

BaseServiceTest.java

BlockEventServiceTest.java

DDC721ServiceTest.java

DDC1155ServiceTest.java

SignEventTest.java