Enhance application-side support on Co-Build Protocol

[devchenyan]

Motivation

CKB Transaction Co-Build Protocol details an off-chain protocol for multiple parties to collaboratively create CKB transactions. It encompasses standard procedures and data formats for transaction building and signing. In real-world scenarios, interactions between wallets and dApps necessitate functionalities like account retrieval, address synchronization, and message signing. Moreover, wallets need to emit relevant events when changes occur in addresses or accounts, for dApps to subscribe to. Additionally, the design and validation of communication methods between wallets and dApps are also essential.

Specification

• Accounts
• Methods
• Events
• Communication Method
• UX Design

Accounts

Component	Description
account_id	chain_reference + : + identity
chain_id	One of (mainnet, testnet, devnet)
identity	The hash obtained by the first pk of the account

Methods

ckb_getAddresses

Get the Address list by specific lock script base, in the format of <code_hash>:<hash_type>.

• Parameters

{
    [<script_base>] :{
       page: {
         size: number           // the size of address list to return
         before: string         // used as the end point of the returned address list(excluded)
         after: string          // used as the start point of the returned address(excluded)
       },
       type: 'generate' | 'all' // set 'generate' to generate new addresses if necessary; set 'all' to get existent addresses
   }
}

• Returns

{
    '<script_base x>' : Address[],
    '<script_base y>' : Address[],
}

ckb_signTransaction

Get a SignedTransaction over the provided instructions.

• Parameters

{
  buildingPacket: {
    message: Message,
    payload: Transaction,
    script_infos: <ScriptInfo defined above>[],
    lock_actions: <lock actions>[]
  }
}

• Returns

{
  witnesses:  Witness[]
}

ckb_sendTransaction

• Parameters

{
   transaction: SignedTransaction 
}

• Returns

{
  hash: string
}

ckb_signMessage

Get a signature for the provided message from the specified signer address.

• Parameters

{
   message: string, // the message to sign
   address: string  // address of which private to sign
}

• Returns

{
  signature: string
}

Events

accountChanged

Emit the event when the account changed

{
   name: "accountChanged",
   data: string
}

addressesChanged

Emit the event when addresses changed

{
   name: "addressesChanged",
   data: {
        addresses: Address[],
        changeType: 'add' | 'consume' // add: new addresses created; consume: addresses consumed
    }
}

compound types

Address

interface Address {
  address: string
  identifier: string
  description: string
  balance: string
  index: number
}

Message

interface Message {
  actions: {
    script_info_hash: string,
    script_hash: string,
    data: object,
  }[],
}

Transaction

interface Transaction {
  cellDeps: {
    outPoint: {
      txHash: string;
      index: string;
    };
    depType: string;
  }[];
  headerDeps: string[];
  inputs: {
    previousOutput: {
      txHash: string;
      index: string;
    };
    since: string;
    capacity: string;
    lock: {
      args: string;
      codeHash: string;
      hashType: 'type' | 'data';
    };
    lockHash: string;
  }[];
  outputs: {
    capacity: string;
    lock: {
      args: string;
      codeHash: string;
      hashType: 'type' | 'data';
    };
    type: {
      args: string;
      codeHash: string;
      hashType: 'type' | 'data';
    };
  }[];
  outputsData: string[];
  description: string;
  [key: string]: any;
}

SignedTransaction

interface interface SignedTransaction {
  transaction: Transaction;
  witnesses: {
    seal: string,
    message: Message
  }[];
}

Communication Method

Currently known methods include:

• Communicating between web pages via URL, primarily used in JoyID scenarios.
• Communicating between web pages via post message, primarily used in JoyID scenarios.
• Communicating between applications via deep link, mainly for app scenarios.
• Using WebRTC to facilitate communication between dapps and wallets.

The CKB Transaction Co-Build Protocol mentions that the size of a CKB transaction varies depending on its content—it could be due to a large number of inputs/outputs, or substantial output data, meaning the size isn't constant. Per the CKB protocol's limitations, a CKB transaction could reach up to 600KB under extreme conditions. This implies that the BuildingPacket's size could be close to or even exceed 600KB, considering it also includes other components like Message, ScriptInfo, etc.

The first three methods all face the issue of having limitations on the size of data that can be transferred. Therefore, we can consider using WebRTC for communication.

Implement WebRTC for establishing a connection and communication:

1. Create RTCPeerConnection:

const peerConnection = new RTCPeerConnection(configuration);

2. Set Up ICE Candidate Event:

peerConnection.onicecandidate = event => {
  if (event.candidate) {
    // Send candidate to remote peer
  }
};

3. Create an Offer (Initiator) or Answer (Receiver):

• Offer:

peerConnection.createOffer().then(offer => {
  return peerConnection.setLocalDescription(offer);
}).then(() => {
  // Send the offer to the remote peer
});

• Answer:

peerConnection.setRemoteDescription(remoteOffer).then(() => {
  return peerConnection.createAnswer();
}).then(answer => {
  return peerConnection.setLocalDescription(answer);
}).then(() => {
  // Send the answer to the remote peer
});

4. Exchange ICE Candidates:
   Exchange the ICE candidates received from onicecandidate event with the remote peer.

5. Data Communication:
   For data transfer, use RTCDataChannel:

const dataChannel = peerConnection.createDataChannel("myDataChannel");
dataChannel.onmessage = event => {
  console.log("Data received:", event.data);
};

UX Design

https://vs0cjf.axshare.com/#id=psrijc&p=walletconnect-general&g=1

[devchenyan]

Aspects not covered by the protocol, which we need to supplement include:

• Synchronizing addresses
• Events

Currently known methods include:

• Communicating between web pages via URL, primarily used in JoyID scenarios.
• Communicating between web pages via post message, primarily used in JoyID scenarios.
• Communicating between applications via deep link, mainly for app scenarios.
• Using WebRTC to facilitate communication between dapps and wallets. (Research on WebRTC #392)