-
Notifications
You must be signed in to change notification settings - Fork 110
/
taro.proto
655 lines (501 loc) · 16.7 KB
/
taro.proto
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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
syntax = "proto3";
package tarorpc;
option go_package = "github.com/lightninglabs/tarorpc";
service Taro {
/* tarocli: `assets mint`
MintAsset will attempts to mint the set of assets (async by default to
ensure proper batching) specified in the request.
*/
rpc MintAsset (MintAssetRequest) returns (MintAssetResponse);
/* tarocli: `assets list`
ListAssets lists the set of assets owned by the target daemon.
*/
rpc ListAssets (ListAssetRequest) returns (ListAssetResponse);
/* tarocli: `assets utxos`
ListUtxos lists the UTXOs managed by the target daemon, and the assets they
hold.
*/
rpc ListUtxos (ListUtxosRequest) returns (ListUtxosResponse);
/* tarocli: `assets groups`
ListGroups lists the asset groups known to the target daemon, and the assets
held in each group.
*/
rpc ListGroups (ListGroupsRequest) returns (ListGroupsResponse);
/* tarocli: `assets balance`
ListBalances lists asset balances
*/
rpc ListBalances (ListBalancesRequest) returns (ListBalancesResponse);
/* tarocli: `assets transfers`
ListTransfers lists outbound asset transfers tracked by the target daemon.
*/
rpc ListTransfers (ListTransfersRequest) returns (ListTransfersResponse);
/* tarocli: `stop`
StopDaemon will send a shutdown request to the interrupt handler, triggering
a graceful shutdown of the daemon.
*/
rpc StopDaemon (StopRequest) returns (StopResponse);
/* tarocli: `debuglevel`
DebugLevel allows a caller to programmatically set the logging verbosity of
tarod. The logging can be targeted according to a coarse daemon-wide logging
level, or in a granular fashion to specify the logging for a target
sub-system.
*/
rpc DebugLevel (DebugLevelRequest) returns (DebugLevelResponse);
/* tarocli: `addrs query`
QueryTaroAddrs queries the set of Taro addresses stored in the database.
*/
rpc QueryAddrs (QueryAddrRequest) returns (QueryAddrResponse);
/* tarocli: `addrs new`
NewAddr makes a new address from the set of request params.
*/
rpc NewAddr (NewAddrRequest) returns (Addr);
/* tarocli: `addrs decode`
DecodeAddr decode a Taro address into a partial asset message that
represents the asset it wants to receive.
*/
rpc DecodeAddr (DecodeAddrRequest) returns (Addr);
/* tarocli: `addrs receives`
List all receives for incoming asset transfers for addresses that were
created previously.
*/
rpc AddrReceives (AddrReceivesRequest) returns (AddrReceivesResponse);
/* tarocli: `proofs verify`
VerifyProof attempts to verify a given proof file that claims to be anchored
at the specified genesis point.
*/
rpc VerifyProof (ProofFile) returns (ProofVerifyResponse);
/* tarocli: `proofs export`
ExportProof exports the latest raw proof file anchored at the specified
script_key.
*/
rpc ExportProof (ExportProofRequest) returns (ProofFile);
/* tarocli: `proofs import`
ImportProof attempts to import a proof file into the daemon. If successful,
a new asset will be inserted on disk, spendable using the specified target
script key, and internal key.
*/
rpc ImportProof (ImportProofRequest) returns (ImportProofResponse);
/* tarocli: `assets send`
SendAsset uses a passed taro address to attempt to complete an asset send.
The method returns information w.r.t the on chain send, as well as the
proof file information the receiver needs to fully receive the asset.
*/
rpc SendAsset (SendAssetRequest) returns (SendAssetResponse);
/*
SubscribeSendAssetEventNtfns registers a subscription to the event
notification stream which relates to the asset sending process.
*/
rpc SubscribeSendAssetEventNtfns (SubscribeSendAssetEventNtfnsRequest)
returns (stream SendAssetEvent);
}
enum AssetType {
/*
Indicates that an asset is capable of being split/merged, with each of the
units being fungible, even across a key asset ID boundary (assuming the
key group is the same).
*/
NORMAL = 0;
/*
Indicates that an asset is a collectible, meaning that each of the other
items under the same key group are not fully fungible with each other.
Collectibles also cannot be split or merged.
*/
COLLECTIBLE = 1;
}
message MintAssetRequest {
// The type of the asset to be created.
AssetType asset_type = 1;
// The name, or "tag" of the asset. This will affect the final asset ID.
string name = 2;
/*
An opaque blob that resents metadata related to the asset. This will affect
the final asset ID.
*/
bytes meta_data = 3;
/*
The total amount of units of the new asset that should be created. If the
AssetType is Collectible, then this field cannot be set.
*/
int64 amount = 4;
/*
If true, then the asset will be created with a key group, which allows for
future asset issuance.
*/
bool enable_emission = 5;
/*
If true, then a batch will be created immediately. Otherwise the asset
creation transaction may be batched with other pending minting requests.
*/
bool skip_batch = 6;
}
message MintAssetResponse {
/*
A public key serialized in compressed format that can be used to uniquely
identify a pending minting batch. Responses that share the same key will be
batched into the same minting transaction.
*/
bytes batch_key = 1;
}
message ListAssetRequest {
}
message AnchorInfo {
// The transaction that anchors the Taro commitment where the asset resides.
bytes anchor_tx = 1;
// The txid of the above transaction.
string anchor_txid = 2;
// The block hash the contains the anchor transaction above.
bytes anchor_block_hash = 3;
// The outpoint (txid:vout) that stores the Taro commitment.
string anchor_outpoint = 4;
/*
The raw internal key that was used to create the anchor Taproot output key.
*/
bytes internal_key = 5;
}
message GenesisInfo {
// The first outpoint of the transaction that created the asset (txid:vout).
string genesis_point = 1;
// The name of the asset.
string name = 2;
// The opaque meta data of the asset.
bytes meta = 3;
// The asset ID that uniquely identifies the asset.
bytes asset_id = 4;
/*
The index of the output that carries the unique Taro commitment in the
genesis transaction.
*/
uint32 output_index = 5;
/*
The full genesis information encoded in a portable manner so it can be
easily copy/pasted for address creation.
*/
bytes genesis_bootstrap_info = 6;
// The version of the Taro commitment that created this asset.
int32 version = 7;
}
message AssetGroup {
// The raw group key which is a normal public key.
bytes raw_group_key = 1;
/*
The tweaked group key, which is derived based on the genesis point and also
asset type.
*/
bytes tweaked_group_key = 2;
// A signature over the genesis point using the above key.
bytes asset_id_sig = 3;
}
message Asset {
// The version of the Taro asset.
int32 version = 1;
// The base genesis information of an asset. This information never changes.
GenesisInfo asset_genesis = 2;
// The type of the asset.
AssetType asset_type = 3;
// The total amount of the asset stored in this Taro UTXO.
int64 amount = 4;
// An optional locktime, as with Bitcoin transactions.
int32 lock_time = 5;
// An optional relative lock time, same as Bitcoin transactions.
int32 relative_lock_time = 6;
// The version of the script, only version 0 is defined at present.
int32 script_version = 7;
// The script key of the asset, which can be spent under Taproot semantics.
bytes script_key = 9;
// The information related to the key group of an asset (if it exists).
AssetGroup asset_group = 10;
// Describes where in the chain the asset is currently anchored.
AnchorInfo chain_anchor = 11;
}
message ListAssetResponse {
repeated Asset assets = 1;
}
message ListUtxosRequest {
}
message ManagedUtxo {
// The outpoint of the UTXO.
string out_point = 1;
// The UTXO amount in satoshis.
int64 amt_sat = 2;
// The internal key used for the on-chain output.
bytes internal_key = 3;
// The Taro root that commits to the set of assets at this UTXO.
bytes taro_root = 4;
// The assets held at this UTXO.
repeated Asset assets = 5;
}
message ListUtxosResponse {
// The set of UTXOs managed by the daemon.
map<string, ManagedUtxo> managed_utxos = 1;
}
message ListGroupsRequest {
}
message AssetHumanReadable {
// The ID of the asset.
bytes id = 1;
// The amount of the asset.
uint64 amount = 2;
// An optional locktime, as with Bitcoin transactions.
int32 lock_time = 3;
// An optional relative locktime, as with Bitcoin transactions.
int32 relative_lock_time = 4;
// The name of the asset.
string tag = 5;
// The opaque metadata of the asset.
bytes meta_data = 6;
// The type of the asset.
AssetType type = 7;
}
message GroupedAssets {
// A list of assets with the same group key.
repeated AssetHumanReadable assets = 1;
}
message ListGroupsResponse {
// The set of assets with a group key.
map<string, GroupedAssets> groups = 1;
}
message ListBalancesRequest {
oneof group_by {
// Group results by asset IDs.
bool asset_id = 1;
// Group results by group keys.
bool group_key = 2;
}
// If the query results should grouped by asset ids, then an optional asset
// filter may be provided to query balance of a specific asset.
bytes asset_filter = 3;
// If the query results should be grouped by group keys, then an optional
// group key filter may be provided to query the balance of a specific
// asset group.
bytes group_key_filter = 4;
}
message AssetBalance {
// The base genesis information of an asset. This information never changes.
GenesisInfo asset_genesis = 1;
// The type of the asset.
AssetType asset_type = 2;
// The balance of the asset owned by the target daemon.
int64 balance = 3;
}
message AssetGroupBalance {
// The group key or nil aggregating assets that don't have a group.
bytes group_key = 1;
// The total balance of the assets in the group.
int64 balance = 2;
}
message ListBalancesResponse {
map<string, AssetBalance> asset_balances = 1;
map<string, AssetGroupBalance> asset_group_balances = 2;
}
message ListTransfersRequest {
}
message ListTransfersResponse {
// The unordered list of outgoing asset transfers.
repeated AssetTransfer transfers = 1;
}
message AssetTransfer {
int64 transfer_timestamp = 1;
// The old/current location of the Taro commitment that was spent as an
// input.
string old_anchor_point = 2;
// The new location of the Taro commitment referenced by the old anchor
// point.
string new_anchor_point = 3;
// The new Taro root that commits to the set of modified and unmodified
// assets.
bytes taro_root = 4;
// The new transaction that commits to the set of Taro assets found at the
// above new anchor point.
bytes anchor_tx_hash = 5;
// Describes the set of mutated assets that now live at the new anchor tx
// point.
repeated AssetSpendDelta asset_spend_deltas = 6;
}
message AssetSpendDelta {
// The asset ID that uniquely identifies the asset.
bytes asset_id = 1;
// The old script key that uniquely identified the spent asset on disk.
bytes old_script_key = 2;
// The new script key. We assume BIP 86 usage when updating the script keys
// on disk.
bytes new_script_key = 3;
// The new amount for the asset.
int64 new_amt = 4;
}
message StopRequest {
}
message StopResponse {
}
message DebugLevelRequest {
// If true, all the valid debug sub-systems will be returned.
bool show = 1;
string level_spec = 2;
}
message DebugLevelResponse {
string sub_systems = 1;
}
message Addr {
// The bech32 encoded Taro address.
string encoded = 1;
// The asset ID that uniquely identifies the asset.
bytes asset_id = 2;
// The type of the asset.
AssetType asset_type = 3;
// The total amount of the asset stored in this Taro UTXO.
int64 amount = 4;
// The group key of the asset (if it exists)
bytes group_key = 5;
/*
The specific script key the asset must commit to in order to transfer
ownership to the creator of the address.
*/
bytes script_key = 6;
// The internal key used for the on-chain output.
bytes internal_key = 7;
/*
The tweaked internal key that commits to the asset and represents the
on-chain output key the Bitcoin transaction must send to in order to
transfer assets described in this address.
*/
bytes taproot_output_key = 8;
}
message QueryAddrRequest {
/*
If set, then only addresses created after this Unix timestamp will be
returned.
*/
int64 created_after = 1;
/*
If set, then only addresses created before this Unix timestamp will be
returned.
*/
int64 created_before = 2;
// The max number of addresses that should be returned.
int32 limit = 3;
// The offset from the addresses that should be returned.
int32 offset = 4;
}
message QueryAddrResponse {
repeated Addr addrs = 1;
}
message NewAddrRequest {
bytes genesis_bootstrap_info = 1;
bytes group_key = 2;
int64 amt = 3;
}
message DecodeAddrRequest {
string addr = 1;
}
message ProofFile {
bytes raw_proof = 1;
string genesis_point = 2;
}
message ProofVerifyResponse {
bool valid = 1;
}
message ExportProofRequest {
bytes asset_id = 1;
bytes script_key = 2;
// TODO(roasbeef): specify information to make new state transition in proof
// file?
}
message ImportProofRequest {
bytes proof_file = 1;
string genesis_point = 2;
}
message ImportProofResponse {
}
enum AddrEventStatus {
ADDR_EVENT_STATUS_UNKNOWN = 0;
ADDR_EVENT_STATUS_TRANSACTION_DETECTED = 1;
ADDR_EVENT_STATUS_TRANSACTION_CONFIRMED = 2;
ADDR_EVENT_STATUS_PROOF_RECEIVED = 3;
ADDR_EVENT_STATUS_COMPLETED = 4;
}
message AddrEvent {
// The time the event was created in unix timestamp seconds.
uint64 creation_time_unix_seconds = 1;
// The address the event was created for.
Addr addr = 2;
// The current status of the event.
AddrEventStatus status = 3;
// The outpoint that contains the inbound asset transfer.
string outpoint = 4;
/*
The amount in satoshis that were transferred on chain along with the asset.
This amount is independent of the requested asset amount, which can be
looked up on the address.
*/
uint64 utxo_amt_sat = 5;
/*
The taproot sibling hash that was used to send to the Taproot output.
NOTE: Not yet implemented.
*/
bytes taproot_sibling = 6;
/*
The height at which the on-chain output was confirmed. If this is zero, it
means the output is unconfirmed.
*/
uint32 confirmation_height = 7;
/*
Indicates whether a proof file can be found for the address' asset ID and
script key.
*/
bool has_proof = 8;
}
message AddrReceivesRequest {
// Filter receives by a specific address. Leave empty to get all receives.
string filter_addr = 1;
// Filter receives by a specific status. Leave empty to get all receives.
AddrEventStatus filter_status = 2;
}
message AddrReceivesResponse {
// The events that match the filter criteria.
repeated AddrEvent events = 1;
}
message SendAssetRequest {
string taro_addr = 1;
// TODO(roasbeef): maybe in future add details re type of ProofCourier or
// w/e
}
message PrevInputAsset {
string anchor_point = 1;
bytes asset_id = 2;
bytes script_key = 3;
int64 amount = 4;
}
message AssetOutput {
string anchor_point = 1;
bytes asset_id = 2;
bytes script_key = 3;
int64 amount = 4;
bytes new_proof_blob = 5;
bytes split_commit_proof = 6;
}
message TaroTransfer {
bytes old_taro_root = 1;
bytes new_taro_root = 2;
repeated PrevInputAsset prev_inputs = 3;
repeated AssetOutput new_outputs = 4;
}
message SendAssetResponse {
string transfer_txid = 1;
int32 anchor_output_index = 2;
bytes transfer_tx_bytes = 3;
TaroTransfer taro_transfer = 4;
int64 total_fee_sats = 5;
}
message SubscribeSendAssetEventNtfnsRequest {
}
message SendAssetEvent {
oneof event {
// An event which indicates that a send state is about to be executed.
ExecuteSendStateEvent execute_send_state_event = 1;
}
}
message ExecuteSendStateEvent {
// Execute timestamp.
int64 timestamp = 1;
// The send state that is about to be executed.
string send_state = 2;
}