spl-transfer-hook-interface 0.9.0

Solana Program Library Transfer Hook Interface
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

## Transfer-Hook Interface

### Example program

Here is an example program that only implements the required "execute" instruction,
assuming that the proper account data is already written to the appropriate 
program-derived address defined by the interface.

```rust
use {
    solana_program::{entrypoint::ProgramResult, program_error::ProgramError},
    spl_tlv_account_resolution::state::ExtraAccountMetaList,
    spl_transfer_hook_interface::instruction::{ExecuteInstruction, TransferHookInstruction},
    spl_type_length_value::state::TlvStateBorrowed,
};
pub fn process_instruction(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    input: &[u8],
) -> ProgramResult {
    let instruction = TransferHookInstruction::unpack(input)?;
    let _amount = match instruction {
        TransferHookInstruction::Execute { amount } => amount,
        _ => return Err(ProgramError::InvalidInstructionData),
    };
    let account_info_iter = &mut accounts.iter();

    // Pull out the accounts in order, none are validated in this test program
    let _source_account_info = next_account_info(account_info_iter)?;
    let mint_info = next_account_info(account_info_iter)?;
    let _destination_account_info = next_account_info(account_info_iter)?;
    let _authority_info = next_account_info(account_info_iter)?;
    let extra_account_metas_info = next_account_info(account_info_iter)?;

    // Only check that the correct pda and account are provided
    let expected_validation_address = get_extra_account_metas_address(mint_info.key, program_id);
    if expected_validation_address != *extra_account_metas_info.key {
        return Err(ProgramError::InvalidSeeds);
    }

    // Load the extra required accounts from the validation account
    let data = extra_account_metas_info.try_borrow_data()?;

    // Check the provided accounts against the validation data
    ExtraAccountMetaList::check_account_infos::<ExecuteInstruction>(
        accounts,
        &TransferHookInstruction::Execute { amount }.pack(),
        program_id,
        &data,
    )?;

    Ok(())
}
```

### Motivation

Token creators may need more control over how their token is transferred. The
most prominent use case revolves around NFT royalties. Whenever a token is moved,
the creator should be entitled to royalties, but due to the design of the current
token program, it's impossible to stop a transfer at the protocol level.

Current solutions typically resort to perpetually freezing tokens, which requires
a whole proxy layer to interact with the token. Wallets and marketplaces need
to be aware of the proxy layer in order to properly use the token.

Worse still, different royalty systems have different proxy layers for using
their token. All in all, these systems harm composability and make development
harder.

### Solution

To improve the situation, Token-2022 introduces the concept of the transfer-hook
interface and extension. A token creator must develop and deploy a program that
implements the interface and then configure their token mint to use their program.

During transfer, Token-2022 calls into the program with the accounts specified
at a well-defined program-derived address for that mint and program id. This
call happens after all other transfer logic, so the accounts reflect the *end*
state of the transfer.

### How to Use

Developers must implement the `Execute` instruction, and optionally the
`InitializeExtraAccountMetaList` instruction to write the required additional account
pubkeys into the program-derived address defined by the mint and program id.

Note: it's technically not required to implement `InitializeExtraAccountMetaList`
at that instruction descriminator. Your program may implement multiple interfaces,
so any other instruction in your program can create the account at the program-derived
address!

When your program stores configurations for extra required accounts in the
well-defined program-derived address, it's possible to send an instruction -
such as `Execute` (transfer) - to your program with only accounts required
for the interface instruction, and all extra required accounts are
automatically resolved!

### Account Resolution

Implementers of the transfer-hook interface are encouraged to make use of the
[spl-tlv-account-resolution](https://github.com/solana-labs/solana-program-library/tree/master/libraries/tlv-account-resolution/README.md)
library to manage the additional required accounts for their transfer hook
program.

TLV Account Resolution is capable of powering on-chain account resolution
when an instruction that requires extra accounts is invoked.
Read more about how account resolution works in the repository's
[README file](https://github.com/solana-labs/solana-program-library/tree/master/libraries/tlv-account-resolution/README.md).

### An Example

You have created a DAO to govern a community. Your DAO's authority is a
multisig account, and you want to ensure that any transfer of your token is
approved by the DAO. You also want to make sure that someone who intends to
transfer your token has the proper permissions to do so.

Let's assume the DAO multisig has some **fixed address**. And let's assume that
in order to have the `can_transfer` permission, a user must have this
**dynamic program-derived address** associated with their wallet via the
following seeds: `"can_transfer" + <wallet_address>`.

Using the transfer-hook interface, you can store these configurations in the
well-defined program-derived address for your mint and program id.

When a user attempts to transfer your token, they might provide to Token-2022:

```rust
[source, mint, destination, owner/delegate]
```

Token-2022 will then call into your program,
**resolving the extra required accounts automatically** from your stored
configurations, to result in the following accounts being provided to your
program:

```rust
[source, mint, destination, owner/delegate, dao_authority, can_transfer_pda]
```

### Utilities

The `spl-transfer-hook-interface` library provides offchain and onchain helpers
for resolving the additional accounts required. See
[onchain.rs](https://github.com/solana-labs/solana-program-library/tree/master/token/transfer-hook/interface/src/onchain.rs)
for usage on-chain, and
[offchain.rs](https://github.com/solana-labs/solana-program-library/tree/master/token/transfer-hook/interface/src/offchain.rs)
for fetching the additional required account metas with any async off-chain client
like `BanksClient` or `RpcClient`.