@atomichub/atomicassets 2.0.0 → 2.0.1
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.
- package/README.md +106 -46
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,13 @@
|
|
|
1
1
|
# @atomichub/atomicassets
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@atomichub/atomicassets)
|
|
4
|
+
[](https://github.com/atomicassets/atomicassets-sdk/blob/main/LICENSE)
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
Read and write [AtomicAssets](https://github.com/atomicassets/atomicassets-contract) NFTs from JavaScript or TypeScript.
|
|
7
|
+
|
|
8
|
+
AtomicAssets is the NFT standard used on WAX and other Antelope chains. Its on-chain data is not plain JSON: attributes are packed into a binary format against a per-collection schema, and ids exceed what a JavaScript number can hold safely. This SDK handles that for you, so fetching someone's NFTs is one call that returns typed objects with the attributes already decoded.
|
|
9
|
+
|
|
10
|
+
If you are building a wallet, a marketplace, a game inventory, or anything that shows or moves NFTs on these chains, this is the client library for it.
|
|
6
11
|
|
|
7
12
|
## Install
|
|
8
13
|
|
|
@@ -10,68 +15,110 @@ The market-side companion package is [@atomichub/atomicmarket](https://github.co
|
|
|
10
15
|
npm install @atomichub/atomicassets
|
|
11
16
|
```
|
|
12
17
|
|
|
13
|
-
|
|
18
|
+
On Node.js the package requires version 20 or newer. Browsers and bundlers are supported through the ESM and IIFE builds. The package has zero runtime dependencies and ships CJS, ESM, and a browser IIFE bundle (`build/atomicassets.global.js`, global `atomicassets`).
|
|
19
|
+
|
|
20
|
+
## Quickstart
|
|
21
|
+
|
|
22
|
+
Show the NFTs an account owns:
|
|
14
23
|
|
|
15
24
|
```ts
|
|
16
|
-
|
|
17
|
-
|
|
25
|
+
import { explorerApiForNetwork } from '@atomichub/atomicassets';
|
|
26
|
+
|
|
27
|
+
const api = explorerApiForNetwork('wax');
|
|
18
28
|
|
|
19
|
-
|
|
20
|
-
|
|
29
|
+
const assets = await api.getAssets({ owner: 'someaccount1' }, 1, 20);
|
|
30
|
+
|
|
31
|
+
for (const asset of assets) {
|
|
32
|
+
console.log(asset.name, asset.collection.collection_name, asset.data['img']);
|
|
33
|
+
}
|
|
21
34
|
```
|
|
22
35
|
|
|
23
|
-
|
|
36
|
+
There is nothing to configure first. `explorerApiForNetwork` points at AtomicHub's public endpoint for the network you name, and `asset.data` already holds the merged, decoded attributes.
|
|
24
37
|
|
|
25
|
-
|
|
38
|
+
Examples below continue from this one and reuse `api`. They use top-level `await`, which needs an ES module; under CommonJS, wrap them in an `async` function.
|
|
26
39
|
|
|
27
|
-
|
|
40
|
+
Responses are typed, so `asset.name` and `asset.collection` autocomplete and are checked at build time. `asset.data` is the exception: its keys come from whatever schema the collection defined, so it stays an open map you index by name.
|
|
28
41
|
|
|
29
|
-
|
|
30
|
-
import { ExplorerApi } from '@atomichub/atomicassets';
|
|
42
|
+
## Picking a client
|
|
31
43
|
|
|
32
|
-
|
|
44
|
+
Two ways to read the same data:
|
|
45
|
+
|
|
46
|
+
| Client | Use it when | Backed by |
|
|
47
|
+
| --- | --- | --- |
|
|
48
|
+
| `ExplorerApi` | You want to filter, sort, paginate, or search. This is the usual choice. | A hosted [atomicassets-api](https://github.com/atomicassets/atomicassets-api) indexer |
|
|
49
|
+
| `RpcApi` | You want to read contract tables directly, with no indexer in the path. | A plain nodeos node |
|
|
50
|
+
|
|
51
|
+
`ExplorerApi` can answer questions the chain itself cannot, such as "the 20 most recently minted assets in this collection", because an indexer has already organized the data. `RpcApi` trades that away for reading straight from a node.
|
|
52
|
+
|
|
53
|
+
## Reading NFT data
|
|
33
54
|
|
|
55
|
+
```ts
|
|
56
|
+
import { AssetsSort, OrderParam } from '@atomichub/atomicassets';
|
|
57
|
+
|
|
58
|
+
// One asset by id
|
|
34
59
|
const asset = await api.getAsset('1099511627786');
|
|
35
60
|
|
|
36
|
-
|
|
61
|
+
// A collection's assets, newest mint first
|
|
62
|
+
const newest = await api.getAssets(
|
|
63
|
+
{ collection_name: 'mycollection', sort: AssetsSort.Minted, order: OrderParam.Desc },
|
|
64
|
+
1,
|
|
65
|
+
50
|
|
66
|
+
);
|
|
67
|
+
|
|
68
|
+
// Templates, collections, and an account summary
|
|
69
|
+
const templates = await api.getTemplates({ collection_name: 'mycollection' });
|
|
70
|
+
const collection = await api.getCollection('mycollection');
|
|
71
|
+
const account = await api.getAccount('someaccount1');
|
|
37
72
|
```
|
|
38
73
|
|
|
39
|
-
`
|
|
74
|
+
`countAssets`, `countTemplates`, and the other `count*` methods return totals for the same filters, which is what you want for pagination. Transfers, offers, burns, and per-asset logs have their own methods on the same client.
|
|
75
|
+
|
|
76
|
+
### Supported networks
|
|
40
77
|
|
|
41
|
-
|
|
78
|
+
`wax`, `wax-testnet`, `vaulta`, `xpr`, `xpr-testnet`, `jungle4`.
|
|
42
79
|
|
|
43
|
-
|
|
80
|
+
Self-hosted or custom deployments use the constructors instead:
|
|
44
81
|
|
|
45
82
|
```ts
|
|
46
|
-
import {
|
|
83
|
+
import { ExplorerApi, RpcApi } from '@atomichub/atomicassets';
|
|
47
84
|
|
|
48
|
-
const api =
|
|
49
|
-
const rpc =
|
|
85
|
+
const api = new ExplorerApi('https://wax.api.atomicassets.io', 'atomicassets', {});
|
|
86
|
+
const rpc = new RpcApi('https://wax.greymass.com', 'atomicassets', {});
|
|
50
87
|
```
|
|
51
88
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
### Serialize and deserialize attribute data
|
|
89
|
+
## Sending transactions
|
|
55
90
|
|
|
56
|
-
|
|
91
|
+
Reading needs no signing. When you want to mint, transfer, or burn, this SDK builds the action objects and hands them to whatever signing library you already use. It does not sign or broadcast anything itself.
|
|
57
92
|
|
|
58
93
|
```ts
|
|
59
|
-
import {
|
|
94
|
+
import { ActionBuilder } from '@atomichub/atomicassets';
|
|
60
95
|
|
|
61
|
-
const
|
|
62
|
-
{ name: 'name', type: 'string' },
|
|
63
|
-
{ name: 'level', type: 'uint16' },
|
|
64
|
-
{ name: 'tags', type: 'string[]' }
|
|
65
|
-
]);
|
|
96
|
+
const builder = new ActionBuilder('atomicassets');
|
|
66
97
|
|
|
67
|
-
const
|
|
68
|
-
|
|
69
|
-
//
|
|
98
|
+
const send = builder.transfer(
|
|
99
|
+
'someaccount1', // from
|
|
100
|
+
'otheraccount', // to
|
|
101
|
+
['1099511627786'], // asset_ids
|
|
102
|
+
'gg' // memo
|
|
103
|
+
);
|
|
70
104
|
```
|
|
71
105
|
|
|
72
|
-
|
|
106
|
+
That plugs straight into a signing library such as [WharfKit](https://wharfkit.com/):
|
|
73
107
|
|
|
74
|
-
|
|
108
|
+
```ts
|
|
109
|
+
await session.transact({
|
|
110
|
+
actions: [{
|
|
111
|
+
...send,
|
|
112
|
+
authorization: [{ actor: 'someaccount1', permission: 'active' }]
|
|
113
|
+
}]
|
|
114
|
+
});
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
`ActionBuilder` is synchronous and returns authorization-free `{account, name, data}` objects, one method per contract action. If you would rather have authorization attached for you, `ActionGenerator` wraps the same builders and returns fully-authorized `EosioActionObject` arrays.
|
|
118
|
+
|
|
119
|
+
### Minting
|
|
120
|
+
|
|
121
|
+
Minting takes more arguments because the contract does, and attribute data has to be typed on the way in:
|
|
75
122
|
|
|
76
123
|
```ts
|
|
77
124
|
import { ActionBuilder, createAttributeMap } from '@atomichub/atomicassets';
|
|
@@ -95,22 +142,33 @@ const mint = builder.mintasset(
|
|
|
95
142
|
);
|
|
96
143
|
```
|
|
97
144
|
|
|
98
|
-
|
|
145
|
+
`createAttributeMap` is what keeps you from hand-building the contract's attribute pairs and getting the types wrong.
|
|
146
|
+
|
|
147
|
+
## Working with attribute data directly
|
|
148
|
+
|
|
149
|
+
Most code never needs this. The API clients decode attributes for you, and `asset.data` is the result. The codec is exported for the cases where you are handling raw contract data yourself:
|
|
99
150
|
|
|
100
151
|
```ts
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
}
|
|
106
|
-
}
|
|
152
|
+
import { ObjectSchema, serialize, deserialize } from '@atomichub/atomicassets';
|
|
153
|
+
|
|
154
|
+
const schema = ObjectSchema([
|
|
155
|
+
{ name: 'name', type: 'string' },
|
|
156
|
+
{ name: 'level', type: 'uint16' },
|
|
157
|
+
{ name: 'tags', type: 'string[]' }
|
|
158
|
+
]);
|
|
159
|
+
|
|
160
|
+
const encoded = serialize({ name: 'Dragon', level: 12, tags: ['fire'] }, schema);
|
|
161
|
+
const decoded = deserialize(encoded, schema);
|
|
162
|
+
// decoded deep-equals the input object
|
|
107
163
|
```
|
|
108
164
|
|
|
109
165
|
## What's new in 2.0.0
|
|
110
166
|
|
|
111
167
|
- Zero runtime dependencies: native `BigInt` replaces bn.js and the built-in `fetch` replaces node-fetch (a custom `fetch` can still be injected).
|
|
112
168
|
- Dual CJS/ESM output with bundled type declarations, plus a browser IIFE build.
|
|
113
|
-
- v2 contract surface: schema-field media types (`setschematyp`)
|
|
169
|
+
- v2 contract surface: schema-field media types (`setschematyp`) and mutable template data (`createtempl2`, `settempldata`).
|
|
170
|
+
- `ActionBuilder`, a synchronous builder, alongside the authorized `ActionGenerator`.
|
|
171
|
+
- Typed table rows, action data payloads, and action names exported from the package root.
|
|
114
172
|
- Serialization codec with strict bounds checking and explicit error classes.
|
|
115
173
|
- Explorer query-parameter, enum, and response-object types are exported from the root; no deep `build/` imports needed.
|
|
116
174
|
|
|
@@ -120,10 +178,12 @@ await session.transact({
|
|
|
120
178
|
- Deep imports such as `atomicassets/build/API/Explorer/Params` are replaced by root exports: `import { AssetsApiParams } from '@atomichub/atomicassets'`.
|
|
121
179
|
- `max_supply` and `template_id` are numbers where the contract ABI defines them as numeric; 64-bit id fields (asset ids, offer ids) remain strings.
|
|
122
180
|
- `AttributeMap` entries are strictly typed as `{ key, value: [type, value] }`; use `createAttributeMap` or `toAttributeMap` instead of hand-building entries. Decoding accepts both `{key, value}` and v2 `{first, second}` pairs.
|
|
123
|
-
- Node.js
|
|
181
|
+
- Node.js 20 or newer is required.
|
|
124
182
|
|
|
125
183
|
## Credits and license
|
|
126
184
|
|
|
127
|
-
Fork of [atomicassets-js](https://github.com/pinknetworkx/atomicassets-js) by pink.network. Maintained by AtomicHub.
|
|
185
|
+
Fork of [atomicassets-js](https://github.com/pinknetworkx/atomicassets-js) by pink.network, updated for the v2 AtomicAssets contract. Maintained by AtomicHub.
|
|
186
|
+
|
|
187
|
+
The market-side companion package is [@atomichub/atomicmarket](https://github.com/atomicassets/atomicmarket-sdk).
|
|
128
188
|
|
|
129
|
-
MIT licensed; see [LICENSE](LICENSE) for the full text including the original pink.network copyright.
|
|
189
|
+
MIT licensed; see [LICENSE](https://github.com/atomicassets/atomicassets-sdk/blob/main/LICENSE) for the full text including the original pink.network copyright.
|