Introduction
SessionKeyAspectClient
is a JavaScript library for managing session keys on the Artela Session-key Aspect. It provides a set of APIs to interact with Aspect for session key operations.
Installation
npm install session-key-aspect-client
Quick start
Import related lib on your node.js project.
const SessionKeyAspectClient = require('session-key-aspect-client');
const Web3 = require('@artela/web3');
Init SessionKeyAspectClient
// 1. init web3 client
const testnetRpc = "https://testnet-rpc1.artela.network"
const web3 = new Web3(testnetRpc);
// 2. init session key client
const testAspectAddress = "0x06786bB59719d7DDD9D42457a16BbCD6953A7cab";
const aspectClient = new SessionKeyAspectClient(web3, testAspectAddress);
Register a session key and query it.
// init your main key
const yourWalletPrivateKey = "0xCAFE....CAFE";
const account = web3.eth.accounts.privateKeyToAccount(yourWalletPrivateKey);
// register session key
const testSessionKeyAddress = "0x0250032b4a11478969dc4caaa11ecc2ea98cfc12";
const testContract = "0330032b4a11478969dc4caaa11ecc2ea98cfcFF";
const testMethods = ["0A0A0A0A", "0B0B0B0B"];
const testExpireBlockNumber = 2000;
let ret = await aspectClient.registerSessionKey(account, testSessionKeyAddress, testContract, testMethods, testExpireBlockNumber);
console.log(ret);
// query this session key
let sessionKey = await aspectClient.getSessionKey(account.address, testSessionKeyAddress, testContract);
console.log(sessionKey)
Usage
Usage 1. Use registerSessionKey
to sign and send the session key.
Usage 2. Use registerSessionKeyUnsignTx
to construct an unsigned transaction and then sign and send it by your web3 client.
Usage 3. Use registerSessionKeyByMetamask
to require Metamask to sign and send the register transaction.
API Reference
registerSessionKey
1. Registers a new session key.
-
Parameters:
-
account
- object: The web3.js account object. Learn more: web3.eth.accounts -
sessionKeyAddress
- string: The session key address. -
bindingContractAddress
- string: The contract address to bind. -
bindingMethodSigSet
- string[]: An array of method signatures. -
expireBlockNumber
- number: The number of blocks until expiration (default 1000).
-
-
Returns: An object containing the success status and transaction receipt.
-
success
- boolean: true | false -
receipt
- object: a web3.js receipt object. Learn more: receipt
-
-
Example:
// init your main key const yourWalletPrivateKey = "0xCAFE....CAFE"; const account = web3.eth.accounts.privateKeyToAccount(yourWalletPrivateKey); // register session key const testSessionKeyAddress = "0x0250032b4a11478969dc4caaa11ecc2ea98cfc12"; const testContract = "0330032b4a11478969dc4caaa11ecc2ea98cfcFF"; const testMethods = ["0A0A0A0A", "0B0B0B0B"]; const testExpireBlockNumber = 2000; let ret = await aspectClient.registerSessionKey(account, testSessionKeyAddress, testContract, testMethods, testExpireBlockNumber);
registerSessionKeyByMetamask
2. Registers a session key through MetaMask. Call this method will ask for Metamask signatrure.
-
Parameters:
-
accountAddress
- string: The address of the account. -
sessionKeyAddress
- string: The session key address. -
bindingContractAddress
- string: The contract address to bind. -
bindingMethodSigSet
- string[]: An array of method signatures. -
expireBlockNumber
- number: The number of blocks until expiration (default 1000).
-
-
Returns: Transaction hash.
-
Example:
// init client const web3 = new Web3(window.ethereum); const testAspectAddress = "0x06786bB59719d7DDD9D42457a16BbCD6953A7cab"; let aspectClient = new SessionKeyAspectClient(web3, aspectAddress); await window.ethereum.enable(); // call api const walletAddress = await window.ethereum.request({ method: 'eth_requestAccounts' }); const testSessionKeyAddress = "0x0250032b4a11478969dc4caaa11ecc2ea98cfc12"; const testContract = "0330032b4a11478969dc4caaa11ecc2ea98cfcFF"; const testMethods = ["0A0A0A0A", "0B0B0B0B"]; const testExpireBlockNumber = 2000; await aspectClient.registerSessionKeyByMetamask(walletAddress, testSessionKeyAddress, testContract, testMethods, testExpireBlockNumber);
registerSessionKeyUnsignTx
3. Generates an unsigned transaction for registering a session key. Then, the caller signs and sends the transaction by themself.
-
Parameters: Similar to
registerSessionKeyByMetamask
. -
Returns: Unsigned transaction object.
-
from
- string: main key address -
to
- string: Aspect system contract address -
gas
- number: gas of this tx -
data
- string: call data of register session key
-
-
Example:
// get unsign tx let unsignTx = await aspectClient.registerSessionKeyUnsignTx(account.address, testSessionKeyAddress, testContract, testMethods, 20); console.log(unsignTx); // sign and send it let signedTx = await web3.eth.accounts.signTransaction(unsignTx, account.privateKey); let receipt = await web3.eth.sendSignedTransaction(signedTx.rawTransaction); console.log(receipt); // query from blockchain sessionKey = await aspectClient.getSessionKey(account.address, testSessionKeyAddress, testContract); console.log(sessionKey);
getSessionKey
4. Retrieves the session key.
-
Parameters:
-
walletAddress
- string: The wallet address. E.g.0xCAFE...CAFE
-
sessionKeyAddress
- string: The session key address. E.g.0xCAFE...CAFE
-
bindingContractAddress
- string: The contract address. E.g.0xCAFE...CAFE
-
-
Returns: Session key object.
-
walletAddress
- string: the main key -
sessionKeyAddress
- string: the session key -
bindingContractAddress
- string: the binding contract of this session key -
bindingMethodSet
- string[]: the binding contract method set of this session key -
expireBlockHeight
- number: the expire block height of this session key
-
-
Example:
// register session key const testMainKeyAddress = "0x0250032b4a11478969dc4caaa11ecc2ea98cfc12"; const testSessionKeyAddress = "0x0250032b4a11478969dc4caaa11ecc2ea98cfc12"; const testContract = "0330032b4a11478969dc4caaa11ecc2ea98cfcFF"; // query this session key let sessionKey = await aspectClient.getSessionKey(testMainKeyAddress, testSessionKeyAddress, testContract); console.log(sessionKey)
getSessioinKeyExpireHeight
5. Retrieves the expiration height of the session key.
-
Parameters: Similar to
getSessionKey
. -
Returns: Number; The block height at which the session key expires.
getAllSessionKey
6. Retrieves all session keys of specific EoA
-
Parameters:
-
walletAddress
- string: The EoA address. E.g.0xCAFE...CAFE
-
-
Returns: Session key object array. The object struct is similar to
getSessionKey
.
bindEoA
7. Bind EoA to the aspect.
-
Parameters:
-
account
- object: The web3.js account object of EoA. Learn more: web3.eth.accounts
-
-
Returns: An object containing the success status and transaction receipt.
-
success
- boolean: true | false -
receipt
- object: a web3.js receipt object. Learn more: receipt
-
-
Example:
// init your main key const yourWalletPrivateKey = "0xCAFE....CAFE"; const account = web3.eth.accounts.privateKeyToAccount(yourWalletPrivateKey); let ret = await aspectClient.bindEoA(account);
unbindEoAByMetamask
8. Bind EoA to the Aspect through MetaMask. Call this method will ask for Metamask signatrure.
-
Parameters:
-
accountAddress
- string: The address of the EoA.
-
- Returns: Transaction hash.
unbindEoA
9. Undind EoA from the Aspect.
-
Parameters:
-
account
- object: The web3.js account object of EoA. Learn more: web3.eth.accounts
-
-
Returns: An object containing the success status and transaction receipt.
-
success
- boolean: true | false -
receipt
- object: a web3.js receipt object. Learn more: receipt
-
-
Example:
// init your main key const yourWalletPrivateKey = "0xCAFE....CAFE"; const account = web3.eth.accounts.privateKeyToAccount(yourWalletPrivateKey); let ret = await aspectClient.unbindEoA(account);
unbindEoAByMetamask
10. Unbind EoA from the Aspect through MetaMask. Call this method will ask for Metamask signatrure.
-
Parameters:
-
accountAddress
- string: The address of the EoA.
-
- Returns: String; Transaction hash.
bindContract
11. Bind a smart contract to the Aspect.
-
Parameters:
-
account
- object: The owner of the smart contract. It's a web3.js account object of EoA. Learn more: web3.eth.accounts -
contractAddress
- string: The smart contract address.
-
-
Returns: An object containing the success status and transaction receipt.
-
success
- boolean: true | false -
receipt
- object: a web3.js receipt object. Learn more: receipt
-
-
Example:
// init your main key const yourWalletPrivateKey = "0xCAFE....CAFE"; const account = web3.eth.accounts.privateKeyToAccount(yourWalletPrivateKey); let ret = await aspectClient.bindContract(account);
bindContractByMetamask
12. Bind a smart contract to the Aspect through MetaMask. Call this method will ask for Metamask signatrure.
-
Parameters:
-
accountAddress
- string: The owner of the smart contract. -
contractAddress
- string: The smart contract address.
-
-
Returns: Transaction hash.
-
Example:
// init your main key const eoaAddress = "0xCAFE....CAFE"; const smartContractAddress = "0xCAFE....CAFE"; let ret = await aspectClient.bindContract(eoaAddress, smartContractAddress);
ifBinding
13. Query if is a EoA or smart contract bound to the Aspect.
-
Parameters:
-
address
- string: The address of EoA or smart contract. E.g.0xCAFE...CAFE
-
- Returns: Bool
getBindingAccount
14. Query all address binding to this Aspect.
- Returns: String array of address