@cancore/contracts 0.2.0-rc.10 → 0.2.0-rc.14
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 +80 -1
- package/dist/index.d.ts +230 -6
- package/dist/index.js +794 -25
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
- package/spec/protocol/asyncapi.json +335 -13
- package/spec/protocol/messages.schema.json +364 -1
- package/spec/protocol/rest.schema.json +62 -3
- package/spec/protocol/vectors/messages.json +206 -13
- package/spec/protocol/vectors/settle-attestations.json +71 -69
|
@@ -72,7 +72,7 @@
|
|
|
72
72
|
},
|
|
73
73
|
"errorCode": {
|
|
74
74
|
"anyOf": [
|
|
75
|
-
{ "enum": ["BAD_REQUEST", "UNAUTHENTICATED", "UNSUPPORTED_VERSION", "UNSUPPORTED_TYPE", "BAD_SIGNATURE", "STALE_MESSAGE", "REPLAYED_MESSAGE", "TICKET_REFUSED", "UNKNOWN_REQUEST", "UNKNOWN_TICKET", "TICKET_CLOSED", "NOT_ELIGIBLE", "RATE_LIMITED", "INTERNAL", "ATTESTATIONS_NOT_READY"] },
|
|
75
|
+
{ "enum": ["BAD_REQUEST", "UNAUTHENTICATED", "UNSUPPORTED_VERSION", "UNSUPPORTED_TYPE", "BAD_SIGNATURE", "STALE_MESSAGE", "REPLAYED_MESSAGE", "TICKET_REFUSED", "UNKNOWN_REQUEST", "UNKNOWN_TICKET", "TICKET_CLOSED", "NOT_ELIGIBLE", "RATE_LIMITED", "INTERNAL", "ATTESTATIONS_NOT_READY", "CANTON_NOT_READY", "CANTON_REFUSED", "CANTON_UNAVAILABLE", "OPERATION_EXPIRED"] },
|
|
76
76
|
{ "$ref": "#/$defs/futureEnumValue" }
|
|
77
77
|
]
|
|
78
78
|
},
|
|
@@ -538,6 +538,369 @@
|
|
|
538
538
|
"threshold": { "type": "integer", "minimum": 1, "maximum": 4294967295, "description": "k of that set" },
|
|
539
539
|
"refundAfter": { "$ref": "#/$defs/timeS", "description": "from this time settle reverts; the node gets its settle included before it" }
|
|
540
540
|
}
|
|
541
|
+
},
|
|
542
|
+
"cantonOp": {
|
|
543
|
+
"description": "A Canton operation of the filler's own external party on the Cancore participant (protocol §3.19): the backend prepares and submits it, the node signs it with its party key and never talks to a Ledger API. party.allocate creates the party (topology); registry.accept accepts the FillerRegistryEntryProposal of the fillerId; delivery.fill exercises DeliveryOrder_Fill of a Canton ticket issued to the filler; intent.settle exercises SwapIntent_SettleWithProof of a Canton-source order the filler delivered; holdings.transfer moves the party's own holdings to a party it names (TransferFactory_Transfer)",
|
|
544
|
+
"anyOf": [
|
|
545
|
+
{ "enum": ["party.allocate", "registry.accept", "delivery.fill", "intent.settle", "holdings.transfer"] },
|
|
546
|
+
{ "type": "string", "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$" }
|
|
547
|
+
]
|
|
548
|
+
},
|
|
549
|
+
"operationId": {
|
|
550
|
+
"type": "string",
|
|
551
|
+
"pattern": "^[!-~]{1,64}$",
|
|
552
|
+
"description": "the handle canton.prepared hands out for canton.submit: opaque, 1..64 printable ASCII, valid until expiresAt"
|
|
553
|
+
},
|
|
554
|
+
"edPublicKey": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "the raw 32-byte Ed25519 public key of the filler's Canton party, lowercase hex" },
|
|
555
|
+
"edSignature": { "type": "string", "pattern": "^0x[0-9a-f]{128}$", "description": "64-byte Ed25519 signature by the party key over the bytes of a leg's hash, lowercase hex" },
|
|
556
|
+
"cantonLegTransaction": {
|
|
557
|
+
"type": "object",
|
|
558
|
+
"description": "A prepared Canton transaction to sign. MUST before signing (protocol §3.19): the node recomputes `hash` from `preparedTransaction` with the participant's prepared-transaction hashing of `hashingSchemeVersion`, decodes the transaction and checks it against `summary` for the op of the message — template and choice, acting and receiving parties, instrument, amount; on any difference it does not sign. It signs the 32 hash bytes with its party key",
|
|
559
|
+
"required": ["legId", "kind", "hash", "preparedTransaction", "hashingSchemeVersion"],
|
|
560
|
+
"properties": {
|
|
561
|
+
"legId": { "type": "string", "minLength": 1, "maxLength": 128 },
|
|
562
|
+
"kind": { "const": "transaction" },
|
|
563
|
+
"hash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "the 32-byte prepared-transaction hash" },
|
|
564
|
+
"preparedTransaction": {
|
|
565
|
+
"type": "string",
|
|
566
|
+
"minLength": 1,
|
|
567
|
+
"pattern": "^[A-Za-z0-9+/]+={0,2}$",
|
|
568
|
+
"description": "the prepared transaction (base64 protobuf) the hash is over. Never logged"
|
|
569
|
+
},
|
|
570
|
+
"hashingSchemeVersion": {
|
|
571
|
+
"type": "string",
|
|
572
|
+
"pattern": "^HASHING_SCHEME_VERSION_V[0-9]+$",
|
|
573
|
+
"description": "the participant's prepared-transaction hashing scheme the hash was computed with"
|
|
574
|
+
}
|
|
575
|
+
}
|
|
576
|
+
},
|
|
577
|
+
"cantonLegTopology": {
|
|
578
|
+
"type": "object",
|
|
579
|
+
"description": "The onboarding topology of the filler's party, in `party.allocate` only (a topology leg in any other op is refused by the schema). MUST before signing (protocol §3.19): the node recomputes the multihash over `topologyTransactions` and checks that they create the party of `summary.partyId` with the key of `summary.publicKey` as its only signing key, hosted on the Cancore participant; on any difference it does not sign. It signs the 34 multihash bytes with its party key",
|
|
580
|
+
"required": ["legId", "kind", "hash", "topologyTransactions"],
|
|
581
|
+
"properties": {
|
|
582
|
+
"legId": { "type": "string", "minLength": 1, "maxLength": 128 },
|
|
583
|
+
"kind": { "const": "topology" },
|
|
584
|
+
"hash": { "type": "string", "pattern": "^0x1220[0-9a-f]{64}$", "description": "the topology multihash: 0x1220 ‖ sha256" },
|
|
585
|
+
"topologyTransactions": {
|
|
586
|
+
"type": "array",
|
|
587
|
+
"minItems": 1,
|
|
588
|
+
"items": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9+/]+={0,2}$" },
|
|
589
|
+
"description": "the topology transactions (base64 protobuf) the multihash is over, in order"
|
|
590
|
+
}
|
|
591
|
+
}
|
|
592
|
+
},
|
|
593
|
+
"cantonSignature": {
|
|
594
|
+
"type": "object",
|
|
595
|
+
"required": ["legId", "signature"],
|
|
596
|
+
"properties": { "legId": { "type": "string", "minLength": 1, "maxLength": 128 }, "signature": { "$ref": "#/$defs/edSignature" } }
|
|
597
|
+
},
|
|
598
|
+
"canton.prepare": {
|
|
599
|
+
"x-direction": "F2S",
|
|
600
|
+
"type": "object",
|
|
601
|
+
"description": "Prepare a Canton operation of the sender's own party (§3.19); answered by canton.prepared (re = this id) or error. params select the operation only: the backend picks every contract itself (holdings, delivery order, intent, registry entry, disclosed contracts, attestor signatures). Admission: party.allocate — the fillerId has no party yet, or this key's party; registry.accept — a proposal for the fillerId and its party is live; delivery.fill — an ISSUED Canton ticket of this filler for (orderHash, attempt), before validUntil; intent.settle — a Canton-source order this filler delivered, with attestations held; holdings.transfer — enough unlocked holdings of the asset beyond what the party's open delivery orders need, to a party other than its own. Each prepare prepares afresh and replaces the filler's open operation of the same op and target",
|
|
602
|
+
"allOf": [
|
|
603
|
+
{ "$ref": "#/$defs/f2sBase" },
|
|
604
|
+
{
|
|
605
|
+
"if": { "type": "object", "properties": { "op": { "const": "party.allocate" } }, "required": ["op"] },
|
|
606
|
+
"then": {
|
|
607
|
+
"type": "object",
|
|
608
|
+
"required": ["params"],
|
|
609
|
+
"properties": { "params": { "type": "object", "required": ["publicKey"], "properties": { "publicKey": { "$ref": "#/$defs/edPublicKey" } } } }
|
|
610
|
+
}
|
|
611
|
+
},
|
|
612
|
+
{
|
|
613
|
+
"if": { "type": "object", "properties": { "op": { "const": "registry.accept" } }, "required": ["op"] },
|
|
614
|
+
"then": { "type": "object", "required": ["params"], "properties": { "params": { "type": "object" } } }
|
|
615
|
+
},
|
|
616
|
+
{
|
|
617
|
+
"if": { "type": "object", "properties": { "op": { "const": "delivery.fill" } }, "required": ["op"] },
|
|
618
|
+
"then": {
|
|
619
|
+
"type": "object",
|
|
620
|
+
"required": ["params"],
|
|
621
|
+
"properties": {
|
|
622
|
+
"params": {
|
|
623
|
+
"type": "object",
|
|
624
|
+
"required": ["orderHash", "attempt"],
|
|
625
|
+
"properties": { "orderHash": { "$ref": "#/$defs/bytes32" }, "attempt": { "$ref": "#/$defs/uint32" } }
|
|
626
|
+
}
|
|
627
|
+
}
|
|
628
|
+
}
|
|
629
|
+
},
|
|
630
|
+
{
|
|
631
|
+
"if": { "type": "object", "properties": { "op": { "const": "intent.settle" } }, "required": ["op"] },
|
|
632
|
+
"then": {
|
|
633
|
+
"type": "object",
|
|
634
|
+
"required": ["params"],
|
|
635
|
+
"properties": { "params": { "type": "object", "required": ["orderHash"], "properties": { "orderHash": { "$ref": "#/$defs/bytes32" } } } }
|
|
636
|
+
}
|
|
637
|
+
},
|
|
638
|
+
{
|
|
639
|
+
"if": { "type": "object", "properties": { "op": { "const": "holdings.transfer" } }, "required": ["op"] },
|
|
640
|
+
"then": {
|
|
641
|
+
"type": "object",
|
|
642
|
+
"required": ["params"],
|
|
643
|
+
"properties": {
|
|
644
|
+
"params": {
|
|
645
|
+
"type": "object",
|
|
646
|
+
"required": ["asset", "amount", "toParty"],
|
|
647
|
+
"properties": {
|
|
648
|
+
"asset": { "$ref": "#/$defs/cantonAsset" },
|
|
649
|
+
"amount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,10})?$", "description": "Daml Decimal, > 0" },
|
|
650
|
+
"toParty": { "type": "string", "minLength": 1, "maxLength": 255, "description": "the receiving Canton party; never the filler's own" }
|
|
651
|
+
}
|
|
652
|
+
}
|
|
653
|
+
}
|
|
654
|
+
}
|
|
655
|
+
}
|
|
656
|
+
],
|
|
657
|
+
"required": ["type", "op", "params"],
|
|
658
|
+
"properties": { "type": { "const": "canton.prepare" }, "op": { "$ref": "#/$defs/cantonOp" }, "params": { "type": "object" } }
|
|
659
|
+
},
|
|
660
|
+
"canton.prepared": {
|
|
661
|
+
"x-direction": "S2F",
|
|
662
|
+
"type": "object",
|
|
663
|
+
"description": "A prepared operation. The node MUST verify every leg before it signs it (cantonLegTransaction, cantonLegTopology): what it signs is what Cancore assembled, and summary is only what Cancore says about it — a leg that does not match summary, or summary that does not match what the node expects of the op, is not signed. Topology legs come with party.allocate only; every other op prepares transactions. Then the node signs every leg's hash with its party key and sends canton.submit before expiresAt. An operationId stays valid until its own expiresAt whatever is prepared after it",
|
|
664
|
+
"allOf": [
|
|
665
|
+
{ "$ref": "#/$defs/s2fBase" },
|
|
666
|
+
{
|
|
667
|
+
"if": { "type": "object", "properties": { "op": { "const": "party.allocate" } }, "required": ["op"] },
|
|
668
|
+
"then": { "type": "object", "properties": { "legs": { "type": "array", "items": { "$ref": "#/$defs/cantonLegTopology" } } } },
|
|
669
|
+
"else": { "type": "object", "properties": { "legs": { "type": "array", "items": { "$ref": "#/$defs/cantonLegTransaction" } } } }
|
|
670
|
+
},
|
|
671
|
+
{
|
|
672
|
+
"if": { "type": "object", "properties": { "op": { "const": "party.allocate" } }, "required": ["op"] },
|
|
673
|
+
"then": {
|
|
674
|
+
"type": "object",
|
|
675
|
+
"required": ["summary"],
|
|
676
|
+
"properties": {
|
|
677
|
+
"summary": {
|
|
678
|
+
"type": "object",
|
|
679
|
+
"required": ["partyId", "publicKey", "hosting"],
|
|
680
|
+
"properties": {
|
|
681
|
+
"partyId": { "type": "string", "minLength": 1 },
|
|
682
|
+
"publicKey": { "$ref": "#/$defs/edPublicKey" },
|
|
683
|
+
"hosting": {
|
|
684
|
+
"type": "object",
|
|
685
|
+
"required": ["participantUid", "permission", "threshold"],
|
|
686
|
+
"description": "how the topology hosts the party: on the Cancore participant alone, with Confirmation permission, threshold 1 — the node checks the decoded topology against it",
|
|
687
|
+
"properties": { "participantUid": { "type": "string", "minLength": 1 }, "permission": { "const": "CONFIRMATION" }, "threshold": { "const": 1 } }
|
|
688
|
+
}
|
|
689
|
+
}
|
|
690
|
+
}
|
|
691
|
+
}
|
|
692
|
+
}
|
|
693
|
+
},
|
|
694
|
+
{
|
|
695
|
+
"if": { "type": "object", "properties": { "op": { "const": "registry.accept" } }, "required": ["op"] },
|
|
696
|
+
"then": {
|
|
697
|
+
"type": "object",
|
|
698
|
+
"required": ["summary"],
|
|
699
|
+
"properties": {
|
|
700
|
+
"summary": {
|
|
701
|
+
"type": "object",
|
|
702
|
+
"required": ["fillerId", "party", "operator", "proposalCid"],
|
|
703
|
+
"properties": {
|
|
704
|
+
"fillerId": { "$ref": "#/$defs/fillerId" },
|
|
705
|
+
"party": { "type": "string", "minLength": 1 },
|
|
706
|
+
"operator": { "type": "string", "minLength": 1 },
|
|
707
|
+
"proposalCid": { "type": "string", "minLength": 1 }
|
|
708
|
+
}
|
|
709
|
+
}
|
|
710
|
+
}
|
|
711
|
+
}
|
|
712
|
+
},
|
|
713
|
+
{
|
|
714
|
+
"if": { "type": "object", "properties": { "op": { "const": "delivery.fill" } }, "required": ["op"] },
|
|
715
|
+
"then": {
|
|
716
|
+
"type": "object",
|
|
717
|
+
"required": ["summary"],
|
|
718
|
+
"properties": {
|
|
719
|
+
"summary": {
|
|
720
|
+
"type": "object",
|
|
721
|
+
"required": [
|
|
722
|
+
"orderHash",
|
|
723
|
+
"attempt",
|
|
724
|
+
"deliveryOrderCid",
|
|
725
|
+
"recipient",
|
|
726
|
+
"asset",
|
|
727
|
+
"amount",
|
|
728
|
+
"repayTo",
|
|
729
|
+
"validUntil",
|
|
730
|
+
"inputHoldingCids",
|
|
731
|
+
"executeBefore",
|
|
732
|
+
"transferFactoryCid"
|
|
733
|
+
],
|
|
734
|
+
"properties": {
|
|
735
|
+
"orderHash": { "$ref": "#/$defs/bytes32" },
|
|
736
|
+
"attempt": { "$ref": "#/$defs/uint32" },
|
|
737
|
+
"deliveryOrderCid": { "type": "string", "minLength": 1 },
|
|
738
|
+
"recipient": { "type": "string", "minLength": 1, "description": "the Canton party the order delivers to" },
|
|
739
|
+
"asset": { "$ref": "#/$defs/cantonAsset" },
|
|
740
|
+
"amount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,10})?$", "description": "DeliveryOrder.amount, Daml Decimal" },
|
|
741
|
+
"repayTo": { "$ref": "#/$defs/repayTo" },
|
|
742
|
+
"validUntil": { "$ref": "#/$defs/timeS" },
|
|
743
|
+
"inputHoldingCids": {
|
|
744
|
+
"type": "array",
|
|
745
|
+
"minItems": 1,
|
|
746
|
+
"items": { "type": "string", "minLength": 1 },
|
|
747
|
+
"description": "the party's holdings the transfer spends; whatever they hold beyond amount comes back as change"
|
|
748
|
+
},
|
|
749
|
+
"executeBefore": { "$ref": "#/$defs/timeS", "description": "the transfer's executeBefore: the order's fillDeadline" },
|
|
750
|
+
"transferFactoryCid": { "type": "string", "minLength": 1, "description": "the registry factory the order pins" }
|
|
751
|
+
}
|
|
752
|
+
}
|
|
753
|
+
}
|
|
754
|
+
}
|
|
755
|
+
},
|
|
756
|
+
{
|
|
757
|
+
"if": { "type": "object", "properties": { "op": { "const": "intent.settle" } }, "required": ["op"] },
|
|
758
|
+
"then": {
|
|
759
|
+
"type": "object",
|
|
760
|
+
"required": ["summary"],
|
|
761
|
+
"properties": {
|
|
762
|
+
"summary": {
|
|
763
|
+
"type": "object",
|
|
764
|
+
"required": ["orderHash", "intentCid", "asset", "amount", "executeBefore", "payee", "giveAmount", "fee"],
|
|
765
|
+
"properties": {
|
|
766
|
+
"orderHash": { "$ref": "#/$defs/bytes32" },
|
|
767
|
+
"intentCid": { "type": "string", "minLength": 1 },
|
|
768
|
+
"asset": { "$ref": "#/$defs/cantonAsset" },
|
|
769
|
+
"amount": {
|
|
770
|
+
"type": "string",
|
|
771
|
+
"pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,10})?$",
|
|
772
|
+
"description": "what the settlement pays the payee: giveAmount less fee.amount, Daml Decimal"
|
|
773
|
+
},
|
|
774
|
+
"executeBefore": { "$ref": "#/$defs/timeS" },
|
|
775
|
+
"payee": { "type": "string", "minLength": 1, "description": "the party paid: the filler's own" },
|
|
776
|
+
"giveAmount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,10})?$", "description": "the intent's committed give, fee-inclusive" },
|
|
777
|
+
"fee": {
|
|
778
|
+
"type": "object",
|
|
779
|
+
"required": ["receiver", "amount"],
|
|
780
|
+
"properties": {
|
|
781
|
+
"receiver": { "type": "string", "minLength": 1, "description": "the operator party" },
|
|
782
|
+
"amount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,10})?$" }
|
|
783
|
+
},
|
|
784
|
+
"description": "the settlement's fee leg; amount 0 when there is none"
|
|
785
|
+
}
|
|
786
|
+
}
|
|
787
|
+
}
|
|
788
|
+
}
|
|
789
|
+
}
|
|
790
|
+
},
|
|
791
|
+
{
|
|
792
|
+
"if": { "type": "object", "properties": { "op": { "const": "holdings.transfer" } }, "required": ["op"] },
|
|
793
|
+
"then": {
|
|
794
|
+
"type": "object",
|
|
795
|
+
"required": ["summary"],
|
|
796
|
+
"properties": {
|
|
797
|
+
"summary": {
|
|
798
|
+
"type": "object",
|
|
799
|
+
"required": ["asset", "amount", "receiver", "inputHoldingCids", "executeBefore"],
|
|
800
|
+
"properties": {
|
|
801
|
+
"asset": { "$ref": "#/$defs/cantonAsset" },
|
|
802
|
+
"amount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,10})?$" },
|
|
803
|
+
"receiver": { "type": "string", "minLength": 1 },
|
|
804
|
+
"inputHoldingCids": {
|
|
805
|
+
"type": "array",
|
|
806
|
+
"minItems": 1,
|
|
807
|
+
"items": { "type": "string", "minLength": 1 },
|
|
808
|
+
"description": "the party's holdings the transfer spends; what they hold beyond amount comes back as change"
|
|
809
|
+
},
|
|
810
|
+
"executeBefore": { "$ref": "#/$defs/timeS" }
|
|
811
|
+
}
|
|
812
|
+
}
|
|
813
|
+
}
|
|
814
|
+
}
|
|
815
|
+
}
|
|
816
|
+
],
|
|
817
|
+
"required": ["type", "re", "operationId", "op", "legs", "summary", "expiresAt"],
|
|
818
|
+
"properties": {
|
|
819
|
+
"type": { "const": "canton.prepared" },
|
|
820
|
+
"re": { "$ref": "#/$defs/messageId" },
|
|
821
|
+
"operationId": { "$ref": "#/$defs/operationId" },
|
|
822
|
+
"op": { "$ref": "#/$defs/cantonOp" },
|
|
823
|
+
"legs": { "type": "array", "minItems": 1 },
|
|
824
|
+
"summary": { "type": "object" },
|
|
825
|
+
"expiresAt": { "$ref": "#/$defs/timeMs" }
|
|
826
|
+
}
|
|
827
|
+
},
|
|
828
|
+
"canton.submit": {
|
|
829
|
+
"x-direction": "F2S",
|
|
830
|
+
"type": "object",
|
|
831
|
+
"description": "Submit a prepared operation: one party-key signature per leg. Idempotent per operationId: a repeat (after a lost answer or CANTON_UNAVAILABLE) is answered with the same canton.submitted and never executes twice. OPERATION_EXPIRED: prepare again",
|
|
832
|
+
"allOf": [{ "$ref": "#/$defs/f2sBase" }],
|
|
833
|
+
"required": ["type", "operationId", "signatures"],
|
|
834
|
+
"properties": {
|
|
835
|
+
"type": { "const": "canton.submit" },
|
|
836
|
+
"operationId": { "$ref": "#/$defs/operationId" },
|
|
837
|
+
"signatures": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/cantonSignature" } }
|
|
838
|
+
}
|
|
839
|
+
},
|
|
840
|
+
"canton.submitted": {
|
|
841
|
+
"x-direction": "S2F",
|
|
842
|
+
"type": "object",
|
|
843
|
+
"description": "The operation committed. updateId is its Canton update (absent for party.allocate, a topology change); result names what it created, by op",
|
|
844
|
+
"allOf": [
|
|
845
|
+
{ "$ref": "#/$defs/s2fBase" },
|
|
846
|
+
{
|
|
847
|
+
"if": { "type": "object", "properties": { "op": { "const": "party.allocate" } }, "required": ["op"] },
|
|
848
|
+
"then": {
|
|
849
|
+
"type": "object",
|
|
850
|
+
"required": ["result"],
|
|
851
|
+
"properties": { "result": { "type": "object", "required": ["partyId"], "properties": { "partyId": { "type": "string", "minLength": 1 } } } }
|
|
852
|
+
}
|
|
853
|
+
},
|
|
854
|
+
{
|
|
855
|
+
"if": { "type": "object", "properties": { "op": { "const": "registry.accept" } }, "required": ["op"] },
|
|
856
|
+
"then": {
|
|
857
|
+
"type": "object",
|
|
858
|
+
"required": ["result"],
|
|
859
|
+
"properties": { "result": { "type": "object", "required": ["entryCid"], "properties": { "entryCid": { "type": "string", "minLength": 1 } } } }
|
|
860
|
+
}
|
|
861
|
+
},
|
|
862
|
+
{
|
|
863
|
+
"if": { "type": "object", "properties": { "op": { "const": "delivery.fill" } }, "required": ["op"] },
|
|
864
|
+
"then": {
|
|
865
|
+
"type": "object",
|
|
866
|
+
"required": ["result"],
|
|
867
|
+
"properties": { "result": { "type": "object", "required": ["receiptCid"], "properties": { "receiptCid": { "type": "string", "minLength": 1 } } } }
|
|
868
|
+
}
|
|
869
|
+
},
|
|
870
|
+
{
|
|
871
|
+
"if": { "type": "object", "properties": { "op": { "const": "intent.settle" } }, "required": ["op"] },
|
|
872
|
+
"then": { "type": "object", "required": ["result"], "properties": { "result": { "type": "object" } } }
|
|
873
|
+
},
|
|
874
|
+
{
|
|
875
|
+
"if": { "type": "object", "properties": { "op": { "const": "holdings.transfer" } }, "required": ["op"] },
|
|
876
|
+
"then": {
|
|
877
|
+
"type": "object",
|
|
878
|
+
"required": ["result"],
|
|
879
|
+
"properties": {
|
|
880
|
+
"result": {
|
|
881
|
+
"type": "object",
|
|
882
|
+
"required": ["outcome"],
|
|
883
|
+
"properties": {
|
|
884
|
+
"outcome": {
|
|
885
|
+
"anyOf": [{ "enum": ["COMPLETED", "PENDING"] }, { "$ref": "#/$defs/futureEnumValue" }],
|
|
886
|
+
"description": "COMPLETED: the receiver holds it (a preapproval accepted it); PENDING: a TransferInstruction waits for the receiver to accept"
|
|
887
|
+
},
|
|
888
|
+
"transferInstructionCid": { "type": "string", "minLength": 1, "description": "with PENDING" }
|
|
889
|
+
}
|
|
890
|
+
}
|
|
891
|
+
}
|
|
892
|
+
}
|
|
893
|
+
}
|
|
894
|
+
],
|
|
895
|
+
"required": ["type", "re", "operationId", "op", "result"],
|
|
896
|
+
"properties": {
|
|
897
|
+
"type": { "const": "canton.submitted" },
|
|
898
|
+
"re": { "$ref": "#/$defs/messageId" },
|
|
899
|
+
"operationId": { "$ref": "#/$defs/operationId" },
|
|
900
|
+
"op": { "$ref": "#/$defs/cantonOp" },
|
|
901
|
+
"updateId": { "type": "string", "minLength": 1 },
|
|
902
|
+
"result": { "type": "object" }
|
|
903
|
+
}
|
|
541
904
|
}
|
|
542
905
|
}
|
|
543
906
|
}
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
3
|
"$id": "https://cancore.io/schemas/filler-protocol/v1/rest.schema.json",
|
|
4
4
|
"title": "Cancore filler protocol v1 — REST fallback",
|
|
5
|
-
"$comment": "protocol §3.6. Bodies are the WebSocket frames: every request body is a filler message with its envelope (id, fillerId, sentAt) and msgSig, verified before processing as on the WebSocket (S-19); every response is a freshly signed S→F message. Login: GET /v1/filler/auth/challenge?fillerId= returns a signed auth.challenge addressed to that fillerId; POST /v1/filler/auth with the auth.response (FillerAuth over it) returns {token, expiresAt}. The challenge route is anonymous and its refusals are UNSIGNED (unsignedErrorBody, no sig, nothing journalled): 400 BAD_REQUEST — fillerId missing or not a fillerId; 404 UNKNOWN_REQUEST — fillerId unknown or not ACTIVE; the anonymous login steps are charged to no fillerId's rate limits (knowing a fillerId cannot lock its filler out); a 429 here comes only from the per-IP limit in front of filler-gateway. POST /v1/filler/auth refuses UNSIGNED too as long as it has checked no signature: 400 BAD_REQUEST — no or a malformed fillerId; 404 UNKNOWN_REQUEST — fillerId unknown or not ACTIVE; 401 UNAUTHENTICATED — the fillerId holds no live challenge (evicted, expired or used: ask for a new one). Its refusals after the signature checks (BAD_SIGNATURE, STALE_MESSAGE, REPLAYED_MESSAGE, UNSUPPORTED_VERSION, NOT_ELIGIBLE, UNAUTHENTICATED) are the signed error. The other /v1/filler/* routes need `Authorization: Bearer <token>`; the token is bound to (fillerId, message key) and stops working when it expires, when the message key is changed, or when the filler is no longer ACTIVE. The same token opens the WebSocket (asyncapi.json: offered as the subprotocol bearer.<token>). A ticket of another filler is 404 UNKNOWN_TICKET. Rate limits are per fillerId, shared by REST and every WebSocket session of it: over the limit a bearer route answers 429 with an UNSIGNED unsignedErrorBody {type: error, code: RATE_LIMITED, message, retryAfterMs} and a Retry-After header (seconds, rounded up), journals nothing one by one, and the request changes nothing; during the cooldown after sustained excess every bearer route answers so. Every 429 is unsigned, on every route; a filler decides by the status and takes retryAfterMs (else Retry-After) as a hint. Every other non-2xx of a bearer route is the signed error. GET /v1/filler/attestations/{orderHash} answers 404 ATTESTATIONS_NOT_READY until the gateway holds ≥ threshold verified signatures for this filler's fill, and 404 UNKNOWN_TICKET when this filler holds no ticket on the order. /v1/draws/* and /v1/gateway are public. Every non-2xx body is the signed `error` frame, with the HTTP status of x-error-status — except a 429 (always unsignedErrorBody) and the unsigned refusals of an endpoint that names an errorBody. x-endpoints: request/query/response/errorBody name a $def here or in messages.schema.json.",
|
|
5
|
+
"$comment": "protocol §3.6. Bodies are the WebSocket frames: every request body is a filler message with its envelope (id, fillerId, sentAt) and msgSig, verified before processing as on the WebSocket (S-19); every response is a freshly signed S→F message. Login: GET /v1/filler/auth/challenge?fillerId= returns a signed auth.challenge addressed to that fillerId; POST /v1/filler/auth with the auth.response (FillerAuth over it) returns {token, expiresAt}. The challenge route is anonymous and its refusals are UNSIGNED (unsignedErrorBody, no sig, nothing journalled): 400 BAD_REQUEST — fillerId missing or not a fillerId; 404 UNKNOWN_REQUEST — fillerId unknown or not ACTIVE; the anonymous login steps are charged to no fillerId's rate limits (knowing a fillerId cannot lock its filler out); a 429 here comes only from the per-IP limit in front of filler-gateway. POST /v1/filler/auth refuses UNSIGNED too as long as it has checked no signature: 400 BAD_REQUEST — no or a malformed fillerId; 404 UNKNOWN_REQUEST — fillerId unknown or not ACTIVE; 401 UNAUTHENTICATED — the fillerId holds no live challenge (evicted, expired or used: ask for a new one). Its refusals after the signature checks (BAD_SIGNATURE, STALE_MESSAGE, REPLAYED_MESSAGE, UNSUPPORTED_VERSION, NOT_ELIGIBLE, UNAUTHENTICATED) are the signed error. The other /v1/filler/* routes need `Authorization: Bearer <token>`; the token is bound to (fillerId, message key) and stops working when it expires, when the message key is changed, or when the filler is no longer ACTIVE. The same token opens the WebSocket (asyncapi.json: offered as the subprotocol bearer.<token>). A ticket of another filler is 404 UNKNOWN_TICKET. Rate limits are per fillerId and rate class (quote, ticket, service, read for every bearer GET, login, cantonPrepare for canton.prepare of §3.19 — an hourly budget per filler, 60 by default — and canton for canton.submit, so a spent prepare budget never holds back the submit of an operation already prepared), shared by REST and every WebSocket session of it: over the limit a bearer route answers 429 with an UNSIGNED unsignedErrorBody {type: error, code: RATE_LIMITED, message, retryAfterMs} and a Retry-After header (seconds, rounded up), journals nothing one by one, and the request changes nothing; during the cooldown after sustained excess every bearer route answers so. Every 429 is unsigned, on every route; a filler decides by the status and takes retryAfterMs (else Retry-After) as a hint. Every other non-2xx of a bearer route is the signed error. GET /v1/filler/attestations/{orderHash} answers 404 ATTESTATIONS_NOT_READY until the gateway holds ≥ threshold verified signatures for this filler's fill, and 404 UNKNOWN_TICKET when this filler holds no ticket on the order. /v1/filler/canton/* (§3.19) serve only the caller's own party: POST prepare and submit take the canton.prepare and canton.submit messages and answer canton.prepared and canton.submitted (the same frames as on the WebSocket); GET party, holdings and delivery-orders read the party registered for the fillerId, and answer 409 CANTON_NOT_READY while it has none. /v1/draws/* and /v1/gateway are public. Every non-2xx body is the signed `error` frame, with the HTTP status of x-error-status — except a 429 (always unsignedErrorBody) and the unsigned refusals of an endpoint that names an errorBody. x-endpoints: request/query/response/errorBody name a $def here or in messages.schema.json.",
|
|
6
6
|
"x-endpoints": [
|
|
7
7
|
{ "method": "GET", "path": "/v1/filler/auth/challenge", "auth": "none", "query": "#/$defs/challengeQuery", "response": "messages.schema.json#/$defs/auth.challenge", "errorBody": "#/$defs/unsignedErrorBody" },
|
|
8
8
|
{ "method": "POST", "path": "/v1/filler/auth", "auth": "none", "request": "messages.schema.json#/$defs/auth.response", "response": "#/$defs/authToken", "errorBody": "#/$defs/unsignedErrorBody" },
|
|
@@ -17,12 +17,17 @@
|
|
|
17
17
|
{ "method": "GET", "path": "/v1/filler/attestations/{orderHash}", "auth": "bearer", "response": "messages.schema.json#/$defs/settle.attestations" },
|
|
18
18
|
{ "method": "GET", "path": "/v1/draws/{orderHash}", "auth": "none", "response": "records.schema.json#/$defs/drawRecord" },
|
|
19
19
|
{ "method": "GET", "path": "/v1/draws/epochs/{id}", "auth": "none", "response": "records.schema.json#/$defs/epochRecord" },
|
|
20
|
-
{ "method": "GET", "path": "/v1/gateway", "auth": "none", "response": "records.schema.json#/$defs/gatewayInfo" }
|
|
20
|
+
{ "method": "GET", "path": "/v1/gateway", "auth": "none", "response": "records.schema.json#/$defs/gatewayInfo" },
|
|
21
|
+
{ "method": "POST", "path": "/v1/filler/canton/prepare", "auth": "bearer", "request": "messages.schema.json#/$defs/canton.prepare", "response": "messages.schema.json#/$defs/canton.prepared" },
|
|
22
|
+
{ "method": "POST", "path": "/v1/filler/canton/submit", "auth": "bearer", "request": "messages.schema.json#/$defs/canton.submit", "response": "messages.schema.json#/$defs/canton.submitted" },
|
|
23
|
+
{ "method": "GET", "path": "/v1/filler/canton/party", "auth": "bearer", "response": "#/$defs/cantonParty" },
|
|
24
|
+
{ "method": "GET", "path": "/v1/filler/canton/holdings", "auth": "bearer", "query": "#/$defs/pageQuery", "response": "#/$defs/cantonHoldingList" },
|
|
25
|
+
{ "method": "GET", "path": "/v1/filler/canton/delivery-orders", "auth": "bearer", "query": "#/$defs/pageQuery", "response": "#/$defs/cantonDeliveryOrderList" }
|
|
21
26
|
],
|
|
22
27
|
"x-error-status": {
|
|
23
28
|
"BAD_REQUEST": 400, "UNAUTHENTICATED": 401, "UNSUPPORTED_VERSION": 400, "UNSUPPORTED_TYPE": 400, "BAD_SIGNATURE": 422,
|
|
24
29
|
"STALE_MESSAGE": 400, "REPLAYED_MESSAGE": 409, "TICKET_REFUSED": 409, "UNKNOWN_REQUEST": 404, "UNKNOWN_TICKET": 404, "TICKET_CLOSED": 409, "NOT_ELIGIBLE": 403, "RATE_LIMITED": 429, "INTERNAL": 500,
|
|
25
|
-
"ATTESTATIONS_NOT_READY": 404
|
|
30
|
+
"ATTESTATIONS_NOT_READY": 404, "CANTON_NOT_READY": 409, "CANTON_REFUSED": 422, "CANTON_UNAVAILABLE": 503, "OPERATION_EXPIRED": 410
|
|
26
31
|
},
|
|
27
32
|
"$defs": {
|
|
28
33
|
"errorBody": { "$ref": "messages.schema.json#/$defs/errorS2F" },
|
|
@@ -129,6 +134,60 @@
|
|
|
129
134
|
"type": "object",
|
|
130
135
|
"required": ["items", "nextCursor"],
|
|
131
136
|
"properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/penaltyRecord" } }, "nextCursor": { "type": ["string", "null"] } }
|
|
137
|
+
},
|
|
138
|
+
"cantonParty": {
|
|
139
|
+
"type": "object",
|
|
140
|
+
"description": "The filler's Canton party and its FillerRegistryEntry with the operator. party null: none allocated or registered yet (party.allocate). registry.state NONE: no proposal yet; PROPOSED: accept it (registry.accept); ACTIVE: the Canton routes may be activated; REMOVED: staff removed the entry",
|
|
141
|
+
"required": ["party", "publicKey", "registry"],
|
|
142
|
+
"properties": {
|
|
143
|
+
"party": { "type": ["string", "null"], "minLength": 1 },
|
|
144
|
+
"publicKey": { "anyOf": [{ "$ref": "messages.schema.json#/$defs/edPublicKey" }, { "type": "null" }] },
|
|
145
|
+
"registry": {
|
|
146
|
+
"type": "object",
|
|
147
|
+
"required": ["state", "proposalCid", "entryCid"],
|
|
148
|
+
"properties": {
|
|
149
|
+
"state": { "anyOf": [{ "enum": ["NONE", "PROPOSED", "ACTIVE", "REMOVED"] }, { "$ref": "messages.schema.json#/$defs/futureEnumValue" }] },
|
|
150
|
+
"proposalCid": { "type": ["string", "null"] },
|
|
151
|
+
"entryCid": { "type": ["string", "null"] }
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
},
|
|
156
|
+
"cantonHolding": {
|
|
157
|
+
"type": "object",
|
|
158
|
+
"required": ["contractId", "asset", "amount", "locked"],
|
|
159
|
+
"properties": {
|
|
160
|
+
"contractId": { "type": "string", "minLength": 1 },
|
|
161
|
+
"asset": { "$ref": "messages.schema.json#/$defs/cantonAsset" },
|
|
162
|
+
"amount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,10})?$", "description": "Daml Decimal" },
|
|
163
|
+
"locked": { "type": "boolean", "description": "held by a lock (an allocation or a pending transfer); not spendable by delivery.fill" }
|
|
164
|
+
}
|
|
165
|
+
},
|
|
166
|
+
"cantonHoldingList": {
|
|
167
|
+
"type": "object",
|
|
168
|
+
"description": "Holdings of the party (CNRX and Canton Coin among them), oldest first",
|
|
169
|
+
"required": ["items", "nextCursor"],
|
|
170
|
+
"properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/cantonHolding" } }, "nextCursor": { "type": ["string", "null"] } }
|
|
171
|
+
},
|
|
172
|
+
"cantonDeliveryOrder": {
|
|
173
|
+
"type": "object",
|
|
174
|
+
"required": ["deliveryOrderCid", "orderHash", "attempt", "asset", "amount", "recipient", "repayTo", "validUntil"],
|
|
175
|
+
"properties": {
|
|
176
|
+
"deliveryOrderCid": { "type": "string", "minLength": 1 },
|
|
177
|
+
"orderHash": { "$ref": "messages.schema.json#/$defs/bytes32" },
|
|
178
|
+
"attempt": { "$ref": "messages.schema.json#/$defs/uint32" },
|
|
179
|
+
"asset": { "$ref": "messages.schema.json#/$defs/cantonAsset" },
|
|
180
|
+
"amount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,10})?$", "description": "Daml Decimal" },
|
|
181
|
+
"recipient": { "type": "string", "minLength": 1 },
|
|
182
|
+
"repayTo": { "$ref": "messages.schema.json#/$defs/repayTo" },
|
|
183
|
+
"validUntil": { "$ref": "messages.schema.json#/$defs/timeS" }
|
|
184
|
+
}
|
|
185
|
+
},
|
|
186
|
+
"cantonDeliveryOrderList": {
|
|
187
|
+
"type": "object",
|
|
188
|
+
"description": "The live DeliveryOrders naming the party as filler, oldest first",
|
|
189
|
+
"required": ["items", "nextCursor"],
|
|
190
|
+
"properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/cantonDeliveryOrder" } }, "nextCursor": { "type": ["string", "null"] } }
|
|
132
191
|
}
|
|
133
192
|
}
|
|
134
193
|
}
|