sidebar_position |
---|
2 |
A user's Valora wallet invokes shortcut hooks when determining asset or dapp related calls-to-action for the user. For example, when a user opens Valora's homescreen. A shortcut hook returns a human readable summary of available actions (e.g., "Claim your 1 cUSD earnings") and if the user chooses to act on them, a set of blockchain or in-app transactions will be executed by Valora with the user's consent.
Note The UI/UX for shortcut hooks in Valora is currently focused on the "claim rewards" use case and requires a position pricing hook to be implemented as well. We plan to expand them to other use cases in the future (shortcuts with custom inputs, not linked to positions, or across dapps).
Hooks are organized by application. For instance GoodDollar hooks are located in https://github.com/valora-inc/hooks/tree/main/src/apps/gooddollar
.
Shortcut hooks must implement the ShortcutsHook
TypeScript interface.
To create a shortcut hook for your application named MyApp
, you will need to create a new folder with the name my-app
in src/apps
and add a shortcuts.ts
file. The file should export an object with the following properties:
import { ShortcutsHook } from '../../types/shortcuts'
const hook: ShortcutsHook = {
async getShortcutDefinitions() {
// TODO: implement
},
}
export default hook
The getShortcutDefinitions
function is called by Valora to get the list of shortcuts.
It should return an array of ShortcutDefinition
objects.
Here's a simplified example of a getShortcutDefinitions
implementation for claiming GoodDollar rewards.
Please take a look at the full implementation for more details.
const hook: ShortcutsHook = {
getShortcutDefinitions() {
return [
{
id: 'claim-reward',
name: 'Claim',
description: 'Claim daily UBI rewards',
networks: ['celo'],
category: 'claim',
async onTrigger(network, address, positionAddress) {
// This isn't strictly needed, but will help while we're developing shortcuts
const { request } = await client.simulateContract({
address: positionAddress as Address, // This is the ubi contract address
abi: ubiSchemeAbi,
functionName: 'claim',
account: address as Address,
})
const data = encodeFunctionData({
abi: request.abi,
args: request.args,
functionName: request.functionName,
})
return [
{
network,
from: address,
to: positionAddress,
data,
},
]
},
},
]
},
}
Here you can see that it contains the following properties:
id
: the unique identifier for the shortcutname
: the title of the button used to trigger the shortcutdescription
: the description of the shortcutnetworks
: the networks the shortcut is available oncategory
: the category of the shortcutonTrigger
: the function that is called when the shortcut is triggered
Once the shortcut is defined, Valora needs to know when to show it to the user, by linking it to an existing position.
This is done by adding the availableShortcutIds
property to the position definition and setting the category
to claimable
for the appropriate token(s).
This way Valora will be able to determine that the position has claimable token(s) and what shortcut to call to claim them.
const position: ContractPositionDefinition = {
type: 'contract-position-definition',
// Setting the `category` to `claimable` to indicate that the token can be claimed
tokens: [{ address: G$_ADDRESS, network, category: 'claimable' }],
// Setting the `availableShortcutIds` to the shortcut id defined above
availableShortcutIds: ['claim-reward'],
// [...] more properties omitted for brevity
}
Once this all done, Valora will show the GoodDollar shortcut in the rewards screen, with the available reward amount, and the button to claim it.
The hooks live preview mode in Valora is the easiest way to test your shortcut hook while developing it.
Alternatively, you can use the following scripts via the command line.
To see your shortcut hook, you can use the getShortcuts
script.
yarn getShortcuts --apps <app-name>[,<app-name2>]
Example for GoodDollar:
yarn getShortcuts --apps gooddollar
To see positions linked to your shortcut hook, you can use with the getPositions
script.
yarn getPositions --network <network> --address <address> --apps <app-name>[,<app-name2>]
Example for GoodDollar:
yarn getPositions --network celo --address 0x2b8441ef13333ffa955c9ea5ab5b3692da95260d --apps gooddollar
To test triggering your shortcut hook, you can use the triggerShortcut
script.
yarn triggerShortcut --network <network> --address <address> --app <app-name> --shortcut <shortcut-id> --positionAddress <position-address>
This will return the transactions that would be executed by Valora, after approval by the user.
You can also optionally pass the --mnemnonic
and --derivationPath
(defaults to the Celo derivation path: m/44'/52752'/0'/0/0
) options to actually sign and send the returned transaction(s).
Example for GoodDollar:
yarn triggerShortcut --network celo --address 0x11489ae0761343c3b03c630a63b00fa025bc4eea --app gooddollar --shortcut claim-reward --positionAddress 0x43d72Ff17701B2DA814620735C39C620Ce0ea4A1