@solana/instructions 2.0.0-experimental.8d5318e → 2.0.0-experimental.ca5fcbd

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +108 -18
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -18,18 +18,29 @@ This package contains types for creating transaction instructions. It can be use
18
18
 
19
19
  ## Types
20
20
 
21
+ ### `AccountRole`
22
+
23
+ The purpose for which an account participates in a transaction is described by the `AccountRole` type. Every account that participates in a transaction can be read from, but only ones that you mark as writable may be written to, and only ones that you indicate must sign the transaction will gain the privileges associated with signers at runtime.
24
+
25
+ | | `isSigner` | `isWritable` |
26
+ | ----------------------------- | ---------- | ------------ |
27
+ | `AccountRole.READONLY` | ❌ | ❌ |
28
+ | `AccountRole.WRITABLE` | ❌ | ✅ |
29
+ | `AccountRole.READONLY_SIGNER` | ✅ | ❌ |
30
+ | `AccountRole.WRITABLE_SIGNER` | ✅ | ✅ |
31
+
21
32
  ### `IAccountMeta<TAddress>`
22
33
 
23
34
  This type represents an account's address and metadata about its mutability and whether it must be a signer of the transaction.
24
35
 
25
36
  Typically, you will use one of its subtypes.
26
37
 
27
- | | `isSigner` | `isWritable` |
28
- | --------------------------------- | ---------- | ------------ |
29
- | `ReadonlyAccount<TAddress>` | &#x274c; | &#x274c; |
30
- | `WritableAccount<TAddress>` | &#x274c; | &#x2705; |
31
- | `ReadonlySignerAccount<TAddress>` | &#x2705; | &#x274c; |
32
- | `WritableSignerAccount<TAddress>` | &#x2705; | &#x2705; |
38
+ | | `role` | `isSigner` | `isWritable` |
39
+ | --------------------------------- | ----------------------------- | ---------- | ------------ |
40
+ | `ReadonlyAccount<TAddress>` | `AccountRole.READONLY` | &#x274c; | &#x274c; |
41
+ | `WritableAccount<TAddress>` | `AccountRole.WRITABLE` | &#x274c; | &#x2705; |
42
+ | `ReadonlySignerAccount<TAddress>` | `AccountRole.READONLY_SIGNER` | &#x2705; | &#x274c; |
43
+ | `WritableSignerAccount<TAddress>` | `AccountRole.WRITABLE_SIGNER` | &#x2705; | &#x2705; |
33
44
 
34
45
  For example, you could type the rent sysvar account like this:
35
46
 
@@ -37,22 +48,101 @@ For example, you could type the rent sysvar account like this:
37
48
  type RentSysvar = ReadonlyAccount<'SysvarRent111111111111111111111111111111111'>;
38
49
  ```
39
50
 
40
- ### `Instruction<TProgramAddress, TAccounts, TData>`
51
+ ### `IAccountLookupMeta<TAddress, TLookupTableAddress>`
52
+
53
+ This type represents a lookup of the account's address in an address lookup table. It specifies which lookup table account in which to perform the lookup, the index of the desired account address in that table, and metadata about its mutability. Notably, account addresses obtained via lookups may not act as signers.
54
+
55
+ Typically, you will use one of its subtypes.
41
56
 
42
- Use this to define the structure of a transaction instruction.
57
+ | | `role` | `isSigner` | `isWritable` |
58
+ | ------------------------------------------------------ | ---------------------- | ---------- | ------------ |
59
+ | `ReadonlyLookupAccount<TAddress, TLookupTableAddress>` | `AccountRole.READONLY` | &#x274c; | &#x274c; |
60
+ | `WritableLookupAccount<TAddress, TLookupTableAddress>` | `AccountRole.WRITABLE` | &#x274c; | &#x2705; |
61
+
62
+ For example, you could type the rent sysvar account that you looked up in a lookup table like this:
43
63
 
44
64
  ```ts
45
- type InitializeStakeInstruction = Instruction<
46
- // Program address
47
- 'StakeConfig11111111111111111111111111111111',
48
- // Accounts
65
+ type RentSysvar = ReadonlyLookupAccount<
66
+ 'SysvarRent111111111111111111111111111111111',
67
+ 'MyLookupTable111111111111111111111111111111'
68
+ >;
69
+ ```
70
+
71
+ ### `IInstruction<TProgramAddress>`
72
+
73
+ Use this to specify an instruction destined for a given program.
74
+
75
+ ```ts
76
+ type StakeProgramInstruction = IInstruction<'StakeConfig11111111111111111111111111111111'>;
77
+ ```
78
+
79
+ ### `IInstructionWithAccounts<TAccounts>`
80
+
81
+ Use this type to specify an instruction that contains certain accounts.
82
+
83
+ ```ts
84
+ type InstructionWithTwoAccounts = IInstructionWithAccounts<
49
85
  [
50
- WritableAccount, // Stake account
51
- RentSysvar
52
- ],
53
- // Data
54
- InitializeStakeInstructionData
86
+ WritableAccount, // First account
87
+ RentSysvar // Second account
88
+ ]
55
89
  >;
56
90
  ```
57
91
 
58
- Instructions that do not require data may omit the `TData` type parameter.
92
+ ### `IInstructionWithData<TData>`
93
+
94
+ Use this type to specify an instruction whose data conforms to a certain type. This is most useful when you have a branded `Uint8Array` that represents a particular instruction.
95
+
96
+ For example, here is how the `AdvanceNonce` instruction is typed.
97
+
98
+ ```ts
99
+ type AdvanceNonceAccountInstruction<
100
+ TNonceAccountAddress extends string = string,
101
+ TNonceAuthorityAddress extends string = string
102
+ > = IInstruction<'11111111111111111111111111111111'> &
103
+ IInstructionWithAccounts<
104
+ [
105
+ WritableAccount<TNonceAccountAddress>,
106
+ ReadonlyAccount<'SysvarRecentB1ockHashes11111111111111111111'>,
107
+ ReadonlySignerAccount<TNonceAuthorityAddress>
108
+ ]
109
+ > &
110
+ IInstructionWithData<AdvanceNonceAccountInstructionData>;
111
+ ```
112
+
113
+ ## Functions
114
+
115
+ ### `isSignerRole(role: AccountRole)`
116
+
117
+ Returns `true` if the `AccountRole` given represents that of a signer. Also refines the TypeScript type of the supplied role.
118
+
119
+ ### `isWritable(role: AccountRole)`
120
+
121
+ Returns `true` if the `AccountRole` given represents that of a writable account. Also refines the TypeScript type of the supplied role.
122
+
123
+ ### `mergeRoles(roleA: AccountRole, roleB: AccountRole)`
124
+
125
+ Given two `AccountRoles`, will return the `AccountRole` that grants the highest privileges of both.
126
+
127
+ Example:
128
+
129
+ ```ts
130
+ // Returns `AccountRole.WRITABLE_SIGNER`
131
+ mergeRoles(AccountRole.READONLY_SIGNER, AccountRole.WRITABLE);
132
+ ```
133
+
134
+ ### `downgradeRoleToNonSigner(role: AccountRole)`
135
+
136
+ Returns an `AccountRole` representing the non-signer variant of the supplied role.
137
+
138
+ ### `downgradeRoleToReadonly(role: AccountRole)`
139
+
140
+ Returns an `AccountRole` representing the non-writable variant of the supplied role.
141
+
142
+ ### `upgradeRoleToSigner(role: AccountRole)`
143
+
144
+ Returns an `AccountRole` representing the signer variant of the supplied role.
145
+
146
+ ### `upgradeRoleToWritable(role: AccountRole)`
147
+
148
+ Returns an `AccountRole` representing the writable variant of the supplied role.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@solana/instructions",
3
- "version": "2.0.0-experimental.8d5318e",
3
+ "version": "2.0.0-experimental.ca5fcbd",
4
4
  "description": "Helpers for creating transaction instructions",
5
5
  "exports": {
6
6
  "browser": {
@@ -49,13 +49,13 @@
49
49
  "@solana/eslint-config-solana": "^1.0.0",
50
50
  "@swc/core": "^1.3.18",
51
51
  "@swc/jest": "^0.2.23",
52
- "@types/jest": "^29.5.0",
52
+ "@types/jest": "^29.5.2",
53
53
  "@typescript-eslint/eslint-plugin": "^5.57.1",
54
54
  "@typescript-eslint/parser": "^5.57.1",
55
55
  "agadoo": "^3.0.0",
56
56
  "eslint": "^8.37.0",
57
57
  "eslint-plugin-sort-keys-fix": "^1.1.2",
58
- "jest": "^29.5.0",
58
+ "jest": "^29.6.1",
59
59
  "jest-runner-eslint": "^2.0.0",
60
60
  "jest-runner-prettier": "^1.0.0",
61
61
  "postcss": "^8.4.12",
@@ -64,7 +64,7 @@
64
64
  "tsup": "6.7.0",
65
65
  "typescript": "^5.0.3",
66
66
  "version-from-git": "^1.1.1",
67
- "@solana/keys": "2.0.0-experimental.8d5318e",
67
+ "@solana/keys": "2.0.0-experimental.ca5fcbd",
68
68
  "build-scripts": "0.0.0",
69
69
  "test-config": "0.0.0",
70
70
  "tsconfig": "0.0.0"