Account & credits

`recall account`

Interaction with the Recall network requires an account (ECDSA, secp256k1). As with any blockchain system, an account can be created at will, transfer funds, and send transactions. A transaction can be a deposit, withdrawal, or (intra-subnet) transfer.

The account command allows you to execute various subcommands:

create: Create a new account with a private key.
credit <subcommand>: Manage credits for your account and sponsoring storage for contracts.
info: Get account information (address, sequence, balance).
deposit: Deposit funds into a subnet from its parent.
withdraw: Withdraw funds from a subnet to its parent.
sponsor: Set or unset an account's default credit sponsor for gas fees.
transfer: Transfer funds to another account in a subnet.

Create an account

Create a new account from a random seed.

recall account create

This command logs a JSON object to stdout with three properties: the private key, EVM public key, and its corresponding Wasm compatible address.

Examples:

Create a new private key:

recall account create

{
  "private_key": "d5020dd0b12d4d8d8793ff0edbaa29bd7197879ddf82d475b7e9a6a34de765b0",
  "address": "0xc37ab532c1409900520a92e04a6c0482394d3133",
  "fvm_address": "t410fyn5lkmwbicmqauqkslqeu3aeqi4u2mjturajlui"
}

Optionally, pipe its output into a file to store the keys:

recall account create > account.json

Credit

Manage credits for your account and sponsoring storage for contracts.

recall account credit <SUBCOMMAND>

Buy credit

Buy credits for an account.

recall account credit buy <AMOUNT>

Positionals	Description
`<AMOUNT>`	The amount of credits to purchase using the subnet's native coin.

Flag	Required?	Description
`-p, --private-key`	Yes	Wallet private key (ECDSA, secp256k1) for signing transactions.
`--to <TO>`	No	The recipient account address (if not present, defaults to the signer's address).
`-b, --broadcast-mode`	No	Broadcast mode for the transaction: `commit`, `sync`, or `async` (default: `commit`).
`--gas-limit`	No	Gas limit for the transaction.
`--gas-fee-cap`	No	Maximum gas fee for the transaction in attoFIL (1FIL = 10**18 attoFIL).
`--gas-premium`	No	Gas premium for the transaction in attoFIL (1FIL = 10**18 attoFIL).
`--sequence`	No	Sequence (i.e., nonce) for the transaction.

You'll see three values in the data field of the response:

credit_free: The number of credits available to spend—equivalent to the amount of credits purchased and not yet committed to storing data.
credit_committed: The number of credits committed to storing data.
last_debit_epoch: The epoch (block height) at which the account last had credits debited.

Examples:

Buy credit with 1 native coins (displayed with $10^{18}$ units).

recall account credit buy 1

{
  "transactionHash": "0x43128b0b87756c715e2de3e28975f9c0f93b82c94423c5ee7e7586b434af9528",
  "transactionIndex": "0x0",
  "blockHash": "0xaf1ce19882c15825ea283a3a4d89a4de9e967dbea174c7c1f4ff73e1c4a59e13",
  "blockNumber": "0x3b5a",
  "from": "0x90f79bf6eb2c4f870365e785982e1f101e93b906",
  "to": "0xff00000000000000000000000000000000000042",
  "cumulativeGasUsed": "0xbc18f5",
  "gasUsed": "0xbc18f5",
  "contractAddress": null,
  "logs": [],
  "status": "0x1",
  "root": "0x0de1c354e371d02f589e56947819036d51492ec7fd33fb4ce3b93ed488b2ac06",
  "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "type": "0x2",
  "effectiveGasPrice": "0x8"
}

Approve credit

Approve a credit amount for a bucket.

recall account credit approve [OPTIONS] --to <TO>

Flag	Required?	Description
`-p, --private-key`	Yes	Wallet private key (ECDSA, secp256k1) for signing transactions.
`--to <TO>`	Yes	The receiver account address.
`--credit-limit <LIMIT>`	No	Credit approval limit. If specified, the approval becomes invalid once the used credits reach the specified limit
`--gas-fee-limit <LIMIT>`	No	Gas fee limit. If specified, the approval becomes invalid once the used gas fees reach the specified limit
`--ttl <TTL>`	No	Credit approval time-to-live epochs. If specified, the approval becomes invalid after this duration

Examples:

Approve a receiver to use credits for any buckets created by the approver (i.e., the account making the approval).

recall account credit approve --to 0x15d34aaf54267db7d7c367839aaf71a00a2c6a65

{
  "transactionHash": "0x6240c30d4a8d470439b0555f27210a6535832fe0f7ef58eb2c2426216ae5026c",
  "transactionIndex": "0x0",
  "blockHash": "0x44fe413b517d2f788e8bc59a77b1877267b4cd4106980c193855e5019e4d495f",
  "blockNumber": "0x3b70",
  "from": "0x90f79bf6eb2c4f870365e785982e1f101e93b906",
  "to": "0xff00000000000000000000000000000000000042",
  "cumulativeGasUsed": "0xefbdc9",
  "gasUsed": "0xefbdc9",
  "contractAddress": null,
  "logs": [],
  "status": "0x1",
  "root": "0xad1dea387e3b056b036f22ad8a2d1b3afb35193f51fb6bd72049536b182a8f11",
  "logsBloom": "0x00...",
  "type": "0x2",
  "effectiveGasPrice": "0x8"
}

Or, approve a receiver to use credits with a TTL, credit limit, and gas fee limit.

recall account credit approve \
--to 0x15d34aaf54267db7d7c367839aaf71a00a2c6a65 \
--ttl 3600 \
--credit-limit 10 \
--gas-fee-limit 10

Revoke credit

Revoke a credit amount for a bucket.

recall account credit revoke [OPTIONS] --to <TO>

Flag	Required?	Description
`-p, --private-key`	Yes	Wallet private key (ECDSA, secp256k1) for signing transactions.
`--to <TO>`	Yes	The receiver account address.

Examples:

Revoke a receiver's approval, disabling credit usage.

recall account credit revoke --to 0x15d34aaf54267db7d7c367839aaf71a00a2c6a65

{
  "transactionHash": "0xa8dd119f2729e4fb4f1a81ce477ad0bf93513c883737808bd00d3fd1fad4655e",
  "transactionIndex": "0x0",
  "blockHash": "0xf29f39645b55c931f43ac490db9ced06346a7574f7d2194b3727469054e2cce2",
  "blockNumber": "0x3c54",
  "from": "0x90f79bf6eb2c4f870365e785982e1f101e93b906",
  "to": "0xff00000000000000000000000000000000000042",
  "cumulativeGasUsed": "0xd92bc4",
  "gasUsed": "0xd92bc4",
  "contractAddress": null,
  "logs": [],
  "status": "0x1",
  "root": "0xd8b4f9eff7d45c9e5bc852026713e8bc8e74202c7b0bc2cbf0e3bd4ef590c57f",
  "logsBloom": "0x00...",
  "type": "0x2",
  "effectiveGasPrice": "0x8"
}

Get credit stats

Get the credit stats for a subnet.

recall account credit stats

This is more of a subnet-wide view, as opposed to an account-specific view. It's helpful because it shows the total number of credits sold and committed, number of accounts that have bought credits, and the credit debit rate.

Flag	Required?	Description
`--height`	No	Query at a specific block height (default: `committed`).

Examples:

recall account credit stats

{
  "balance": "50006.999416020598397372",
  "credit_sold": "50007000000000000000000.0",
  "credit_committed": "443136.0",
  "credit_debited": "91848.0",
  "token_credit_rate": "1000000000000000000000000000000000000",
  "num_accounts": 10
}

Get account info

Get account information, such as its address, nonce, token balance, credit balance, and approvals.

recall account info {--private-key <PRIVATE_KEY> | --address <ADDRESS>}

This commands logs a JSON object to stdout: its public key, addresses, current sequence (nonce), current subnet balance, and its balance on the parent subnet.

Flag	Required?	Description
`-p, --private-key`	Yes, if no `address`	Wallet private key (ECDSA, secp256k1) for signing transactions.
`-a, --address`	Yes, if no `private-key`	Account address; the signer's address is used if no address is given.
`--height`	No	Query at a specific block height (default: `committed`).
`--evm-rpc-url`	No	The Ethereum API RPC HTTP endpoint.
`--evm-rpc-timeout`	No	Timeout for calls to the Ethereum API (default: `60 seconds`).
`--evm-rpc-auth-token`	No	Bearer token for any Authorization header.
`--evm-gateway`	No	The gateway contract address.
`--evm-registry`	No	The registry contract address.
`--evm-supply-source`	No	The supply source contract address.

Examples:

Get account info for a specific address:

recall account info \
--address 0x90f79bf6eb2c4f870365e785982e1f101e93b906

{
  "address": "0x90f79bf6eb2c4f870365e785982e1f101e93b906",
  "fvm_address": "t410fsd3zx5xlfrhyoa3f46czqlq7capjhoighmzagaq",
  "sequence": 87,
  "balance": "4988.999999999914071354",
  "parent_balance": "98.0",
  "credit": {
    "credit_free": "5003999999999999465016.0",
    "credit_committed": "450336.0",
    "credit_sponsor": "0x15d34aaf54267db7d7c367839aaf71a00a2c6a65",
    "last_debit_epoch": 14400,
    "approvals_to": {
      "0x9965507d1a55bcc2695c58ba16fb37d819b0a4dc": {
        "credit_used": "0.0",
        "gas_fee_used": "0.0"
      }
    },
    "approvals_from": {},
    "gas_allowance": "5003.999442777056242753"
  }
}

Deposit funds

Deposit funds into a subnet from its parent.

recall account deposit [--to <TO>] <AMOUNT>

Think of the deposit command as transferring funds from a parent to a child subnet. If you want to build on Recall, you start by moving funds from the parent L1 (rootnet) to the Recall subnet. This goes through a smart contract (i.e., the gateway contract) call that locks the funds in a smart contract on the parent, later minting them to the address on the subnet (i.e., a bridging flow).

Positionals	Description
`<AMOUNT>`	The amount to transfer.

Optionally, you can pass the --to flag to deposit funds from the parent to a specific address on the child. If you don't specify anything, the funds will be deposited to the address corresponding to the provided private key. Note that the global --network flag (defaults to testnet) will set all of the --evm-... presets for you, but you can override them with your own values, if needed.

Flag	Required?	Description
`-p, --private-key`	Yes	Wallet private key (ECDSA, secp256k1) for signing transactions.
`--to <TO>`	No	The recipient account address (if not present, defaults to the signer's address).
`--evm-rpc-url`	No	The Ethereum API RPC HTTP endpoint.
`--evm-rpc-timeout`	No	Timeout for calls to the Ethereum API (default: `60 seconds`).
`--evm-rpc-auth-token`	No	Bearer token for any Authorization header.
`--evm-gateway`	No	The gateway contract address.
`--evm-registry`	No	The registry contract address.

Examples:

Deposit funds to the signer's address:

recall account deposit 10

{
  "transactionHash": "0x92b26cfc805ca0db03d5ee90f9843f1266ab68d52de3f636be16ae239d7e4892",
  "transactionIndex": "0x0",
  "blockHash": "0x6570a143dfdc9cfcba64b995950c2704e60aa1c38a3f62691784cec784bc1f93",
  "blockNumber": "0x83",
  "from": "0x90f79bf6eb2c4f870365e785982e1f101e93b906",
  "to": "0x9a676e781a523b5d0c0e43731313a708cb607508",
  "cumulativeGasUsed": "0x23772",
  "gasUsed": "0x23772",
  "contractAddress": null,
  "logs": [
    {
      "address": "0x4a679253410272dd5232b3ff7cf5dbb88f295319",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "0x00000000000000000000000090f79bf6eb2c4f870365e785982e1f101e93b906",
        "0x0000000000000000000000009a676e781a523b5d0c0e43731313a708cb607508"
      ],
      "data": "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000",
      "blockHash": "0x6570a143dfdc9cfcba64b995950c2704e60aa1c38a3f62691784cec784bc1f93",
      "blockNumber": "0x83",
      "transactionHash": "0x92b26cfc805ca0db03d5ee90f9843f1266ab68d52de3f636be16ae239d7e4892",
      "transactionIndex": "0x0",
      "logIndex": "0x0",
      "removed": false
    },
    {
      "address": "0x9a676e781a523b5d0c0e43731313a708cb607508",
      "topics": [
        "0xfdd39ce2560484814971f663392e78ae37dc62ba184b3370d830371dd271a8b7",
        "0x000000000000000000000000f1823bc4243b40423b8c8c3f6174e687a4c690b8"
      ],
      "data": "0x00...",
      "blockHash": "0x6570a143dfdc9cfcba64b995950c2704e60aa1c38a3f62691784cec784bc1f93",
      "blockNumber": "0x83",
      "transactionHash": "0x92b26cfc805ca0db03d5ee90f9843f1266ab68d52de3f636be16ae239d7e4892",
      "transactionIndex": "0x0",
      "logIndex": "0x1",
      "removed": false
    }
  ],
  "status": "0x1",
  "logsBloom": "0x00...",
  "type": "0x2",
  "effectiveGasPrice": "0x3b9aca40",
  "blobGasPrice": "0x1"
}

Deposit funds to another address:

recall account deposit --to 0x15d34aaf54267db7d7c367839aaf71a00a2c6a65 10

Withdraw funds

Withdraw funds from a subnet to its parent.

recall account withdraw [--to <TO>] <AMOUNT>

The withdraw command is the opposite of a deposit. It moves funds from a subnet to its parent, which happens through a smart contract call that unlocks the funds in the smart contract on the parent. Note that the global --network flag (defaults to testnet) will set all of the --evm-... presets for you, but you can override them with your own values, if needed.

Positionals	Description
`<AMOUNT>`	The amount to transfer.

Similarly, you can pass the --to flag to withdraw subnet funds to a specific address on the parent, but if you don't, the funds will be withdrawn to the address corresponding to the provided private key.

Flag	Required?	Description
`-p, --private-key`	Yes	Wallet private key (ECDSA, secp256k1) for signing transactions.
`--to <TO>`	No	The recipient account address (if not present, defaults to the signer's address).
`--evm-rpc-url`	No	The Ethereum API RPC HTTP endpoint.
`--evm-rpc-timeout`	No	Timeout for calls to the Ethereum API (default: `60 seconds`).
`--evm-rpc-auth-token`	No	Bearer token for any Authorization header.
`--evm-gateway`	No	The gateway contract address.
`--evm-registry`	No	The registry contract address.

Examples:

Withdraw funds to the signer's address:

recall account withdraw 10

{
  "transactionHash": "0xb098e39c4b358e5f55cd6f2db941092ff50b46d99db53c34101cac3f0f65f20d",
  "transactionIndex": "0x0",
  "blockHash": "0x3ebcd0c3b94a5076fffbeef95fd23cdd764a222679450e451dac6ce28b601eb2",
  "blockNumber": "0x19532",
  "from": "0x90f79bf6eb2c4f870365e785982e1f101e93b906",
  "to": "0x77aa40b105843728088c0132e43fc44348881da8",
  "cumulativeGasUsed": "0x5e63fa3",
  "gasUsed": "0x5e63fa3",
  "contractAddress": null,
  "logs": [],
  "status": "0x1",
  "root": "0x341c4ad32b230e66cdc5bf75e522934defa276afb88d705ce52a34336655b3a1",
  "logsBloom": "0x00...",
  "type": "0x2",
  "effectiveGasPrice": "0x0"
}

Withdraw funds to another address:

recall account withdraw --to 0x90f79bf6eb2c4f870365e785982e1f101e93b906 10

Set or unset an account's default credit sponsor for gas fees. This assumes the sponsor has approved your account via a credit approval.

recall account sponsor <SUBCOMMAND>

Subcommand	Description
`set`	Set an account's default credit sponsor for gas fees.
`unset`	Unset an account's default credit sponsor for gas fees.

In each command, it takes the following positionals:

Positionals	Description
`<SPONSOR>`	Credit sponsor address.

Examples:

Both of these examples presume the account 0x15d34aaf54267db7d7c367839aaf71a00a2c6a65 has executed a credit approval for your account.

Set an account's default credit sponsor for gas fees.

recall account sponsor set 0x15d34aaf54267db7d7c367839aaf71a00a2c6a65

Unset an account's default credit sponsor for gas fees.

recall account sponsor unset 0x15d34aaf54267db7d7c367839aaf71a00a2c6a65

Transfer funds

Transfer funds to another account within a subnet.

recall account transfer --to <TO> <AMOUNT>

Positionals	Description
`<AMOUNT>`	The amount to transfer.

The --to flag is the destination address within the subnet that you want to send funds to. Note that the global --network flag (defaults to testnet) will set all of the --evm-... presets for you, but you can override them with your own values, if needed. This transaction happens fully within the subnet (and does not interact with the rootnet).

Flag	Required?	Description
`-p, --private-key`	Yes	Wallet private key (ECDSA, secp256k1) for signing transactions.
`--to <TO>`	Yes	The recipient account address.
`--evm-rpc-url`	No	The Ethereum API RPC HTTP endpoint.
`--evm-rpc-timeout`	No	Timeout for calls to the Ethereum API (default: `60 seconds`).
`--evm-rpc-auth-token`	No	Bearer token for any Authorization header.
`--evm-gateway`	No	The gateway contract address.
`--evm-registry`	No	The registry contract address.

Examples:

Transfer funds to another address:

recall account transfer \
--to 0x4D5286d81317E284Cd377cB98b478552Bbe641ae \
10

{
  "transactionHash": "0x814759e167906ffc65dd20c6ceb4cdd42e5f64f9af7ca5bcd2ac1ea365ce715d",
  "transactionIndex": "0x0",
  "blockHash": "0xf496f8f9bdfb909696513411f01abd72184446a9c846f6016a85c9601294d4d0",
  "blockNumber": "0x1a7d2",
  "from": "0x90f79bf6eb2c4f870365e785982e1f101e93b906",
  "to": "0x4d5286d81317e284cd377cb98b478552bbe641ae",
  "cumulativeGasUsed": "0x18f28a",
  "gasUsed": "0x18f28a",
  "contractAddress": null,
  "logs": [],
  "status": "0x1",
  "root": "0x05b06003f5986d96409d53af89e0d1ad44b8f8487254beb6bef20cda0d7e0874",
  "logsBloom": "0x00...",
  "type": "0x2",
  "effectiveGasPrice": "0x410"
}

When you transfer funds from an account that already exists on the subnet to an account that doesn't exist, the recipient will effectively be created. Thus, it's much faster (a couple of seconds) than a deposit or withdraw, which require a two-step process that eventually settles on the rootnet.

Account & credits

On this page