YOYOW Middleware Instruction（Nodejs）¶
Using YOYOW middleware is the easiest way to integrate with the platform. It mainly provides three interfaces: account authorization, platform incentives and content chaining. You can use Docker one-click deployment to get the corresponding API, and easily interact with the YOYOW blockchain.
YOYOW middleware communicates with YOYOW network through the API interface of YOYOW node, which provides platform service providers with convenient access to data on the chain, ensuring that the traditional business codes can also reach the requirements of being on chain with only minimal changes. The specific diagram is as follows:
For the creation steps of the platform, please refer to: Create a YOYOW platform account from scratch
Deployment Start¶
Configuration File Description¶
The path to the configuration file is in the conf/config.js file in the code path. If you start it in docker mode, you can map the configuration file to the /app/conf directory in the container.
{
// The api server address, the testnet public api address is as follows, for the official network deployment, please change the address
apiServer: "ws://47.52.155.181:10011",
// The validity time of the security request, and the unit is "s". If the requested content exceeds the validity period, it will return 1003 the request has expired.
secure_ageing: 60,
// The platform security request verification key can be customized. For details, see "Security Access".
secure_key: "",
// Platform owner active key
active_key: "",
// Platform owner secondary key
secondary_key: "",
// Platform owner memo key
memo_key: "",
// Platform id (yoyow id)
platform_id: "",
// Whether to use points for the operating fee
use_csaf: true,
// Whether the transfer is transferred to the balance, otherwise it is transferred to tipping
to_balance: false,
// Wallet authorization page URL, testnet address is as follows, official network address “https://wallet.yoyow.org/#/authorize-service”
wallet_url: "http://demo.yoyow.org:8000/#/authorize-service",
// The IP list that is allowed to access； forcing the specific IP address to be specified. "*" or "0.0.0.0" is not supported at this time.
allow_ip: ["localhost", "127.0.0.1"]
}
Note:
- In the general use scenario, the middleware value needs to use the secondary key and the memo key at most, and just the secondary key and the memo key can satisfy most of the requirements. Do not write the active key into the configuration file unless you are sure you need to use the active key.
- The middleware uses the restriction IP (
allow_ip) and encryption request (secure_key) to ensure security. However, it is still strongly recommended that the intranet be deployed and isolated, and the security of the private key is quite important. - It is recommended to use the point deduction for the operation fee. If the deduction fails, it will directly report the error and will not automatically deduct the tipping as the fee.
Docker One-Click Deployment¶
docker run -itd --name yoyow-middleware -v <Local configuration file path>:/app/conf -p 3001:3001 yoyoworg/yoyow-middleware
Manual Deployment¶
- clone source code
git clone git@github.com:yoyow-org/yoyow-node-sdk.git - Modify middleware configuration；modify the file
yoyow-node-sdk/middleware/conf/config.jswith reference to the configuration file description (). - The node library required to install the middleware service; go to the
~/yoyow-node-sdk/middleware/directory and findnpm install. - Start middleware service
npm start
Normal start as shown below
Interface Descriptions¶
Request Documentation and Examples¶
4. About Auth¶
4.1. Signature Platform¶
sign
Requst Type：GET
Request Parameters：null
Request Example：
localhost:3000/auth/sign
Return Results：
{
code: operation results,
message: return message,
data: {
sign: signature results,
time: operation time millisecond value,
platform: platform owner id,
url: wallet authorization url
}
}
4.2 Signature Verification¶
verify
Request Type：GET
Request Parameters：
{Number} yoyow - account id
{Number} time - operation time millisecond value
{String} sign - signature results
Request Example：
localhost:3000/auth/verify?sign=20724e65c0d763a0cc99436ab79b95c02fbb3f352e3f9f749716b6dac84c1dc27e5e34ff8f0499ba7d94f1d14098c6a60f21f2a24a1597791d8f7dda47559c39a0&time=1517534429858&yoyow=217895094
Return Results：
{
code: operation results,
message: return message,
data: {
verify: is the signature successful or not,
name: signed YOYOW user name
}
}
4.3 Signature Platform Returned QR Code¶
signQR
Request Type：GET
Request Parameters：
{String} state - The extra data will be sent to the platform together with the user signature information when the platform login interface is invoked. It is used when the platform login interface needs a customized parameter. If there is no such requirement, it may not be transmitted.
Request Example：
localhost:3000/auth/signQR?state=platformCustomParams
Return Results：
{
code: operation results,
message: return message,
data: QR code picture base64 string
}
4.4 Platform Extra Data Protocol Descriptions¶
platform attributes extra_data extra data JSON object format string
{
"login":"http://example/login" //Platform QR code scanning login request interface
"description":"platform description" //platform description
"image":"http://example.image.jpg" //platform image，platform image displayed in yoyow app 1.1
"h5url":"http://exampleH5.com" //Platform h5 address, used to adjust the h5 page without the app jumping
"packagename":"com.example.app" //Platform android jump
"urlscheme":"example://" //Platform ios jump
}
4.5 Platform Login by Scanning QR Code¶
When the wallet App scans QR code and it will access and post signature object to “login” url in extra data.
{
{Number} yoyow - Current operating user account id
{String} time - Signature timestamp string
{String} sign - Signature string
{String} state - Custom information passed in when the platform is signing (refer to About Auth 4.3 - signQR)
}
the interface provided by the platform must return the following information
{
{Number} code - operation result 0 means passing. Any non-zero condition is considered an error
{String} message - operation result description
}
Request for Returning Error Code Status Description¶
1001 invalid signature type
1002 invalid signature time
1003 request has expired
1004 invalid operation time
1005 invalid operation signature
1006 account information does not match the chain (usually after the private key is restored, using the local data of other computers or the old backup file for authorization operation)
1007 Unauthorized platform
2000 api underlying exception
2001 account does not exist
2002 invalid account
2003 invalid transfer amount
2004 tipping and points are insufficient for paying fees
2005 insufficient tipping
2006 invalid asset symbol or id
3001 Post ID must be the previous post ID +1 of the issuer of the platform (platform post management id)
Security Request Verification¶
Operations related to financial security, such as transfer, posting, and other write operations, will be verified for their effectiveness in the middleware service. The information of such requests needs to be converted into ciphertext by encryption and then sent to the middleware service. The encryption method uses symmetric encryption AES, and the key is secure_key in the configuration file.
Encryption example (crypto-js version of javascript, other languages use similar AES encryption)
Default mode CBC , padding scheme Pkcs7
For example：transfer operation
let key = 'customkey123456'; // This key is the same as the secure_key in the config in the middleware.
let sendObj = {
"uid": 9638251,
"amount": 100,
"asset_id": 0,
"memo": "hello yoyow",
"time": Date.now() //time field
The operation time takes the current time millisecond value.
Encryption must have this field for verifying the operation time
}
let cipher = CryptoJS.AES.encrypt(JSON.stringify(sendObj), key);
$.ajax({
url: 'localhost:3000/api/v1/transfer',
type: 'POST',
data: {
ct: cipher.ciphertext.toString(CryptoJS.enc.Hex),
iv: cipher.iv.toString(),
s: cipher.salt.toString()
},
success: function(res){
// do something ...
}
})
PHP encryption
function cryptoJsAesEncrypt($passphrase, $value){
$salt = openssl_random_pseudo_bytes(8);
$salted = '';
$dx = '';
while (strlen($salted) < 48) {
$dx = md5($dx.$passphrase.$salt, true);
$salted .= $dx;
}
$key = substr($salted, 0, 32);
$iv = substr($salted, 32,16);
$encrypted_data = openssl_encrypt($value, 'aes-256-cbc', $key, true, $iv);
$data = array("ct" => bin2hex($encrypted_data), "iv" => bin2hex($iv), "s" => bin2hex($salt));
return json_encode($data);
}
For other operations that require secure request verification, change sendObj according to the documentation