Trezor钱包集成JS开发文档:公共API

getPublicKey - 导出公钥

使用getPublicKey()方法获取指定路径的BIP32扩展公钥。将展示给 用户所请求密钥的描述并要求确认导出操作。

方法调用

ES6:

const result = await TrezorConnect.getPublicKey(params);

CommonJS:

TrezorConnect.getPublicKey(params).then(function(result) {

});

调用参数:

可选的公共参数

导出单个公钥:

  • path:密钥路径,字符串或数值数组,必须
  • coin:数字货币代码,在coins.json中定义,可选。如果未设置该参数,则利用path参数进行推导
  • crossChain:是否跨链,可选 批量导出公钥:

  • bundle:导出目标对象的数组,每个对象包含path、coin和crossChain字段

示例代码

返回第5个比特币账户的公钥:

TrezorConnect.getPublicKey({
    path: "m/49'/0'/4'",
    coin: "btc"
});

返回多个比特币账户的公钥:

TrezorConnect.getPublicKey({
    bundle: [
        { path: "m/49'/0'/0'" }, // account 1
        { path: "m/49'/0'/1'" }, // account 2
        { path: "m/49'/0'/2'" }  // account 3
    ]
});

返回结果

单个公钥的返回结果:

{
    success: true,
    payload: {
        path: Array<number>, // hardended path
        serializedPath: string, // serialized path
        xpub: string,        // xpub in legacy format
        xpubSegwit?: string, // optional for segwit accounts: xpub in segwit format
        chainCode: string,   // BIP32 serialization format
        childNum: number,    // BIP32 serialization format
        publicKey: string,   // BIP32 serialization format
        fingerprint: number, // BIP32 serialization format
        depth: number,       // BIP32 serialization format
    }
}

批量导出公钥返回结果:

{
    success: true,
    payload: [
        { path, serializedPath, xpub, xpubSegwit?, chainCode, childNum, publicKey, fingerprint, depth }, // account 1
        { path, serializedPath, xpub, xpubSegwit?, chainCode, childNum, publicKey, fingerprint, depth }, // account 2
        { path, serializedPath, xpub, xpubSegwit?, chainCode, childNum, publicKey, fingerprint, depth }  // account 3
    ]
}

错误信息:

{
    success: false,
    payload: {
        error: string // error message
    }
}

从之前版本迁移

version 4及之前版本:

TrezorConnect.getXPubKey("m/49'/0'/0'", function(result) {
    result.path           // not changed
    result.serializedPath // not changed
    result.xpubkey        // renamed to "xpub"
    // added "xpubSegwit" field for segwit accounts
    result.chainCode      // not changed
    result.publicKey      // not changed
    // added "fingerprint" field
    // added "childNum" field
    // added "depth" field
});

version 5:

// params are key-value pairs inside Object
TrezorConnect.getPublicKey({ 
    path: "m/49'/0'/0'" 
}).then(function(result) {
    ...
})

requestLogin - 请求登录

通过Trezor钱包的挑战/应答验证。为了对抗重放攻击,开发者应当 使用后端生成的随机的challengeHidden。开发者也可以提供在钱包上 可视的挑战。

服务后端需要检查签名是否匹生成的challengeHidden、提供的 challengeVisual和保存的publicKey字段。如果是的话,后端 要么创建账户(如果publicKey是首次出现),要么登入用户 (如果publicKey是已知用户)。

要理解完整机制,请参考 SLIP-0013:确定性层级验证。

调用方法

ES6:

const result = await TrezorConnect.requestLogin(params);
CommonJS:

TrezorConnect.requestLogin(params).then(function(result) {

});

参数:

可选的公共参数:

  • useEmptyPassphrase:总是设置为true,并且本方法忽略 使用服务端异步挑战的登录:

  • callback:TrezorConnect将调用该函数来获取challengeHidden和challengeVisual,必须 不使用异步挑战的登录:

  • challengeHidden:16进制字符串,必须

  • challengeVisual:显示在Trezor上的文本,必须

示例代码

基于服务端异步挑战的登录:

TrezorConnect.requestLogin({ 
    callback: function() {
        // here should be a request to server to fetch "challengeHidden" and "challengeVisual"
        return {
            challengeHidden: '0123456789abcdef',
            challengeVisual: 'Login to',
        }
    }
})

不使用异步挑战的登录:

TrezorConnect.requestLogin({ 
    challengeHidden: '0123456789abcdef',
    challengeVisual: 'Login to',
})

返回结果

{
    success: true,
    payload: {
        address: string,
        publicKey: string,
        signature: string,
    }
}

错误信息:

{
    success: false,
    payload: {
        error: string // error message
    }
}

服务端示例

下面是不同语言的服务端签名验证示例:

C# Javascript PHP Python Ruby

从之前版本迁移

版本4及更早:

// site icon, optional. at least 48x48px
var hosticon = 'https://example.com/icon.png';
// server-side generated and randomized challenges
var challenge_hidden = '';
var challenge_visual = '';
TrezorConnect.requestLogin(
    hosticon,                // hosticon is moved to common parameters
    challenge_hidden,
    challenge_visual
    function(result) {
        result.signatures    // not changed
        result.public_key    // renamed to "publicKey"
        result.version       // removed, it's not possible to use this method witch outdated firmware
        // added "address" field
    }
);

版本5:

// params are key-value pairs inside Object
TrezorConnect.requestLogin({ 
    challengeHidden: '',
    challengeVisual: '',
}).then(function(result) {
    ...
})

cipherKeyValue - 对称加密键值

cipherKeyValue方法提供Trezor设备的对称加密能力,用户需要确认 钱包显示的加密/解密。用于加密的密钥从BIP地址的私钥构造,密钥 将显示在钱包显示屏上。不同的路径、密钥或确认信息将得到不同的 加密密钥和IV。因此,你不能使用不同的输入来跳过确认步骤。IV 可以手工设置,或者使用密钥算出。值必须16字节块对齐。应用需要 自己补齐块以确保安全性。例如,使用PKCS7。

详细信息可参考 SLIP-0011

调用方法

ES6:

const result = await TrezorConnect.cipherKeyValue(params);

CommonJS:

TrezorConnect.cipherKeyValue(params).then(function(result) {

});

调用参数:

可选的公共参数:

  • useEmptyPassphrase:始终设置为true,本方法忽略 加密单个值:

  • path:密钥路径,字符串或数值数组,必须

  • key:钱包显示的文本,可选
  • value:待加密内容,16字节倍长的16进制字符串,可选
  • askOnEncrypt:是否需要用户确认加密,布尔值,可选
  • askOnDecrypt:是否需要用户确认解密,布尔值,可选
  • iv:初始化向量,可选 加密多个值:

  • bundle:上述对象数组

示例代码

返回加密数据:

TrezorConnect.cipherKeyValue({
    path: "m/49'/0'/0'",
    key: "This text is displayed on Trezor during encrypt",
    value: "1c0ffeec0ffeec0ffeec0ffeec0ffee1",
    encrypt: true,
    askOnEncrypt: true,
    askOnDecrypt: true
});

返回批量加密数据:

TrezorConnect.cipherKeyValue({
    bundle: [
        { path: "m/49'/0'/0'", key: "1 text on Trezor", value: "1c0ffeec0ffeec0ffeec0ffeec0ffee1", encrypt: true  },
        { path: "m/49'/0'/1'", key: "2 text on Trezor", value: "1c0ffeec0ffeec0ffeec0ffeec0ffee1", encrypt: false },
        { path: "m/49'/0'/2'", key: "3 text on Trezor", value: "1c0ffeec0ffeec0ffeec0ffeec0ffee1" }
    ]
});

返回结果

单值返回结果:

{
    success: true,
    payload: {
        value: string
    }
}

批量返回结果:

{
    success: true,
    payload: [
        { value: string },
        { value: string },
        { value: string }
    ]
}

错误信息

{
    success: false,
    payload: {
        error: string // error message
    }
}

从之前版本迁移

版本4及更早:

TrezorConnect.cipherKeyValue(
    "m/49'/0'/0'",     // path
    "This is displayed on Trezor during encrypt", // key
    "1c0ffeec0ffeec0ffeec0ffeec0ffee1",           // value
    true,              // encrypt
    true,              // ask on encrypt
    true,              // ask on decrypt
    function(result) { // callback
        // result not changed
    }
);

版本5:

// params are key-value pairs inside Object
TrezorConnect.cipherKeyValue({ 
    path: "m/49'/0'/0'",
    key: "This is displayed on Trezor during encrypt",
    value: "1c0ffeec0ffeec0ffeec0ffeec0ffee1",
    encrypt: true,
    askOnEncrypt: true,
    askOnDecrypt: true
}).then(function(result) {
    // result not changed
})

wipeDevice - 重置钱包到出厂状态

将设备重置到出厂状态,删除所有私有数据。

调用方法

ES6:

const result = await TrezorConnect.wipeDevice(params);
CommonJS:

TrezorConnect.wipeDevice(params).then(function(result) {

});

参数:

可选的公共参数:

  • useEmptyPassphrase:设置为true
  • allowSeedlessDevice:设置为true

示例代码

TrezorConnect.wipeDevice();

返回结果

{
    success: true,
    payload: {
        message: 'Device wiped'
    }
}

错误信息

{
    success: false,
    payload: {
        error: string // error message
    }
}

resetDevice - 复位钱包

进行钱包设置,生成新的种子。

调用方法

ES6:

const result = await TrezorConnect.resetDevice(params);
CommonJS:

TrezorConnect.resetDevice(params).then(function(result) {

});

参数:

可选的公共参数。

  • strength:强度,有效值为[128|192|256],可选,默认值:256
  • label:标签,字符串,可选
  • u2fCounter:计数器,可选,默认值:当前秒计时间戳
  • pinProtection:是否使用pin保护,布尔值,可选
  • passphraseProtection:是否使用密码保护,布尔值,可选
  • skipBackup:是否跳过备份,布尔值,可选
  • noBackup:是否创建无种子设备,布尔值,可选

示例代码

TrezorConnect.resetDevice({
    label: 'My fancy Trezor',
});

返回结果

{
    success: true,
    payload: {
        message: 'Device successfully initialized'
    }
}

错误信息:

{
    success: false,
    payload: {
        error: string // error message
    }
}
全部评论(0)
给作者留言