Locked/Leased FLOW Account Setup

This guide is for custodians and wallet providers who wish to create user accounts that can hold leased or locked FLOW tokens from the Flow token sale.

If you already have an account and wish to stake tokens, please see our guides on staking here.

Introduction

This guide covers the technical integration required for custodians to create accounts that store locked and/or leased FLOW tokens for users.

Before discussing the account creation process, some terminology needs to be defined:

• Flow Token Admin - The user who controls the locked and vesting tokens from the Flow Token sale. This user maintains a record of users, their account addresses, and how many Flow tokens they will receive according to their vesting schedule. This user also is required to co-sign any transactions that transfer locked tokens before they have been unlocked via the vesting schedule.

• User - A user who has bought Flow tokens in the Flow token sale or auction.

• Custody/Wallet Provider - A service that is managing accounts on behalf of users.

Every user who holds locked FLOW tokens gets two accounts.

• Account 1 - User Account: This is the user's normal Flow account. This account is completely controlled by the user. It can have already been created by the custody provider or can be created along with the user's second account.

• Account 2 - Shared Account: This account is shared between the Flow token admin and the user. In the case of a locked token relationship with a user who owns the tokens in this account, The user's key will have weight 900 and the token admin's key will have weight 100. The pre-generated token admin's key with weight 100 will be easily accessible for the custody provider to fetch and use to create this account. Any transactions that directly access this account need to be signed by the user and the token admin. The locked tokens are stored in this account and the token admin has the authority to unlock tokens as outlined by the vesting schedule. This account also manages access to the staking and delegating functionality that a user signs up for.

In the case of a leased token relationship where the token admin has leased tokens to a user for the purposes or node operation, the user does not own the tokens in the shared account. The token admin's key will have weight 1000. The pre-generated token admin's key with weight 1000 will be easily accessible for the custody provider to fetch and use to create this account. This account also manages access to the staking and delegating functionality that a user signs up for.

The User Account will include an object that manages access to the staking functionality contained in the shared account. The user submits token withdrawal and staking transactions with locked tokens with their normal account, without the need for a signature from the token admin. The user can also withdraw staking rewards from the shared account without the need for a signature from the token admin.

Setup

Configure a Creator Account

As the custodian, you must configure a Flow account that you will use to create user accounts. This is called your creator account.

You can convert an existing account into a creator account by running the Set Up Creator Account (C.01) transaction.

This transaction creates an AccountCreator object and stores it in the custodian's account. It also publishes a capability that allows the token admin to grant the custodian the authority to register locked token accounts.

Receive Account Creator Capability

Note: Once you reach this step, please contact the token admin.

After you have set up your creator account, the token admin needs to submit one more transaction to enable your account to register new user accounts to receive locked tokens.

The Deposit Account Creator (TA.06) transaction must be signed and authorized by the token admin account. It requires the following arguments:

Argument	Type	Description
custodyProviderAddress	Address	The address of the custodian's account.

This transaction gives the account registration capability to the custodian's creator account that was configured in the previous transaction.

Account Creation

When a custodian uses these transactions, they must also ensure that the token admin knows which account addresses map to which users. This is so the token admin knows how much to pay to each locked account, how many tokens to unlock via the vesting schedule, and/or which accounts apply to each node operator.

1. Create Both Accounts for the User

If your user does not have a regular account created for them yet, you must create both accounts using the Create Shared Lease Accounts (C.04) transaction with the following arguments:

Argument	Type	Description
fullAdminPublicKey	[UInt8]	The public key of the token admin. Must be Weight: 1000
fullUserPublicKey	[UInt8]	The public key of the user. Must be Weight: 1000

2. Create the Shared Account for an Existing User Account

If your user already has a personal account allocated to them, you can run a transaction that creates the shared account and gives their existing account the capability to interact with their locked tokens.

This transaction MUST also be signed and authorized by the existing user account. It needs this because it needs to have access to the user's private storage and Authorized access.

To attach a shared account to an existing user account, run the Create Only Shared Account (C.03) transaction with the following arguments:

Argument	Type	Description
fullAdminPublicKey	[UInt8]	The public key of the token admin. Must be Weight: 1000

3. (Optional) Convert the Shared account to a locked account.

If the account is intended to be a leased tokens account, then there is no more action to take. The token admin by default should have control of the shared account, and the user has access to staking capabilities on the shared account, but not the tokens themselves.

If you would like to convert the shared account to a locked token account instead of a leased account, you must contact the token admin, who will submit a transaction that sets the keys on the shared account to the locked account set up, which consists of the admin key with weight 100 and the user key with weight 900.

Summary

The account creation transactions generally perform these actions:

1. Create the shared account and add the public keys to the account.
2. Create and store the Locked Token Manager object in the shared account.
3. Create the Token Holder object and store it in the user account. This object is what the user interacts with to withdraw unlocked tokens and perform staking actions.
4. Register the new accounts with the token admin account so that it can receive locked tokens from the vesting schedule.
5. Override the default Flow Token receiver to mark received tokens as unlocked.
6. Create a different Flow Token receiver that the token admin account uses to deposit locked tokens.