From c8b2b9040385ad405481f06b090f7bebc1a0070c Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Mon, 16 Mar 2026 15:28:35 +0200 Subject: [PATCH 01/19] fix: strip __origin__ from Encoding and Variables maps The origin-tracking YAML loader injects __origin__ as a key inside any map-valued field to record source location. Typed Go maps (map[string]*Encoding, map[string]*ServerVariable) treat __origin__ as a real entry, causing false positive diffs when the same spec is loaded from two different file paths (issue oasdiff/oasdiff#806). Fix by deleting originKey from these maps after JSON unmarshaling, mirroring the existing pattern for Extensions and the unmarshalStringMapP helper already used by Content, Schemas, Headers, etc. Co-Authored-By: Claude Sonnet 4.6 --- openapi3/encoding.go | 9 +++++++++ openapi3/media_type.go | 4 ++-- openapi3/server.go | 11 ++++++++++- 3 files changed, 21 insertions(+), 3 deletions(-) diff --git a/openapi3/encoding.go b/openapi3/encoding.go index 113eb730c..a6d849925 100644 --- a/openapi3/encoding.go +++ b/openapi3/encoding.go @@ -24,6 +24,15 @@ func NewEncoding() *Encoding { return &Encoding{} } +// Encodings is a map of encoding objects keyed by field name. +type Encodings map[string]*Encoding + +// UnmarshalJSON sets Encodings to a copy of data, stripping __origin__ metadata. +func (encodings *Encodings) UnmarshalJSON(data []byte) (err error) { + *encodings, _, err = unmarshalStringMapP[Encoding](data) + return +} + func (encoding *Encoding) WithHeader(name string, header *Header) *Encoding { return encoding.WithHeaderRef(name, &HeaderRef{ Value: header, diff --git a/openapi3/media_type.go b/openapi3/media_type.go index c3bb1bea6..de2d2a23d 100644 --- a/openapi3/media_type.go +++ b/openapi3/media_type.go @@ -19,7 +19,7 @@ type MediaType struct { Schema *SchemaRef `json:"schema,omitempty" yaml:"schema,omitempty"` Example any `json:"example,omitempty" yaml:"example,omitempty"` Examples Examples `json:"examples,omitempty" yaml:"examples,omitempty"` - Encoding map[string]*Encoding `json:"encoding,omitempty" yaml:"encoding,omitempty"` + Encoding Encodings `json:"encoding,omitempty" yaml:"encoding,omitempty"` } var _ jsonpointer.JSONPointable = (*MediaType)(nil) @@ -57,7 +57,7 @@ func (mediaType *MediaType) WithExample(name string, value any) *MediaType { func (mediaType *MediaType) WithEncoding(name string, enc *Encoding) *MediaType { encoding := mediaType.Encoding if encoding == nil { - encoding = make(map[string]*Encoding) + encoding = make(Encodings) mediaType.Encoding = encoding } encoding[name] = enc diff --git a/openapi3/server.go b/openapi3/server.go index ea7751745..4f6e3b7f8 100644 --- a/openapi3/server.go +++ b/openapi3/server.go @@ -55,7 +55,7 @@ type Server struct { URL string `json:"url" yaml:"url"` // Required Description string `json:"description,omitempty" yaml:"description,omitempty"` - Variables map[string]*ServerVariable `json:"variables,omitempty" yaml:"variables,omitempty"` + Variables ServerVariables `json:"variables,omitempty" yaml:"variables,omitempty"` } // BasePath returns the base path extracted from the default values of variables, if any. @@ -234,6 +234,15 @@ func (server *Server) Validate(ctx context.Context, opts ...ValidationOption) (e // ServerVariable is specified by OpenAPI/Swagger standard version 3. // See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#server-variable-object +// ServerVariables is a map of ServerVariable objects keyed by variable name. +type ServerVariables map[string]*ServerVariable + +// UnmarshalJSON sets ServerVariables to a copy of data, stripping __origin__ metadata. +func (serverVariables *ServerVariables) UnmarshalJSON(data []byte) (err error) { + *serverVariables, _, err = unmarshalStringMapP[ServerVariable](data) + return +} + type ServerVariable struct { Extensions map[string]any `json:"-" yaml:"-"` Origin *Origin `json:"__origin__,omitempty" yaml:"__origin__,omitempty"` From 23e4e36d32a99407a959ba234da503f6429bc9eb Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Mon, 16 Mar 2026 17:44:43 +0200 Subject: [PATCH 02/19] docs: update API docs and changelog for Encodings and ServerVariables types MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Run docs.sh to regenerate .github/docs/openapi3.txt after the type changes in encoding.go and server.go (map[string]*Encoding → Encodings, map[string]*ServerVariable → ServerVariables). Add v0.135.0 breaking API changes entries to README.md. Co-Authored-By: Claude Sonnet 4.6 --- .github/docs/openapi3.txt | 32 +++++++++++++++++++++++--------- README.md | 4 ++++ 2 files changed, 27 insertions(+), 9 deletions(-) diff --git a/.github/docs/openapi3.txt b/.github/docs/openapi3.txt index 720a4760f..a8ec46977 100644 --- a/.github/docs/openapi3.txt +++ b/.github/docs/openapi3.txt @@ -485,6 +485,13 @@ func (encoding *Encoding) WithHeader(name string, header *Header) *Encoding func (encoding *Encoding) WithHeaderRef(name string, ref *HeaderRef) *Encoding +type Encodings map[string]*Encoding + Encodings is a map of encoding objects keyed by field name. + +func (encodings *Encodings) UnmarshalJSON(data []byte) (err error) + UnmarshalJSON sets Encodings to a copy of data, stripping __origin__ + metadata. + type Example struct { Extensions map[string]any `json:"-" yaml:"-"` Origin *Origin `json:"__origin__,omitempty" yaml:"__origin__,omitempty"` @@ -862,10 +869,10 @@ type MediaType struct { Extensions map[string]any `json:"-" yaml:"-"` Origin *Origin `json:"__origin__,omitempty" yaml:"__origin__,omitempty"` - Schema *SchemaRef `json:"schema,omitempty" yaml:"schema,omitempty"` - Example any `json:"example,omitempty" yaml:"example,omitempty"` - Examples Examples `json:"examples,omitempty" yaml:"examples,omitempty"` - Encoding map[string]*Encoding `json:"encoding,omitempty" yaml:"encoding,omitempty"` + Schema *SchemaRef `json:"schema,omitempty" yaml:"schema,omitempty"` + Example any `json:"example,omitempty" yaml:"example,omitempty"` + Examples Examples `json:"examples,omitempty" yaml:"examples,omitempty"` + Encoding Encodings `json:"encoding,omitempty" yaml:"encoding,omitempty"` } MediaType is specified by OpenAPI/Swagger 3.0 standard. See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#media-type-object @@ -2067,9 +2074,9 @@ type Server struct { Extensions map[string]any `json:"-" yaml:"-"` Origin *Origin `json:"__origin__,omitempty" yaml:"__origin__,omitempty"` - URL string `json:"url" yaml:"url"` // Required - Description string `json:"description,omitempty" yaml:"description,omitempty"` - Variables map[string]*ServerVariable `json:"variables,omitempty" yaml:"variables,omitempty"` + URL string `json:"url" yaml:"url"` // Required + Description string `json:"description,omitempty" yaml:"description,omitempty"` + Variables ServerVariables `json:"variables,omitempty" yaml:"variables,omitempty"` } Server is specified by OpenAPI/Swagger standard version 3. See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#server-object @@ -2102,8 +2109,6 @@ type ServerVariable struct { Default string `json:"default,omitempty" yaml:"default,omitempty"` Description string `json:"description,omitempty" yaml:"description,omitempty"` } - ServerVariable is specified by OpenAPI/Swagger standard version 3. See - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#server-variable-object func (serverVariable ServerVariable) MarshalJSON() ([]byte, error) MarshalJSON returns the JSON encoding of ServerVariable. @@ -2118,6 +2123,15 @@ func (serverVariable *ServerVariable) Validate(ctx context.Context, opts ...Vali Validate returns an error if ServerVariable does not comply with the OpenAPI spec. +type ServerVariables map[string]*ServerVariable + ServerVariable is specified by OpenAPI/Swagger standard version 3. See + https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#server-variable-object + ServerVariables is a map of ServerVariable objects keyed by variable name. + +func (serverVariables *ServerVariables) UnmarshalJSON(data []byte) (err error) + UnmarshalJSON sets ServerVariables to a copy of data, stripping __origin__ + metadata. + type Servers []*Server Servers is specified by OpenAPI/Swagger standard version 3. diff --git a/README.md b/README.md index 951ae0204..6f37ae89b 100644 --- a/README.md +++ b/README.md @@ -294,6 +294,10 @@ for _, path := range doc.Paths.InMatchingOrder() { ## CHANGELOG: Sub-v1 breaking API changes +### v0.135.0 +* `openapi3.MediaType.Encoding` field type changed from `map[string]*Encoding` to `Encodings` +* `openapi3.Server.Variables` field type changed from `map[string]*ServerVariable` to `ServerVariables` + ### v0.134.0 * `openapi3.Location` gained `File` and `Name` fields (`string` type, replacing previous `int`-only struct layout) * `openapi3.Origin` gained `Sequences` field (`map[string][]Location`, extending previous `map[string]Location`-only struct) From a09d176e52ca80d2f6413bb141ebe591cbee96df Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Mon, 16 Mar 2026 17:50:13 +0200 Subject: [PATCH 03/19] style: run go fmt on encoding and server files Co-Authored-By: Claude Sonnet 4.6 --- .gitignore | 1 + openapi3/media_type.go | 8 ++++---- openapi3/server.go | 4 ++-- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/.gitignore b/.gitignore index 40b671156..9c3b22a33 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ # IntelliJ / GoLand .idea .vscode +.claude/ diff --git a/openapi3/media_type.go b/openapi3/media_type.go index de2d2a23d..92e92e4e9 100644 --- a/openapi3/media_type.go +++ b/openapi3/media_type.go @@ -16,10 +16,10 @@ type MediaType struct { Extensions map[string]any `json:"-" yaml:"-"` Origin *Origin `json:"__origin__,omitempty" yaml:"__origin__,omitempty"` - Schema *SchemaRef `json:"schema,omitempty" yaml:"schema,omitempty"` - Example any `json:"example,omitempty" yaml:"example,omitempty"` - Examples Examples `json:"examples,omitempty" yaml:"examples,omitempty"` - Encoding Encodings `json:"encoding,omitempty" yaml:"encoding,omitempty"` + Schema *SchemaRef `json:"schema,omitempty" yaml:"schema,omitempty"` + Example any `json:"example,omitempty" yaml:"example,omitempty"` + Examples Examples `json:"examples,omitempty" yaml:"examples,omitempty"` + Encoding Encodings `json:"encoding,omitempty" yaml:"encoding,omitempty"` } var _ jsonpointer.JSONPointable = (*MediaType)(nil) diff --git a/openapi3/server.go b/openapi3/server.go index 4f6e3b7f8..9415cb23c 100644 --- a/openapi3/server.go +++ b/openapi3/server.go @@ -53,8 +53,8 @@ type Server struct { Extensions map[string]any `json:"-" yaml:"-"` Origin *Origin `json:"__origin__,omitempty" yaml:"__origin__,omitempty"` - URL string `json:"url" yaml:"url"` // Required - Description string `json:"description,omitempty" yaml:"description,omitempty"` + URL string `json:"url" yaml:"url"` // Required + Description string `json:"description,omitempty" yaml:"description,omitempty"` Variables ServerVariables `json:"variables,omitempty" yaml:"variables,omitempty"` } From 04ac044b3a3959105d3294ef20333134ca1c418b Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Mon, 16 Mar 2026 18:07:23 +0200 Subject: [PATCH 04/19] chore: update yaml and yaml3 to fix panic on empty mapping in sequence Co-Authored-By: Claude Sonnet 4.6 --- go.mod | 4 ++-- go.sum | 4 ++++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/go.mod b/go.mod index ee9ffcf04..77ba18c8d 100644 --- a/go.mod +++ b/go.mod @@ -6,8 +6,8 @@ require ( github.com/go-openapi/jsonpointer v0.21.0 github.com/gorilla/mux v1.8.0 github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 - github.com/oasdiff/yaml v0.0.0-20260313112342-a3ea61cb4d4c - github.com/oasdiff/yaml3 v0.0.0-20260224194419-61cd415a242b + github.com/oasdiff/yaml v0.0.0-20260316160413-530022a25b2e + github.com/oasdiff/yaml3 v0.0.0-20260316155952-42d24df7b091 github.com/perimeterx/marshmallow v1.1.5 github.com/stretchr/testify v1.9.0 github.com/woodsbury/decimal128 v1.3.0 diff --git a/go.sum b/go.sum index ef7fb971d..e4013dd9a 100644 --- a/go.sum +++ b/go.sum @@ -20,8 +20,12 @@ github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 h1:RWengNIwukTxcDr9 github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826/go.mod h1:TaXosZuwdSHYgviHp1DAtfrULt5eUgsSMsZf+YrPgl8= github.com/oasdiff/yaml v0.0.0-20260313112342-a3ea61cb4d4c h1:7ACFcSaQsrWtrH4WHHfUqE1C+f8r2uv8KGaW0jTNjus= github.com/oasdiff/yaml v0.0.0-20260313112342-a3ea61cb4d4c/go.mod h1:JKox4Gszkxt57kj27u7rvi7IFoIULvCZHUsBTUmQM/s= +github.com/oasdiff/yaml v0.0.0-20260316160413-530022a25b2e h1:ggq8bceybJlAyeZNmQnWV1h04Nwcxq3P1CNKFIwzTmc= +github.com/oasdiff/yaml v0.0.0-20260316160413-530022a25b2e/go.mod h1:9BgjwzmYck7y58Uph7CTOIHpxrQyLLuWDiU29paDzNU= github.com/oasdiff/yaml3 v0.0.0-20260224194419-61cd415a242b h1:vivRhVUAa9t1q0Db4ZmezBP8pWQWnXHFokZj0AOea2g= github.com/oasdiff/yaml3 v0.0.0-20260224194419-61cd415a242b/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= +github.com/oasdiff/yaml3 v0.0.0-20260316155952-42d24df7b091 h1:9BhI2ddVLDF7hbq1NZNF7jZDjRGxBzLLCrpw349pV6o= +github.com/oasdiff/yaml3 v0.0.0-20260316155952-42d24df7b091/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= github.com/perimeterx/marshmallow v1.1.5 h1:a2LALqQ1BlHM8PZblsDdidgv1mWi1DgC2UmX50IvK2s= github.com/perimeterx/marshmallow v1.1.5/go.mod h1:dsXbUu8CRzfYP5a87xpp0xq9S3u0Vchtcl8we9tYaXw= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= From d256ed541308c1c40e94a8b36dd4236fa4bf39d5 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Mon, 16 Mar 2026 19:10:44 +0200 Subject: [PATCH 05/19] chore: update yaml and yaml3 to v0.0.0-20260316 Co-Authored-By: Claude Sonnet 4.6 --- go.mod | 4 ++-- go.sum | 12 ++++-------- 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/go.mod b/go.mod index 77ba18c8d..7f5af3a3b 100644 --- a/go.mod +++ b/go.mod @@ -6,8 +6,8 @@ require ( github.com/go-openapi/jsonpointer v0.21.0 github.com/gorilla/mux v1.8.0 github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 - github.com/oasdiff/yaml v0.0.0-20260316160413-530022a25b2e - github.com/oasdiff/yaml3 v0.0.0-20260316155952-42d24df7b091 + github.com/oasdiff/yaml v0.0.0-20260316 + github.com/oasdiff/yaml3 v0.0.0-20260316 github.com/perimeterx/marshmallow v1.1.5 github.com/stretchr/testify v1.9.0 github.com/woodsbury/decimal128 v1.3.0 diff --git a/go.sum b/go.sum index e4013dd9a..49b15e026 100644 --- a/go.sum +++ b/go.sum @@ -18,14 +18,10 @@ github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0 github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc= github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 h1:RWengNIwukTxcDr9M+97sNutRR1RKhG96O6jWumTTnw= github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826/go.mod h1:TaXosZuwdSHYgviHp1DAtfrULt5eUgsSMsZf+YrPgl8= -github.com/oasdiff/yaml v0.0.0-20260313112342-a3ea61cb4d4c h1:7ACFcSaQsrWtrH4WHHfUqE1C+f8r2uv8KGaW0jTNjus= -github.com/oasdiff/yaml v0.0.0-20260313112342-a3ea61cb4d4c/go.mod h1:JKox4Gszkxt57kj27u7rvi7IFoIULvCZHUsBTUmQM/s= -github.com/oasdiff/yaml v0.0.0-20260316160413-530022a25b2e h1:ggq8bceybJlAyeZNmQnWV1h04Nwcxq3P1CNKFIwzTmc= -github.com/oasdiff/yaml v0.0.0-20260316160413-530022a25b2e/go.mod h1:9BgjwzmYck7y58Uph7CTOIHpxrQyLLuWDiU29paDzNU= -github.com/oasdiff/yaml3 v0.0.0-20260224194419-61cd415a242b h1:vivRhVUAa9t1q0Db4ZmezBP8pWQWnXHFokZj0AOea2g= -github.com/oasdiff/yaml3 v0.0.0-20260224194419-61cd415a242b/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= -github.com/oasdiff/yaml3 v0.0.0-20260316155952-42d24df7b091 h1:9BhI2ddVLDF7hbq1NZNF7jZDjRGxBzLLCrpw349pV6o= -github.com/oasdiff/yaml3 v0.0.0-20260316155952-42d24df7b091/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= +github.com/oasdiff/yaml v0.0.0-20260316 h1:dJiu6PDGmIQHA/6lUXZiYkIR8QZqrkfiHH42l0ECDW8= +github.com/oasdiff/yaml v0.0.0-20260316/go.mod h1:QPkB/+RiVpYSW0K2LPN4dV4HX/kyajYlgO5LZoA6LZY= +github.com/oasdiff/yaml3 v0.0.0-20260316 h1:E5kcP7Xtg0l1RfDqAAFbNpwQf4AvRFq75LOlFDEg28g= +github.com/oasdiff/yaml3 v0.0.0-20260316/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= github.com/perimeterx/marshmallow v1.1.5 h1:a2LALqQ1BlHM8PZblsDdidgv1mWi1DgC2UmX50IvK2s= github.com/perimeterx/marshmallow v1.1.5/go.mod h1:dsXbUu8CRzfYP5a87xpp0xq9S3u0Vchtcl8we9tYaXw= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= From 322dd54a317520df73107decf81e144d85ce1a4d Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Mon, 16 Mar 2026 19:27:18 +0200 Subject: [PATCH 06/19] chore: update yaml and yaml3 to v0.0.1 Co-Authored-By: Claude Sonnet 4.6 --- go.mod | 4 ++-- go.sum | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/go.mod b/go.mod index 7f5af3a3b..f0a2122c1 100644 --- a/go.mod +++ b/go.mod @@ -6,8 +6,8 @@ require ( github.com/go-openapi/jsonpointer v0.21.0 github.com/gorilla/mux v1.8.0 github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 - github.com/oasdiff/yaml v0.0.0-20260316 - github.com/oasdiff/yaml3 v0.0.0-20260316 + github.com/oasdiff/yaml v0.0.1 + github.com/oasdiff/yaml3 v0.0.1 github.com/perimeterx/marshmallow v1.1.5 github.com/stretchr/testify v1.9.0 github.com/woodsbury/decimal128 v1.3.0 diff --git a/go.sum b/go.sum index 49b15e026..3c0f7628f 100644 --- a/go.sum +++ b/go.sum @@ -18,10 +18,10 @@ github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0 github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc= github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 h1:RWengNIwukTxcDr9M+97sNutRR1RKhG96O6jWumTTnw= github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826/go.mod h1:TaXosZuwdSHYgviHp1DAtfrULt5eUgsSMsZf+YrPgl8= -github.com/oasdiff/yaml v0.0.0-20260316 h1:dJiu6PDGmIQHA/6lUXZiYkIR8QZqrkfiHH42l0ECDW8= -github.com/oasdiff/yaml v0.0.0-20260316/go.mod h1:QPkB/+RiVpYSW0K2LPN4dV4HX/kyajYlgO5LZoA6LZY= -github.com/oasdiff/yaml3 v0.0.0-20260316 h1:E5kcP7Xtg0l1RfDqAAFbNpwQf4AvRFq75LOlFDEg28g= -github.com/oasdiff/yaml3 v0.0.0-20260316/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= +github.com/oasdiff/yaml v0.0.1 h1:dPrn0F2PJ7HdzHPndJkArvB2Fw0cwgFdVUKCEkoFuds= +github.com/oasdiff/yaml v0.0.1/go.mod h1:r8bgVgpWT5iIN/AgP0GljFvB6CicK+yL1nIAbm+8/QQ= +github.com/oasdiff/yaml3 v0.0.1 h1:kReOSraQLTxuuGNX9aNeJ7tcsvUB2MS+iupdUrWe4Z0= +github.com/oasdiff/yaml3 v0.0.1/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= github.com/perimeterx/marshmallow v1.1.5 h1:a2LALqQ1BlHM8PZblsDdidgv1mWi1DgC2UmX50IvK2s= github.com/perimeterx/marshmallow v1.1.5/go.mod h1:dsXbUu8CRzfYP5a87xpp0xq9S3u0Vchtcl8we9tYaXw= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= From a9c7141745663520e612ec8133e206d0a10a34bd Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Mon, 16 Mar 2026 21:20:54 +0200 Subject: [PATCH 07/19] fix: rename module path to github.com/oasdiff/kin-openapi Allows consumers to depend on this fork directly without a replace directive, fixing go install failures (oasdiff/oasdiff#810). Co-Authored-By: Claude Sonnet 4.6 --- .github/docs/openapi2.txt | 2 +- .github/docs/openapi2conv.txt | 2 +- .github/docs/openapi3.txt | 2 +- .github/docs/openapi3filter.txt | 2 +- .github/docs/openapi3gen.txt | 2 +- .github/docs/routers.txt | 2 +- .github/docs/routers_gorillamux.txt | 2 +- .github/docs/routers_legacy.txt | 2 +- .github/docs/routers_legacy_pathpattern.txt | 2 +- README.md | 3 +++ cmd/validate/main.go | 6 +++--- go.mod | 2 +- openapi2/marsh.go | 2 +- openapi2/openapi2.go | 2 +- openapi2/openapi2_test.go | 2 +- openapi2/operation.go | 2 +- openapi2/parameter.go | 2 +- openapi2/path_item.go | 2 +- openapi2/response.go | 2 +- openapi2/schema.go | 4 ++-- openapi2/security_scheme.go | 2 +- openapi2conv/issue1016_test.go | 2 +- openapi2conv/issue1069_test.go | 4 ++-- openapi2conv/issue1091_test.go | 2 +- openapi2conv/issue187_test.go | 4 ++-- openapi2conv/issue440_test.go | 4 ++-- openapi2conv/issue979_test.go | 4 ++-- openapi2conv/openapi2_conv.go | 4 ++-- openapi2conv/openapi2_conv_test.go | 4 ++-- openapi3/additionalProperties_test.go | 2 +- openapi3/example_refs_test.go | 2 +- openapi3/issue241_test.go | 2 +- openapi3/issue513_test.go | 2 +- openapi3/issue594_test.go | 2 +- openapi3/issue615_test.go | 2 +- openapi3/issue652_test.go | 2 +- openapi3/issue657_test.go | 2 +- openapi3/issue689_test.go | 2 +- openapi3/issue735_test.go | 2 +- openapi3/issue767_test.go | 2 +- openapi3/issue883_test.go | 2 +- openapi3/load_cicular_ref_with_external_file_test.go | 2 +- openapi3/load_with_go_embed_test.go | 2 +- openapi3/marsh.go | 2 +- openapi3/race_test.go | 2 +- openapi3/schema.go | 4 ++-- openapi3/schema_validation_settings_test.go | 2 +- openapi3/unique_items_checker_test.go | 2 +- openapi3/validation_issue409_test.go | 2 +- openapi3filter/authentication_input.go | 2 +- openapi3filter/csv_file_upload_test.go | 6 +++--- openapi3filter/errors.go | 2 +- openapi3filter/issue1045_test.go | 4 ++-- openapi3filter/issue1110_test.go | 4 ++-- openapi3filter/issue201_test.go | 4 ++-- openapi3filter/issue267_test.go | 4 ++-- openapi3filter/issue436_test.go | 6 +++--- openapi3filter/issue624_test.go | 4 ++-- openapi3filter/issue625_test.go | 6 +++--- openapi3filter/issue639_test.go | 4 ++-- openapi3filter/issue641_test.go | 6 +++--- openapi3filter/issue689_test.go | 4 ++-- openapi3filter/issue707_test.go | 4 ++-- openapi3filter/issue722_test.go | 6 +++--- openapi3filter/issue733_test.go | 6 +++--- openapi3filter/issue743_test.go | 10 +++++----- openapi3filter/issue789_test.go | 6 +++--- openapi3filter/issue884_test.go | 4 ++-- openapi3filter/issue949_test.go | 6 +++--- openapi3filter/middleware.go | 2 +- openapi3filter/middleware_test.go | 6 +++--- openapi3filter/options.go | 2 +- openapi3filter/options_test.go | 6 +++--- openapi3filter/req_resp_decoder.go | 2 +- openapi3filter/req_resp_decoder_test.go | 4 ++-- openapi3filter/testdata/issue1100_test.go | 6 +++--- openapi3filter/unpack_errors_test.go | 6 +++--- openapi3filter/upload_arbitrary_file_test.go | 6 +++--- openapi3filter/validate_readonly_test.go | 4 ++-- openapi3filter/validate_request.go | 2 +- openapi3filter/validate_request_example_test.go | 4 ++-- openapi3filter/validate_request_input.go | 4 ++-- openapi3filter/validate_request_test.go | 8 ++++---- openapi3filter/validate_response.go | 2 +- openapi3filter/validate_response_test.go | 2 +- openapi3filter/validate_set_default_test.go | 4 ++-- openapi3filter/validation_discriminator_test.go | 4 ++-- openapi3filter/validation_enum_test.go | 4 ++-- openapi3filter/validation_error_encoder.go | 4 ++-- openapi3filter/validation_error_test.go | 4 ++-- openapi3filter/validation_handler.go | 6 +++--- openapi3filter/validation_test.go | 4 ++-- openapi3filter/zip_file_upload_test.go | 6 +++--- openapi3gen/openapi3gen.go | 2 +- openapi3gen/openapi3gen_newschemarefforvalue_test.go | 6 +++--- openapi3gen/openapi3gen_test.go | 6 +++--- openapi3gen/simple_test.go | 2 +- routers/gorillamux/example_test.go | 6 +++--- routers/gorillamux/router.go | 6 +++--- routers/gorillamux/router_test.go | 4 ++-- routers/issue356_test.go | 10 +++++----- routers/legacy/issue444_test.go | 6 +++--- routers/legacy/router.go | 6 +++--- routers/legacy/router_test.go | 4 ++-- routers/legacy/validate_request_test.go | 6 +++--- routers/types.go | 2 +- 106 files changed, 194 insertions(+), 191 deletions(-) diff --git a/.github/docs/openapi2.txt b/.github/docs/openapi2.txt index 9025f5a83..37119d136 100644 --- a/.github/docs/openapi2.txt +++ b/.github/docs/openapi2.txt @@ -1,4 +1,4 @@ -package openapi2 // import "github.com/getkin/kin-openapi/openapi2" +package openapi2 // import "github.com/oasdiff/kin-openapi/openapi2" Package openapi2 parses and writes OpenAPIv2 specification documents. diff --git a/.github/docs/openapi2conv.txt b/.github/docs/openapi2conv.txt index e24925aa3..1a076b72c 100644 --- a/.github/docs/openapi2conv.txt +++ b/.github/docs/openapi2conv.txt @@ -1,4 +1,4 @@ -package openapi2conv // import "github.com/getkin/kin-openapi/openapi2conv" +package openapi2conv // import "github.com/oasdiff/kin-openapi/openapi2conv" Package openapi2conv converts an OpenAPI v2 specification document to v3. diff --git a/.github/docs/openapi3.txt b/.github/docs/openapi3.txt index a8ec46977..0dcd86f21 100644 --- a/.github/docs/openapi3.txt +++ b/.github/docs/openapi3.txt @@ -1,4 +1,4 @@ -package openapi3 // import "github.com/getkin/kin-openapi/openapi3" +package openapi3 // import "github.com/oasdiff/kin-openapi/openapi3" Package openapi3 parses and writes OpenAPI 3 specification documents. diff --git a/.github/docs/openapi3filter.txt b/.github/docs/openapi3filter.txt index 2239377e6..018b90637 100644 --- a/.github/docs/openapi3filter.txt +++ b/.github/docs/openapi3filter.txt @@ -1,4 +1,4 @@ -package openapi3filter // import "github.com/getkin/kin-openapi/openapi3filter" +package openapi3filter // import "github.com/oasdiff/kin-openapi/openapi3filter" Package openapi3filter validates that requests and inputs request an OpenAPI 3 specification file. diff --git a/.github/docs/openapi3gen.txt b/.github/docs/openapi3gen.txt index e8543a47d..d506da61f 100644 --- a/.github/docs/openapi3gen.txt +++ b/.github/docs/openapi3gen.txt @@ -1,4 +1,4 @@ -package openapi3gen // import "github.com/getkin/kin-openapi/openapi3gen" +package openapi3gen // import "github.com/oasdiff/kin-openapi/openapi3gen" Package openapi3gen generates OpenAPIv3 JSON schemas from Go types. diff --git a/.github/docs/routers.txt b/.github/docs/routers.txt index e2605a80a..126290de5 100644 --- a/.github/docs/routers.txt +++ b/.github/docs/routers.txt @@ -1,4 +1,4 @@ -package routers // import "github.com/getkin/kin-openapi/routers" +package routers // import "github.com/oasdiff/kin-openapi/routers" VARIABLES diff --git a/.github/docs/routers_gorillamux.txt b/.github/docs/routers_gorillamux.txt index a7c8a8ec4..01f4b8300 100644 --- a/.github/docs/routers_gorillamux.txt +++ b/.github/docs/routers_gorillamux.txt @@ -1,4 +1,4 @@ -package gorillamux // import "github.com/getkin/kin-openapi/routers/gorillamux" +package gorillamux // import "github.com/oasdiff/kin-openapi/routers/gorillamux" Package gorillamux implements a router. diff --git a/.github/docs/routers_legacy.txt b/.github/docs/routers_legacy.txt index 9082e9304..2059cade7 100644 --- a/.github/docs/routers_legacy.txt +++ b/.github/docs/routers_legacy.txt @@ -1,4 +1,4 @@ -package legacy // import "github.com/getkin/kin-openapi/routers/legacy" +package legacy // import "github.com/oasdiff/kin-openapi/routers/legacy" Package legacy implements a router. diff --git a/.github/docs/routers_legacy_pathpattern.txt b/.github/docs/routers_legacy_pathpattern.txt index db79f7ac7..a9832c6f0 100644 --- a/.github/docs/routers_legacy_pathpattern.txt +++ b/.github/docs/routers_legacy_pathpattern.txt @@ -1,4 +1,4 @@ -package pathpattern // import "github.com/getkin/kin-openapi/routers/legacy/pathpattern" +package pathpattern // import "github.com/oasdiff/kin-openapi/routers/legacy/pathpattern" Package pathpattern implements path matching. diff --git a/README.md b/README.md index 6f37ae89b..9fccac897 100644 --- a/README.md +++ b/README.md @@ -294,6 +294,9 @@ for _, path := range doc.Paths.InMatchingOrder() { ## CHANGELOG: Sub-v1 breaking API changes +### v0.136.0 +* Module renamed from `github.com/getkin/kin-openapi` to `github.com/oasdiff/kin-openapi`. Update all imports accordingly: `openapi2`, `openapi2conv`, `openapi3`, `openapi3filter`, `openapi3gen`, `routers`, `routers/gorillamux`, `routers/legacy`, `routers/legacy/pathpattern` + ### v0.135.0 * `openapi3.MediaType.Encoding` field type changed from `map[string]*Encoding` to `Encodings` * `openapi3.Server.Variables` field type changed from `map[string]*ServerVariable` to `ServerVariables` diff --git a/cmd/validate/main.go b/cmd/validate/main.go index 751940708..2cbba19ac 100644 --- a/cmd/validate/main.go +++ b/cmd/validate/main.go @@ -8,8 +8,8 @@ import ( "github.com/oasdiff/yaml" - "github.com/getkin/kin-openapi/openapi2" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi2" + "github.com/oasdiff/kin-openapi/openapi3" ) var ( @@ -36,7 +36,7 @@ func main() { flag.Parse() filename := flag.Arg(0) if len(flag.Args()) != 1 || filename == "" { - log.Fatalf("Usage: go run github.com/getkin/kin-openapi/cmd/validate@latest [--circular] [--defaults] [--examples] [--ext] [--patterns] -- \nGot: %+v\n", os.Args) + log.Fatalf("Usage: go run github.com/oasdiff/kin-openapi/cmd/validate@latest [--circular] [--defaults] [--examples] [--ext] [--patterns] -- \nGot: %+v\n", os.Args) } data, err := os.ReadFile(filename) diff --git a/go.mod b/go.mod index f0a2122c1..dfcf8db82 100644 --- a/go.mod +++ b/go.mod @@ -1,4 +1,4 @@ -module github.com/getkin/kin-openapi +module github.com/oasdiff/kin-openapi go 1.22.5 diff --git a/openapi2/marsh.go b/openapi2/marsh.go index 1745734b1..4ef55bef1 100644 --- a/openapi2/marsh.go +++ b/openapi2/marsh.go @@ -19,7 +19,7 @@ func unmarshalError(jsonUnmarshalErr error) error { func unmarshal(data []byte, v any) error { var jsonErr, yamlErr error - // See https://github.com/getkin/kin-openapi/issues/680 + // See https://github.com/oasdiff/kin-openapi/issues/680 if jsonErr = json.Unmarshal(data, v); jsonErr == nil { return nil } diff --git a/openapi2/openapi2.go b/openapi2/openapi2.go index bd3375339..825963fc8 100644 --- a/openapi2/openapi2.go +++ b/openapi2/openapi2.go @@ -3,7 +3,7 @@ package openapi2 import ( "encoding/json" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) // T is the root of an OpenAPI v2 document diff --git a/openapi2/openapi2_test.go b/openapi2/openapi2_test.go index d1b3aa56a..9d545b16f 100644 --- a/openapi2/openapi2_test.go +++ b/openapi2/openapi2_test.go @@ -8,7 +8,7 @@ import ( "github.com/oasdiff/yaml" - "github.com/getkin/kin-openapi/openapi2" + "github.com/oasdiff/kin-openapi/openapi2" ) func Example() { diff --git a/openapi2/operation.go b/openapi2/operation.go index 64f10d1f1..e7d811034 100644 --- a/openapi2/operation.go +++ b/openapi2/operation.go @@ -3,7 +3,7 @@ package openapi2 import ( "encoding/json" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) type Operation struct { diff --git a/openapi2/parameter.go b/openapi2/parameter.go index 7f2bddb2c..084248461 100644 --- a/openapi2/parameter.go +++ b/openapi2/parameter.go @@ -4,7 +4,7 @@ import ( "encoding/json" "sort" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) type Parameters []*Parameter diff --git a/openapi2/path_item.go b/openapi2/path_item.go index 624cc74dc..84a71240c 100644 --- a/openapi2/path_item.go +++ b/openapi2/path_item.go @@ -5,7 +5,7 @@ import ( "fmt" "net/http" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) type PathItem struct { diff --git a/openapi2/response.go b/openapi2/response.go index 3a2983ce1..850d876b5 100644 --- a/openapi2/response.go +++ b/openapi2/response.go @@ -3,7 +3,7 @@ package openapi2 import ( "encoding/json" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) type Response struct { diff --git a/openapi2/schema.go b/openapi2/schema.go index 64bed2751..08fd6e522 100644 --- a/openapi2/schema.go +++ b/openapi2/schema.go @@ -4,7 +4,7 @@ import ( "encoding/json" "strings" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) type ( @@ -260,7 +260,7 @@ func (schema *Schema) UnmarshalJSON(data []byte) error { *schema = Schema(x) if schema.Format == "date" { - // This is a fix for: https://github.com/getkin/kin-openapi/issues/697 + // This is a fix for: https://github.com/oasdiff/kin-openapi/issues/697 if eg, ok := schema.Example.(string); ok { schema.Example = strings.TrimSuffix(eg, "T00:00:00Z") } diff --git a/openapi2/security_scheme.go b/openapi2/security_scheme.go index cd6e6a5dd..01aff19ce 100644 --- a/openapi2/security_scheme.go +++ b/openapi2/security_scheme.go @@ -3,7 +3,7 @@ package openapi2 import ( "encoding/json" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) type SecurityRequirements []map[string][]string diff --git a/openapi2conv/issue1016_test.go b/openapi2conv/issue1016_test.go index acd87d077..7e979003f 100644 --- a/openapi2conv/issue1016_test.go +++ b/openapi2conv/issue1016_test.go @@ -5,7 +5,7 @@ import ( "encoding/json" "testing" - "github.com/getkin/kin-openapi/openapi2" + "github.com/oasdiff/kin-openapi/openapi2" "github.com/stretchr/testify/require" ) diff --git a/openapi2conv/issue1069_test.go b/openapi2conv/issue1069_test.go index f7bb8bcdc..b34ca76d8 100644 --- a/openapi2conv/issue1069_test.go +++ b/openapi2conv/issue1069_test.go @@ -4,8 +4,8 @@ import ( "context" "testing" - "github.com/getkin/kin-openapi/openapi2" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi2" + "github.com/oasdiff/kin-openapi/openapi3" "github.com/oasdiff/yaml" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" diff --git a/openapi2conv/issue1091_test.go b/openapi2conv/issue1091_test.go index bf3e1864d..dfc453e31 100644 --- a/openapi2conv/issue1091_test.go +++ b/openapi2conv/issue1091_test.go @@ -6,7 +6,7 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi2" + "github.com/oasdiff/kin-openapi/openapi2" ) func TestIssue1091_PropertyExtensions(t *testing.T) { diff --git a/openapi2conv/issue187_test.go b/openapi2conv/issue187_test.go index 4cec87532..5274e7a53 100644 --- a/openapi2conv/issue187_test.go +++ b/openapi2conv/issue187_test.go @@ -8,8 +8,8 @@ import ( "github.com/oasdiff/yaml" "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi2" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi2" + "github.com/oasdiff/kin-openapi/openapi3" ) func v2v3JSON(spec2 []byte) (doc3 *openapi3.T, err error) { diff --git a/openapi2conv/issue440_test.go b/openapi2conv/issue440_test.go index 5c9f67dc0..3fa3d6825 100644 --- a/openapi2conv/issue440_test.go +++ b/openapi2conv/issue440_test.go @@ -8,8 +8,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi2" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi2" + "github.com/oasdiff/kin-openapi/openapi3" ) func TestIssue440(t *testing.T) { diff --git a/openapi2conv/issue979_test.go b/openapi2conv/issue979_test.go index 8d87902c9..93db47f0c 100644 --- a/openapi2conv/issue979_test.go +++ b/openapi2conv/issue979_test.go @@ -7,8 +7,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi2" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi2" + "github.com/oasdiff/kin-openapi/openapi3" ) func TestIssue979(t *testing.T) { diff --git a/openapi2conv/openapi2_conv.go b/openapi2conv/openapi2_conv.go index e50e15186..478d44695 100644 --- a/openapi2conv/openapi2_conv.go +++ b/openapi2conv/openapi2_conv.go @@ -7,8 +7,8 @@ import ( "sort" "strings" - "github.com/getkin/kin-openapi/openapi2" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi2" + "github.com/oasdiff/kin-openapi/openapi3" ) // ToV3 converts an OpenAPIv2 spec to an OpenAPIv3 spec diff --git a/openapi2conv/openapi2_conv_test.go b/openapi2conv/openapi2_conv_test.go index ce3423787..4c54fa3a3 100644 --- a/openapi2conv/openapi2_conv_test.go +++ b/openapi2conv/openapi2_conv_test.go @@ -7,8 +7,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi2" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi2" + "github.com/oasdiff/kin-openapi/openapi3" ) func TestConvOpenAPIV3ToV2(t *testing.T) { diff --git a/openapi3/additionalProperties_test.go b/openapi3/additionalProperties_test.go index 46cf0dbe8..41a64c841 100644 --- a/openapi3/additionalProperties_test.go +++ b/openapi3/additionalProperties_test.go @@ -9,7 +9,7 @@ import ( "github.com/oasdiff/yaml3" "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) func TestMarshalAdditionalProperties(t *testing.T) { diff --git a/openapi3/example_refs_test.go b/openapi3/example_refs_test.go index b2f36e3ea..be6d4943f 100644 --- a/openapi3/example_refs_test.go +++ b/openapi3/example_refs_test.go @@ -3,7 +3,7 @@ package openapi3_test import ( "testing" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" "github.com/stretchr/testify/require" ) diff --git a/openapi3/issue241_test.go b/openapi3/issue241_test.go index 9a643ede4..3babc43ef 100644 --- a/openapi3/issue241_test.go +++ b/openapi3/issue241_test.go @@ -8,7 +8,7 @@ import ( "github.com/oasdiff/yaml3" "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) func TestIssue241(t *testing.T) { diff --git a/openapi3/issue513_test.go b/openapi3/issue513_test.go index 38454f672..248cdbaaa 100644 --- a/openapi3/issue513_test.go +++ b/openapi3/issue513_test.go @@ -34,7 +34,7 @@ paths: `[1:]) // When that site fails to respond: - // see https://github.com/getkin/kin-openapi/issues/495 + // see https://github.com/oasdiff/kin-openapi/issues/495 // http://schemas.sentex.io/store/categories.json // { diff --git a/openapi3/issue594_test.go b/openapi3/issue594_test.go index 42bc7e797..df11052c8 100644 --- a/openapi3/issue594_test.go +++ b/openapi3/issue594_test.go @@ -6,7 +6,7 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) func TestIssue594(t *testing.T) { diff --git a/openapi3/issue615_test.go b/openapi3/issue615_test.go index 02532bb5a..992a88e49 100644 --- a/openapi3/issue615_test.go +++ b/openapi3/issue615_test.go @@ -5,7 +5,7 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) func TestIssue615(t *testing.T) { diff --git a/openapi3/issue652_test.go b/openapi3/issue652_test.go index 738569a4b..a75a13c45 100644 --- a/openapi3/issue652_test.go +++ b/openapi3/issue652_test.go @@ -6,7 +6,7 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) func TestIssue652(t *testing.T) { diff --git a/openapi3/issue657_test.go b/openapi3/issue657_test.go index a745e5606..7bb610a50 100644 --- a/openapi3/issue657_test.go +++ b/openapi3/issue657_test.go @@ -5,7 +5,7 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) func TestOneOf_Warning_Errors(t *testing.T) { diff --git a/openapi3/issue689_test.go b/openapi3/issue689_test.go index b7479f9f4..3963e5e1f 100644 --- a/openapi3/issue689_test.go +++ b/openapi3/issue689_test.go @@ -5,7 +5,7 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) func TestIssue689(t *testing.T) { diff --git a/openapi3/issue735_test.go b/openapi3/issue735_test.go index eb57ab896..1b02dc404 100644 --- a/openapi3/issue735_test.go +++ b/openapi3/issue735_test.go @@ -155,7 +155,7 @@ func TestIssue735(t *testing.T) { value: map[string]any{"foo": 42}, extraNotContains: []any{42}, }, - // TODO: uncomment when https://github.com/getkin/kin-openapi/issues/502 is fixed + // TODO: uncomment when https://github.com/oasdiff/kin-openapi/issues/502 is fixed //{ // name: "read only properties", // schema: NewSchema().WithProperties(map[string]*Schema{ diff --git a/openapi3/issue767_test.go b/openapi3/issue767_test.go index 04fd9d03f..54b4f947d 100644 --- a/openapi3/issue767_test.go +++ b/openapi3/issue767_test.go @@ -5,7 +5,7 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) func TestIssue767(t *testing.T) { diff --git a/openapi3/issue883_test.go b/openapi3/issue883_test.go index 7609e6ac3..eea90f103 100644 --- a/openapi3/issue883_test.go +++ b/openapi3/issue883_test.go @@ -7,7 +7,7 @@ import ( yamlv3 "github.com/oasdiff/yaml3" "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) func TestIssue883(t *testing.T) { diff --git a/openapi3/load_cicular_ref_with_external_file_test.go b/openapi3/load_cicular_ref_with_external_file_test.go index cff5c01fe..69c76f2a1 100644 --- a/openapi3/load_cicular_ref_with_external_file_test.go +++ b/openapi3/load_cicular_ref_with_external_file_test.go @@ -11,7 +11,7 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) //go:embed testdata/circularRef/* diff --git a/openapi3/load_with_go_embed_test.go b/openapi3/load_with_go_embed_test.go index 27b46b29f..374d4025b 100644 --- a/openapi3/load_with_go_embed_test.go +++ b/openapi3/load_with_go_embed_test.go @@ -8,7 +8,7 @@ import ( "fmt" "net/url" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) //go:embed testdata/recursiveRef/* diff --git a/openapi3/marsh.go b/openapi3/marsh.go index 657862f5a..0299a34a4 100644 --- a/openapi3/marsh.go +++ b/openapi3/marsh.go @@ -20,7 +20,7 @@ func unmarshalError(jsonUnmarshalErr error) error { func unmarshal(data []byte, v any, includeOrigin bool, location *url.URL) error { var jsonErr, yamlErr error - // See https://github.com/getkin/kin-openapi/issues/680 + // See https://github.com/oasdiff/kin-openapi/issues/680 if jsonErr = json.Unmarshal(data, v); jsonErr == nil { return nil } diff --git a/openapi3/race_test.go b/openapi3/race_test.go index 405942520..907ee65c2 100644 --- a/openapi3/race_test.go +++ b/openapi3/race_test.go @@ -6,7 +6,7 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) func TestRaceyPatternSchemaValidateHindersIt(t *testing.T) { diff --git a/openapi3/schema.go b/openapi3/schema.go index 9ccba3891..954c4c144 100644 --- a/openapi3/schema.go +++ b/openapi3/schema.go @@ -476,7 +476,7 @@ func (schema *Schema) UnmarshalJSON(data []byte) error { schema.Example = stripOriginFromAny(schema.Example) if schema.Format == "date" { - // This is a fix for: https://github.com/getkin/kin-openapi/issues/697 + // This is a fix for: https://github.com/oasdiff/kin-openapi/issues/697 if eg, ok := schema.Example.(string); ok { schema.Example = strings.TrimSuffix(eg, "T00:00:00Z") } @@ -1211,7 +1211,7 @@ func (schema *Schema) visitJSON(settings *schemaValidationSettings, value any) ( return schema.visitJSONArray(settings, value) case map[string]any: return schema.visitJSONObject(settings, value) - case map[any]any: // for YAML cf. issue https://github.com/getkin/kin-openapi/issues/444 + case map[any]any: // for YAML cf. issue https://github.com/oasdiff/kin-openapi/issues/444 values := make(map[string]any, len(value)) for key, v := range value { if k, ok := key.(string); ok { diff --git a/openapi3/schema_validation_settings_test.go b/openapi3/schema_validation_settings_test.go index db52d3bdf..cc1100dc5 100644 --- a/openapi3/schema_validation_settings_test.go +++ b/openapi3/schema_validation_settings_test.go @@ -3,7 +3,7 @@ package openapi3_test import ( "fmt" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) func ExampleSetSchemaErrorMessageCustomizer() { diff --git a/openapi3/unique_items_checker_test.go b/openapi3/unique_items_checker_test.go index 1c81180b4..7599cde11 100644 --- a/openapi3/unique_items_checker_test.go +++ b/openapi3/unique_items_checker_test.go @@ -5,7 +5,7 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) func TestRegisterArrayUniqueItemsChecker(t *testing.T) { diff --git a/openapi3/validation_issue409_test.go b/openapi3/validation_issue409_test.go index 561594fca..cc522823a 100644 --- a/openapi3/validation_issue409_test.go +++ b/openapi3/validation_issue409_test.go @@ -6,7 +6,7 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) func TestIssue409PatternIgnored(t *testing.T) { diff --git a/openapi3filter/authentication_input.go b/openapi3filter/authentication_input.go index a53484b99..6ad34b4a1 100644 --- a/openapi3filter/authentication_input.go +++ b/openapi3filter/authentication_input.go @@ -3,7 +3,7 @@ package openapi3filter import ( "fmt" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) type AuthenticationInput struct { diff --git a/openapi3filter/csv_file_upload_test.go b/openapi3filter/csv_file_upload_test.go index 89efb96d9..c3e83beab 100644 --- a/openapi3filter/csv_file_upload_test.go +++ b/openapi3filter/csv_file_upload_test.go @@ -12,9 +12,9 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestValidateCsvFileUpload(t *testing.T) { diff --git a/openapi3filter/errors.go b/openapi3filter/errors.go index ea7c7c312..61a2b2ff0 100644 --- a/openapi3filter/errors.go +++ b/openapi3filter/errors.go @@ -4,7 +4,7 @@ import ( "bytes" "fmt" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) var _ error = &RequestError{} diff --git a/openapi3filter/issue1045_test.go b/openapi3filter/issue1045_test.go index 048dbd374..fa084b47d 100644 --- a/openapi3filter/issue1045_test.go +++ b/openapi3filter/issue1045_test.go @@ -7,8 +7,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestIssue1045(t *testing.T) { diff --git a/openapi3filter/issue1110_test.go b/openapi3filter/issue1110_test.go index a3dfb475f..b821b578b 100644 --- a/openapi3filter/issue1110_test.go +++ b/openapi3filter/issue1110_test.go @@ -7,8 +7,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestIssue1110(t *testing.T) { diff --git a/openapi3filter/issue201_test.go b/openapi3filter/issue201_test.go index ec0b2a1f1..dcc0c5ac9 100644 --- a/openapi3filter/issue201_test.go +++ b/openapi3filter/issue201_test.go @@ -9,8 +9,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestIssue201(t *testing.T) { diff --git a/openapi3filter/issue267_test.go b/openapi3filter/issue267_test.go index 44e0cab10..907a90f75 100644 --- a/openapi3filter/issue267_test.go +++ b/openapi3filter/issue267_test.go @@ -7,8 +7,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestIssue267(t *testing.T) { diff --git a/openapi3filter/issue436_test.go b/openapi3filter/issue436_test.go index fa106c5a1..f8ff942c3 100644 --- a/openapi3filter/issue436_test.go +++ b/openapi3filter/issue436_test.go @@ -9,9 +9,9 @@ import ( "net/textproto" "strings" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func Example_validateMultipartFormData() { diff --git a/openapi3filter/issue624_test.go b/openapi3filter/issue624_test.go index 1fdbdea34..c5c402969 100644 --- a/openapi3filter/issue624_test.go +++ b/openapi3filter/issue624_test.go @@ -6,8 +6,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestIssue624(t *testing.T) { diff --git a/openapi3filter/issue625_test.go b/openapi3filter/issue625_test.go index d92906457..6cbed8114 100644 --- a/openapi3filter/issue625_test.go +++ b/openapi3filter/issue625_test.go @@ -7,9 +7,9 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestIssue625(t *testing.T) { diff --git a/openapi3filter/issue639_test.go b/openapi3filter/issue639_test.go index 136967953..3482dc6d1 100644 --- a/openapi3filter/issue639_test.go +++ b/openapi3filter/issue639_test.go @@ -9,8 +9,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestIssue639(t *testing.T) { diff --git a/openapi3filter/issue641_test.go b/openapi3filter/issue641_test.go index 845e3f7e1..ed565d18c 100644 --- a/openapi3filter/issue641_test.go +++ b/openapi3filter/issue641_test.go @@ -7,9 +7,9 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestIssue641(t *testing.T) { diff --git a/openapi3filter/issue689_test.go b/openapi3filter/issue689_test.go index 592d53f74..08512b209 100644 --- a/openapi3filter/issue689_test.go +++ b/openapi3filter/issue689_test.go @@ -8,8 +8,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestIssue689(t *testing.T) { diff --git a/openapi3filter/issue707_test.go b/openapi3filter/issue707_test.go index a7cbc39ed..b884a2f72 100644 --- a/openapi3filter/issue707_test.go +++ b/openapi3filter/issue707_test.go @@ -7,8 +7,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestIssue707(t *testing.T) { diff --git a/openapi3filter/issue722_test.go b/openapi3filter/issue722_test.go index 73648e0fe..ba8d0ce48 100644 --- a/openapi3filter/issue722_test.go +++ b/openapi3filter/issue722_test.go @@ -10,9 +10,9 @@ import ( "strings" "testing" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestValidateMultipartFormDataContainingAllOf(t *testing.T) { diff --git a/openapi3filter/issue733_test.go b/openapi3filter/issue733_test.go index f43a826e8..9810ab958 100644 --- a/openapi3filter/issue733_test.go +++ b/openapi3filter/issue733_test.go @@ -12,9 +12,9 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestIntMax(t *testing.T) { diff --git a/openapi3filter/issue743_test.go b/openapi3filter/issue743_test.go index 24122e104..60f079ed2 100644 --- a/openapi3filter/issue743_test.go +++ b/openapi3filter/issue743_test.go @@ -9,9 +9,9 @@ import ( "strings" "testing" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/gorillamux" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" ) @@ -72,7 +72,7 @@ security: AuthenticationFunc: func(ctx context.Context, ai *openapi3filter.AuthenticationInput) error { defer req.Body.Close() - // NOTE that reading from `req.Body` appears to trigger the underlying issue raised in https://github.com/getkin/kin-openapi/issues/743 + // NOTE that reading from `req.Body` appears to trigger the underlying issue raised in https://github.com/oasdiff/kin-openapi/issues/743 // this doesn't seem to occur when using `req.GetBody()`, but as that's less common to do, we should support both types body, err := io.ReadAll(ai.RequestValidationInput.Request.Body) assert.NoError(t, err) @@ -131,7 +131,7 @@ security: authenticatorFunc := func(ctx context.Context, ai *openapi3filter.AuthenticationInput) error { defer ai.RequestValidationInput.Request.Body.Close() - // NOTE that reading from `req.Body` appears to trigger the underlying issue raised in https://github.com/getkin/kin-openapi/issues/743 + // NOTE that reading from `req.Body` appears to trigger the underlying issue raised in https://github.com/oasdiff/kin-openapi/issues/743 // this doesn't seem to occur when using `req.GetBody()`, but as that's less common to do, we should support both types body, err := io.ReadAll(ai.RequestValidationInput.Request.Body) assert.NoError(t, err) diff --git a/openapi3filter/issue789_test.go b/openapi3filter/issue789_test.go index 79d471849..96fbd12f2 100644 --- a/openapi3filter/issue789_test.go +++ b/openapi3filter/issue789_test.go @@ -7,9 +7,9 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestIssue789(t *testing.T) { diff --git a/openapi3filter/issue884_test.go b/openapi3filter/issue884_test.go index ea6e461c0..e91a0811a 100644 --- a/openapi3filter/issue884_test.go +++ b/openapi3filter/issue884_test.go @@ -8,8 +8,8 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestIssue884(t *testing.T) { diff --git a/openapi3filter/issue949_test.go b/openapi3filter/issue949_test.go index f87fae378..0a5535dbe 100644 --- a/openapi3filter/issue949_test.go +++ b/openapi3filter/issue949_test.go @@ -12,9 +12,9 @@ import ( "strings" "testing" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/gorillamux" "github.com/stretchr/testify/require" ) diff --git a/openapi3filter/middleware.go b/openapi3filter/middleware.go index d20889ed9..da3bbef1c 100644 --- a/openapi3filter/middleware.go +++ b/openapi3filter/middleware.go @@ -7,7 +7,7 @@ import ( "log" "net/http" - "github.com/getkin/kin-openapi/routers" + "github.com/oasdiff/kin-openapi/routers" ) // Validator provides HTTP request and response validation middleware. diff --git a/openapi3filter/middleware_test.go b/openapi3filter/middleware_test.go index d492bec0c..711fed1f7 100644 --- a/openapi3filter/middleware_test.go +++ b/openapi3filter/middleware_test.go @@ -16,9 +16,9 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) const validatorSpec = ` diff --git a/openapi3filter/options.go b/openapi3filter/options.go index b85f932b2..9520eb7c2 100644 --- a/openapi3filter/options.go +++ b/openapi3filter/options.go @@ -1,6 +1,6 @@ package openapi3filter -import "github.com/getkin/kin-openapi/openapi3" +import "github.com/oasdiff/kin-openapi/openapi3" // Options used by ValidateRequest and ValidateResponse type Options struct { diff --git a/openapi3filter/options_test.go b/openapi3filter/options_test.go index fd19329ff..8f4165638 100644 --- a/openapi3filter/options_test.go +++ b/openapi3filter/options_test.go @@ -6,9 +6,9 @@ import ( "net/http" "strings" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func ExampleOptions_WithCustomSchemaErrorFunc() { diff --git a/openapi3filter/req_resp_decoder.go b/openapi3filter/req_resp_decoder.go index 3e71a8735..03543e306 100644 --- a/openapi3filter/req_resp_decoder.go +++ b/openapi3filter/req_resp_decoder.go @@ -19,7 +19,7 @@ import ( yaml "github.com/oasdiff/yaml3" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) // ParseErrorKind describes a kind of ParseError. diff --git a/openapi3filter/req_resp_decoder_test.go b/openapi3filter/req_resp_decoder_test.go index ee59b11f3..f2359db42 100644 --- a/openapi3filter/req_resp_decoder_test.go +++ b/openapi3filter/req_resp_decoder_test.go @@ -17,8 +17,8 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - legacyrouter "github.com/getkin/kin-openapi/routers/legacy" + "github.com/oasdiff/kin-openapi/openapi3" + legacyrouter "github.com/oasdiff/kin-openapi/routers/legacy" ) var ( diff --git a/openapi3filter/testdata/issue1100_test.go b/openapi3filter/testdata/issue1100_test.go index b5147dfe8..498cc852c 100644 --- a/openapi3filter/testdata/issue1100_test.go +++ b/openapi3filter/testdata/issue1100_test.go @@ -5,11 +5,11 @@ import ( "strings" "testing" - "github.com/getkin/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/openapi3filter" "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestIssue1100(t *testing.T) { diff --git a/openapi3filter/unpack_errors_test.go b/openapi3filter/unpack_errors_test.go index 3ebe5c0bd..220ab649b 100644 --- a/openapi3filter/unpack_errors_test.go +++ b/openapi3filter/unpack_errors_test.go @@ -7,9 +7,9 @@ import ( "sort" "strings" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func Example() { diff --git a/openapi3filter/upload_arbitrary_file_test.go b/openapi3filter/upload_arbitrary_file_test.go index f0d771f04..744c1ce67 100644 --- a/openapi3filter/upload_arbitrary_file_test.go +++ b/openapi3filter/upload_arbitrary_file_test.go @@ -11,9 +11,9 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestValidateUploadArbitraryBinaryFile(t *testing.T) { diff --git a/openapi3filter/validate_readonly_test.go b/openapi3filter/validate_readonly_test.go index d640f274f..02d3c7dd5 100644 --- a/openapi3filter/validate_readonly_test.go +++ b/openapi3filter/validate_readonly_test.go @@ -9,8 +9,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - legacyrouter "github.com/getkin/kin-openapi/routers/legacy" + "github.com/oasdiff/kin-openapi/openapi3" + legacyrouter "github.com/oasdiff/kin-openapi/routers/legacy" ) func TestReadOnlyWriteOnlyPropertiesValidation(t *testing.T) { diff --git a/openapi3filter/validate_request.go b/openapi3filter/validate_request.go index b064de8ed..62cd15def 100644 --- a/openapi3filter/validate_request.go +++ b/openapi3filter/validate_request.go @@ -11,7 +11,7 @@ import ( "sort" "strings" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) // ErrAuthenticationServiceMissing is returned when no authentication service diff --git a/openapi3filter/validate_request_example_test.go b/openapi3filter/validate_request_example_test.go index 653db3039..8e343b6ee 100644 --- a/openapi3filter/validate_request_example_test.go +++ b/openapi3filter/validate_request_example_test.go @@ -7,8 +7,8 @@ import ( "log" "net/http" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func ExampleAuthenticationFunc() { diff --git a/openapi3filter/validate_request_input.go b/openapi3filter/validate_request_input.go index c7565ebb7..c666eee37 100644 --- a/openapi3filter/validate_request_input.go +++ b/openapi3filter/validate_request_input.go @@ -4,8 +4,8 @@ import ( "net/http" "net/url" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers" ) // A ContentParameterDecoder takes a parameter definition from the OpenAPI spec, diff --git a/openapi3filter/validate_request_test.go b/openapi3filter/validate_request_test.go index 82b091294..b5a8b3f20 100644 --- a/openapi3filter/validate_request_test.go +++ b/openapi3filter/validate_request_test.go @@ -13,10 +13,10 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers" - "github.com/getkin/kin-openapi/routers/gorillamux" - legacyrouter "github.com/getkin/kin-openapi/routers/legacy" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers" + "github.com/oasdiff/kin-openapi/routers/gorillamux" + legacyrouter "github.com/oasdiff/kin-openapi/routers/legacy" ) func setupTestRouter(t *testing.T, spec string) routers.Router { diff --git a/openapi3filter/validate_response.go b/openapi3filter/validate_response.go index 5fb330900..b05e77e3e 100644 --- a/openapi3filter/validate_response.go +++ b/openapi3filter/validate_response.go @@ -10,7 +10,7 @@ import ( "sort" "strings" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) // ValidateResponse is used to validate the given input according to previous diff --git a/openapi3filter/validate_response_test.go b/openapi3filter/validate_response_test.go index e61a58192..7027f5a70 100644 --- a/openapi3filter/validate_response_test.go +++ b/openapi3filter/validate_response_test.go @@ -8,7 +8,7 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) func Test_validateResponseHeader(t *testing.T) { diff --git a/openapi3filter/validate_set_default_test.go b/openapi3filter/validate_set_default_test.go index 03c863388..af4e9b137 100644 --- a/openapi3filter/validate_set_default_test.go +++ b/openapi3filter/validate_set_default_test.go @@ -10,8 +10,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - legacyrouter "github.com/getkin/kin-openapi/routers/legacy" + "github.com/oasdiff/kin-openapi/openapi3" + legacyrouter "github.com/oasdiff/kin-openapi/routers/legacy" ) func TestValidatingRequestParameterAndSetDefault(t *testing.T) { diff --git a/openapi3filter/validation_discriminator_test.go b/openapi3filter/validation_discriminator_test.go index adabf409d..e439b46fd 100644 --- a/openapi3filter/validation_discriminator_test.go +++ b/openapi3filter/validation_discriminator_test.go @@ -7,8 +7,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - legacyrouter "github.com/getkin/kin-openapi/routers/legacy" + "github.com/oasdiff/kin-openapi/openapi3" + legacyrouter "github.com/oasdiff/kin-openapi/routers/legacy" ) func TestValidationWithDiscriminatorSelection(t *testing.T) { diff --git a/openapi3filter/validation_enum_test.go b/openapi3filter/validation_enum_test.go index aae3a1ffa..a3ce9a2cb 100644 --- a/openapi3filter/validation_enum_test.go +++ b/openapi3filter/validation_enum_test.go @@ -7,8 +7,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - legacyrouter "github.com/getkin/kin-openapi/routers/legacy" + "github.com/oasdiff/kin-openapi/openapi3" + legacyrouter "github.com/oasdiff/kin-openapi/routers/legacy" ) func TestValidationWithIntegerEnum(t *testing.T) { diff --git a/openapi3filter/validation_error_encoder.go b/openapi3filter/validation_error_encoder.go index 4369ca6b3..aa19d12ad 100644 --- a/openapi3filter/validation_error_encoder.go +++ b/openapi3filter/validation_error_encoder.go @@ -6,8 +6,8 @@ import ( "net/http" "strings" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers" ) // ValidationErrorEncoder wraps a base ErrorEncoder to handle ValidationErrors diff --git a/openapi3filter/validation_error_test.go b/openapi3filter/validation_error_test.go index 8a1ff8262..c69feafdf 100644 --- a/openapi3filter/validation_error_test.go +++ b/openapi3filter/validation_error_test.go @@ -12,8 +12,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers" ) func newPetstoreRequest(t *testing.T, method, path string, body io.Reader) *http.Request { diff --git a/openapi3filter/validation_handler.go b/openapi3filter/validation_handler.go index d4bb1efa0..1acd377d0 100644 --- a/openapi3filter/validation_handler.go +++ b/openapi3filter/validation_handler.go @@ -4,9 +4,9 @@ import ( "context" "net/http" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers" - legacyrouter "github.com/getkin/kin-openapi/routers/legacy" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers" + legacyrouter "github.com/oasdiff/kin-openapi/routers/legacy" ) // AuthenticationFunc allows for custom security requirement validation. diff --git a/openapi3filter/validation_test.go b/openapi3filter/validation_test.go index 865ffa254..16810a720 100644 --- a/openapi3filter/validation_test.go +++ b/openapi3filter/validation_test.go @@ -15,8 +15,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - legacyrouter "github.com/getkin/kin-openapi/routers/legacy" + "github.com/oasdiff/kin-openapi/openapi3" + legacyrouter "github.com/oasdiff/kin-openapi/routers/legacy" ) type ExampleRequest struct { diff --git a/openapi3filter/zip_file_upload_test.go b/openapi3filter/zip_file_upload_test.go index a61804062..1182111d1 100644 --- a/openapi3filter/zip_file_upload_test.go +++ b/openapi3filter/zip_file_upload_test.go @@ -11,9 +11,9 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func TestValidateZipFileUpload(t *testing.T) { diff --git a/openapi3gen/openapi3gen.go b/openapi3gen/openapi3gen.go index 5d9b64abf..740cd5a15 100644 --- a/openapi3gen/openapi3gen.go +++ b/openapi3gen/openapi3gen.go @@ -10,7 +10,7 @@ import ( "strings" "time" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) // CycleError indicates that a type graph has one or more possible cycles. diff --git a/openapi3gen/openapi3gen_newschemarefforvalue_test.go b/openapi3gen/openapi3gen_newschemarefforvalue_test.go index ada3d8860..ef0965296 100644 --- a/openapi3gen/openapi3gen_newschemarefforvalue_test.go +++ b/openapi3gen/openapi3gen_newschemarefforvalue_test.go @@ -6,9 +6,9 @@ import ( "reflect" "strings" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3gen" - "github.com/getkin/kin-openapi/openapi3gen/internal/subpkg" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3gen" + "github.com/oasdiff/kin-openapi/openapi3gen/internal/subpkg" ) // Make sure that custom schema name generator is employed and results produced with it are properly used diff --git a/openapi3gen/openapi3gen_test.go b/openapi3gen/openapi3gen_test.go index e18d8619c..06171a5f9 100644 --- a/openapi3gen/openapi3gen_test.go +++ b/openapi3gen/openapi3gen_test.go @@ -13,8 +13,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3gen" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3gen" ) func ExampleGenerator_SchemaRefs() { @@ -330,7 +330,7 @@ func TestEmbeddedPointerStructs(t *testing.T) { require.Equal(t, true, ok) } -// See: https://github.com/getkin/kin-openapi/issues/500 +// See: https://github.com/oasdiff/kin-openapi/issues/500 func TestEmbeddedPointerStructsWithSchemaCustomizer(t *testing.T) { type EmbeddedStruct struct { ID string diff --git a/openapi3gen/simple_test.go b/openapi3gen/simple_test.go index 11b3b26a4..1702b59ef 100644 --- a/openapi3gen/simple_test.go +++ b/openapi3gen/simple_test.go @@ -5,7 +5,7 @@ import ( "fmt" "time" - "github.com/getkin/kin-openapi/openapi3gen" + "github.com/oasdiff/kin-openapi/openapi3gen" ) type ( diff --git a/routers/gorillamux/example_test.go b/routers/gorillamux/example_test.go index 9f949bdc5..43c61bb0b 100644 --- a/routers/gorillamux/example_test.go +++ b/routers/gorillamux/example_test.go @@ -5,9 +5,9 @@ import ( "fmt" "net/http" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/gorillamux" ) func Example() { diff --git a/routers/gorillamux/router.go b/routers/gorillamux/router.go index c73a70312..2b39a980b 100644 --- a/routers/gorillamux/router.go +++ b/routers/gorillamux/router.go @@ -15,8 +15,8 @@ import ( "github.com/gorilla/mux" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers" ) var _ routers.Router = &Router{} @@ -151,7 +151,7 @@ func makeServers(in openapi3.Servers) ([]srv, error) { // then url.Parse() cannot parse "http://domain.tld:`bEncode({port})`/bla" // and mux is not able to set the {port} variable // So we just use the default value for this variable. - // See https://github.com/getkin/kin-openapi/issues/367 + // See https://github.com/oasdiff/kin-openapi/issues/367 var varsUpdater varsf if lhs := strings.Index(serverURL, ":{"); lhs > 0 { rest := serverURL[lhs+len(":{"):] diff --git a/routers/gorillamux/router_test.go b/routers/gorillamux/router_test.go index 4f40719b6..b29c65c81 100644 --- a/routers/gorillamux/router_test.go +++ b/routers/gorillamux/router_test.go @@ -9,8 +9,8 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers" ) func TestRouter(t *testing.T) { diff --git a/routers/issue356_test.go b/routers/issue356_test.go index 100e0183d..cba550ff8 100644 --- a/routers/issue356_test.go +++ b/routers/issue356_test.go @@ -10,11 +10,11 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers" - "github.com/getkin/kin-openapi/routers/gorillamux" - "github.com/getkin/kin-openapi/routers/legacy" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers" + "github.com/oasdiff/kin-openapi/routers/gorillamux" + "github.com/oasdiff/kin-openapi/routers/legacy" ) func TestIssue356(t *testing.T) { diff --git a/routers/legacy/issue444_test.go b/routers/legacy/issue444_test.go index c1e9b14f2..e0ef2f5e6 100644 --- a/routers/legacy/issue444_test.go +++ b/routers/legacy/issue444_test.go @@ -8,9 +8,9 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - legacyrouter "github.com/getkin/kin-openapi/routers/legacy" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + legacyrouter "github.com/oasdiff/kin-openapi/routers/legacy" ) func TestIssue444(t *testing.T) { diff --git a/routers/legacy/router.go b/routers/legacy/router.go index 306449d3c..ce5ddac16 100644 --- a/routers/legacy/router.go +++ b/routers/legacy/router.go @@ -13,9 +13,9 @@ import ( "net/http" "strings" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers" - "github.com/getkin/kin-openapi/routers/legacy/pathpattern" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers" + "github.com/oasdiff/kin-openapi/routers/legacy/pathpattern" ) // Routers maps a HTTP request to a Router. diff --git a/routers/legacy/router_test.go b/routers/legacy/router_test.go index 2bc30ea83..0a2dedc18 100644 --- a/routers/legacy/router_test.go +++ b/routers/legacy/router_test.go @@ -8,8 +8,8 @@ import ( "github.com/stretchr/testify/require" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/routers" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/routers" ) func TestRouter(t *testing.T) { diff --git a/routers/legacy/validate_request_test.go b/routers/legacy/validate_request_test.go index 77d8bc1de..e21f01ae5 100644 --- a/routers/legacy/validate_request_test.go +++ b/routers/legacy/validate_request_test.go @@ -6,9 +6,9 @@ import ( "fmt" "net/http" - "github.com/getkin/kin-openapi/openapi3" - "github.com/getkin/kin-openapi/openapi3filter" - "github.com/getkin/kin-openapi/routers/legacy" + "github.com/oasdiff/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3filter" + "github.com/oasdiff/kin-openapi/routers/legacy" ) const spec = ` diff --git a/routers/types.go b/routers/types.go index 93746cfe9..1a3ae9bbf 100644 --- a/routers/types.go +++ b/routers/types.go @@ -3,7 +3,7 @@ package routers import ( "net/http" - "github.com/getkin/kin-openapi/openapi3" + "github.com/oasdiff/kin-openapi/openapi3" ) // Router helps link http.Request.s and an OpenAPIv3 spec From 697d4b92a8b7b792e4f1fcb92c688ee303fd799d Mon Sep 17 00:00:00 2001 From: Thomas Visser Date: Wed, 18 Mar 2026 14:39:42 +0100 Subject: [PATCH 08/19] fix: strip __origin__ from slices in example values stripOriginFromAny only recursed into map[string]any but not []any, so __origin__ keys inside array elements (e.g. example values with lists of objects) survived stripping and caused false positive diffs. Co-Authored-By: Claude Opus 4.6 --- openapi3/origin.go | 20 +++++--- openapi3/origin_test.go | 47 +++++++++++++++++++ .../testdata/origin/example_with_array.yaml | 25 ++++++++++ 3 files changed, 85 insertions(+), 7 deletions(-) create mode 100644 openapi3/testdata/origin/example_with_array.yaml diff --git a/openapi3/origin.go b/openapi3/origin.go index d96121465..dbddbe675 100644 --- a/openapi3/origin.go +++ b/openapi3/origin.go @@ -26,13 +26,19 @@ type Location struct { // dedicated UnmarshalJSON to consume the origin metadata injected by // the YAML origin-tracking loader. func stripOriginFromAny(v any) any { - m, ok := v.(map[string]any) - if !ok { + switch x := v.(type) { + case map[string]any: + delete(x, originKey) + for k, val := range x { + x[k] = stripOriginFromAny(val) + } + return x + case []any: + for i, val := range x { + x[i] = stripOriginFromAny(val) + } + return x + default: return v } - delete(m, originKey) - for k, val := range m { - m[k] = stripOriginFromAny(val) - } - return m } diff --git a/openapi3/origin_test.go b/openapi3/origin_test.go index 09c98ee36..79fcdad01 100644 --- a/openapi3/origin_test.go +++ b/openapi3/origin_test.go @@ -436,6 +436,53 @@ func TestOrigin_XML(t *testing.T) { base.Origin.Fields["prefix"]) } +func TestStripOriginFromAny_Slice(t *testing.T) { + // Simulates what the YAML origin-tracking loader produces for example + // values that contain arrays of objects. + input := map[string]any{ + "name": "test", + "items": []any{ + map[string]any{ + "__origin__": map[string]any{"file": "a.yaml", "line": 1}, + "id": 1, + }, + map[string]any{ + "__origin__": map[string]any{"file": "a.yaml", "line": 2}, + "id": 2, + }, + }, + } + + result := stripOriginFromAny(input) + m := result.(map[string]any) + items := m["items"].([]any) + for _, item := range items { + itemMap := item.(map[string]any) + require.NotContains(t, itemMap, "__origin__") + } +} + +func TestOrigin_ExampleWithArrayValue(t *testing.T) { + loader := NewLoader() + + IncludeOrigin = true + defer unsetIncludeOrigin() + + doc, err := loader.LoadFromFile("testdata/origin/example_with_array.yaml") + require.NoError(t, err) + + example := doc.Paths.Find("/subscribe").Post.RequestBody.Value.Content["application/json"].Examples["bar"] + require.NotNil(t, example.Value) + + // The example value contains a list of objects; __origin__ must be stripped from each. + value := example.Value.Value.(map[string]any) + items := value["items"].([]any) + for _, item := range items { + itemMap := item.(map[string]any) + require.NotContains(t, itemMap, "__origin__") + } +} + // TestOrigin_OriginExistsInProperties verifies that loading fails when a specification // contains a property named "__origin__", highlighting a limitation in the current implementation. func TestOrigin_OriginExistsInProperties(t *testing.T) { diff --git a/openapi3/testdata/origin/example_with_array.yaml b/openapi3/testdata/origin/example_with_array.yaml new file mode 100644 index 000000000..b2ec724b6 --- /dev/null +++ b/openapi3/testdata/origin/example_with_array.yaml @@ -0,0 +1,25 @@ +openapi: 3.0.0 +info: + title: Example with Array Value + version: 1.0.0 +paths: + /subscribe: + post: + requestBody: + content: + application/json: + schema: + type: object + examples: + bar: + summary: A bar example with array + value: + name: test + items: + - id: 1 + label: first + - id: 2 + label: second + responses: + "200": + description: OK From 35356fd517be79481ea334bc1d14d8e4019685e6 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Tue, 31 Mar 2026 00:27:33 +0300 Subject: [PATCH 09/19] chore: bump yaml and yaml3 to v0.0.3 (#5) Picks up the fix that skips __origin__ entries during alias expansion, preventing spurious "excessive aliasing" errors on large specs with many YAML aliases (follow-up to oasdiff/oasdiff#821). Co-authored-by: Claude Sonnet 4.6 --- go.mod | 4 +- go.sum | 12 +- openapi3/alias_issue_test.go | 15 + openapi3/testdata/alias.yml | 8686 ++++++++++++++++++++++++++++++++++ 4 files changed, 8711 insertions(+), 6 deletions(-) create mode 100644 openapi3/alias_issue_test.go create mode 100644 openapi3/testdata/alias.yml diff --git a/go.mod b/go.mod index dfcf8db82..1c9053614 100644 --- a/go.mod +++ b/go.mod @@ -6,8 +6,8 @@ require ( github.com/go-openapi/jsonpointer v0.21.0 github.com/gorilla/mux v1.8.0 github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 - github.com/oasdiff/yaml v0.0.1 - github.com/oasdiff/yaml3 v0.0.1 + github.com/oasdiff/yaml v0.0.3 + github.com/oasdiff/yaml3 v0.0.3 github.com/perimeterx/marshmallow v1.1.5 github.com/stretchr/testify v1.9.0 github.com/woodsbury/decimal128 v1.3.0 diff --git a/go.sum b/go.sum index 3c0f7628f..00c494ca7 100644 --- a/go.sum +++ b/go.sum @@ -18,10 +18,14 @@ github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0 github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc= github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 h1:RWengNIwukTxcDr9M+97sNutRR1RKhG96O6jWumTTnw= github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826/go.mod h1:TaXosZuwdSHYgviHp1DAtfrULt5eUgsSMsZf+YrPgl8= -github.com/oasdiff/yaml v0.0.1 h1:dPrn0F2PJ7HdzHPndJkArvB2Fw0cwgFdVUKCEkoFuds= -github.com/oasdiff/yaml v0.0.1/go.mod h1:r8bgVgpWT5iIN/AgP0GljFvB6CicK+yL1nIAbm+8/QQ= -github.com/oasdiff/yaml3 v0.0.1 h1:kReOSraQLTxuuGNX9aNeJ7tcsvUB2MS+iupdUrWe4Z0= -github.com/oasdiff/yaml3 v0.0.1/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= +github.com/oasdiff/yaml v0.0.2 h1:sKQkI6JmuBgie+7geGJGbYvRaMoLIk4NqPgbXxOnunM= +github.com/oasdiff/yaml v0.0.2/go.mod h1:rKaD4gBtiSjZLsrvo4vw3YR8aR8vKeAAkysJI3d8tdo= +github.com/oasdiff/yaml v0.0.3 h1:IORGNY4IZ1+SKFSUuu288zE/33JYxx0FWp3ZTqn+Hdc= +github.com/oasdiff/yaml v0.0.3/go.mod h1:cGJc1tLIzdmJs4PPPJsLHDh2j1bEgJLDyZ02wyp5tvg= +github.com/oasdiff/yaml3 v0.0.2 h1:KAbH+Qi4aT7PQbG4AASP25Yob3u+VyAVjLrTHaR/FOE= +github.com/oasdiff/yaml3 v0.0.2/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= +github.com/oasdiff/yaml3 v0.0.3 h1:AoDWNMgx8ND5gmaxeUSX4LjrlxrYB6CGzKdVi/1zAPQ= +github.com/oasdiff/yaml3 v0.0.3/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= github.com/perimeterx/marshmallow v1.1.5 h1:a2LALqQ1BlHM8PZblsDdidgv1mWi1DgC2UmX50IvK2s= github.com/perimeterx/marshmallow v1.1.5/go.mod h1:dsXbUu8CRzfYP5a87xpp0xq9S3u0Vchtcl8we9tYaXw= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= diff --git a/openapi3/alias_issue_test.go b/openapi3/alias_issue_test.go new file mode 100644 index 000000000..cf404b743 --- /dev/null +++ b/openapi3/alias_issue_test.go @@ -0,0 +1,15 @@ +package openapi3 + +import ( + "testing" + + "github.com/stretchr/testify/require" +) + +func TestAliasIssue(t *testing.T) { + // IncludeOrigin = true + loader := NewLoader() + _, err := loader.LoadFromFile("testdata/alias.yml") + require.NoError(t, err) + // require.Nil(t, doc) +} diff --git a/openapi3/testdata/alias.yml b/openapi3/testdata/alias.yml new file mode 100644 index 000000000..83493b3b5 --- /dev/null +++ b/openapi3/testdata/alias.yml @@ -0,0 +1,8686 @@ +openapi: 3.0.3 +info: + title: Cardano Wallet Backend API + version: v2025-12-15 + license: + name: Apache-2.0 + url: https://raw.githubusercontent.com/cardano-foundation/cardano-wallet/master/LICENSE + description: | +

+ +

+externalDocs: + description: Need more? Click here to access our API guide and walkthrough. + url: https://cardano-foundation.github.io/cardano-wallet/ + +servers: + - url: https://localhost:8090/v2/ + +############################################################################# +# # +# FIELDS # +# # +############################################################################# + +x-date: &date + type: string + format: iso-8601-date-and-time + example: 2019-02-27T14:46:45Z + +x-slotNumber: &slotNumber + type: integer + description: The zero-based slot index within an epoch. + minimum: 0 + example: 1337 + +x-stakePoolsNumber: &stakePoolsNumber + type: integer + minimum: 0 + example: 100 + +x-numberOfSeconds: &numberOfSeconds + type: object + required: + - quantity + - unit + properties: + quantity: + type: number + minimum: 0.0 + example: 10.0 + unit: + type: string + enum: ["second"] + +x-epochNumber: &epochNumber + type: integer + description: An epoch is a time period which is divided into slots. + minimum: 0 + example: 14 + +x-epochInfo: &epochInfo + type: object + required: + - epoch_number + - epoch_start_time + properties: + epoch_number: *epochNumber + epoch_start_time: *date + +x-blockId: &blockId + description: The hash of a block + type: string + format: hex + maxLength: 64 + minLength: 64 + example: 3c07030e36bfffe67e2e2ec09e5293d384637cd2f004356ef320f3fe6c52041a + +x-absoluteSlot: &absoluteSlot + type: integer + description: The 0-based slot index starting from genesis of the blockchain. + minimum: 0 + example: 8086 + +x-witnessCount: &witnessCount + type: integer + description: The number of witnesses detected + minimum: 0 + maximum: 127 + +x-numberOfSlots: &numberOfSlots + type: object + required: + - quantity + - unit + properties: + quantity: + type: integer + minimum: 0 + example: 42000 + unit: + type: string + enum: ["slot"] + +x-numberOfBlocks: &numberOfBlocks + type: object + required: + - quantity + - unit + properties: + quantity: + type: integer + minimum: 0 + example: 1337 + unit: + type: string + enum: + - block + example: "block" + +x-genesis: &genesis + type: string + enum: ["from_genesis"] + example: "from_genesis" + +x-tip: &tip + type: string + enum: ["from_tip"] + example: "from_tip" + +x-blockReference: &blockReference + description: A reference to a particular time slot, and the block height at that point. + type: object + required: + - absolute_slot_number + - slot_number + - epoch_number + - time + - height + properties: + absolute_slot_number: *absoluteSlot + slot_number: *slotNumber + epoch_number: *epochNumber + time: *date + height: *numberOfBlocks + +x-chainPoint : &chainPoint + description: A reference to a particular block. + type: object + required: + - block_header_hash + - absolute_slot_number + properties: + block_header_hash: *blockId + absolute_slot_number: *absoluteSlot + +x-slotId: &slotId + description: A slot identifier, given by epoch number and local slot index. + type: object + required: + - epoch_number + - slot_number + properties: + epoch_number: *epochNumber + slot_number: *slotNumber + +x-slotReference: &slotReference + description: A reference to a particular time slot. + type: object + required: + - absolute_slot_number + - slot_number + - epoch_number + - time + properties: + absolute_slot_number: *absoluteSlot + epoch_number: *epochNumber + slot_number: *slotNumber + time: *date + +x-genesisBlock: &genesisBlock + description: A reference to a particular block. + type: object + required: + - slot_number + - epoch_number + properties: + slot_number: + <<: *slotNumber + maximum: 0 + example: 0 + epoch_number: + <<: *epochNumber + maximum: 0 + example: 0 + +x-percentage: &percentage + type: object + required: + - quantity + - unit + properties: + quantity: + type: number + minimum: 0 + maximum: 100 + example: 42 + unit: + type: string + enum: + - percent + +x-microseconds: µseconds + type: object + required: + - quantity + - unit + properties: + quantity: + type: number + example: 42 + unit: + type: string + enum: + - microsecond + +x-syncProgress: &syncProgress + type: object + required: + - status + properties: + status: + type: string + enum: + - ready + - syncing + - not_responding + progress: + <<: *percentage + description: | + + if: status == syncing +
+ example: + status: ready + +x-syncClockProgress: &syncClockProgress + type: object + required: + - status + properties: + status: + type: string + enum: + - unavailable + - pending + - available + offset: + <<: *microseconds + description: | + + if: status == available +
+ example: + status: pending + +x-amount: &amount + description: Coins, in Lovelace. Only relates to 'Ada'. Refer to `assets` for multi-assets wallets instead. + type: object + required: + - quantity + - unit + properties: + quantity: + type: integer + minimum: 0 + example: 42000000 + unit: + type: string + enum: + - lovelace + +x-stakeAddress: &stakeAddress + type: string + format: bech32 + example: stake1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2x + +x-addressId: &addressId + type: string + format: base58|bech32 + example: addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g + description: | + A sequence of characters that encodes (in Base58 or Bech32) a sequence of bytes + which represents an address on the Cardano blockchain. + Sequences in Base58 encoding are expected to be legacy Byron addresses, + whereas sequences in Bech32 encoding correspond to current Shelley addresses. + + For more details, see + [CIP-0019 — Cardano addresses](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0019) + . + +x-addressState: &addressState + type: string + enum: + - used + - unused + +x-txType: &txType + type: string + pattern: "^Tx AlonzoEra$" + +x-txDescription: &txDescription + description: A description of transaction + type: string + minLength: 0 + maxLength: 256 + example: "Asset minting transaction" + +x-txInNode: &txInNode + type: string + pattern: "^[0-9abcdef]+#[0-9]+$" + minLength: 66 + maxLength: 68 + example: 2f8cd2ef706e5500307636b8477198ee2f204c4181b53c507f46d195140493cb#1 + +x-dataHash: &dataHash + type: string + format: hex + minLength: 64 + maxLength: 64 + example: ca54c8836c475a77c6914b4fd598080acadb0f0067778773484d2c12ae7dc756 + +x-stakePoolMetadataUrl: &stakePoolMetadataUrl + description: A URL to the stake pool's website. + type: string + format: uri + pattern: "^https://.+" + maxLength: 250 + +x-stakePoolMetadataHash: &stakePoolMetadataHash + type: string + format: hex + minLength: 64 + maxLength: 64 + example: ca54c8836c475a77c6914b4fd598080acadb0f0067778773484d2c12ae7dc756 + +x-stakePoolOwner: &stakePoolOwner + type: string + format: bech32 + pattern: "^(ed25519_pk)1[0-9a-z]*$" + +x-adaQuantity: &adaQuantity + type: integer + minimum: 0 + maximum: 45000000000000000 + +x-assetQuantity: &assetQuantity + type: integer + description: | + Number of assets for the given `policy_id` and `asset_name`. + minimum: 0 + +x-assetValueNode: &assetValueNode + description: | + Map of asset values along with their quantities. + assetName in field name is expected (max length 64-character hex-encoded text) + type: object + additionalProperties: *assetQuantity + # Note: propertyNames pattern not supported in current OpenAPI version. + # propertyNames: + # pattern: '^(assetName)$' + example: + - {"asset1": 12, "asset2": 33} + +x-valueNode: &valueNode + nullable: false + oneOf: + - <<: *adaQuantity + title: ada coin + - <<: *assetValueNode + title: asset value + +x-valueNodes: &valueNodes + description: | + Map of values along with their quantities. Can be lovelace or asset. + In the former case 'lovelace' name is expected. + In the latter case assetPolicyId name is expected (56-character hex-encoded text) + type: object + additionalProperties: *valueNode + # Note: propertyNames pattern not supported in current OpenAPI version. + # propertyNames: + # pattern: '^(lovelace)|(assetPolicyId)$' + example: + - {"lovelace": 1423} + - {"lovelace": 1423, "7191ae0e1286891fe5c027a5dc041b7401689938e18e14ec83cf74fb": {"asset1": 12, "asset2": 33}} + +x-stakePoolId: &stakePoolId + type: string + format: hex|bech32 + example: pool1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm + description: A unique identifier for the pool. + +x-drepKeyHashNew: &drepKeyHashNew + type: string + format: bech32 + example: drep_vkh15k6929drl7xt0spvudgcxndryn4kmlzpk4meed0xhqe254czjh2 + description: | + DRep's verification key hash according to CIP-0105. + Replacing now deprecated 'drep' which is now used for drep credential. + pattern: "^(drep_vkh)1[0-9a-z]*$" + +x-drepKeyHash: &drepKeyHash + type: string + format: bech32 + example: drep1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm + description: | + DRep's key hash according to CIP-0105 (deprecated). + + DRep credential which is special byte prepended to script/key hash payload. + Introduced by CIP-0129 and the byte prepended is 0x22 and 0x23 for + key and script hash, respectively. + pattern: "^(drep)1[0-9a-z]*$" + +x-drepScriptHash: &drepScriptHash + type: string + format: bech32 + example: drep1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm + description: | + DRep's script hash according to CIP-0105. + pattern: "^(drep_script)1[0-9a-z]*$" + +x-walletAccountXPubkey: &walletAccountXPubkey + description: An extended account public key (public key + chain code) + type: string + format: hex + minLength: 128 + maxLength: 128 + example: 1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db11423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1 + +x-sharedWalletAccountXPubkey: &sharedWalletAccountXPubkey + description: An extended account public key (public key + chain code) of shared wallet + type: string + format: bech32 + pattern: "^(acct_shared_xvk)1[0-9a-z]*$" + +x-cosigner: &cosigner + type: string + pattern: "^(cosigner#)[0-9]+$" + +x-cosigners: &cosigners + description: Map of cosigners and their account public keys. Use key as in &cosigner, eg. "cosigner#" + type: object + additionalProperties: *sharedWalletAccountXPubkey + # Note: propertyNames pattern not supported in current OpenAPI version. + # propertyNames: + # pattern: '^(cosigner#)[0-9]+$' + example: + - {"cosigner#0": "acct_shared_xvk1z8kc04yh544ksc9h2yhp7p6qwpf6syv5qnm8sgnhdne5z2esht5cwssxsec2wzw3nhxm2d9ph4s6ldmqdvxa0zuxzmukpajhyc7flug3te037"} + +x-self: &self + type: string + enum: + - self + +x-accountPubkeyOrSelf: &accountPubkeyOrSelf + nullable: false + oneOf: + - <<: *sharedWalletAccountXPubkey + title: public key + - <<: *self + title: self + +x-cosignersEntry: &cosignersEntry + description: Map of cosigners and their account public keys. Use key as in &cosigner, eg. "cosigner#"or 'self' + type: object + additionalProperties: *accountPubkeyOrSelf + # Note: propertyNames pattern not supported in current OpenAPI version. + # propertyNames: + # pattern: '^(cosigner#)[0-9]+$' + example: + - {"cosigner#0": "acct_shared_xvk1z8kc04yh544ksc9h2yhp7p6qwpf6syv5qnm8sgnhdne5z2esht5cwssxsec2wzw3nhxm2d9ph4s6ldmqdvxa0zuxzmukpajhyc7flug3te037"} + - {"cosigner#0": "self"} + +x-walletId: &walletId + description: A unique identifier for the wallet + type: string + format: hex + maxLength: 40 + minLength: 40 + example: 2512a00e9653fe49a44a5886202e24d77eeb998f + +x-walletDiscovery: &walletDiscovery + description: Mechanism used for discovering addresses. + type: string + enum: + - random + - sequential + example: sequential + +x-oneChangeAddressMode: &oneChangeAddressMode + type: boolean + default: false + +x-restorationMode: &restorationMode + description: | + The wallet restoration mode determines since when the wallet should + be restored from the blockchain. + + cardano-wallet uses so-called `ChainSync` protocol under the hood to + scan the chain and restore its state from blocks and transactions. + [Ogmios](https://ogmios.dev/mini-protocols/local-chain-sync/) documentation provides a detailed + explanation of this underlying process. + oneOf: + - title: Restore from genesis + description: | + Restore the wallet from the genesis block. This will cause the wallet + to be restored from the very beginning of the blockchain, which is + expected to take a long time (several hours on mainnet). + <<: *genesis + - title: Restore from tip + description: | + Restore the wallet from the tip of the blockchain. The wallet queries + the current tip of the chain and then starts synchronizing from that point. + It waits for the _next block_ to appear before returning a result, which + on _mainnet_ will take an average of 30 seconds. + <<: *tip + - title: Restore from block + description: | + Restore the wallet after a specific _point_ identified by a block hash and + slot number. Note that any transaction which is part of that specified block + won't be restored. + <<: *chainPoint + +x-walletName: &walletName + type: string + maxLength: 255 + minLength: 1 + example: Alan's Wallet + +x-poolMetadataSource: &poolMetadataSource + description: | + Pool metadata source. This sets the metadata fetching strategy. + + Possible values are + * none -> no fetching + * direct -> direct fetching + * uri -> use SMASH server + type: string + pattern: '^(none|direct|https?:\/\/[a-zA-Z0-9-_~.]+(:[0-9]+)?/?)$' + example: https://smash.cardano-mainnet.iohk.io/ + +x-scriptHash: &scriptHash + description: A script hash - 28 bytes + type: string + format: bech32 + pattern: "^(script)1[0-9a-z]*$" + example: + - script1gr69m385thgvkrtspk73zmkwk537wxyxuevs2u9cukglvtlkz4k + +x-scriptIntegrityHash: &scriptIntegrityHash + description: A script data integrity hash - 32 bytes + type: string + format: bech32 + pattern: "^(script_data)1[0-9a-z]*$" + example: + - script_data16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7qau558d + +x-extraSignatureHash: &extraSignatureHash + description: An extra signature hash - 28 bytes + type: string + format: bech32 + pattern: "^(req_signer_vkh)1[0-9a-z]*$" + example: + - addr_keyhash1gr69m385thgvkrtspk73zmkwk537wxyxuevs2u9cukglvtlkz4k + +x-credentialPubKey: &credentialPubKey + description: A public key (public key without chain code) for credential - 32 bytes + type: string + format: bech32 + pattern: "^((addr_vk)|(stake_vk))1[0-9a-z]*$" + example: + - stake_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7qau558d + - addr_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7q3yvuv2 + +x-credentialExtendedPubKey: &credentialExtendedPubKey + description: An extended public key (public key with chain code) for credential - 64 bytes + type: string + format: bech32 + pattern: "^((addr_xvk)|(stake_xvk))1[0-9a-z]*$" + example: + - stake_xvk1qqqqzqqpqyqqzqgpqyqszqgpqqqqzqgpqqqqqqqpqyqqzqgqqqqqqqgpqqqqqqgqqyqszqqpqyqsqqqqqyqszqqqqqqqqqqpqqqqzqqgjanje + - addr_xvk1qyqqqqgqqyqsqqgqqyqsqqgqqqqszqqpqyqsqqgqqqqqqqgqqyqqqqqpqqqsqqqpqyqszqqpqqqszqgpqqqqzqgpqqqqqqqqqqqsqqqptg5dh + +x-credentialKeyHash: &credentialKeyHash + description: A key hash for credential - 28 bytes + type: string + format: bech32 + pattern: "^((addr_vkh)|(stake_vkh))1[0-9a-z]*$" + example: + - stake_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq + - addr_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq + +x-validationLevel: &validationLevel + description: | + Script validation level. Required validation sifts off scripts that would not + be accepted by the ledger. Recommended level filters out scripts that do not pass + required validation and additionally when: + * 'all' is non-empty + * there are redundant timelocks in a given level + * there are no duplicated verification keys in a given level + * 'at_least' coefficient is positive + * 'all', 'any' are non-empty and `'at_least' has no less elements in the list + than the coefficient after timelocks are filtered out. + + type: string + enum: + - required + - recommended + +x-anyAddress: &anyAddress + description: A Shelley address representing either enterprise, reward account or delegating address + type: string + format: bech32 + pattern: "^((addr)|(stake)|(addr_test)|(stake_test))1[0-9a-z]*$" + example: + - stake17xt2z3pa7etaxp7jurdg0m8jhsmtp4r2z56pd3a5q3jhxycdxzmx9 + - addr1wy5np0m5x03tax3kcdh6e2cet98qcfs80wtv4cyvl5taclc6dnd8e + - addr1xy5np0m5x03tax3kcdh6e2cet98qcfs80wtv4cyvl5tacluk59zrmajh6vra9cx6slk090pkkr2x59f5zmrmgpr9wvfs37hjk4 + +x-ScriptValue: &ScriptValue + oneOf: + - title: Key Hash + description: Leaf value for a script designating a required verification key hash. + type: string + format: bech32 + pattern: "^((addr_shared_vkh)|(stake_shared_vkh)|(policy_vkh))1[0-9a-z]*$" + + - title: All + type: object + required: + - all + properties: + all: + description: Script primitive for which all signing keys corresponding to all list elements' verification keys are expected to make the script valid. + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ScriptValue" + + - title: Any + type: object + required: + - any + properties: + any: + description: Script primitive for which a signing key corresponding to any of the list elements' verification keys is expected to make the script valid. It is equivalent to `some` with `"at_least"=1`. + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ScriptValue" + + - title: Some + type: object + required: + - some + properties: + some: + description: Script primitive for which at least a given number of signing keys corresponding to the list elements' verification keys are expected to make the script valid. + type: object + required: + - at_least + - from + properties: + at_least: + type: integer + minimum: 1 + maximum: 255 + from: + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ScriptValue" + + - title: Active from slot + type: object + required: + - active_from + properties: + active_from: + description: Transaction is only valid starting at the specified slot number (`≥ active_from`). + type: integer + minimum: 0 + + - title: Active until slot + type: object + required: + - active_until + properties: + active_until: + description: Transaction is only valid before the specified slot number (`< active_until`). + type: integer + minimum: 0 + +# ScriptValueGeneral allows any key hash prefix, used in decoded transactions +# where scripts can come from any source (not just shared wallets) +x-ScriptValueGeneral: &ScriptValueGeneral + oneOf: + - title: Key Hash + description: Leaf value for a script designating a required verification key hash. + type: string + format: bech32 + pattern: "^((addr_shared_vkh)|(stake_shared_vkh)|(addr_vkh)|(stake_vkh)|(policy_vkh))1[0-9a-z]*$" + + - title: All + type: object + required: + - all + properties: + all: + description: Script primitive for which all signing keys corresponding to all list elements' verification keys are expected to make the script valid. + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ScriptValueGeneral" + + - title: Any + type: object + required: + - any + properties: + any: + description: Script primitive for which a signing key corresponding to any of the list elements' verification keys is expected to make the script valid. It is equivalent to `some` with `"at_least"=1`. + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ScriptValueGeneral" + + - title: Some + type: object + required: + - some + properties: + some: + description: Script primitive for which at least a given number of signing keys corresponding to the list elements' verification keys are expected to make the script valid. + type: object + required: + - at_least + - from + properties: + at_least: + type: integer + minimum: 1 + maximum: 255 + from: + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ScriptValueGeneral" + + - title: Active from slot + type: object + required: + - active_from + properties: + active_from: + description: Transaction is only valid starting at the specified slot number (`≥ active_from`). + type: integer + minimum: 0 + + - title: Active until slot + type: object + required: + - active_until + properties: + active_until: + description: Transaction is only valid before the specified slot number (`< active_until`). + type: integer + minimum: 0 + +x-script: &script + <<: *ScriptValue + +x-ScriptTemplateValue: &ScriptTemplateValue + oneOf: + - title: Cosigner + description: Leaf value for a script designating a cosigner co-sharing the script. + type: string + pattern: "^(cosigner#)[0-9]*$" + + - title: All + type: object + required: + - all + properties: + all: + description: Script primitive for which all signing keys corresponding to all list cosigners' verification keys are expected to make the script valid. + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ScriptTemplateValue" + + - title: Any + type: object + required: + - any + properties: + any: + description: Script primitive for which a signing key corresponding to any of the list cosigners' verification keys is expected to make the script valid. It is equivalent to `some` with `"at_least"=1`. + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ScriptTemplateValue" + + - title: Some + type: object + required: + - some + properties: + some: + description: Script primitive for which at least a given number of signing keys corresponding to the list cosigners' verification keys are expected to make the script valid. + type: object + required: + - at_least + - from + properties: + at_least: + type: integer + minimum: 1 + maximum: 255 + from: + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ScriptTemplateValue" + + - title: Active from slot + type: object + required: + - active_from + properties: + active_from: + description: Transaction is only valid starting at the specified slot number (`≥ active_from`). + type: integer + minimum: 0 + + - title: Active until slot + type: object + required: + - active_until + properties: + active_until: + description: Transaction is only valid before the specified slot number (`< active_until`). + type: integer + minimum: 0 + +x-scriptTemplate: &scriptTemplate + type: object + required: + - cosigners + - template + properties: + cosigners: *cosigners + template: *ScriptTemplateValue + +x-scriptTemplateEntry: &scriptTemplateEntry + type: object + required: + - cosigners + - template + properties: + cosigners: *cosignersEntry + template: *ScriptTemplateValue + +x-CredentialValue: &CredentialValue + nullable: false + oneOf: + - <<: *credentialPubKey + title: public key + - <<: *credentialExtendedPubKey + title: extended public key + - <<: *credentialKeyHash + title: key hash + - <<: *script + title: script + - <<: *scriptHash + title: script hash + example: + any: + - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq + + - stake_shared_vkh1nqc00hvlc6cq0sfhretk0rmzw8dywmusp8retuqnnxzajtzhjg5 + + - all: + - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq + - addr_shared_vkh1y3zl4nqgm96ankt96dsdhc86vd5geny0wr7hu8cpzdfcqskq2cp + + - any: + - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq + - all: + - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq + - addr_shared_vkh1y3zl4nqgm96ankt96dsdhc86vd5geny0wr7hu8cpzdfcqskq2cp + + - some: + at_least: 2 + from: + - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq + - addr_shared_vkh1y3zl4nqgm96ankt96dsdhc86vd5geny0wr7hu8cpzdfcqskq2cp + +x-settings: &settings + description: Settings + type: object + required: + - pool_metadata_source + properties: + pool_metadata_source: + <<: *poolMetadataSource + description: | + Select stake pool metadata fetching strategy: + - `none` - metadata is not fetched at all, + - `direct` - metadata is fetched directly URLs registered on chain, + - `uri` - metadata is fetched from an external Stake-Pool Metadata Aggregation Server (SMASH) + + After update existing metadata will be dropped forcing it to re-sync automatically with the new setting. + +x-assetName: &assetName + type: string + description: | + The asset on-chain type which acts as a sub-identifier within a + policy. Although we call it "asset name", the value needn't be + text, and it could even be empty. + + For policies with a single fungible asset item, asset name is + typically an empty string. + + This value can be up to 32 bytes of arbitrary data (which is 64 + hexadecimal digits). + format: hex + maxLength: 64 + example: "" + +x-assetPolicyId: &assetPolicyId + type: string + description: | + A unique identifier of the asset's monetary policy. The policy + controls how assets of this kind are created and destroyed. + + The contents are the blake2b-224 hash of the monetary policy + script, encoded in hexadecimal. + format: hex + minLength: 56 + maxLength: 56 + example: 65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b + +x-assetFingerprint: &assetFingerprint + type: string + description: | + A user-facing short fingerprint which combines the `policy_id` and `asset_name` + to allow for an easier human comparison of assets. Note that it is generally + **not okay** to use this fingerprint as a unique identifier for it is not collision + resistant. Yet within the context of a single wallet, it makes for a (rather) + short user-facing comparison mean. + pattern: "^(asset)1[0-9a-z]*$" + maxLength: 44 + minLength: 44 + example: asset1rjklcrnsdzqp65wjgrg55sy9723kw09mlgvlc3 + +x-assetMetadataName: &assetMetadataName + type: string + maxLength: 50 + minLength: 1 + description: | + A human-readable name for the asset, intended for display in user + interfaces. + example: SwaggerCoin + +x-assetMetadataTicker: &assetMetadataTicker + type: string + maxLength: 5 + minLength: 2 + description: | + An optional human-readable very short name or acronym for the + asset, intended for display in user interfaces. If `ticker` is not + present, then `name` will be used, but it might be truncated to + fit within the available space. + example: SWAG + +x-assetMetadataDescription: &assetMetadataDescription + description: | + A human-readable description for the asset. Good for display in + user interfaces. + type: string + maxLength: 500 + +x-assetMetadataDecimals: &assetMetadataDecimals + type: integer + description: | + Defines a scaling factor for the asset of 10-n. The + decimals value _n_ is therefore the number of digits after the + decimal point for quantities of this token. + + It is up to API clients to use this metadata field to decimalize + asset quantities before displaying to users. The wallet backend + will always return unscaled token quantities as whole numbers. + minimum: 0 + maximum: 255 + example: 2 + +x-assetMetadataUrl: &assetMetadataUrl + description: | + A URL to the policy's owner(s) or the entity website in charge of the asset. + type: string + format: uri + pattern: "^https://.+" + maxLength: 250 + +x-assetMetadataLogo: &assetMetadataLogo + description: | + A base64-encoded `image/png` for displaying the asset. The end image can be expected + to be smaller than 64KB. + type: string + format: base64 + maxLength: 87400 + +x-assetMetadata: &assetMetadata + title: Native Assets Metadata + description: | + In the Mary era of Cardano, UTxO may contain native assets. These + assets are represented on-chain by opaque identifiers which are + meaningless to end-users. Therefore, user-facing metadata + regarding each token must be stored off-chain, in a metadata + registry. + + Token creators may publish metadata into the registry and client + applications can consume these metadata for display to end + users. This will work in a similar way to how it is done for stake + pool metadata. + type: object + additionalProperties: false + required: + - name + - description + properties: + name: *assetMetadataName + description: *assetMetadataDescription + ticker: *assetMetadataTicker + decimals: *assetMetadataDecimals + url: *assetMetadataUrl + logo: *assetMetadataLogo + +x-walletMnemonicSentence: &walletMnemonicSentence + description: A list of mnemonic words + type: array + minItems: 15 + maxItems: 24 + items: + type: string + format: bip-0039-mnemonic-word{english} + example: ["squirrel", "material", "silly", "twice", "direct", "slush", "pistol", "razor", "become", "junk", "kingdom", "flee", "squirrel", "silly", "twice"] + +x-walletSecondFactor: &walletSecondFactor + description: An optional passphrase used to encrypt the mnemonic sentence. + type: array + minItems: 9 + maxItems: 12 + items: + type: string + format: bip-0039-mnemonic-word{english} + example: ["squirrel", "material", "silly", "twice", "direct", "slush", "pistol", "razor", "become"] + +x-walletPassphrase: &walletPassphrase + description: A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds) + type: string + minLength: 10 + maxLength: 255 + example: Secure Passphrase + +x-keyExtended: &keyExtended + description: Determines whether extended (with chain code) or normal (without chain code) key is requested + type: string + enum: + - extended + - non_extended + +x-lenientPassphrase: &lenientPassphrase + description: A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds) + type: string + minLength: 0 + maxLength: 255 + example: Secure Passphrase + +x-walletPassphraseHash: &walletPassphraseHash + description: | + A hash of master passphrase. The hash should be an output of a Scrypt function with the following parameters: + - logN = 14 + - r = 8 + - p = 1 + type: string + format: hex + example: 31347c387c317c574342652b796362417576356c2b4258676a344a314c6343675375414c2f5653393661364e576a2b7550766655513d3d7c2f376738486c59723174734e394f6e4e753253302b6a65515a6b5437316b45414941366a515867386539493d + +x-walletEncryptedRootPrivateKey: &walletEncryptedRootPrivateKey + description: | + A root private key, encrypted using a given passphrase. The underlying key should contain: + - A private key + - A chain code + - A public key + type: string + format: hex + minLength: 256 + maxLength: 256 + +x-walletAddressPoolGap: &walletAddressPoolGap + description: | + Number of consecutive unused addresses allowed. + + **IMPORTANT DISCLAIMER:** Using values other than `20` automatically makes your wallet invalid with regards to BIP-44 address discovery. It means that you **will not** be able to fully restore + your wallet in a different software which is strictly following BIP-44. + + Beside, using large gaps is **not recommended** as it may induce important performance degradations. Use at your own risks. + + **IMPORTANT DISCLAIMER 2:** There is no way to `import` addresses generated outside (e.g. using cardano-addresses) into the wallet. + Wallet only discovers transactions on its used and unused addresses that are within its currently seen `address_pool_gap`. + Transactions on addresses that "belong" to the wallet but happen to be beyond its `address_pool_gap` will not be visible to the wallet. + This is a technical limitation of the industry standard [BIP-44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki). See also [CIP-1852](https://github.com/cardano-foundation/CIPs/blob/master/CIP-1852/CIP-1852.md). + + type: integer + minimum: 10 + maximum: 100000 + example: 20 + default: 20 + +x-walletState: &walletState + <<: *syncProgress + description: Whether a wallet is ready to use or still syncing + +x-walletBalance: &walletBalance + description: Wallet current Ada balance(s). + type: object + required: + - available + - reward + - total + properties: + available: + <<: *amount + description: Available Ada UTxO balance (funds that can be spent without condition). + reward: + <<: *amount + description: The Ada balance of the reward account for this wallet. + total: + <<: *amount + description: Total Ada balance (available balance plus pending change and reward balance). + +x-walletAsset: &walletAsset + description: | + An asset on the Cardano blockchain. An asset is uniquely identified by + its `policy_id` and `asset_name` (together, these form the _asset id_). + + Two assets with the same `asset_name` and `policy_id` are + interchangeable. Yet, different assets with a same `policy_id` but + different `asset_name` are treated as separate assets, as are two + assets with the same `asset_name` but different `policy_id`. + type: object + required: + - policy_id + - asset_name + - quantity + properties: + policy_id: *assetPolicyId + asset_name: *assetName + quantity: *assetQuantity + +x-walletAssets: &walletAssets + description: A flat list of assets (possibly empty). + type: array + items: *walletAsset + +x-walletAssetsBalance: &walletAssetsBalance + description: | + Current non-Ada asset holdings of the wallet. + + The amount of assets available to spend may be less than the total + unspent assets due to transaction change amounts which are yet to + be fully confirmed (pending). + type: object + required: + - available + - total + properties: + available: + <<: *walletAssets + description: | + Available UTxO asset balances (funds that can be spent without + condition). + total: + <<: *walletAssets + description: | + Total asset balances (available balances plus pending change balances). + +x-byronWalletBalance: &byronWalletBalance + description: Byron wallet's current balance(s) + type: object + required: + - available + - total + properties: + available: + <<: *amount + description: Available balance (funds that can be spent) + total: + <<: *amount + description: Total balance (available balance plus pending change) + +x-walletPassphraseInfo :: &walletPassphraseInfo + description: Information about the wallet's passphrase + type: object + required: + - last_updated_at + properties: + last_updated_at: *date + +x-transactionId: &transactionId + description: A unique identifier for this transaction + type: string + format: hex + maxLength: 64 + minLength: 64 + example: 1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1 + +x-datum: &datum + description: A datum hash. + type: string + format: hex + maxLength: 64 + minLength: 64 + example: 16f30f4e8d665d53eb4ab6028bd0ac971809d514c92d423856bc91c49e928faf + +x-transactionInsertedAt: &transactionInsertedAt + description: | + + if: status == in_ledger +
+ Absolute time at which the transaction was inserted in a block. + <<: *blockReference + +x-transactionExpiresAt: &transactionExpiresAt + description: | + + if: status == pending OR status == expired +
+ Absolute time and slot at which the pending transaction TTL (time to live) will lapse. + <<: *slotReference + +x-transactionPendingSince: &transactionPendingSince + description: | + + if: status == pending +
+ The point in time at which a transaction became pending. + <<: *blockReference + +x-transactionDepth: &transactionDepth + description: | + + if: status == in_ledger +
+ Current depth of the transaction in the local chain + <<: *numberOfBlocks + +x-transactionDirection: &transactionDirection + type: string + enum: + - outgoing + - incoming + +x-addresses: &addresses + description: A list of addresses + type: array + minItems: 1 + items: *addressId + +x-transactionInputs: &transactionInputs + description: | + A list of transaction inputs. + + `assets` and `address` are always present for `outgoing` + transactions but generally absent for `incoming` + transactions. This information is present on the Cardano explorer, + but is not tracked by the wallet. + type: array + minItems: 0 + items: + type: object + required: + - id + - index + properties: + address: *addressId + amount: *amount + assets: *walletAssets + id: *transactionId + index: + type: integer + minimum: 0 + +x-referenceInput: &referenceInput + description: | + A reference input. + type: object + required: + - id + - index + properties: + id: *transactionId + index: + type: integer + minimum: 0 + +x-transactionCollateral: &transactionCollateral + description: | + A list of transaction inputs used for collateral. + type: array + minItems: 0 + items: + type: object + required: + - id + - index + properties: + address: *addressId + amount: *amount + id: *transactionId + index: + type: integer + minimum: 0 + +x-derivationSegment: &derivationSegment + description: | + An individual segment within a derivation path. + + The `H` suffix indicates a _Hardened_ child private key, which + means that children of this key cannot be derived from the public + key. Indices without a `H` suffix are called _Soft_. + type: string + example: 1852H + +x-derivationPath: &derivationPath + description: A path for deriving a child key from a parent key. + type: array + minItems: 1 + items: *derivationSegment + +x-transactionOutputs: &transactionOutputs + description: | + A list of target outputs with amounts specified. + + When creating a new transaction, the wallet software ensures that all + user-specified transaction outputs have ada amounts that satisfy the ledger + minimum UTxO rule: + + - If a user-specified transaction output has an ada `amount` that is + **zero**, the wallet software will automatically assign a minimal amount + of ada to the output so that it satisfies the ledger minimum UTxO rule. + + - If a user-specified transaction output has an ada `amount` that is + **non-zero**, the wallet software will verify that the specified amount + is large enough to satisfy the ledger minimum UTxO rule. If the amount is + not large enough, the wallet software will return a `utxo_too_small` + error, together with a revised ada amount that does satisfy the minimum + UTxO rule. + + type: array + minItems: 0 + items: + type: object + required: + - address + - amount + properties: + address: *addressId + amount: *amount + assets: *walletAssets + +x-transactionCollateralOutputs: &transactionCollateralOutputs + description: A list of collateral return outputs with amounts specified. + type: array + minItems: 0 + maxItems: 1 + items: + type: object + required: + - address + - amount + properties: + address: *addressId + amount: *amount + assets: *walletAssets + +x-delegationAction: &delegationAction + description: | + A delegation action. + + Pool id is only required for "join". + type: object + required: + - action + properties: + action: + type: string + enum: ["quit", "join"] + pool: *stakePoolId + +x-delegationTarget: &delegationTarget + <<: *stakePoolId + description: A unique Stake-Pool identifier (present only if status = `delegating`) + +x-rewardAccountPath: &rewardAccountPath + type: array + minItems: 5 + maxItems: 5 + items: + type: string + +x-certificate: &certificate + description: | + A delegation certificate belonging to wallet + + Only for 'join_pool' the 'pool' property is required. + type: object + required: + - certificate_type + - reward_account_path + properties: + certificate_type: + type: string + enum: ["join_pool", "quit_pool", "register_reward_account"] + pool: + <<: *stakePoolId + reward_account_path: + <<: *rewardAccountPath + +x-certificateNotOurs: &certificateNotOurs + description: | + A delegation certificate not belonging to wallet + + Only for 'join_pool' the 'pool' property is required. + type: object + required: + - certificate_type + - reward_account + properties: + certificate_type: + type: string + enum: ["join_pool_external", "quit_pool_external", "register_reward_account_external"] + pool: + <<: *stakePoolId + reward_account: + <<: *stakeAddress + +x-otherCertificate: &otherCertificate + type: object + required: + - certificate_type + properties: + certificate_type: + type: string + enum: ["mir", "genesis"] + +x-transactionRedemptionRequest: &transactionRedemptionRequest + <<: *walletMnemonicSentence + description: | + When provided, attempts to withdraw rewards from the default stake address + corresponding to the given mnemonic. + + Should the rewards be null or too small to be worth withdrawing (i.e. the + cost of adding them into the transaction is more than their own intrinsic + value), the server will reject the request with a + `withdrawal_not_beneficial` error. + + withdrawal field | reward balance | result + --- | --- | --- + any recovery phrase | too small | x Error 403 `withdrawal_not_beneficial` + any recovery phrase | big enough | ✓ withdrawal generated + +x-transactionWithdrawalRequestSelf: &transactionWithdrawalRequestSelf + type: string + enum: ["self"] + description: | + When provided, instruments the server to automatically withdraw rewards from the source wallet when they are deemed + sufficient (i.e. they contribute to the balance for at least as much as they cost). + + As a consequence, the resulting transaction may or may not have a withdrawal object. Summarizing: + + withdrawal field | reward balance | result + --- | --- | --- + `null` | too small | ✓ no withdrawals generated + `null` | big enough | ✓ no withdrawals generated + `"self"` | too small | ✓ no withdrawals generated + `"self"` | big enough | ✓ withdrawal generated + +x-transactionWithdrawals: &transactionWithdrawals + description: A list of withdrawals from stake addresses. + type: array + minItems: 0 + items: + type: object + additionalProperties: false + required: + - stake_address + - amount + properties: + stake_address: *stakeAddress + amount: *amount + +x-ours: &ours + type: string + enum: ["ours"] + description: | + Used when withdrawal or output is ours. + +x-transactionWithdrawalsGeneral: &transactionWithdrawalsGeneral + description: | + A list of withdrawals from stake addresses. Withdrawal belonging to the wallet + is underlined. + type: array + minItems: 0 + items: + type: object + additionalProperties: false + required: + - stake_address + - amount + properties: + stake_address: *stakeAddress + amount: *amount + context: *ours + +x-softIndex: &softIndex + type: integer + minimum: 0 + maximum: 2147483647 + description: A soft derivation index. + +x-multiDelegationAction: &multiDelegationAction + description: | + A delegation action for a given stake key denoted by its soft index. + Pool id is only required for "join". + Stake key index are required for both actions. + oneOf: + - type: object + required: + - join + properties: + join: + type: object + required: + - pool + - stake_key_index + properties: + pool: *stakePoolId + stake_key_index: *derivationSegment + - type: object + required: + - quit + properties: + quit: + type: object + required: + - stake_key_index + properties: + stake_key_index: *derivationSegment + +x-transactionDelegations: &transactionDelegations + description: | +

status: stable

+ + A list of staking actions (joining, rejoining or leaving from stake pools). + Using '0H' stake key index is supported at this moment. This will change with + multi-account support. + Only one delegation action can be used. + type: array + minItems: 0 + items: + <<: *multiDelegationAction + +x-transactionChange: &transactionChange + description: A list of transaction change outputs. + type: array + minItems: 0 + items: + type: object + required: + - address + - amount + - derivation_path + properties: + address: *addressId + amount: *amount + assets: *walletAssets + derivation_path: *derivationPath + +x-transactionResolvedInputs: &transactionResolvedInputs + description: A list of transaction inputs + type: array + items: + type: object + required: + - id + - index + - address + - amount + - derivation_path + properties: + address: *addressId + amount: *amount + assets: *walletAssets + id: *transactionId + derivation_path: *derivationPath + index: + type: integer + minimum: 0 + +x-transactionInputsOutsideWallet: &transactionInputsOutsideWallet + description: | + A transaction input not belonging to a given wallet. + type: object + required: + - id + - index + properties: + id: *transactionId + index: + type: integer + minimum: 0 + +x-transactionInputsInsideWallet: &transactionInputsInsideWallet + description: | + A transaction input belonging to a given wallet. + type: object + required: + - id + - index + - address + - amount + - derivation_path + properties: + address: *addressId + amount: *amount + assets: *walletAssets + id: *transactionId + derivation_path: *derivationPath + index: + type: integer + minimum: 0 + +x-transactionInputsGeneral: &transactionInputsGeneral + type: array + minItems: 0 + items: + oneOf: + - <<: *transactionInputsOutsideWallet + title: tx inputs without source not belonging to a given wallet + - <<: *transactionInputsInsideWallet + title: tx inputs belonging to a given wallet + +x-transactionOutputsOutsideWallet: &transactionOutputsOutsideWallet + description: | + A transaction output not belonging to the wallet + type: object + required: + - address + - amount + properties: + address: *addressId + amount: *amount + assets: *walletAssets + +x-transactionOutputsInsideWallet: &transactionOutputsInsideWallet + description: | + A transaction output not belonging to the wallet + type: object + required: + - address + - amount + - derivation_path + properties: + address: *addressId + amount: *amount + assets: *walletAssets + derivation_path: *derivationPath + +x-transactionOutputsGeneral: &transactionOutputsGeneral + type: array + minItems: 0 + items: + oneOf: + - <<: *transactionOutputsOutsideWallet + title: tx outputs not belonging to a given wallet + - <<: *transactionOutputsInsideWallet + title: tx outputs belonging to a given wallet + +x-transactionCollateralOutputsGeneral: &transactionCollateralOutputsGeneral + type: array + minItems: 0 + maxItems: 1 + items: + oneOf: + - <<: *transactionOutputsOutsideWallet + title: tx outputs not belonging to a given wallet + - <<: *transactionOutputsInsideWallet + title: tx outputs belonging to a given wallet + +x-transactionResolvedCollateral: &transactionResolvedCollateral + description: A list of transaction inputs used for collateral + type: array + items: + type: object + required: + - id + - index + - address + - amount + - derivation_path + properties: + address: *addressId + amount: *amount + id: *transactionId + derivation_path: *derivationPath + index: + type: integer + minimum: 0 + +x-transactionResolvedWithdrawals: &transactionResolvedWithdrawals + description: A list of withdrawals from stake addresses. + type: array + minItems: 0 + items: + type: object + additionalProperties: false + required: + - stake_address + - derivation_path + - amount + properties: + stake_address: *stakeAddress + derivation_path: *derivationPath + amount: *amount + +x-serialisedTransactionBase64: &serialisedTransactionBase64 + description: | + The CBOR-encoded transaction, represented in base64 encoding. + This always includes the transaction body and the witness set, even if the + latter is empty. + type: string + format: base64 + +x-serialisedTransactionHex: &serialisedTransactionHex + description: | + The CBOR-encoded transaction, represented in hexadecimal encoding (base-16). + This always includes the transaction body and the witness set, even if the + latter is empty. + type: string + format: hex + +x-serialisedTransactionEncoded: &serialisedTransactionEncoded + description: | + The CBOR-encoded transaction, represented in either hex or base64 encoding. + This always includes the transaction body and the witness set, even if the + latter is empty. + type: string + format: "base64|base16" + +x-signedTransactionBlob: &signedTransactionBlob + description: Signed transaction message binary blob. + type: string + format: binary + +x-transactionBodyBlob: &transactionBodyBlob + description: CBOR-encoded transaction body + type: string + format: binary + +x-transactionStatus: &transactionStatus + description: | + Current transaction status. + + ``` + *-----------* + ---> | PENDING |----------------* + *-----------* | + | | + V V + *-----------* *-----------* + | |----------> EXPIRED | + | | (ttl) *-----------* + | SUBMITTED | + | <----------------* + | | | + *-----------* (rollback) + | | + (in ledger) *-----------* + | | | + *---------------> IN_LEDGER | + | | + *-----------* + ``` + type: string + enum: + - pending + - submitted + - in_ledger + - expired + +x-transactionSerializedMetadata: &transactionSerializedMetadata + type: string + format: base64 + description: Transaction metadata, serialized according to the expected on-chain binary format, base64-encoded. + +x-transactionMetadata: &transactionMetadata + description: | + **⚠️ WARNING ⚠️** + + _Please note that metadata provided in a transaction will be + stored on the blockchain forever. Make sure not to include any sensitive data, + in particular personally identifiable information (PII)._ + + Extra application data attached to the transaction. + + Cardano allows users and developers to embed their own + authenticated metadata when submitting transactions. Metadata can + be expressed as a JSON object with some restrictions: + + 1. All top-level keys must be integers between `0` and `2^64 - 1`. + + 2. Each metadata value is tagged with its type. + + 3. Strings must be at most 64 bytes when UTF-8 encoded. + + 4. Bytestrings are hex-encoded, with a maximum length of 64 bytes. + + Metadata aren't stored as JSON on the Cardano blockchain but are + instead stored using a compact binary encoding (CBOR). + + The binary encoding of metadata values supports three simple types: + + * Integers in the range `-(2^64 - 1)` to `2^64 - 1` + * Strings (UTF-8 encoded) + * Bytestrings + + And two compound types: + + * Lists of metadata values + * Mappings from metadata values to metadata values + + It is possible to transform any JSON object into this schema. + + However, if your application uses floating point values, they will + need to be converted somehow, according to your + requirements. Likewise for `null` or `bool` values. When reading + metadata from chain, be aware that integers may exceed the + javascript numeric range, and may need special "bigint" parsing. + + # with oneOf we get errors about the 2 schema being both valid + # anyOf seems broken trying to find properties + anyOf: + - type: object + title: full + nullable: true + additionalProperties: + $ref: "#/components/schemas/TransactionMetadataValue" + example: + 0: { "string": "cardano" } + 1: { "int": 14 } + 2: { "bytes": "2512a00e9653fe49a44a5886202e24d77eeb998f" } + 3: { "list": [ { "int": 14 }, { "int": 42 }, { "string": "1337" } ] } + 4: { "map": [{ "k": { "string": "key" }, "v": { "string": "value" }}, { "k": { "int": 14 }, "v": { "int": 42 } }] } + - type: object + title: simple + nullable: true + additionalProperties: + $ref: "#/components/schemas/TransactionMetadataValueNoSchema" + example: + 0: "cardano" + 1: 14 + 2: [14, 42 , "1337" ] + 3: {"key1": "value" , "key2": 42 } + + # Note: propertyNames pattern not supported in current OpenAPI version. + # propertyNames: + # pattern: '^[0-9]+$' + +x-encryptionMethod: &encryptionMethod + type: string + enum: + - basic + +x-encryptMetadata: &encryptMetadata + description: | + If used then metadata in a transaction is going to be encrypted by + AES 256 using CBC mode which is a default method (called base). + PBKDF2 password stretching is used to get a 32-byte secret key and a 16-byte + initialization vector required in the cipher. + PBKDF2 encryption algorithm using HMAC with the SHA256 hash algorithm is employed, + and 10000 iterations to get key and iv pair are used. + Cipher algorithm uses 8-byte salt, PKCS#7 padding as specified in + https://datatracker.ietf.org/doc/html/rfc5652#section-6.3 is applied. + Only metadata value under `msg` field is encrypted. If `msg` field is missing error + will be emitted. + Metadata encryption is in accordance to CIP 83 (https://cips.cardano.org/cips/cip83/). + type: object + required: + - passphrase + properties: + method: *encryptionMethod + passphrase: *lenientPassphrase + +x-transactionTTL: &transactionTTL + description: | + The TTL (time to live) is the time period in which the transaction + will be accepted into node mempools. + + After the TTL has lapsed, the transaction is considered + expired. At this point, nodes will give up on broadcasting the + transaction, and the wallet will release the funds allocated to + the transaction so they can be used for other payments. + + The TTL should be long enough that the transaction has time to be + propagated through the network and confirmed, but short enough so + that - in the event of failures - UTxO are returned to the wallet + in a timely manner. + + The TTL value is given in seconds. It will be converted to a slot + number internally. + + If the TTL is not provided for a payment, a reasonable default + value will be used. + + <<: *numberOfSeconds + +x-validityBound: &validityBound + oneOf: + - <<: *numberOfSeconds + title: number of seconds + - <<: *numberOfSlots + title: number of slots + +x-stakePoolApparentPerformance: &stakePoolApparentPerformance + description: | + Apparent performance of the stake pool over past epochs. This indicator is computed + using data available to the server. In particular, the server can't reliably know the + stake distribution of past epochs without being during those epochs. The performance + are therefore an average measure that is more accurate for servers that are online + often. + + The performance is a float with double-precision which is _typically_ within `0` and `1`: + + - `0` means that a pool is not performing well. + - `1` means that a pool is performing _as expected_. + - above `1` means the pool is performing beyond expectations. + + Pools that are lucky enough to win most of their slots early in the epoch will tend to look + like they're over-performing for a while. Having a wallet regularly connected to the network + would harmonize the performance and give better results. + + type: number + minimum: 0 + example: 0.5053763440860215 + +x-stakePoolMetadata: &stakePoolMetadata + description: | + Information about the stake pool. + type: object + required: + - ticker + - name + - homepage + additionalProperties: false + properties: + ticker: + type: string + minLength: 3 + maxLength: 5 + example: IOHK + name: + type: string + minLength: 1 + maxLength: 50 + description: + type: string + maxLength: 255 + homepage: + type: string + format: uri + example: https://iohk.io + +x-stakePoolRetirement: &stakePoolRetirement + <<: *epochInfo + description: | + The epoch in which a stake pool retires. + + May be omitted if the wallet hasn't yet found a retirement certificate + for this stake pool. + +x-stakePoolPledge: &stakePoolPledge + <<: *amount + description: | + Minimal stake amount that a stake pool is willing to honor. + + May be omitted if the wallet hasn't found the pool's registration cerificate yet. + +x-stakePoolCost: &stakePoolCost + <<: *amount + description: | + Estimated cost set by the pool operator when registering his pool. + This fixed cost is taken from each reward earned by the pool before splitting rewards between stakeholders. + + May be omitted if the wallet hasn't found the pool's registration cerificate yet. + +x-stakePoolMargin: &stakePoolMargin + <<: *percentage + description: | + Variable margin on the total reward given to an operator before splitting rewards between stakeholders. + + May be omitted if the wallet hasn't found the pool's registration cerificate yet. + +x-stakePoolSaturation: &stakePoolSaturation + type: number + minimum: 0 + description: | + Saturation-level of the pool based on the desired number of pools aimed by the network. + A value above `1` indicates that the pool is saturated. + + The `non_myopic_member_rewards` take oversaturation into account, as specified by the [specs](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec). + + The saturation is based on the live `relative_stake`. The saturation at the end of epoch e, + will affect the rewards paid out at the end of epoch e+3. + + example: 0.74 + +x-non-myopic-member-rewards: &nonMyopicMemberRewards + <<: *amount + description: | + The rewards the wallet can expect to receive at the end of an epoch, in the long term, if delegating to + this pool. + + For more details, see the + [Design Specification for Delegation and Incentives in Cardano](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec) + document. + +x-stakePoolMetrics: &stakePoolMetrics + type: object + required: + - relative_stake + - non_myopic_member_rewards + - produced_blocks + - saturation + properties: + non_myopic_member_rewards: *nonMyopicMemberRewards + relative_stake: + <<: *percentage + description: | + The live pool stake relative to the *total* stake. + + For more details, see the section "Relative Stake: Active vs Total" in + [Design Specification for Delegation and Incentives in Cardano](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec). + saturation: *stakePoolSaturation + produced_blocks: + <<: *numberOfBlocks + description: Number of blocks produced by a given stake pool in its lifetime. + +x-stakePoolFlag: &stakePoolFlag + type: string + enum: + - delisted + +x-stakePoolFlags: &stakePoolFlags + type: array + description: | + Various flags applicable to stake pools. Possible flags: + + | flag | description | + | --- | --- | + | delisted | The pool is marked as delisted on a configured SMASH server; metadata for this pool have therefore been dropped. | + items: *stakePoolFlag + +x-networkInformationSyncProgress: &networkInformationSyncProgress + <<: *syncProgress + description: | + Estimated synchronization progress of the node with the underlying network. Note that this may + change quite arbitrarily as the node may switch to shorter or longer chain forks. + +x-networkClockSyncProgress: &networkClockSyncProgress + <<: *syncClockProgress + description: | + The status progress of syncing local ntp client aiming to get ntp offset. + +x-networkInformationNtpStatus: &networkInformationNtpStatus + type: object + description: | + [Network Time Protocol](https://en.wikipedia.org/wiki/Network_Time_Protocol) information of the server. + + **Important:** This piece of information only makes sense when the server runs on the same host machine as the node. + required: + - status + properties: + status: + type: string + enum: + - available + - unavailable + - pending + offset: + type: object + description: | + + if: status == available +
+ Drift offset of the local clock. + required: + - quantity + - unit + properties: + quantity: + type: integer + example: 14 + unit: + type: string + enum: + - microsecond + +x-networkInformationNodeTip: &networkInformationNodeTip + <<: *blockReference + description: Underlying node's tip + +x-networkInformationProtocolUpdate: &networkInformationProtocolUpdate + type: string + description: | + Whether protocol updates have been submitted and accepted by the network. + enum: + - up_to_date + - update_available + +x-delegationStatus: &delegationStatus + type: string + enum: + - not_delegating + - delegating + - voting + - delegating_and_voting + +x-addressIndex: &addressIndex + type: number + minimum: 0 + # 2 ^ 32 - 1, whole range (soft and hard) for random addresses: + maximum: 4294967295 + description: | + An address derivation index. + +x-gCStatus :: &gCStatus + +x-deposits: &deposits + description: A list of deposits associated with a transaction. + type: array + minItems: 0 + items: *amount + +x-minimumCoins: &minimumCoins + description: | + A list of minimum coin values that each output in a payment must satisfy. The values themselves depends on two things: + + - (a) Some updatable protocol parameters fixed by the network. + - (b) The nature of the outputs (i.e. the kind of assets it includes). + + The list is a direct 1:1 mapping of the requested outputs. Said differently, it has the **same number of items** and **items + are ordered in the same way** as **requested outputs** are ordered. In the case where there's no explicitly requested outputs (e.g. + when calculating fee for delegation), this list is empty. + + For example, an output containing only `Ada` may require to be of at least `1 Ada`. An output containing only an hypothetical `AppleCoin` + may require to also carry a minimum of `1.2 Ada`. Note that no matter what, a minimum coin value is always given in Lovelace / Ada. + + > ℹ️ This mechanism is used by the protocol to protect against flooding of the network with worthless assets. By requiring a minimum coin value to every + UTxO, they are given an intrinsic value indexed itself on the value of Ada. + type: array + minItems: 0 + items: *amount + +x-collateralInputCount: &collateralInputCount + type: integer + minimum: 0 + example: 3 + +x-collateralPercentage: &collateralPercentage + type: integer + minimum: 0 + +x-maximumTokenBundleSize: &maximumTokenBundleSize + type: object + description: | + The maximum size of a serialized `TokenBundle`. The concept was added in Mary where + it was hard-coded to 4000 bytes. In Alonzo it was made an updateable protocol parameter (`_maxValSize`). + required: + - quantity + - unit + properties: + quantity: + type: number + minimum: 0 + example: 4000 + unit: + type: string + enum: + - byte + +x-txScriptValidity: &txScriptValidity + description: | + Indicates whether the phase-2 monetary policy script (e.g. Plutus script) + used in the transaction validated or not. Validity may be null if this + transaction was from an era that doesn't support phase-2 monetary policy + scripts, or is a pending transaction (we don't know if validation passed or + failed until the transaction hits the ledger). + nullable: true + type: string + enum: + - valid + - invalid + +x-rationalAsPair: &rationalAsPair + type: object + required: + - denominator + - numerator + properties: + denominator: + type: integer + minimum: 0 + numerator: + type: integer + minimum: 0 + +x-rationalAsNumber: &rationalAsNumber + type: number # NOTE: intended to be 'integer', but logic to serialize as rationalAsPair is missing. + minimum: 0 + +x-rational: &rational + nullable: false + oneOf: + - <<: *rationalAsNumber + title: rational as number + - <<: *rationalAsPair + title: rational as denominator and numerator + +x-executionUnitPrices: &executionUnitPrices + type: object + description: | + The price of time unit and memory unit used for calculating a fee of a script execution. + required: + - step_price + - memory_unit_price + properties: + step_price: *rational + memory_unit_price: *rational + +############################################################################# +# # +# DEFINITIONS # +# # +############################################################################# + +components: + schemas: + ApiAddressWithPath: &ApiAddressWithPath + type: object + required: + - id + - state + - derivation_path + properties: + id: *addressId + state: *addressState + derivation_path: *derivationPath + + ApiAddressInspect: &ApiAddressInspect + type: object + required: + - address_style + - stake_reference + properties: + address_style: + type: string + enum: + - Shelley + - Icarus + - Byron + stake_reference: + type: string + enum: + - none + - by value + - by pointer + network_tag: + description: Can be null for 'Icarus' and 'Byron' styles. + type: integer + minimum: 0 + spending_key_hash: + type: string + format: base16 + minLength: 56 + maxLength: 56 + spending_key_bech32: + type: string + format: bech32 + stake_key_hash: + type: string + format: base16 + minLength: 56 + maxLength: 56 + stake_key_bech32: + type: string + format: bech32 + script_hash: + type: string + format: base16 + minLength: 64 + maxLength: 64 + script_hash_bech32: + type: string + format: bech32 + pointer: + type: object + additionalProperties: false + required: + - slot_num + - transaction_index + - output_index + properties: + slot_num: + type: integer + minimum: 0 + transaction_index: + type: integer + minimum: 0 + output_index: + type: integer + minimum: 0 + address_root: + description: Only for 'Icarus' and 'Byron' styles. + type: string + format: base16 + derivation_path: + description: Only for 'Byron' style. + type: string + format: base16 + address_type: + description: | + The raw type field of the address. + + Details about possible address types are following (refer also to [cddl](https://github.com/IntersectMBO/cardano-ledger/blob/master/eras/alonzo/test-suite/cddl-files/alonzo.cddl)). + + | address_type | binary prefix | Meaning | + | ------------ |:--------------:|:--------------------------------------------------------:| + | 0 | 0000 | base address: keyhash28,keyhash28 | + | 1 | 0001 | base address: scripthash28,keyhash28 | + | 2 | 0010 | base address: keyhash28,scripthash28 | + | 3 | 0011 | base address: scripthash28,scripthash28 | + | 4 | 0100 | pointer address: keyhash28, 3 variable length uint | + | 5 | 0101 | pointer address: scripthash28, 3 variable length uint | + | 6 | 0110 | enterprise address: keyhash28 | + | 7 | 0111 | enterprise address: scripthash28 | + | 8 | 1000 | byron/icarus | + | 14 | 1110 | reward account: keyhash28 | + | 15 | 1111 | reward account: scripthash28 | + type: integer + minimum: 0 + maximum: 15 + + ApiNetworkTip: &ApiNetworkTip + <<: *slotReference + description: The time slot corresponding the network tip. + + ApiEra: &ApiEra + type: string + enum: + - byron + - shelley + - allegra + - mary + - alonzo + - babbage + - conway + + NetworkInfo: &NetworkInfo + type: object + required: + - protocol_magic + - network_id + properties: + protocol_magic: + description: The unique magic number defining the network the wallet is working on. + type: integer + network_id: + description: A name just distinguishing mainnet from testnets + type: string + enum: + - mainnet + - testnet + + ApiNetworkInformation: &ApiNetworkInformation + type: object + required: + - sync_progress + - node_tip + - node_era + - network_info + - wallet_mode + properties: + sync_progress: *networkInformationSyncProgress + node_tip: *networkInformationNodeTip + network_tip: *ApiNetworkTip + next_epoch: *epochInfo + node_era: *ApiEra + network_info: *NetworkInfo + wallet_mode: + type: string + enum: + - light + - node + + ApiNetworkClock: &ApiNetworkClock + <<: *networkInformationNtpStatus + + nullableEpochInfo: &nullableEpochInfo + <<: *epochInfo + nullable: True + + ApiEraInfo: &ApiEraInfo + type: object + properties: + byron: *nullableEpochInfo + shelley: *nullableEpochInfo + allegra: *nullableEpochInfo + mary: *nullableEpochInfo + alonzo: *nullableEpochInfo + babbage: *nullableEpochInfo + conway: *nullableEpochInfo + description: | + + If and when each era started or will start. + + The object is keyed by era names. The values either describe the epoch boundary + when the era starts (can be in the future or in the past), or are null if not yet + confirmed on-chain. + + If you need to know the current era, see the `node_era` field of + `GET /network/information`. + + > Due to complications with our current tooling, we cannot mark the era names + > as required, but the keys are in fact always present. + + ApiNetworkParameters: &ApiNetworkParameters + type: object + required: + - genesis_block_hash + - blockchain_start_time + - slot_length + - epoch_length + - security_parameter + - active_slot_coefficient + - decentralization_level + - desired_pool_number + - eras + - maximum_collateral_input_count + - maximum_token_bundle_size + properties: + genesis_block_hash: *blockId + blockchain_start_time: *date + slot_length: *numberOfSeconds + epoch_length: *numberOfSlots + security_parameter: *numberOfBlocks + active_slot_coefficient: *percentage + decentralization_level: *percentage + desired_pool_number: *stakePoolsNumber + eras: *ApiEraInfo + maximum_collateral_input_count: + <<: *collateralInputCount + description: | + The maximum number of collateral inputs that can be used in a single + transaction. + minimum_collateral_percentage: + <<: *collateralPercentage + description: | + The minimum required amount of collateral as a percentage of the + total transaction fee. + maximum_token_bundle_size: + <<: *maximumTokenBundleSize + execution_unit_prices: + <<: *executionUnitPrices + + ApiSelectCoinsPayments: &ApiSelectCoinsPayments + type: object + required: + - payments + properties: + payments: *transactionOutputs + withdrawal: *transactionWithdrawalRequestSelf + metadata: *transactionMetadata + + ApiSelectCoinsRedemption: &ApiSelectCoinsRedemption + type: object + required: + - payments + - withdrawal + properties: + payments: *transactionOutputs + withdrawal: *transactionRedemptionRequest + metadata: *transactionMetadata + + ApiSelectCoinsAction: &ApiSelectCoinsAction + type: object + required: + - delegation_action + properties: + delegation_action: *delegationAction + + ApiSelectCoinsData: &ApiSelectCoinsData + type: object + oneOf: + - title: Normal payment + <<: *ApiSelectCoinsPayments + - title: Delegation + <<: *ApiSelectCoinsAction + - title: Reward redemption + <<: *ApiSelectCoinsRedemption + + ApiByronSelectCoinsData: &ApiByronSelectCoinsData + type: object + required: + - payments + properties: + payments: *transactionOutputs + + ApiCoinSelection: &ApiCoinSelection + type: object + required: + - inputs + - outputs + - change + properties: + inputs: *transactionResolvedInputs + outputs: *transactionOutputs + change: *transactionChange + collateral: *transactionResolvedCollateral + withdrawals: *transactionResolvedWithdrawals + certificates: + type: array + items: *certificate + deposits_taken: *deposits + deposits_returned: *deposits + metadata: *transactionSerializedMetadata + + ApiGCStatus: &ApiGCStatus + type: object + description: | + Gives an indication if metadata GC checking for delisted pools + has run and if so, when. + + Possible values are: + - not_applicable -> we're currently not querying a SMASH server for metadata + - not_started -> the GC hasn't started yet, try again in a short while + - restarting -> the GC thread is currently restarting, try again in short while + - has_run -> the GC has run successfully + + When 'status' is 'restarting' or 'has_run' then the field 'last_run' + is set to the last GC time in UTC. + required: + - status + properties: + status: + type: string + enum: + - not_applicable + - not_started + - restarting + - has_run + last_run: *date + + ApiMaintenanceActionPostData: &ApiMaintenanceActionPostData + type: object + required: + - maintenance_action + description: | + The maintenance action to carry out, current values are + - gc_stake_pools -> trigger looking up delisted pools from the remote SMASH server + properties: + maintenance_action: + type: string + enum: ['gc_stake_pools'] + + ApiMaintenanceAction: &ApiMaintenanceAction + type: object + required: + - gc_stake_pools + properties: + gc_stake_pools: *ApiGCStatus + + ApiStakePool: &ApiStakePool + type: object + required: + - id + - metrics + - cost + - margin + - pledge + - flags + properties: + id: *stakePoolId + metrics: *stakePoolMetrics + cost: *stakePoolCost + margin: *stakePoolMargin + pledge: *stakePoolPledge + metadata: *stakePoolMetadata + retirement: *stakePoolRetirement + flags: *stakePoolFlags + + ApiFee: &ApiFee + type: object + required: + - estimated_min + - estimated_max + - minimum_coins + - deposit + properties: + estimated_min: *amount + estimated_max: *amount + minimum_coins: *minimumCoins + deposit: *amount + + ApiPutAddressesData: &ApiPutAddressesData + type: object + required: + - addresses + properties: + addresses: + <<: *addresses + description: The imported addresses. + + ApiVerificationKeyShelley: &ApiVerificationKeyShelley + type: string + format: bech32 + pattern: "^((addr_vk)|(stake_vk)|(addr_vkh)|(stake_vkh))1[0-9a-z]*$" + + ApiVerificationKeyShared: &ApiVerificationKeyShared + type: string + format: bech32 + pattern: "^((addr_shared_vk)|(stake_shared_vk)|(addr_shared_vkh)|(stake_shared_vkh))1[0-9a-z]*$" + + ApiAccountKey: &ApiAccountKey + type: string + format: bech32 + pattern: "^((acct_xvk)|(acct_vk)|(acct_shared_xvk)|(acct_shared_vk))1[0-9a-z]*$" + + ApiAccountKeyShared: &ApiAccountKeyShared + type: string + format: bech32 + pattern: "^((acct_shared_xvk)|(acct_shared_vk))1[0-9a-z]*$" + + ApiPolicyKey: &ApiPolicyKey + type: string + format: bech32 + pattern: "^((policy_vk)|(policy_vkh))1[0-9a-z]*$" + + ApiPostPolicyKeyData: &ApiPostPolicyKeyData + type: object + required: + - passphrase + properties: + passphrase: *walletPassphrase + + ApiPolicyId: &ApiPolicyId + type: object + required: + - policy_id + properties: + policy_id: *assetPolicyId + + ApiPostPolicyIdData: &ApiPostPolicyIdData + type: object + required: + - policy_script_template + properties: + policy_script_template: *ScriptTemplateValue + + ApiTxId: &ApiTxId + type: object + required: + - id + properties: + id: *transactionId + + ApiSerialisedTransaction: &ApiSerialisedTransaction + description: | + An encoded transaction. + required: + - transaction + properties: + transaction: *serialisedTransactionEncoded + + ApiSerialisedTransactionEncoded: &ApiSerialisedTransactionEncoded + description: | + An encoded transaction. + required: + - transaction + properties: + transaction: *serialisedTransactionEncoded + + ApiTokenAmountFingerprint: &ApiTokenAmountFingerprint + type: object + required: + - asset_name + - quantity + - fingerprint + properties: + asset_name: *assetName + quantity: *assetQuantity + fingerprint: *assetFingerprint + + PlutusScriptInfo: &PlutusScriptInfo + type: object + required: + - language_version + - script_hash + properties: + language_version: + type: string + enum: ["v1", "v2"] + script_hash: + type: string + format: hex + minLength: 56 + maxLength: 56 + + AnyScript: &AnyScript + oneOf: + - type: object + title: native script + required: + - script_type + - script + properties: + script_type: + type: string + enum: ["native"] + script: *ScriptValue + reference: *referenceInput + - type: object + title: plutus script + required: + - script_type + - script_info + properties: + script_type: + type: string + enum: ["plutus"] + script_info: *PlutusScriptInfo + reference: *referenceInput + - type: object + title: reference script + required: + - script_type + - script_hash + - references + properties: + script_type: + type: string + enum: ["reference script"] + script_hash: + type: string + format: hex + minLength: 56 + maxLength: 56 + references: + type: array + minItems: 1 + items: *referenceInput + + AnyExplicitScript: &AnyExplicitScript + oneOf: + - type: object + title: native script + required: + - script_type + - script + properties: + script_type: + type: string + enum: ["native"] + script: *ScriptValueGeneral + reference: *referenceInput + - type: object + title: plutus script + required: + - script_type + - script_info + properties: + script_type: + type: string + enum: ["plutus"] + script_info: *PlutusScriptInfo + reference: *referenceInput + + ApiTokens: &ApiTokens + type: object + required: + - policy_id + - policy_script + - assets + properties: + policy_id: *assetPolicyId + policy_script: *AnyScript + assets: + type: array + minItems: 1 + items: *ApiTokenAmountFingerprint + + ApiAssetMintBurn: &ApiAssetMintBurn + type: object + required: + - tokens + properties: + tokens: + type: array + minItems: 0 + items: *ApiTokens + wallet_policy_key_hash: *ApiPolicyKey + wallet_policy_key_index: *derivationSegment + + ApiConstructTransaction: &ApiConstructTransaction + type: object + required: + - transaction + - coin_selection + - fee + properties: + transaction: *serialisedTransactionEncoded + coin_selection: *ApiCoinSelection + fee: *amount + + ApiInputsGeneral: &ApiInputsGeneral + <<: *transactionInputsGeneral + description: | + Inputs that could be external or belong to the wallet. + + ApiOutputsGeneral: &ApiOutputsGeneral + <<: *transactionOutputsGeneral + description: | + Outputs that could be external or belong to the wallet. + + ApiCollateralOutputsGeneral: &ApiCollateralOutputsGeneral + <<: *transactionCollateralOutputsGeneral + description: | + Outputs that could be external or belong to the wallet. + + ApiWithdrawalsGeneral: &ApiWithdrawalsGeneral + <<: *transactionWithdrawalsGeneral + description: | + Withdrawals that could be external or belong to the wallet. + + ApiStakePoolMetadata: &ApiStakePoolMetadata + type: object + required: + - url + - hash + properties: + url: *stakePoolMetadataUrl + hash: *stakePoolMetadataHash + + ApiRegisterPool: &ApiRegisterPool + type: object + required: + - certificate_type + - pool_id + - pool_owners + - pool_margin + - pool_cost + - pool_pledge + properties: + certificate_type: + type: string + enum: ["register_pool"] + pool_id: *stakePoolId + pool_owners: + type: array + minItems: 0 + items: *stakePoolOwner + pool_margin: *stakePoolMargin + pool_cost: *stakePoolCost + pool_pledge: *stakePoolPledge + pool_metadata: *ApiStakePoolMetadata + + ApiDeregisterPool: &ApiDeregisterPool + type: object + required: + - certificate_type + - pool_id + - retirement_epoch + properties: + certificate_type: + type: string + enum: ["deregister_pool"] + pool_id: *stakePoolId + retirement_epoch: *epochNumber + + ApiCertificate: &ApiCertificate + description: | + Any certificate that could occur in an arbitrary transaction: + might be related to delegation, pool activities, genesis or MIR. + oneOf: + - <<: *certificate + title: delegation certificate belonging to the wallet + - <<: *certificateNotOurs + title: delegation certificate not belonging to the wallet + - <<: *ApiRegisterPool + title: pool registration certificate + - <<: *ApiDeregisterPool + title: pool deregistration certificate + - <<: *otherCertificate + title: genesis or MIR certificate + + ApiValidityIntervalExplicit: &ApiValidityIntervalExplicit + type: object + required: + - invalid_before + - invalid_hereafter + properties: + invalid_before: *numberOfSlots + invalid_hereafter: *numberOfSlots + + ApiWitnessCount: &ApiWitnessCount + description: | + Specifies the number of verification key and bootstrap wintesses. + As scripts act as witnesses they are also included. Scripts can be specified + and spent in a given transaction or defined to be consumed later. + In the latter case they are defined in transaction outputs (feature possible from Babbage era) + in one transaction and referenced in other later transaction(s). The script referencing + is realized via including of reference in a reference input. If reference script + is present here it included the form of the script and reference to be used later, + ie. tx id and index of tx out where the script was included. + type: object + required: + - verification_key + - scripts + - bootstrap + properties: + verification_key: *witnessCount + scripts: + type: array + minItems: 0 + items: *AnyExplicitScript + bootstrap: *witnessCount + + ApiDecodedTransaction: &ApiDecodedTransaction + type: object + required: + - id + - fee + - inputs + - outputs + - withdrawals + - mint + - burn + - certificates + - witness_count + properties: + id: *transactionId + fee: *amount + inputs: *ApiInputsGeneral + outputs: *ApiOutputsGeneral + collateral: *ApiInputsGeneral + collateral_outputs: *ApiCollateralOutputsGeneral + withdrawals: *ApiWithdrawalsGeneral + mint: *ApiAssetMintBurn + burn: *ApiAssetMintBurn + certificates: + type: array + minItems: 0 + items: *ApiCertificate + metadata: *transactionMetadata + deposits_taken: *deposits + deposits_returned: *deposits + script_validity: *txScriptValidity + validity_interval: *ApiValidityIntervalExplicit + witness_count: *ApiWitnessCount + + ApiTransaction: &ApiTransaction + type: object + required: + - id + - amount + - fee + - deposit_taken + - deposit_returned + - direction + - inputs + - outputs + - withdrawals + - status + properties: + id: *transactionId + amount: + <<: *amount + description: | + An amount of Ada spent or received, from the perspective of the wallet. + + That is, for outgoing transaction, it represents the amount of Ada consumed + as inputs including the amount of Ada spent as fees or deposits. + + For incoming transaction, it represents the total amount of Ada received to + addresses that belong to the wallet. + fee: *amount + deposit_taken: *amount + deposit_returned: *amount + inserted_at: *transactionInsertedAt + expires_at: *transactionExpiresAt + pending_since: *transactionPendingSince + depth: *transactionDepth + direction: *transactionDirection + inputs: *transactionInputs + outputs: *transactionOutputs + collateral: *transactionCollateral + collateral_outputs: *transactionCollateralOutputs + withdrawals: *transactionWithdrawals + status: *transactionStatus + metadata: *transactionMetadata + script_validity: *txScriptValidity + certificates: + type: array + minItems: 0 + items: *ApiCertificate + mint: *ApiAssetMintBurn + burn: *ApiAssetMintBurn + validity_interval: *ApiValidityIntervalExplicit + script_integrity: *scriptIntegrityHash + extra_signatures: + type: array + minItems: 0 + items: *extraSignatureHash + + x-txBody: &txBody + oneOf: + - <<: *serialisedTransactionBase64 + title: Serialized transaction body + + x-txWits: &txWitnesses + type: array + items: *serialisedTransactionBase64 + title: Serialized transaction witnesses + + ApiSignedTransaction: &ApiSignedTransaction + <<: *ApiSerialisedTransaction + description: | + The result of signing a transaction (serialized and encoded). + + ApiSignedTransactionEncoded: &ApiSignedTransactionEncoded + <<: *ApiSerialisedTransactionEncoded + description: | + The result of signing a transaction (serialized and encoded). + + ApiDRep: &ApiDRep + description: | + Decentralized representative (DRep) + that the wallet is delegating its vote to. + One can abstain, give no confidence vote, + or vote for a representative specified by a key hash or script hash. + Vote delegation can be done together with stake delegation action. + nullable: false + type: string + oneOf: + - enum: + - abstain + - no_confidence + title: casting a default vote + - <<: *drepKeyHash + title: vote to a drep represented by key hash (deprecated) + - <<: *drepScriptHash + title: vote to a drep represented by script hash + - <<: *drepKeyHashNew + title: vote to a drep represented by key hash + + ApiWalletDelegationNext: &ApiWalletDelegationNext + type: object + description: Next delegation status becomes active at the start of the second epoch after the corresponding delegation certificate was discovered. The exact moment is specified by changes_at + required: + - status + - changes_at + properties: + status: *delegationStatus + target: *delegationTarget + voting: *ApiDRep + changes_at: *epochInfo + example: + status: not_delegating + changes_at: + epoch_number: 14 + epoch_start_time: 2020-01-22T10:06:39.037Z + + ApiWalletDelegation: &ApiWalletDelegation + description: Delegation settings + type: object + required: + - active + - next + properties: + active: + type: object + description: Currently active delegation status. + required: + - status + properties: + status: *delegationStatus + target: *delegationTarget + voting: *ApiDRep + example: + status: delegating + target: 1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1 + next: + type: array + items: *ApiWalletDelegationNext + + ApiWallet: &ApiWallet + type: object + required: + - id + - address_pool_gap + - balance + - assets + - delegation + - name + - state + - tip + properties: + id: *walletId + address_pool_gap: *walletAddressPoolGap + balance: *walletBalance + assets: *walletAssetsBalance + delegation: *ApiWalletDelegation + name: *walletName + passphrase: *walletPassphraseInfo + state: *walletState + tip: *blockReference + + ApiByronWallet: &ApiByronWallet + type: object + required: + - id + - balance + - assets + - discovery + - name + - state + - tip + properties: + id: *walletId + balance: *byronWalletBalance + assets: *walletAssetsBalance + discovery: *walletDiscovery + name: *walletName + passphrase: *walletPassphraseInfo + state: *walletState + tip: *blockReference + + ApiWalletPostData: &ApiWalletPostData + type: object + description: Restore from root private key + required: + - name + - mnemonic_sentence + - passphrase + properties: + name: *walletName + mnemonic_sentence: *walletMnemonicSentence + mnemonic_second_factor: *walletSecondFactor + passphrase: *walletPassphrase + address_pool_gap: *walletAddressPoolGap + one_change_address_mode: *oneChangeAddressMode + restoration_mode: *restorationMode + + ApiAccountPostData: &ApiAccountPostData + type: object + description: Restore from account public key + required: + - name + - account_public_key + properties: + name: *walletName + account_public_key: *walletAccountXPubkey + address_pool_gap: *walletAddressPoolGap + restoration_mode: *restorationMode + + ApiWalletOrAccountPostData: &ApiWalletOrAccountPostData + type: object + oneOf: + - <<: *ApiWalletPostData + title: shelley + - <<: *ApiAccountPostData + title: shelley (from xpub) + + ApiActiveSharedWallet: &ApiActiveSharedWallet + type: object + required: + - id + - name + - account_index + - address_pool_gap + - payment_script_template + - balance + - assets + - delegation + - state + - tip + properties: + id: *walletId + name: *walletName + account_index: *derivationSegment + address_pool_gap: *walletAddressPoolGap + passphrase: *walletPassphraseInfo + payment_script_template: *scriptTemplate + delegation_script_template: *scriptTemplate + balance: *walletBalance + assets: *walletAssetsBalance + delegation: *ApiWalletDelegation + state: *walletState + tip: *blockReference + + ApiIncompleteSharedWallet: &ApiIncompleteSharedWallet + type: object + required: + - id + - name + - account_index + - address_pool_gap + - payment_script_template + - state + properties: + id: *walletId + name: *walletName + account_index: *derivationSegment + address_pool_gap: *walletAddressPoolGap + payment_script_template: *scriptTemplate + delegation_script_template: *scriptTemplate + state: + type: object + required: + - status + properties: + status: + description: | + An incomplete shared wallet does not have a complete set + of keys, so the only possible status is `incomplete`. + type: string + enum: + - incomplete + + ApiSharedWallet: &ApiSharedWallet + type: object + oneOf: + - title: Incomplete shared wallet (collecting account public keys for each co-signer) + <<: *ApiIncompleteSharedWallet + - title: Active shared wallet (account public keys for each co-signers is collected) + <<: *ApiActiveSharedWallet + + ApiSharedWalletPostDataFromMnemonics: &ApiSharedWalletPostDataFromMnemonics + type: object + required: + - name + - mnemonic_sentence + - passphrase + - account_index + - payment_script_template + properties: + name: *walletName + mnemonic_sentence: *walletMnemonicSentence + mnemonic_second_factor: *walletSecondFactor + passphrase: *walletPassphrase + account_index: *derivationSegment + payment_script_template: *scriptTemplateEntry + delegation_script_template: *scriptTemplateEntry + script_validation: *validationLevel + one_change_address_mode: *oneChangeAddressMode + + ApiSharedWalletPostDataFromAccountPubX: &ApiSharedWalletPostDataFromAccountPubX + type: object + required: + - name + - account_public_key + - account_index + - payment_script_template + properties: + name: *walletName + account_public_key: *sharedWalletAccountXPubkey + account_index: *derivationSegment + payment_script_template: *scriptTemplateEntry + delegation_script_template: *scriptTemplateEntry + script_validation: *validationLevel + + ApiSharedWalletPostData: &ApiSharedWalletPostData + type: object + oneOf: + - title: Create shared wallet from mnemonics + <<: *ApiSharedWalletPostDataFromMnemonics + - title: Create shared wallet from account public key + <<: *ApiSharedWalletPostDataFromAccountPubX + + ApiSharedWalletPatchData: &ApiSharedWalletPatchData + <<: *cosigners + + ApiAsset: &ApiAsset + type: object + required: + - policy_id + - fingerprint + - asset_name + properties: + policy_id: *assetPolicyId + asset_name: *assetName + fingerprint: *assetFingerprint + metadata: *assetMetadata + metadata_error: + type: string + description: | + If there was an error fetching metadata from the server, + this will be set to one of `fetch` or `parse`, to indicate + the kind of error. + enum: + - fetch + - parse + + ApiWalletMigrationBalance: &ApiWalletMigrationBalance + type: object + required: + - ada + - assets + properties: + ada: *amount + assets: *walletAssets + + ApiWalletMigrationPlan: &ApiWalletMigrationPlan + type: object + required: + - selections + - total_fee + - balance_leftover + - balance_selected + properties: + selections: + type: array + items: *ApiCoinSelection + description: | + The complete set of selections required for a migration. + + Each selection is the basis for a single transaction. + + The ordering of selections within the list is not significant. + After conversion into transactions, the transactions can be + broadcast to the network in any order to perform the migration. + total_fee: + <<: *amount + description: | + The total amount to be paid in fees for a migration. + + This is the total sum of the fees of the individual selections. + balance_leftover: + <<: *ApiWalletMigrationBalance + description: | + The total balance of assets that **cannot** be migrated. + + The **ada** component of this balance is the total sum of all dust + ada entries in the UTxO set. An ada entry is considered to be dust + if its value is not large enough to pay for the marginal cost of + including it in a transaction. + + The **assets** component of this balance is the total sum of all + non-ada assets that cannot currently be migrated. Tokens of a + non-ada asset cannot be migrated if there is insufficient ada + available to pay for their inclusion in a transaction. + balance_selected: + <<: *ApiWalletMigrationBalance + description: | + The total balance of assets that **can** be migrated. + + ApiWalletPassphrase: &ApiWalletPassphrase + type: object + required: + - passphrase + properties: + passphrase: + <<: *lenientPassphrase + description: The source wallet's master passphrase. + + ApiWalletMigrationPlanPostData: &ApiWalletMigrationPlanPostData + type: object + required: + - addresses + properties: + addresses: + <<: *addresses + description: The recipient addresses. + + ApiByronWalletMigrationPostData: &ApiByronWalletMigrationPostData + type: object + required: + - passphrase + - addresses + properties: + passphrase: + <<: *lenientPassphrase + description: The wallet's master passphrase. + addresses: + <<: *addresses + description: The recipient addresses. + + ApiShelleyWalletMigrationPostData: &ApiShelleyWalletMigrationPostData + type: object + required: + - passphrase + - addresses + properties: + passphrase: + <<: *walletPassphrase + description: The wallet's master passphrase. + addresses: + <<: *addresses + description: The recipient addresses. + + ApiWalletUtxoSnapshotEntry: &ApiWalletUtxoSnapshotEntry + type: object + required: + - ada + - assets + properties: + ada: + <<: *amount + description: | + The ada quantity associated with this UTxO entry. + assets: + <<: *walletAssets + description: | + The set of non-ada assets associated with this UTxO entry. + + ApiWalletUtxoSnapshot: &ApiWalletUtxoSnapshot + type: object + required: + - entries + properties: + entries: + type: array + items: *ApiWalletUtxoSnapshotEntry + minItems: 0 + description: | + The complete set of UTxO entries associated with a wallet. + + ApiWalletUTxOsStatistics: &ApiWalletUTxOsStatistics + type: object + required: + - total + - scale + - distribution + properties: + total: *amount + scale: + type: string + enum: + - log10 + distribution: + type: object + additionalProperties: + type: integer + example: + total: + quantity: 42000000 + unit: lovelace + scale: log10 + distribution: + 10: 1 + 100: 0 + 1000: 8 + 10000: 14 + 100000: 32 + 1000000: 3 + 10000000: 0 + 100000000: 12 + 1000000000: 0 + 10000000000: 0 + 100000000000: 0 + 1000000000000: 0 + 10000000000000: 0 + 100000000000000: 0 + 1000000000000000: 0 + 10000000000000000: 0 + 45000000000000000: 0 + + ApiWalletSignData: &ApiWalletSignData + type: object + required: + - passphrase + - metadata + properties: + passphrase: *lenientPassphrase + metadata: *transactionMetadata + + ApiScript: &ApiScript + <<: *script + + ApiPubKey: &ApiPubKey + <<: *credentialPubKey + + AnyAddress: &AnyAddress + type: object + required: + - address + properties: + address: *anyAddress + + ApiCredential: &ApiCredential + <<: *CredentialValue + + ApiAddressData: &ApiAddressData + type: object + nullable: false + properties: + payment: *ApiCredential + stake: + <<: *ApiCredential + example: stake_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7qau558d + validation: *validationLevel + + ApiByronWalletRandomPostData: &ApiByronWalletRandomPostData + type: object + required: + - name + - mnemonic_sentence + - passphrase + properties: + style: + type: string + enum: ["random"] + name: *walletName + passphrase: *walletPassphrase + mnemonic_sentence: + <<: *walletMnemonicSentence + minItems: 12 + maxItems: 24 + + ApiByronWalletRandomXPrvPostData: &ApiByronWalletRandomXPrvPostData + type: object + description: patate + required: + - name + - encrypted_root_private_key + - passphrase_hash + properties: + style: + type: string + enum: ["random"] + name: *walletName + encrypted_root_private_key: + <<: *walletEncryptedRootPrivateKey + deprecated: true + + passphrase_hash: + <<: *walletPassphraseHash + deprecated: true + + ApiByronWalletIcarusPostData: &ApiByronWalletIcarusPostData + type: object + required: + - name + - mnemonic_sentence + - passphrase + properties: + style: + type: string + enum: ["icarus"] + name: *walletName + passphrase: *walletPassphrase + mnemonic_sentence: + <<: *walletMnemonicSentence + minItems: 12 + maxItems: 24 + + ApiByronWalletTrezorPostData: &ApiByronWalletTrezorPostData + type: object + required: + - name + - mnemonic_sentence + - passphrase + properties: + style: + type: string + enum: ["trezor"] + name: *walletName + passphrase: *walletPassphrase + mnemonic_sentence: + <<: *walletMnemonicSentence + minItems: 12 + maxItems: 24 + + ApiByronWalletLedgerPostData: &ApiByronWalletLedgerPostData + type: object + required: + - name + - mnemonic_sentence + - passphrase + properties: + style: + type: string + enum: ["ledger"] + name: *walletName + passphrase: *walletPassphrase + mnemonic_sentence: + <<: *walletMnemonicSentence + minItems: 12 + maxItems: 24 + + ApiWalletPutData: &ApiWalletPutData + type: object + properties: + name: *walletName + + ApiWalletPutDataExtended: &ApiWalletPutDataExtended + type: object + properties: + name: *walletName + one_change_address_mode: *oneChangeAddressMode + + ApiPostAccountKeyData: &ApiPostAccountKeyData + type: object + required: + - passphrase + - format + properties: + passphrase: *walletPassphrase + format: *keyExtended + + ApiPostAccountKeyDataWithPurpose: &ApiPostAccountKeyDataWithPurpose + type: object + required: + - passphrase + - format + properties: + passphrase: *walletPassphrase + format: *keyExtended + purpose: *derivationSegment + + ApiSettingsPutData: &ApiSettingsPutData + type: object + properties: + settings: *settings + + ApiSmashServer: &ApiSmashServer + type: string + pattern: '^https?:\/\/[a-zA-Z0-9-_~.]+(:[0-9]+)?/?$' + example: https://smash.cardano-mainnet.iohk.io/ + description: A base SMASH uri without endpoint path. + + ApiHealthCheck: &ApiHealthCheck + type: object + required: + - health + properties: + health: + type: string + enum: ["available", "unavailable", "unreachable", "no_smash_configured"] + description: | + The status of the SMASH server. Possible values are: + + health | description + --- | --- + `"available"` | server is awaiting your requests + `"unavailable"` | server is running, but currently unavailable, try again in a short time + `"unreachable"` | server could not be reached or didn't return a health status + `"no_smash_configured"` | SMASH is currently not configured, adjust the Settings first + + ApiWalletPutPassphraseOldPassphraseData: &ApiWalletPutPassphraseOldPassphraseData + type: object + required: + - old_passphrase + - new_passphrase + properties: + old_passphrase: + <<: *walletPassphrase + description: The current master passphrase. + new_passphrase: + <<: *walletPassphrase + description: A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds). + + ApiWalletPutPassphraseMnemonicData: &ApiWalletPutPassphraseMnemonicData + type: object + required: + - mnemonic_sentence + - new_passphrase + properties: + mnemonic_second_factor: *walletSecondFactor + mnemonic_sentence: + <<: *walletMnemonicSentence + description: The mnemonic list of words to restore the wallet + new_passphrase: + <<: *walletPassphrase + description: The new master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds) + + ApiWalletPutPassphraseData: &ApiWalletPutPassphraseData + type: object + oneOf: + - <<: *ApiWalletPutPassphraseOldPassphraseData + title: "providing old passphrase" + - <<: *ApiWalletPutPassphraseMnemonicData + title: "providing mnemonic" + + ApiByronWalletPutPassphraseData: &ApiByronWalletPutPassphraseData + type: object + required: + - new_passphrase + properties: + old_passphrase: + <<: *lenientPassphrase + description: The current passphrase if present. + new_passphrase: + <<: *walletPassphrase + description: A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds). + + ApiDecodeTransactionPostData: &ApiDecodeTransactionPostData + type: object + required: + - transaction + properties: + decrypt_metadata: + <<: *encryptMetadata + description: The metadata passphrase for decryption. + transaction: *serialisedTransactionEncoded + + ApiSignTransactionPostData: &ApiSignTransactionPostData + type: object + required: + - passphrase + - transaction + properties: + passphrase: + <<: *lenientPassphrase + description: The wallet's master passphrase. + transaction: *serialisedTransactionEncoded + encoding: + type: string + enum: ["base16", "base64"] + description: Encoding of transaction CBOR returned in response (base64 by default). + + # ADP-908 Deprecated + ApiPostTransactionDataByron: &ApiPostTransactionDataByron + type: object + required: + - payments + - passphrase + properties: + payments: *transactionOutputs + passphrase: + <<: *lenientPassphrase + description: The wallet's master passphrase. + + # ADP-908 Deprecated + ApiPostTransactionData: &ApiPostTransactionData + type: object + required: + - payments + - passphrase + properties: + passphrase: + <<: *lenientPassphrase + description: The wallet's master passphrase. + payments: *transactionOutputs + withdrawal: *transactionWithdrawalRequestSelf + metadata: *transactionMetadata + time_to_live: *transactionTTL + + # ADP-908 Deprecated + ApiPostRedemptionData: &ApiPostRedemptionData + type: object + required: + - payments + - passphrase + - withdrawal + properties: + passphrase: + <<: *lenientPassphrase + description: The wallet's master passphrase. + payments: *transactionOutputs + withdrawal: *transactionRedemptionRequest + + # ADP-910 Deprecated + ApiPostTransactionFeeDataByron: &ApiPostTransactionFeeDataByron + type: object + required: + - payments + properties: + payments: *transactionOutputs + + # ADP-910 Deprecated + ApiPostTransactionFeeData: &ApiPostTransactionFeeData + type: object + required: + - payments + properties: + payments: *transactionOutputs + withdrawal: *transactionWithdrawalRequestSelf + metadata: *transactionMetadata + time_to_live: *transactionTTL + + # ADP-910 Deprecated + ApiPostRedemptionFeeData: &ApiPostRedemptionFeeData + type: object + required: + - payments + - withdrawal + properties: + payments: *transactionOutputs + withdrawal: *transactionRedemptionRequest + + ApiPostRandomAddressData: &ApiPostRandomAddressData + type: object + required: + - passphrase + properties: + passphrase: *lenientPassphrase + address_index: *addressIndex + + ApiValidityInterval: &ApiValidityInterval + description: | + Specify only invalid_before or invalid_hereafter or both. + + Please note that, if not set, the default values are: + - `"invalid_before": {"quantity":0, "unit":"slot"}` + - `"invalid_hereafter":{"quantity":7200, "unit":"second"}` + + Which translates to 2h transaction TTL. + type: object + properties: + invalid_before: *validityBound + invalid_hereafter: *validityBound + + ApiPaymentDestination: &ApiPaymentDestination + <<: *transactionOutputs + + ApiMintData: &ApiMintData + type: object + required: + - quantity + properties: + receiving_address: *addressId + quantity: *assetQuantity + + ApiBurnData: &ApiBurnData + type: object + required: + - quantity + properties: + quantity: *assetQuantity + + ApiMintBurnOperation: &ApiMintBurnOperation + type: object + oneOf: + - title: "mint" + properties: + mint: *ApiMintData + - title: "burn" + properties: + burn: *ApiBurnData + + ApiMintBurnData: &ApiMintBurnData + oneOf: + - type: object + title: minting via script template + required: + - operation + - policy_script_template + properties: + policy_script_template: *ScriptTemplateValue + asset_name: *assetName + operation: *ApiMintBurnOperation + - type: object + title: minting via script reference + required: + - operation + - reference_input + - policy_id + properties: + reference_input: *referenceInput + policy_id: *assetPolicyId + asset_name: *assetName + operation: *ApiMintBurnOperation + + ApiConstructTransactionData: &ApiConstructTransactionData + description: At least one field needs to be chosen + type: object + properties: + payments: *ApiPaymentDestination + withdrawal: *transactionWithdrawalRequestSelf + metadata: *transactionMetadata + encrypt_metadata: *encryptMetadata + mint_burn: + type: array + items: *ApiMintBurnData + minItems: 1 + description: | + An entry for each unique asset to be minted and/or burned, + containing helpful information. + vote: *ApiDRep + delegations: *transactionDelegations + validity_interval: *ApiValidityInterval + reference_policy_script_template: + <<: *ScriptTemplateValue + description: | + Optional policy script template that could be used as a script reference + in another transaction. + In the current transaction, the script will be included as + the first output (`index = 0`). + The script is constructed by replacing the cosigner + with the policy public key of the wallet. + In future transactions, the reference script can be used + by any wallet multiple times + by referencing the current transaction `id` and `index = 0`. + The script template must contain a single cosigner only, but it may include time locks. + encoding: + type: string + enum: ["base16", "base64"] + description: Encoding of transaction CBOR returned in response (base64 by default). + + CredentialValue: *CredentialValue + + ScriptValue: *ScriptValue + + ScriptValueGeneral: *ScriptValueGeneral + + ScriptTemplateValue: *ScriptTemplateValue + + # https://github.com/IntersectMBO/cardano-ledger/blob/8d836e61bb88bda4a6a5c00694735928390067a1/shelley/chain-and-ledger/executable-spec/src/Shelley/Spec/Ledger/MetaData.hs#L48-L65 + TransactionMetadataValue: &TransactionMetadataValue + oneOf: + - title: String + type: object + required: + - string + properties: + string: + type: string + maxLength: 64 + + - title: Int + type: object + required: + - int + properties: + int: + type: integer + + - title: ByteString + type: object + required: + - bytes + properties: + bytes: + type: string + pattern: "^[0-9a-fA-F]*$" + maxLength: 128 + + - title: List + type: object + required: + - list + properties: + list: + type: array + items: + $ref: "#/components/schemas/TransactionMetadataValue" + + - title: Map + type: object + required: + - map + properties: + map: + type: array + items: + type: object + nullable: true + properties: + k: + $ref: "#/components/schemas/TransactionMetadataValue" + v: + $ref: "#/components/schemas/TransactionMetadataValue" + + TransactionMetadataValueNoSchema: &TransactionMetadataValueNoSchema + oneOf: + - title: String + type: string + + - title: Int + type: integer + + - title: List + type: array + items: + $ref: "#/components/schemas/TransactionMetadataValueNoSchema" + + - title: Map + type: object + additionalProperties: + $ref: "#/components/schemas/TransactionMetadataValueNoSchema" + + ApiGetSettings: &ApiGetSettings + type: object + required: + - pool_metadata_source + properties: + pool_metadata_source: *poolMetadataSource + + SomeByronWalletPostData: &SomeByronWalletPostData + oneOf: + - <<: *ApiByronWalletRandomPostData + title: random + - <<: *ApiByronWalletIcarusPostData + title: icarus + - <<: *ApiByronWalletTrezorPostData + title: trezor + - <<: *ApiByronWalletLedgerPostData + title: ledger + - <<: *ApiAccountPostData + title: icarus/trezor/ledger (from xpub) + - <<: *ApiByronWalletRandomXPrvPostData + title: random (from xprv) + + ApiOurStakeKey: &ApiOurStakeKey + type: object + required: + - index + - key + - stake + - reward_balance + - delegation + properties: + index: *softIndex + key: *stakeAddress + stake: *amount + reward_balance: *amount + delegation: *ApiWalletDelegation + + ApiForeignStakeKey: &ApiForeignStakeKey + type: object + required: + - key + - stake + - reward_balance + properties: + key: *stakeAddress + stake: *amount + reward_balance: *amount + ApiNullStakeKey: &ApiNullStakeKey + type: object + required: + - stake + properties: + stake: *amount + description: | + The absence of a stake key. The `stake` field shows how much of the wallet funds + are not associated with an identifiable stake key. + + Most likely, these funds are associated with enterprise addresses lacking staking rights. + But they /could/ also be associate with more rare types of addresses like pointer addresses. + ApiStakeKeys: &ApiStakeKeys + type: object + required: + - ours + - foreign + - "none" + properties: + ours: + type: array + items: *ApiOurStakeKey + description: | + Stake keys belonging to the wallet. + foreign: + type: array + items: *ApiForeignStakeKey + description: | + Stake keys found in the wallet's UTxO, but does not belong to the wallet. + + "none": *ApiNullStakeKey + + ApiRedeemerSpending: &ApiRedeemerSpending + type: object + required: + - purpose + - data + - input + properties: + purpose: + type: string + enum: ["spending"] + data: + type: string + format: base16 + input: + type: object + required: + - id + - index + properties: + id: *transactionId + index: + type: integer + minimum: 0 + + ApiRedeemerMinting: &ApiRedeemerMinting + type: object + required: + - purpose + - data + - policy_id + properties: + purpose: + type: string + enum: ["minting"] + data: + type: string + format: base16 + policy_id: + type: string + format: hex + maxLength: 56 + + ApiRedeemerRewarding: &ApiRedeemerRewarding + type: object + required: + - purpose + - data + - stake_address + properties: + purpose: + type: string + enum: ["rewarding"] + data: + type: string + format: base16 + stake_address: *stakeAddress + + ApiRedeemer: &ApiRedeemer + oneOf: + - title: spending + <<: *ApiRedeemerSpending + + - title: minting + <<: *ApiRedeemerMinting + + - title: rewarding + <<: *ApiRedeemerRewarding + + ApiBalanceTransactionPostData: &ApiBalanceTransactionPostData + type: object + required: + - transaction + properties: + transaction: *serialisedTransactionEncoded + inputs: + description: | + Mapping from inputs (`id`, `ix`) in the supplied `transaction` binary to outputs (`amount`, `assets`, ...). It is not required to include inputs present in the `cardano-node` UTxO, as `cardano-wallet` will automatically query for them. + + In other words, this field can be left empty unless the supplied `transaction` contains inputs referring to pending transactions. + type: array + items: + type: object + required: + - id + - index + - address + - amount + - assets + properties: + id: *transactionId + index: + type: integer + minimum: 0 + address: *addressId + amount: *amount + datum: *datum + assets: *walletAssets + redeemers: + description: A list of redeemers data with their purpose. The redeemers in the `transaction` binary will be overwritten by this value. + type: array + items: *ApiRedeemer + encoding: + type: string + enum: ["base16", "base64"] + description: Encoding of transaction CBOR returned in response (base64 by default). + + ApiBlockHeader: &ApiBlockHeader + description: | + A Block Header. + required: + - header_hash + - slot_no + - block_height + properties: + header_hash: *blockId + slot_no: *numberOfSlots + block_height: *numberOfBlocks + +############################################################################# +# # +# PARAMETERS # +# # +############################################################################# + +x-parametersWalletId: ¶metersWalletId + in: path + name: walletId + required: true + schema: + type: string + format: hex + maxLength: 40 + minLength: 40 + +x-parametersIntendedStakeAmount: ¶metersIntendedStakeAmount + in: query + name: stake + required: true + schema: + type: integer + minimum: 0 + maximum: 45000000000000000 # 45 B ada (in Lovelace) + description: | + The stake the user intends to delegate in Lovelace. Required. + +x-parametersTransactionId: ¶metersTransactionId + in: path + name: transactionId + required: true + schema: + type: string + format: hex + maxLength: 64 + minLength: 64 + +x-parametersStakePoolId: ¶metersStakePoolId + in: path + name: stakePoolId + required: true + schema: + type: string + format: hex|bech32 + +x-parametersAddressId: ¶metersAddressId + in: path + name: addressId + required: true + schema: + type: string + format: base58 + example: DdzFFzCqrhtCNjPk5Lei7E1FxnoqMoAYtJ8VjAWbFmDb614nNBWBwv3kt6QHJa59cGezzf6piMWsbK7sWRB5sv325QqWdRuusMqqLdMt + +x-parametersRole: ¶metersRole + in: path + name: role + required: true + schema: + type: string + enum: + - utxo_external + - utxo_internal + - mutable_account + +x-parametersDerivationSegment: ¶metersDerivationSegment + in: path + name: index + required: true + schema: *derivationSegment + +x-parametersDerivationHash: ¶metersDerivationHash + in: query + name: hash + schema: + type: boolean + default: false + description: | + Whether to return the key hash instead of the key. + +x-parametersStartDate: ¶metersStartDate + in: query + name: start + description: | + An optional start time in ISO 8601 date-and-time format. Basic and + extended formats are both accepted. Times can be local (with a + timezone offset) or UTC. + + If both a start time and an end time are specified, then the start + time must not be later than the end time. + + Example: `2008-08-08T08:08:08Z` + schema: + type: string + format: ISO 8601 + +x-parametersEndDate: ¶metersEndDate + in: query + name: end + description: | + An optional end time in ISO 8601 date-and-time format. Basic and + extended formats are both accepted. Times can be local (with a + timezone offset) or UTC. + + If both a start time and an end time are specified, then the start + time must not be later than the end time. + + Example: `2008-08-08T08:08:08Z` + schema: + type: string + format: ISO 8601 + +x-parametersSortOrder: ¶metersSortOrder + in: query + name: order + description: An optional sort order. + schema: + type: string + enum: + - ascending + - descending + default: descending + +x-parametersMaxCount: ¶metersMaxCount + in: query + name: max_count + description: | + An optional maximum count. + schema: + type: integer + minimum: 1 + +x-parametersAddress: ¶metersAddress + in: query + name: address + description: | + An optional address. + If given, the list of transactions will be filtered + to only contain transactions that refer to this address in their inputs or outputs. + This may exclude transactions whose inputs reference outside transactions + that are not part of the transaction history of the wallet. + schema: *addressId + +x-parametersAddressState: ¶metersAddressState + in: query + name: state + description: An optional filter on the address state. + schema: + type: string + enum: + - used + - unused + +x-parametersForceNtpCheck: ¶metersForceNtpCheck + in: query + name: forceNtpCheck + allowEmptyValue: true + description: | + NTP checks are cached for short duration to avoid sending too many queries to the central NTP servers. In some cases however, a client may want to force a new check. + + When this flag is set, the request **will block** until NTP server responds or will timeout after a while without any answer from the NTP server. + schema: + type: boolean + +x-parametersMetadataFormat: ¶metersMetadataFormat + in: query + name: simple-metadata + schema: + type: boolean + allowEmptyValue: true + description: | + When present (or equal to true) in the query, the metadata format for the + transaction(s) in the output will be untyped plain json as specified in + [CIP 25](https://cips.cardano.org/cips/cip25/) + +x-parametersMinWithdrawal: ¶metersMinWithdrawal + in: query + name: minWithdrawal + description: | + Returns only transactions that have at least one withdrawal above the given amount. + This is particularly useful when set to `1` in order to list the withdrawal history of a wallet. + schema: + type: integer + minimum: 1 + +x-parametersPolicyId: ¶metersPolicyId + in: path + name: policyId + required: true + schema: + type: string + format: hex + maxLength: 56 + minLength: 56 + +x-parametersAssetName: ¶metersAssetName + in: path + name: assetName + required: true + schema: + type: string + format: hex + maxLength: 64 + +x-parametersDRepId: ¶metersDRepId + in: path + name: drepId + required: true + schema: *ApiDRep + +############################################################################# +# # +# RESPONSES # +# # +############################################################################# + +x-responsesErr: &responsesErr + type: object + required: + - message + - code + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + description: A specific error code for this error, more precise than HTTP ones. + example: an_error_code + +x-errNotFound: &errNotFound + <<: *responsesErr + title: not_found + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['not_found'] + +x-errSoftDerivationRequired: &errSoftDerivationRequired + <<: *responsesErr + title: not_found + properties: + message: + type: string + description: A descriptive error message. + code: + type: string + enum: ['soft_derivation_required'] + +x-errHardenedDerivationRequired: &errHardenedDerivationRequired + <<: *responsesErr + title: not_found + properties: + message: + type: string + description: | + Occurs when hardened derivation is required and soft index is used + (without suffix 'H'). + code: + type: string + enum: ['hardened_derivation_required'] + +x-errNoUtxosAvailable: &errNoUtxosAvailable + <<: *responsesErr + title: no_utxos_available + properties: + message: + type: string + description: | + Indicates that the wallet has no unspent transaction outputs (UTxOs) + available. A transaction must spend at least one UTxO in order to be + accepted for inclusion on the Cardano blockchain. + code: + type: string + enum: ['no_utxos_available'] + +x-errWalletNotInitialized: &errWalletNotInitialized + <<: *responsesErr + title: wallet_not_initialized + properties: + message: + type: string + description: | + May occur when the database for the requested wallet is not initialized. + code: + type: string + enum: ['wallet_not_initialized'] + +x-errNoSuchWallet: &errNoSuchWallet + <<: *responsesErr + title: no_such_wallet + properties: + message: + type: string + description: | + May occur when a given walletId does not match with any known + wallets (because it has been deleted, or has never existed). + code: + type: string + enum: ['no_such_wallet'] + info: + type: object + required: + - wallet_id + properties: + wallet_id: *walletId + +x-errNoSuchTransaction: &errNoSuchTransaction + <<: *responsesErr + title: no_such_transaction + properties: + message: + type: string + description: May occur when a given transactionId does not match with any known transactions. + code: + type: string + enum: ['no_such_transaction'] + info: + type: object + required: + - transaction_id + properties: + transaction_id: *transactionId + +x-errTransactionAlreadyInLedger: &errTransactionAlreadyInLedger + <<: *responsesErr + title: transaction_already_in_ledger + properties: + message: + type: string + description: Occurs when attempting to delete a transaction which is neither pending nor expired. + code: + type: string + enum: ['transaction_already_in_ledger'] + info: + type: object + required: + - transaction_id + properties: + transaction_id: *transactionId + +x-errWalletAlreadyExists: &errWalletAlreadyExists + <<: *responsesErr + title: wallet_already_exists + properties: + message: + type: string + description: May occur when a otherwise valid request would yield a wallet that already exists. + code: + type: string + enum: ['wallet_already_exists'] + +x-errNoRootKey: &errNoRootKey + <<: *responsesErr + title: no_root_key + properties: + message: + type: string + description: May occur when an action require a signing key but the wallet has only access to verification keys. + code: + type: string + enum: ['no_root_key'] + +x-errWalletMetadataNotFound: &errWalletMetadataNotFound + <<: *responsesErr + title: wallet_metadata_not_found + properties: + message: + type: string + description: | + Indicates that it was not possible to find any metadata for the given + wallet within the database. + + May occur when a shared wallet has not yet become active after being in + the incomplete state. + code: + type: string + enum: ['wallet_metadata_not_found'] + +x-errWrongEncryptionPassphrase: &errWrongEncryptionPassphrase + <<: *responsesErr + title: wrong_encryption_passphrase + properties: + message: + type: string + description: May occur when the given spending passphrase is wrong. + code: + type: string + enum: ['wrong_encryption_passphrase'] + info: + type: object + required: + - wallet_id + properties: + wallet_id: *walletId + +x-errWrongMnemonic: &errWrongMnemonic + <<: *responsesErr + title: wrong_mnemonics + properties: + message: + type: string + description: May occur when the given mnemonic is wrong. + code: + type: string + enum: ['wrong_mnemonic'] + +x-errMalformedTxPayload: &errMalformedTxPayload + <<: *responsesErr + title: malformed_tx_payload + properties: + message: + type: string + description: May occur when submitting a malformed serialized transaction. + code: + type: string + enum: ['malformed_tx_payload'] + +x-errMempoolIsFull: &errMempoolIsFull + <<: *responsesErr + title: mempool_is_full + properties: + message: + type: string + description: May occur when submitting a serialized transaction to a node with full mempool. + code: + type: string + enum: [mempool_is_full] + +x-errTokensMintedButNotSpentOrBurned: &errTokensMintedButNotSpentOrBurned + <<: *responsesErr + title: tokens_minted_but_not_spent_or_burned + properties: + message: + type: string + description: | + Returned when a user mints funds but does not spend or burn them all. + code: + type: string + enum: ['tokens_minted_but_not_spent_or_burned'] + +# TODO: Map this error to the place it belongs. +x-errKeyNotFoundForAddress: &errKeyNotFoundForAddress + <<: *responsesErr + title: key_not_found_for_address + properties: + message: + type: string + description: Should never happen unless the server screwed up and has lost track of previously known addresses. + code: + type: string + enum: ['key_not_found_for_address'] + +x-errNotEnoughMoney: &errNotEnoughMoney + <<: *responsesErr + title: not_enough_money + properties: + message: + type: string + description: | + Indicates that there's not enough money in the wallet for the operation + to succeed. + + The 'shortfall' object indicates the additional quantity of each asset + that would be needed in order for the operation to succeed. + code: + type: string + enum: ['not_enough_money'] + info: + type: object + required: + - shortfall + properties: + shortfall: + description: | + The additional quantity of each asset that would be needed in order + for the operation to succeed. + type: object + required: + - ada + - assets + properties: + ada: *amount + assets: *walletAssets + +x-errInsufficientCollateral: &errInsufficientCollateral + <<: *responsesErr + title: insufficient_collateral + properties: + message: + type: string + description: | + May occur when the total balance of pure ada UTxOs in the wallet is + insufficient to cover the minimum collateral amount required for a + transaction requiring collateral. + code: + type: string + enum: ['insufficient_collateral'] + +x-errTransactionIsTooBig: &errTransactionIsTooBig + <<: *responsesErr + title: transaction_is_too_big + properties: + message: + type: string + description: May occur when the wallet can't cover for all requested outputs without making the transaction too large. + code: + type: string + enum: ['transaction_is_too_big'] + +x-errCreatedMultidelegationTransaction: &errCreatedMultidelegationTransaction + <<: *responsesErr + title: created_multidelegation_transaction + properties: + message: + type: string + description: Occurs when more than 1 delegation action is included in a transaction. + code: + type: string + enum: ['created_multidelegation_transaction'] + +x-errCreatedMultiaccountTransaction: &errCreatedMultiaccountTransaction + <<: *responsesErr + title: created_multiaccount_transaction + properties: + message: + type: string + description: Occurs when a delegation action does not use '0H' account. + code: + type: string + enum: ['created_multiaccount_transaction'] + +x-errCreatedWrongPolicyScriptTemplate: &errCreatedWrongPolicyScriptTemplate + <<: *responsesErr + title: created_wrong_policy_script_template + properties: + message: + type: string + description: | + Occurs when a policy script template either does not pass validation + or has more than one cosigner. + code: + type: string + enum: ['created_wrong_policy_script_template'] + +x-errAssetNameTooLong: &errAssetNameTooLong + <<: *responsesErr + title: asset_name_too_long + properties: + message: + type: string + description: Occurs when an asset name exceeds 32 bytes in length. + code: + type: string + enum: ['asset_name_too_long'] + +x-errMintOrBurnAssetQuantityOutOfBounds: &errMintOrBurnAssetQuantityOutOfBounds + <<: *responsesErr + title: mint_or_burn_asset_quantity_out_of_bounds + properties: + message: + type: string + description: | + Occurs when attempting to mint or burn an asset quantity that is not + greater than zero or exceeds 9223372036854775807 (2^63 - 1). + code: + type: string + enum: ['mint_or_burn_asset_quantity_out_of_bounds'] + +x-errInvalidValidityBounds: &errInvalidValidityBounds + <<: *responsesErr + title: invalid_validity_bounds + properties: + message: + type: string + description: | + Occurs when attempting to create a transaction with invalid validity + bounds. The 'invalid_before' bound must precede the 'invalid_hereafter' + bound, and the given time values must not be negative. + code: + type: string + enum: ['invalid_validity_bounds'] + +x-errValidityIntervalNotInsideScriptTimelock: &errValidityIntervalNotInsideScriptTimelock + <<: *responsesErr + title: validity_interval_not_inside_script_timelock + properties: + message: + type: string + description: | + Occurs when attempting to create a transaction with a validity interval + that is not a subinterval of an associated script's timelock interval. + code: + type: string + enum: ['validity_interval_not_inside_script_timelock'] + +x-errSharedWalletIncomplete: &errSharedWalletIncomplete + <<: *responsesErr + title: shared_wallet_incomplete + properties: + message: + type: string + description: | + Occurs when attempting to create a transaction for an incomplete shared wallet. + code: + type: string + enum: ['shared_wallet_incomplete'] + +x-errDelegationInvalid: &errDelegationInvalid + <<: *responsesErr + title: staking_invalid + properties: + message: + type: string + description: | + Occurs when attempting to create a delegation transaction for a shared wallet + without a delegation script template. + code: + type: string + enum: ['staking_invalid'] + +x-errVotingInInvalidEra: &errVotingInInvalidEra + <<: *responsesErr + title: voting_in_invalid_era + properties: + message: + type: string + description: | + Occurs when attempting to create a transaction that has voting + before Conway era. + code: + type: string + enum: ['voting_in_invalid_era'] + +x-errWithdrawalNotPossibleWithoutVote: &errWithdrawalNotPossibleWithoutVote + <<: *responsesErr + title: withdrawal_not_possible_without_vote + properties: + message: + type: string + description: | + Occurs when attempting to create a transaction that contains withdrawals + but previous voting was not performed (in Conway era onwards). + code: + type: string + enum: ['withdrawal_not_possible_without_vote'] + +x-errInvalidMetadataEncryption: &errInvalidMetadataEncryption + <<: *responsesErr + title: invalid_metadata_encryption + properties: + message: + type: string + description: | + The supplied metadata object is not compatible with the format + specified by CIP-83 (https://cips.cardano.org/cip/CIP-83). + code: + type: string + enum: ['invalid_metadata_encryption'] + +x-errInvalidMetadataDecryption: &errInvalidMetadataDecryption + <<: *responsesErr + title: invalid_metadata_decryption + properties: + message: + type: string + description: | + The supplied encrypted metadata object is not compatible with standard + specified by CIP-83 (https://cips.cardano.org/cip/CIP-83). + code: + type: string + enum: ['invalid_metadata_decryption'] + +x-errInputsDepleted: &errInputsDepleted + <<: *responsesErr + title: inputs_depleted + properties: + message: + type: string + description: May occur when there's enough money to pay for a payment, but not enough UTxO to allow for paying each output independently. + code: + type: string + enum: ['inputs_depleted'] + +x-errCannotCoverFee: &errCannotCoverFee + <<: *responsesErr + title: cannot_cover_fee + properties: + message: + type: string + description: May occur when a transaction can't be balanced for fees. + code: + type: string + enum: ['cannot_cover_fee'] + +x-errInvalidCoinSelection: &errInvalidCoinSelection + <<: *responsesErr + title: invalid_coin_selection + properties: + message: + type: string + description: Should never happen unless the server screwed up with the creation of a coin selection. + code: + type: string + enum: ['invalid_coin_selection'] + +x-errOutputTokenBundleSizeExceedsLimit: &errOutputTokenBundleSizeExceedsLimit + <<: *responsesErr + title: output_token_bundle_size_exceeds_limit + properties: + message: + type: string + description: | + Returned when a user-specified transaction output contains a token + bundle whose serialized length exceeds the limit supported by the + protocol. + code: + type: string + enum: ['output_token_bundle_size_exceeds_limit'] + info: + type: object + required: + - address + - bundle_size + properties: + address: *addressId + bundle_size: + type: integer + minimum: 0 + +x-errOutputTokenQuantityExceedsLimit: &errOutputTokenQuantityExceedsLimit + <<: *responsesErr + title: output_token_quantity_exceeds_limit + properties: + message: + type: string + description: | + Returned when a user-specified transaction output contains, for some + asset, a token quantity that exceeds the limit supported by the + protocol. + code: + type: string + enum: ['output_token_quantity_exceeds_limit'] + info: + type: object + required: + - address + - policy_id + - asset_name + - quantity + - max_quantity + properties: + address: *addressId + policy_id: *assetPolicyId + asset_name: *assetName + quantity: *assetQuantity + max_quantity: *assetQuantity + +x-errSharedWalletActive: &errSharedWalletActive + <<: *responsesErr + title: shared_wallet_active + properties: + message: + type: string + description: | + Returned when a user tries to add cosigner key to a shared wallet + that is active, not incomplete anymore. + code: + type: string + enum: ['shared_wallet_active'] + +x-errSharedWalletNoDelegationTemplate: &errSharedWalletNoDelegationTemplate + <<: *responsesErr + title: shared_wallet_no_delegation_template + properties: + message: + type: string + description: | + Returned when a user tries to add cosigner key to a shared wallet + for delegation, but the shared wallet misses the delegation template. + code: + type: string + enum: ['shared_wallet_no_delegation_template'] + +x-errSharedWalletKeyAlreadyExists: &errSharedWalletKeyAlreadyExists + <<: *responsesErr + title: shared_wallet_key_already_exists + properties: + message: + type: string + description: | + Returned when a user tries to add cosigner key to a shared wallet + but the same key is already present in a given template. + code: + type: string + enum: ['shared_wallet_key_already_exists'] + +x-errSharedWalletNoSuchCosigner: &errSharedWalletNoSuchCosigner + <<: *responsesErr + title: shared_wallet_no_such_cosigner + properties: + message: + type: string + description: | + Returned when a user tries to add cosigner key to a shared wallet + in script template that misses the cosigner. + code: + type: string + enum: ['shared_wallet_no_such_cosigner'] + info: + type: object + required: + - cosigner_index + - credential_type + properties: + cosigner_index: + type: integer + minimum: 0 + maximum: 255 + credential_type: + type: string + enum: + - delegation + - payment + +x-errSharedWalletCannotUpdateKey: &errSharedWalletCannotUpdateKey + <<: *responsesErr + title: shared_wallet_cannot_update_key + properties: + message: + type: string + description: | + Returned when a user tries to update cosigner key that contains a key of a shared wallet. + Only other cosigner keys can be updated. + code: + type: string + enum: ['shared_wallet_cannot_update_key'] + +x-errSharedWalletScriptTemplateInvalid: &errSharedWalletScriptTemplateInvalid + <<: *responsesErr + title: shared_wallet_script_template_invalid + properties: + message: + type: string + description: | + Returned when a user tries to create a shared wallet with script template + that does not pass validation. + code: + type: string + enum: ['shared_wallet_script_template_invalid'] + +# TODO: Map this error to the place it belongs. +x-errNetworkUnreachable: &errNetworkUnreachable + <<: *responsesErr + title: network_unreachable + properties: + message: + type: string + description: May occur when the connection with the node is lost or not responding. + code: + type: string + enum: ['network_unreachable'] + +# TODO: Map this error to the place it belongs. +x-errNetworkMisconfigured: &errNetworkMisconfigured + <<: *responsesErr + title: network_misconfigured + properties: + message: + type: string + description: May occur when trying to connect to a wrong network (e.g. testnet instead of mainnet). + code: + type: string + enum: ['network_misconfigured'] + +# TODO: Map this error to the place it belongs. +x-errNetworkQueryFailed: &errNetworkQueryFailed + <<: *responsesErr + title: network_query_failed + properties: + message: + type: string + description: Occurs when a ledger query fails in an unexpected manner. + code: + type: string + enum: ['network_query_failed'] + +x-errCreatedInvalidTransaction: &errCreatedInvalidTransaction + <<: *responsesErr + title: created_invalid_transaction + properties: + message: + type: string + description: Should never happen unless the server screwed up with the creation of transaction. + code: + type: string + enum: ['created_invalid_transaction'] + +x-errForeignTransaction: &errForeignTransaction + <<: *responsesErr + title: foreign_transaction + properties: + message: + type: string + description: Occurs when a transaction to be submitted does have neither input, output nor withdrawal belonging to a given wallet. + code: + type: string + enum: ['foreign_transaction'] + +x-errMissingWitnessesInTransaction: &errMissingWitnessesInTransaction + <<: *responsesErr + title: missing_witnesses_in_transaction + properties: + message: + type: string + description: Occurs when a transaction to be submitted is not fully signed. + code: + type: string + enum: ['missing_witnesses_in_transaction'] + info: + type: object + required: + - detected_number_of_key_wits + - expected_number_of_key_wits + properties: + detected_number_of_key_wits: + type: integer + minimum: 0 + expected_number_of_key_wits: + type: integer + minimum: 0 + +x-errRejectedByCoreNode: &errRejectedByCoreNode + <<: *responsesErr + title: rejected_by_core_node + properties: + message: + type: string + description: Should never happen unless the server screwed up with the creation of transaction. + code: + type: string + enum: ['rejected_by_core_node'] + +x-errBadRequest: &errBadRequest + <<: *responsesErr + title: bad_request + properties: + message: + type: string + description: | + May occur when a request is not well-formed; that is, it fails to parse + successfully. This could be the case when some required parameters + are missing or, when malformed values are provided. + code: + type: string + enum: ['bad_request'] + +x-errNodeNotYetInRecentEra: &errNodeNotYetInRecentEra + <<: *responsesErr + title: node_not_yet_in_recent_era + description: Occurs when the operation requires the node to be in a recent era, but is not. + properties: + message: + type: string + code: + type: string + enum: ['node_not_yet_in_recent_era'] + info: + type: object + required: + - node_era + - recent_eras + properties: + node_era: *ApiEra + recent_eras: + type: array + items: *ApiEra + +x-errTxNotInNodeEra: &errTxNotInNodeEra + <<: *responsesErr + title: tx_not_in_node_era + properties: + message: + type: string + description: The transaction could be deserialised, just not in the era of the local node. + code: + type: string + enum: ["tx_not_in_node_era"] + +x-errBalanceTxConflictingNetworks: &errBalanceTxConflictingNetworks + <<: *responsesErr + title: balance_tx_conflicting_networks + deprecated: true # TODO: Remove this error as soon as bump.sh allows us to + properties: + message: + type: string + description: | + There are withdrawals for multiple networks + (e.g. both mainnet and testnet) in the provided transaction. + This makes no sense, and I'm confused. + code: + type: string + enum: ["balance_tx_conflicting_networks"] + +x-errTranslationByronTxOutInContext: &errTranslationByronTxOutInContext + <<: *responsesErr + title: translation_byron_tx_out_in_context + properties: + message: + type: string + description: | + The given transaction contains a Byron-style TxOut which i not supported when executing + Plutus scripts. + code: + type: string + enum: ["translation_byron_tx_out_in_context"] + +x-errBalanceTxInlinePlutusV3ScriptNotSupportedInBabbage: &errBalanceTxInlinePlutusV3ScriptNotSupportedInBabbage + <<: *responsesErr + title: balance_tx_inline_plutus_v3_script_not_supported_in_babbage + properties: + message: + type: string + description: | + Inline Plutus V3 scripts are not supported in Babbage. + code: + type: string + enum: ["balance_tx_inline_plutus_v3_script_not_supported_in_babbage"] + +x-errBalanceTxExistingCollateral: &errBalanceTxExistingCollateral + <<: *responsesErr + title: balance_tx_existing_collateral + properties: + message: + type: string + description: I cannot balance transactions with pre-defined collateral. + code: + type: string + enum: ["balance_tx_existing_collateral"] + +x-errBalanceTxExistingKeyWitnesses: &errBalanceTxExistingKeyWitnesses + <<: *responsesErr + title: balance_tx_existing_key_witnesses + properties: + message: + type: string + description: | + The transaction could not be balanced, because it contains + existing key-witnesses which would be invalid after + the transaction body is modified. + Please sign the transaction after it is balanced instead. + code: + type: string + enum: ["balance_tx_existing_key_witnesses"] + +x-errBalanceTxExistingReturnCollateral: &errBalanceTxExistingReturnCollateral + <<: *responsesErr + title: balance_tx_existing_collateral_return_outputs + properties: + message: + type: string + description: | + Balancing transactions with pre-defined collateral return outputs + is not yet supported. + code: + type: string + enum: ["balance_tx_existing_collateral_return_outputs"] + +x-errBalanceTxExistingTotalCollateral: &errBalanceTxExistingTotalCollateral + <<: *responsesErr + title: balance_tx_existing_total_collateral + properties: + message: + type: string + description: | + I cannot balance transactions with pre-defined total collateral. + code: + type: string + enum: ["balance_tx_existing_total_collateral"] + +x-errBalanceTxInternalError: &errBalanceTxInternalError + <<: *responsesErr + title: balance_tx_internal_error + properties: + message: + type: string + description: | + Balancing transaction failed for an internal reason. + code: + type: string + enum: ["balance_tx_internal_error"] + +x-errBalanceTxUnderestimatedFee: &errBalanceTxUnderestimatedFee + <<: *responsesErr + title: balance_tx_underestimated_fee + properties: + message: + type: string + description: | + I have somehow underestimated the fee of the transaction + and cannot finish balancing. + code: + type: string + enum: ["balance_tx_underestimated_fee"] + +x-errMethodNotAllowed: &errMethodNotAllowed + <<: *responsesErr + title: method_not_allowed + properties: + message: + type: string + description: May occur when sending a request on a wrong endpoint. + code: + type: string + enum: ['method_not_allowed'] + +x-errNotAcceptable: &errNotAcceptable + <<: *responsesErr + title: not_acceptable + properties: + message: + type: string + description: May occur when providing an invalid 'Accept' header. + code: + type: string + enum: ['not_acceptable'] + +x-errUnsupportedMediaType: &errUnsupportedMediaType + <<: *responsesErr + title: unsupported_media_type + properties: + message: + type: string + description: May occur when providing an invalid 'Content-Type' header. + code: + type: string + enum: ['unsupported_media_type'] + +# TODO: Map this error to the place it belongs. +x-errUnexpectedError: &errUnexpectedError + <<: *responsesErr + title: unexpected_error + properties: + message: + type: string + description: Should never occur, unless the server screwed up badly. + code: + type: string + enum: ['unexpected_error'] + +x-errStartTimeLaterThanEndTime: &errStartTimeLaterThanEndTime + <<: *responsesErr + title: start_time_later_than_end_time + properties: + message: + type: string + description: May occur when a provided time-range is unsound. + code: + type: string + enum: ['start_time_later_than_end_time'] + info: + type: object + required: + - start_time + - end_time + properties: + start_time: *date + end_time: *date + +# TODO: Map this error to the place it belongs. +x-errUnableToDetermineCurrentEpoch: &errUnableToDetermineCurrentEpoch + <<: *responsesErr + title: unable_to_determine_current_epoch + properties: + message: + type: string + description: May occur under rare circumstances if the underlying node isn't enough synced with the network. + code: + type: string + enum: ['unable_to_determine_current_epoch'] + +# TODO: Map this error to the place it belongs. +x-errNotSynced: &errNotSynced + <<: *responsesErr + title: not_synced + properties: + message: + type: string + description: May occur under rare circumstances if the underlying node isn't enough synced with the network. + code: + type: string + enum: ['not_synced'] + +# TODO: Map this error to the place it belongs. +x-errNothingToMigrate: &errNothingToMigrate + <<: *responsesErr + title: nothing_to_migrate + properties: + message: + type: string + description: May occur when trying to migrate a wallet that is empty or full of dust. + code: + type: string + enum: ['nothing_to_migrate'] + +x-errNoSuchPool: &errNoSuchPool + <<: *responsesErr + title: no_such_pool + properties: + message: + type: string + description: May occur when a given poolId does not match any known pool. + code: + type: string + enum: ['no_such_pool'] + info: + type: object + required: + - pool_id + properties: + pool_id: *stakePoolId + +x-errPoolAlreadyJoined: &errPoolAlreadyJoined + <<: *responsesErr + title: pool_already_joined + properties: + message: + type: string + description: May occur when a given poolId matches the current delegation preferences of the wallet's account (not in Conway onwards provided different vote was also casted). + code: + type: string + enum: ['pool_already_joined'] + +x-errPoolAlreadyJoinedSameVote: &errPoolAlreadyJoinedSameVote + <<: *responsesErr + title: pool_already_joined_same_vote + properties: + message: + type: string + description: May occur in Conway onwards when a given poolId matches the current delegation preferences of the wallet's account and also the same vote was cast. + code: + type: string + enum: ['pool_already_joined_same_vote'] + +x-errSameVote: &errSameVote + <<: *responsesErr + title: same_vote + properties: + message: + type: string + description: May occur in Conway onwards when the same vote was cast. + code: + type: string + enum: ['same_vote'] + +x-errNotDelegatingTo: &errNotDelegatingTo + <<: *responsesErr + title: not_delegating_to + properties: + message: + type: string + description: May occur when trying to quit a pool on an account that isn't delegating. + code: + type: string + enum: ['not_delegating_to'] + +# TODO: Map this error to the place it belongs. +x-errNotImplemented: &errNotImplemented + <<: *responsesErr + title: not_implemented + properties: + message: + type: string + description: May occur when reaching an endpoint under construction. + code: + type: string + enum: ['not_implemented'] + +# TODO: Map this error to the place it belongs. +x-errWalletNotResponding: &errWalletNotResponding + <<: *responsesErr + title: wallet_not_responding + properties: + message: + type: string + description: Should never occur unless something really wrong happened causing a background worker to die. + code: + type: string + enum: ['wallet_not_responding'] + +# TODO: Map this error to the place it belongs. +x-errAddressAlreadyExists: &errAddressAlreadyExists + <<: *responsesErr + title: address_already_exists + properties: + message: + type: string + description: May occur when trying to import an address that is already known of the wallet's account. + code: + type: string + enum: ['address_already_exists'] + +x-errInvalidWalletType: &errInvalidWalletType + <<: *responsesErr + title: invalid_wallet_type + properties: + message: + type: string + description: May occur when trying to perform an operation not supported by this type of wallet. + code: + type: string + enum: ['invalid_wallet_type'] + +x-errMissingPolicyPublicKey: &errMissingPolicyPublicKey + <<: *responsesErr + title: missing_policy_public_key + properties: + message: + type: string + description: Occurs when trying to construct with minting/burning on shelley wallet without policy public key. + code: + type: string + enum: ['missing_policy_public_key'] + +x-errQueryParamMissing: &errQueryParamMissing + <<: *responsesErr + title: query_param_missing + properties: + message: + type: string + description: May occur when an endpoint requires the presence of a query parameter that is missing. + code: + type: string + enum: ['query_param_missing'] + +x-errNonNullRewards: &errNonNullRewards + <<: *responsesErr + title: non_null_rewards + properties: + message: + type: string + description: May occur when trying to unregister a stake key that still has rewards attached to it. + code: + type: string + enum: ['non_null_rewards'] + +x-errMissingRewardAccount: &errMissingRewardAccount + <<: *responsesErr + title: missing_reward_account + properties: + message: + type: string + description: May occur when there is a missing reward account but wallet participates in staking. + code: + type: string + enum: ['missing_reward_account'] + +x-errUtxoTooSmall: &errUtxoTooSmall + <<: *responsesErr + title: utxo_too_small + properties: + message: + type: string + description: + Occurs when a requested output has a quantity of lovelace that is below + the minimum required by the ledger. + code: + type: string + enum: ['utxo_too_small'] + info: + type: object + required: + - tx_output_index + - tx_output_lovelace_specified + - tx_output_lovelace_required_minimum + properties: + tx_output_index: + type: integer + minimum: 0 + tx_output_lovelace_specified: *amount + tx_output_lovelace_required_minimum: *amount + +x-errMinWithdrawalWrong: &errMinWithdrawalWrong + <<: *responsesErr + title: min_withdrawal_wrong + properties: + message: + type: string + description: May occur when trying to withdraw less than the minimal UTxO value. + code: + type: string + enum: ['min_withdrawal_wrong'] + +x-errAlreadyWithdrawing: &errAlreadyWithdrawing + <<: *responsesErr + title: already_withdrawing + properties: + message: + type: string + description: May occur when submitting a withdrawal while another withdrawal is pending. + code: + type: string + enum: ['already_withdrawing'] + +# TODO: Map this error to the place it belongs. +x-errWithdrawalNotBeneficial: &errWithdrawalNotBeneficial + <<: *responsesErr + title: withdrawal_not_beneficial + properties: + message: + type: string + description: | + Occurs when the cost of withdrawing a reward balance would be greater + than the reward balance itself. + code: + type: string + enum: ['withdrawal_not_beneficial'] + +# TODO: Map this error to the place it belongs. +x-errPastHorizon: &errPastHorizon + <<: *responsesErr + title: past_horizon + properties: + message: + type: string + description: May occur in rare cases when converting slot to time can't be done, typically near hard-forks. + code: + type: string + enum: ['past_horizon'] + +# TODO: Map this error to the place it belongs. +x-errUnableToAssignInputOutput: &errUnableToAssignInputOutput + <<: *responsesErr + title: unable_to_assign_input_output + properties: + message: + type: string + description: Should never occur unless the server screwed up with a coin selection. + code: + type: string + enum: ['unable_to_assign_input_output'] + +x-errAssetNotPresent: &errAssetNotPresent + <<: *responsesErr + title: asset_not_present + properties: + message: + type: string + description: | + Occurs when requesting information about an asset which is not + involved in any transaction related to the wallet. + code: + type: string + enum: ['asset_not_present'] + +x-errTransactionAlreadyBalanced: &errTransactionAlreadyBalanced + <<: *responsesErr + title: transaction_already_balanced + properties: + message: + type: string + description: | + Occurs when a transaction is already balanced. + code: + type: string + enum: ['transaction_already_balanced'] + +x-errRedeemerScriptFailure: &errRedeemerScriptFailure + <<: *responsesErr + title: redeemer_script_failure + properties: + message: + type: string + description: | + Occurs when balancing transaction with failing scripts. + code: + type: string + enum: ['redeemer_script_failure'] + +x-errRedeemerTargetNotFound: &errRedeemerTargetNotFound + <<: *responsesErr + title: redeemer_target_not_found + properties: + message: + type: string + description: | + Occurs when balancing transaction with reedemers that point to unknown entities. + code: + type: string + enum: ['redeemer_target_not_found'] + +x-errUnresolvedInputs: &errUnresolvedInputs + <<: *responsesErr + title: unresolved_inputs + properties: + message: + type: string + description: | + There are inputs in the transaction for which the corresponding outputs + could not be found. + code: + type: string + enum: ['unknown_inputs'] + +x-errUnresolvedRefunds: &errUnresolvedRefunds + <<: *responsesErr + title: unresolved_refunds + properties: + message: + type: string + description: | + There are stake key deregistration certificates in the transaction for which corresponding + deposit amounts could not be found. + code: + type: string + enum: ['unresolved_refunds'] + +x-errRedeemerInvalidData: &errRedeemerInvalidData + <<: *responsesErr + title: redeemer_invalid_data + properties: + message: + type: string + description: | + Occurs when data in provided redeemers do not decode to valid Plutus data. + code: + type: string + enum: ['redeemer_invalid_data'] + +x-errTranslationError: &errTranslationError + <<: *responsesErr + title: translation_error + properties: + message: + type: string + description: | + Occurs when any data in a provided transaction cannot be translated in a given era + code: + type: string + enum: ['translation_error'] + +x-errExistingKeyWitnesses: &errExistingKeyWitnesses + <<: *responsesErr + title: existing_key_witnesses + properties: + message: + type: string + description: | + Occurs when trying to balance a transaction that already has key witnesses. + code: + type: string + enum: ['existing_key_witnesses'] + +x-errInputResolutionConflicts: &errInputResolutionConflicts + <<: *responsesErr + title: input_resolution_conflicts + properties: + message: + type: string + description: | + At least one of the provided inputs has an + asset quantity or address that is different from that + recorded in the wallet's UTxO set. + code: + type: string + enum: ['input_resolution_conflicts'] + +x-errBlockHeaderNotFound: &errBlockHeaderNotFound + <<: *responsesErr + title: block_header_not_found + properties: + message: + type: string + description: | + Occurs when trying to retrieve a block header + that is not in the local node's chain. + code: + type: string + enum: ['block_header_not_found'] + +x-errUnsupportedEra: &errUnsupportedEra + <<: *responsesErr + title: unsupported_era + properties: + message: + type: string + code: + type: string + enum: ['unsupported_era'] + info: + type: object + required: + - unsupported_era + - supported_eras + properties: + unsupported_era: *ApiEra + supported_eras: + type: array + items: *ApiEra + +x-responsesErr400: &responsesErr400 + 400: + description: Bad Request + content: + application/json: + schema: *errBadRequest + +x-responsesErr403: &responsesErr403 + 403: + description: Forbidden + content: + application/json: + schema: *responsesErr + +x-responsesErr404: &responsesErr404 + 404: + description: Not Found + content: + application/json: + schema: *responsesErr + +x-responsesErr406: &responsesErr406 + 406: + description: Not Acceptable + content: + application/json: + schema: *errNotAcceptable + +x-responsesErr409: &responsesErr409 + 409: + description: Conflict + content: + application/json: + schema: *responsesErr + +x-responsesErr410: &responsesErr410 + 410: + description: Gone + content: + application/json: + schema: *responsesErr + +x-responsesErr415: &responsesErr415 + 415: + description: Unsupported Media Type + content: + application/json: + schema: *responsesErr + +x-responsesErr423: &responsesErr423 + 423: + description: Locked + content: + application/json: + schema: *responsesErr + +x-responsesErr425MempoolIsFull: &responsesErr425MempoolIsFull + 425: + description: Mempool is Full + content: + application/json: + schema: *errMempoolIsFull + +x-responsesErr404WalletNotFound: &responsesErr404WalletNotFound + 404: + description: Not Found + content: + application/json: + schema: *errNoSuchWallet + +x-responsesErr404WalletNotInitialized: &responsesErr404WalletNotInitialized + 404: + description: Wallet not yet initialized + content: + application/json: + schema: *errWalletNotInitialized + +x-responsesErr503WalletMetadataNotFound: &responsesErr503WalletMetadataNotFound + 503: + description: No meta + content: + application/json: + schema: *errWalletMetadataNotFound + +x-responsesErr409WalletAlreadyExists: &responsesErr409WalletAlreadyExists + 409: + description: Conflict + content: + application/json: + schema: *errWalletAlreadyExists + +x-responsesErr415UnsupportedMediaType: &responsesErr415UnsupportedMediaType + 415: + description: Unsupported Media Type + content: + application/json: + schema: *errUnsupportedMediaType + +x-responsesListWallets: &responsesListWallets + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiWallet + +x-responsesListSharedWallets: &responsesListSharedWallets + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiSharedWallet + +x-responsesErr404AssetNotPresent: &responsesErr404AssetNotPresent + 404: + description: Not Found + content: + application/json: + schema: *errAssetNotPresent + +x-responsesListAssets: &responsesListAssets + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiAsset + +x-responsesGetAsset: &responsesGetAsset + <<: + - *responsesErr404AssetNotPresent + - *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiAsset + +x-responsesListByronWallets: &responsesListByronWallets + <<: *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiByronWallet + +x-responsesGetUTxOsStatistics: &responsesGetUTxOsStatistics + <<: + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiWalletUTxOsStatistics + +x-responsesGetWalletUtxoSnapshot: &responsesGetWalletUtxoSnapshot + <<: + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiWalletUtxoSnapshot + +x-responsesPostWallet: &responsesPostWallet + <<: + - *responsesErr400 + - *responsesErr406 + - *responsesErr409WalletAlreadyExists + - *responsesErr415UnsupportedMediaType + 201: + description: Created + content: + application/json: + schema: *ApiWallet + +x-responsesPostSharedWallet: &responsesPostSharedWallet + <<: + - *responsesErr400 + - *responsesErr406 + - *responsesErr409WalletAlreadyExists + - *responsesErr415UnsupportedMediaType + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errSharedWalletScriptTemplateInvalid + 500: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errMissingRewardAccount + 201: + description: Created + content: + application/json: + schema: *ApiSharedWallet + +x-responsesPostByronWallet: &responsesPostByronWallet + <<: + - *responsesErr400 + - *responsesErr406 + - *responsesErr409 + - *responsesErr415 + 201: + description: Created + content: + application/json: + schema: *ApiByronWallet + +x-responsesGetWallet: &responsesGetWallet + <<: + - *responsesErr400 + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiWallet + +x-responsesGetByronWallet: &responsesGetByronWallet + <<: + - *responsesErr404 + - *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiByronWallet + +x-responsesGetSharedWallet: &responsesGetSharedWallet + <<: + - *responsesErr400 + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiSharedWallet + +x-responsesPatchSharedWallet: &responsesPatchSharedWallet + <<: + - *responsesErr400 + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + - *responsesErr503WalletMetadataNotFound + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errSharedWalletKeyAlreadyExists + - <<: *errSharedWalletNoDelegationTemplate + - <<: *errSharedWalletActive + - <<: *errSharedWalletNoSuchCosigner + - <<: *errSharedWalletCannotUpdateKey + 200: + description: Ok + content: + application/json: + schema: *ApiSharedWallet + +x-responsesCreateWalletMigrationPlan: &responsesCreateWalletMigrationPlan + <<: + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + 403: + description: Forbidden + content: + application/json: + schema: *errNothingToMigrate + 202: + description: Accepted + content: + application/json: + schema: *ApiWalletMigrationPlan + +x-responsesMigrateWallet: &responsesMigrateWallet + <<: + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errNothingToMigrate + - <<: *errNoRootKey + - <<: *errWrongEncryptionPassphrase + 202: + description: Accepted + content: + application/json: + schema: + type: array + items: *ApiTransaction + minItems: 1 + +x-responsesDeleteWallet: &responsesDeleteWallet + <<: + - *responsesErr400 + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + 204: + description: No Content + +x-responsesForceResyncWallet: &responsesForceResyncWallet + <<: + - *responsesErr400 + - *responsesErr403 + - *responsesErr404 + - *responsesErr406 + - *responsesErr415 + 204: + description: No Content + +x-responsesPutWallet: &responsesPutWallet + <<: + - *responsesErr400 + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + 200: + description: Ok + content: + application/json: + schema: *ApiWallet + +x-responsesPutSharedWallet: &responsesPutSharedWallet + <<: + - *responsesErr400 + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + 200: + description: Ok + content: + application/json: + schema: *ApiSharedWallet + +x-responsesPutWalletPassphrase: &responsesPutWalletPassphrase + <<: + - *responsesErr400 + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errNoRootKey + - <<: *errWrongEncryptionPassphrase + - <<: *errWrongMnemonic + 204: + description: No Content + +x-responsesSelectCoins: &responsesSelectCoins + <<: + - *responsesErr400 + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errAlreadyWithdrawing + - <<: *errUtxoTooSmall + - <<: *errNoUtxosAvailable + - <<: *errNotEnoughMoney + - <<: *errInsufficientCollateral + - <<: *errCannotCoverFee + - <<: *errInputsDepleted + - <<: *errInvalidCoinSelection + - <<: *errOutputTokenQuantityExceedsLimit + - <<: *errOutputTokenBundleSizeExceedsLimit + 200: + description: OK + content: + application/json: + schema: *ApiCoinSelection + +x-responsesDeleteTransaction: &responsesDeleteTransaction + <<: + - *responsesErr406 + 403: + description: Forbidden + content: + application/json: + schema: *errTransactionAlreadyInLedger + 404: + description: Not Found + content: + application/json: + schema: + oneOf: + - <<: *errNoSuchWallet + - <<: *errWalletNotInitialized + - <<: *errNoSuchTransaction + 204: + description: No Content + +x-responsesListTransactions: &responsesListTransactions + <<: + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + 400: + description: Bad Request + content: + application/json: + schema: + oneOf: + - <<: *errMinWithdrawalWrong + - <<: *errStartTimeLaterThanEndTime + 200: + description: Ok + headers: + Content-Range: + schema: + type: string + format: inserted-at {range-start}-{range-end}/{total} + content: + application/json: + schema: + type: array + items: *ApiTransaction +x-responsesGetTransaction: &responsesGetTransaction + 404: + description: Not Found + content: + application/json: + schema: + oneOf: + - <<: *errNoSuchWallet + - <<: *errWalletNotInitialized + - <<: *errNoSuchTransaction + <<: *responsesErr406 + 200: + description: OK + content: + application/json: + schema: *ApiTransaction + +# ADP-908 Deprecated +x-responsesPostTransaction: &responsesPostTransaction + <<: + - *responsesErr400 + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + - *responsesErr425MempoolIsFull + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errInvalidWalletType + - <<: *errAlreadyWithdrawing + - <<: *errUtxoTooSmall + - <<: *errCannotCoverFee + - <<: *errNoUtxosAvailable + - <<: *errNotEnoughMoney + - <<: *errInsufficientCollateral + - <<: *errTransactionIsTooBig + - <<: *errNoRootKey + - <<: *errWrongEncryptionPassphrase + - <<: *errUnsupportedEra + 202: + description: Accepted + content: + application/json: + schema: *ApiTransaction + +x-responsesConstructTransaction: &responsesConstructTransaction + <<: + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + 400: + description: Bad Request + content: + application/json: + schema: + oneOf: + - <<: *errBadRequest + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errInvalidWalletType + - <<: *errAlreadyWithdrawing + - <<: *errUtxoTooSmall + - <<: *errCannotCoverFee + - <<: *errNoUtxosAvailable + - <<: *errNotEnoughMoney + - <<: *errInsufficientCollateral + - <<: *errTransactionIsTooBig + - <<: *errCreatedMultidelegationTransaction + - <<: *errCreatedMultiaccountTransaction + - <<: *errCreatedWrongPolicyScriptTemplate + - <<: *errAssetNameTooLong + - <<: *errMintOrBurnAssetQuantityOutOfBounds + - <<: *errInvalidValidityBounds + - <<: *errValidityIntervalNotInsideScriptTimelock + - <<: *errSharedWalletIncomplete + - <<: *errDelegationInvalid + - <<: *errVotingInInvalidEra + - <<: *errWithdrawalNotPossibleWithoutVote + - <<: *errInvalidMetadataEncryption + - <<: *errSameVote + 202: + description: Accepted + content: + application/json: + schema: *ApiConstructTransaction + +x-responsesSignTransaction: &responsesSignTransaction + <<: + - *responsesErr400 + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errNoRootKey + - <<: *errWrongEncryptionPassphrase + 202: + description: Accepted + content: + application/json: + schema: *ApiSignedTransaction + +x-responsesDecodedTransaction: &responsesDecodedTransaction + <<: + - *responsesErr400 + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errInvalidMetadataDecryption + 202: + description: Accepted + content: + application/json: + schema: *ApiDecodedTransaction + +x-responsesSubmitTransaction: &responsesSubmitTransaction + <<: + - *responsesErr400 + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + 202: + description: Accepted + content: + application/json: + schema: *ApiTxId + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errForeignTransaction + - <<: *errMissingWitnessesInTransaction + - <<: *errCreatedMultidelegationTransaction + +x-responsesPostExternalTransaction: &responsesPostExternalTransaction + <<: + - *responsesErr400 + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + - *responsesErr425MempoolIsFull + 202: + description: Accepted + content: + application/json: + schema: *ApiTxId + +x-responsesPostAnyAddress: &responsesPostAnyAddress + <<: + - *responsesErr400 + - *responsesErr406 + - *responsesErr415 + 202: + description: Accepted + content: + application/json: + schema: *AnyAddress + +x-responsesPostTransactionFee: &responsesPostTransactionFee + <<: + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + 400: + description: Bad Request + content: + application/json: + schema: + oneOf: + - <<: *errBadRequest + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errInvalidWalletType + - <<: *errAlreadyWithdrawing + - <<: *errUtxoTooSmall + - <<: *errCannotCoverFee + - <<: *errNoUtxosAvailable + - <<: *errNotEnoughMoney + - <<: *errInsufficientCollateral + - <<: *errInputsDepleted + - <<: *errInvalidCoinSelection + - <<: *errOutputTokenQuantityExceedsLimit + - <<: *errOutputTokenBundleSizeExceedsLimit + - <<: *errTransactionIsTooBig + 202: + description: Accepted + content: + application/json: + schema: *ApiFee + +x-responsesGetDelegationFee: &responsesGetDelegationFee + <<: + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + 403: + description: Forbidden + content: + application/json: + schema: *errCannotCoverFee + 200: + description: Ok + content: + application/json: + schema: *ApiFee + +x-responsesListAddresses: &responsesListAddresses + <<: + - *responsesErr400 + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiAddressWithPath + +x-responsesGetShelleyKey: &responsesGetShelleyKey + <<: + - *responsesErr400 + - *responsesErr404 + - *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiVerificationKeyShelley + +x-responsesPostPolicyKey: &responsesPostPolicyKey + <<: + - *responsesErr400 + - *responsesErr406 + - *responsesErr415 + 202: + description: Accepted + content: + application/json: + schema: *ApiPolicyKey + +x-responsesPostPolicyId: &responsesPostPolicyId + <<: + - *responsesErr400 + - *responsesErr406 + - *responsesErr415 + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errInvalidWalletType + - <<: *errMissingPolicyPublicKey + - <<: *errCreatedWrongPolicyScriptTemplate + 202: + description: Accepted + content: + application/json: + schema: *ApiPolicyId + +x-responsesGetPolicyKey: &responsesGetPolicyKey + <<: + - *responsesErr400 + - *responsesErr404 + - *responsesErr406 + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errInvalidWalletType + - <<: *errMissingPolicyPublicKey + 200: + description: Ok + content: + application/json: + schema: *ApiPolicyKey + +x-responsesGetSharedKey: &responsesGetSharedKey + <<: + - *responsesErr400 + - *responsesErr404 + - *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiVerificationKeyShared + +x-responsesGetAccountSharedKey: &responsesGetAccountSharedKey + <<: + - *responsesErr400 + - *responsesErr404 + - *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiAccountKeyShared + +x-responsesPostAccountKey: &responsesPostAccountKey + <<: + - *responsesErr400 + - *responsesErr406 + - *responsesErr415 + 202: + description: Accepted + content: + application/json: + schema: *ApiAccountKey + +x-responsesGetAccountKey: &responsesGetAccountKey + <<: + - *responsesErr400 + - *responsesErr404 + - *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiAccountKey + +x-responsesPostAccountKeyShared: &responsesPostAccountKeyShared + <<: + - *responsesErr400 + - *responsesErr406 + - *responsesErr415 + 202: + description: Accepted + content: + application/json: + schema: *ApiAccountKeyShared + +x-responsesListStakePools: &responsesListStakePools + 400: + description: Bad Request + content: + application/json: + schema: *errQueryParamMissing + 200: + description: Ok + content: + application/json: + schema: + type: array + items: *ApiStakePool + +x-responsesListStakeKeys: &responsesListStakeKeys + 200: + description: Ok + content: + application/json: + schema: *ApiStakeKeys + +x-responsesPostMaintenanceAction: &responsesPostMaintenanceAction + <<: + - *responsesErr404 + 204: + description: No Content + +x-responsesGetMaintenanceAction: &responsesGetMaintenanceAction + 200: + description: Ok + content: + application/json: + schema: + <<: *ApiMaintenanceAction + +x-responsesJoinStakePool: &responsesJoinStakePool + <<: + - *responsesErr400 + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errCannotCoverFee + - <<: *errNoRootKey + - <<: *errNoUtxosAvailable + - <<: *errWrongEncryptionPassphrase + - <<: *errPoolAlreadyJoined + - <<: *errPoolAlreadyJoinedSameVote + - <<: *errSameVote + 404: + description: Not Found + content: + application/json: + schema: + oneOf: + - <<: *errNoSuchWallet + - <<: *errWalletNotInitialized + - <<: *errNoSuchPool + 202: + description: Accepted + content: + application/json: + schema: *ApiTransaction + +x-responsesJoinDRep: &responsesJoinDRep + <<: + - *responsesErr400 + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errCannotCoverFee + - <<: *errNoRootKey + - <<: *errNoUtxosAvailable + - <<: *errWrongEncryptionPassphrase + - <<: *errSameVote + 404: + description: Not Found + content: + application/json: + schema: + oneOf: + - <<: *errNoSuchWallet + - <<: *errWalletNotInitialized + - <<: *errNoSuchPool + 202: + description: Accepted + content: + application/json: + schema: *ApiTransaction + +x-responsesQuitStakePool: &responsesQuitStakePool + <<: + - *responsesErr400 + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errCannotCoverFee + - <<: *errNoRootKey + - <<: *errNoUtxosAvailable + - <<: *errWrongEncryptionPassphrase + - <<: *errNotDelegatingTo + - <<: *errNonNullRewards + 202: + description: Accepted + content: + application/json: + schema: *ApiTransaction + +x-responsesGetNetworkInformation: &responsesGetNetworkInformation + <<: + - *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiNetworkInformation + +x-responsesGetNetworkClock: &responsesGetNetworkClock + <<: + - *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiNetworkClock + +x-responsesGetNetworkParameters: &responsesGetNetworkParameters + <<: + - *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiNetworkParameters + +x-responsesPostRandomAddress: &responsesPostRandomAddress + <<: + - *responsesErr400 + - *responsesErr403 + - *responsesErr406 + - *responsesErr415 + 201: + description: Created + content: + application/json: + schema: *ApiAddressWithPath + +x-responsesPutRandomAddress: &responsesPutRandomAddress + <<: + - *responsesErr400 + - *responsesErr403 + 204: + description: No Content + +x-responsesPutRandomAddresses: &responsesPutRandomAddresses + <<: + - *responsesErr400 + - *responsesErr403 + 204: + description: No Content + +x-responsesInspectAddress: &responsesInspectAddress + <<: + - *responsesErr400 + 200: + description: Ok + content: + application/json: + schema: *ApiAddressInspect + +x-responsesPutSettings: &responsesPutSettings + <<: + - *responsesErr400 + - *responsesErr415UnsupportedMediaType + 204: + description: No Content + +x-responsesGetSettings: &responsesGetSettings + 200: + description: Ok + content: + application/json: + schema: *ApiGetSettings + +x-responsesPostSignatures: &responsesPostSignatures + <<: + - *responsesErr400 + - *responsesErr406 + - *responsesErr415 + 200: + description: OK + content: + application/octet-stream: + schema: + type: string + format: binary + +x-responsesGetSmashHealth: &responsesGetSmashHealth + <<: + - *responsesErr400 + - *responsesErr406 + 200: + description: Ok + content: + application/json: + schema: *ApiHealthCheck + +x-responsesBalanceTransaction: &responsesBalanceTransaction + 400: + description: Bad Request + content: + application/json: + schema: + oneOf: + - <<: *errBadRequest + - <<: *errRedeemerScriptFailure + - <<: *errRedeemerTargetNotFound + - <<: *errRedeemerInvalidData + - <<: *errTranslationError + - <<: *errUnresolvedInputs + - <<: *errInputResolutionConflicts + 403: + description: Forbidden + content: + application/json: + schema: + oneOf: + - <<: *errAlreadyWithdrawing + - <<: *errNodeNotYetInRecentEra + - <<: *errBalanceTxConflictingNetworks + - <<: *errBalanceTxExistingCollateral + - <<: *errBalanceTxExistingKeyWitnesses + - <<: *errBalanceTxExistingReturnCollateral + - <<: *errBalanceTxExistingTotalCollateral + - <<: *errBalanceTxInternalError + - <<: *errCannotCoverFee + - <<: *errInsufficientCollateral + - <<: *errInvalidWalletType + - <<: *errNoUtxosAvailable + - <<: *errNotEnoughMoney + - <<: *errTransactionAlreadyBalanced + - <<: *errTransactionIsTooBig + - <<: *errUtxoTooSmall + - <<: *errTxNotInNodeEra + - <<: *errBalanceTxInlinePlutusV3ScriptNotSupportedInBabbage + - <<: *errTranslationByronTxOutInContext + <<: + - *responsesErr404WalletNotFound + - *responsesErr404WalletNotInitialized + - *responsesErr406 + - *responsesErr415UnsupportedMediaType + 202: + description: Accepted + content: + application/json: + schema: *ApiSerialisedTransaction + +############################################################################# +# # +# PATHS # +# # +############################################################################# + +x-tagGroups: + - name: Shelley (Sequential) + tags: + - Wallets + - Assets + - Addresses + - Coin Selections + - Transactions + - Transactions New + - Migrations + - Stake Pools + - DReps + - Keys + + - name: Shelley (Shared Wallets) + tags: + - Shared Wallets + - Shared Keys + - Shared Addresses + - Shared Transactions + + - name: Byron (Random) + tags: + - Byron Wallets + - Byron Assets + - Byron Addresses + - Byron Coin Selections + - Byron Transactions + - Byron Migrations + + - name: Miscellaneous + tags: + - Utils + - Network + - Proxy + - Settings + - Experimental + - Node + +paths: + /wallets/{walletId}/signatures/{role}/{index}: + post: + operationId: signMetadata + tags: ["Experimental"] + summary: Sign Metadata + description: | +

status: experimental

+ + **⚠️ WARNING ⚠️** + + This endpoint is experimental and for internal use in the Catalyst project. This + functionality will be refined in the forthcoming future and the interface is likely + to change in **NON-BACKWARD COMPATIBLE WAYS**. + + Note: Only `Soft` indexes are supported by this endpoint. + parameters: + - *parametersWalletId + - *parametersRole + - *parametersDerivationSegment + requestBody: + required: true + content: + application/json: + schema: *ApiWalletSignData + responses: *responsesPostSignatures + + /wallets: + post: + operationId: postWallet + tags: ["Wallets"] + summary: Create / Restore + description: | +

status: stable

+ + Create and restore a wallet from a mnemonic sentence or account public key. + requestBody: + required: true + content: + application/json: + schema: *ApiWalletOrAccountPostData + responses: *responsesPostWallet + + get: + operationId: listWallets + tags: ["Wallets"] + summary: List + description: | +

status: stable

+ + Return a list of known wallets, ordered from oldest to newest. + responses: *responsesListWallets + + /wallets/{walletId}/assets: + get: + operationId: listAssets + tags: ["Assets"] + summary: List Assets + description: | + List all assets associated with the wallet, and their metadata + if known. + + An asset is _associated_ with a wallet if, at one point in history, + it was spendable by the wallet. + parameters: + - *parametersWalletId + responses: *responsesListAssets + + /wallets/{walletId}/assets/{policyId}/{assetName}: + get: + operationId: getAsset + tags: ["Assets"] + summary: Get Asset + description: | + Fetch a single asset from its `policy_id` and `asset_name`, + with its metadata if any. + + The asset must be associated with the wallet. + parameters: + - *parametersWalletId + - *parametersPolicyId + - *parametersAssetName + responses: *responsesGetAsset + + /wallets/{walletId}/assets/{policyId}: + get: + operationId: getAssetDefault + tags: ["Assets"] + summary: Get Asset (empty name) + description: | + Fetch the asset from `policy_id` with an empty name. + + The asset must be associated with the wallet. + parameters: + - *parametersWalletId + - *parametersPolicyId + responses: *responsesGetAsset + + /wallets/{walletId}/statistics/utxos: + get: + operationId: getUTxOsStatistics + tags: ["Wallets"] + summary: UTxO Statistics + description: | +

status: stable

+ + Return the UTxO distribution across the whole wallet, in the form of a histogram. + + ``` + │ + 100 ─ + │ + │ ┌───┐ + 10 ─ ┌───┐ │ │ ┌───┐ + │ ┌───┐ │ │ │ │ │ │ + │ │ │ │ │ │ │ ┌───┐ │ │ + 1 ─ ┌───┐ │ │ │ │ │ │ │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ │ + │ │ │ │ │ │ │ │ │ │ ╷ │ │ ╷ │ │ ╷ ╷ │ │ + └─┘ └─│───────│─┘ └─│─┘ └─│─┘ └─│─┘ └─│───────│─┘ └──── + 10μ₳ 100μ₳ 1000μ₳ 0.1₳ 1₳ 10₳ 100₳ + ``` + parameters: + - *parametersWalletId + responses: *responsesGetUTxOsStatistics + + /wallets/{walletId}/utxo: + get: + operationId: getWalletUtxoSnapshot + tags: ["Wallets"] + summary: A snapshot of the wallet's UTxO set + description: | + Generate a snapshot of the wallet's UTxO set. + + This endpoint is intended for debugging purposes. + parameters: + - *parametersWalletId + responses: *responsesGetWalletUtxoSnapshot + + /wallets/{walletId}: + get: + operationId: getWallet + tags: ["Wallets"] + summary: Get + description: | +

status: stable

+ parameters: + - *parametersWalletId + responses: *responsesGetWallet + + delete: + operationId: deleteWallet + tags: ["Wallets"] + summary: Delete + description: | +

status: stable

+ parameters: + - *parametersWalletId + responses: *responsesDeleteWallet + + put: + operationId: putWallet + tags: ["Wallets"] + summary: Update Metadata + description: | +

status: stable

+ parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiWalletPutDataExtended + responses: *responsesPutWallet + + /wallets/{walletId}/passphrase: + put: + operationId: putWalletPassphrase + tags: ["Wallets"] + summary: Update Passphrase + description: | +

status: stable

+ parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiWalletPutPassphraseData + responses: *responsesPutWalletPassphrase + + /wallets/{walletId}/payment-fees: + post: + operationId: postTransactionFee + tags: ["Transactions"] + summary: Estimate Fee + # ADP-908 - Deprecated soon + deprecated: false + description: | +

status: stable

+ + Estimate fee for the transaction. The estimate is made by + assembling multiple transactions and analyzing the + distribution of their fees. The estimated_max is the highest + fee observed, and the estimated_min is the fee which is lower + than at least 90% of the fees observed. + + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: + oneOf: + - <<: *ApiPostTransactionFeeData + title: "payment" + - <<: *ApiPostRedemptionFeeData + title: "redemption" + responses: *responsesPostTransactionFee + + /wallets/{walletId}/transactions: + post: + operationId: postTransaction + tags: ["Transactions"] + summary: Create + # ADP-908 - Deprecated soon + deprecated: false + description: | +

status: stable

+ + Create and send transaction from the wallet. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: + oneOf: + - <<: *ApiPostTransactionData + title: "payment" + - <<: *ApiPostRedemptionData + title: "redemption" + responses: *responsesPostTransaction + + get: + operationId: listTransactions + tags: ["Transactions"] + summary: List + description: | +

status: stable

+ + Lists all incoming and outgoing wallet's transactions. + parameters: + - *parametersWalletId + - *parametersStartDate + - *parametersEndDate + - *parametersSortOrder + - *parametersMaxCount + - *parametersMinWithdrawal + - *parametersMetadataFormat + - *parametersAddress + responses: *responsesListTransactions + + /wallets/{walletId}/transactions/{transactionId}: + get: + operationId: getTransaction + tags: ["Transactions"] + summary: Get + description: | +

status: stable

+ + Get transaction by id. + parameters: + - *parametersWalletId + - *parametersTransactionId + - *parametersMetadataFormat + responses: *responsesGetTransaction + + delete: + operationId: deleteTransaction + tags: ["Transactions"] + summary: Forget + description: | +

status: stable

+ + Forget pending transaction. Importantly, a transaction, when sent, + cannot be cancelled. One can only request forgetting about it + in order to try spending (concurrently) the same UTxO in another + transaction. But, the transaction may still show up later in a block + and therefore, appear in the wallet. + parameters: + - *parametersWalletId + - *parametersTransactionId + responses: *responsesDeleteTransaction + + /wallets/{walletId}/transactions-construct: + post: + operationId: constructTransaction + tags: ["Transactions New"] + summary: Construct + description: | +

status: stable

+ + Create a transaction to be signed from the wallet. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiConstructTransactionData + responses: *responsesConstructTransaction + + /wallets/{walletId}/transactions-sign: + post: + operationId: signTransaction + tags: ["Transactions New"] + summary: Sign + description: | +

status: stable

+ + Signs a serialised transaction either hex-encoded or base64-encoded, + returning the modified transaction. + + This endpoint will add new witnesses using the keys available + to this wallet. Any existing witnesses will remain in the + witness set. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiSignTransactionPostData + responses: *responsesSignTransaction + + /wallets/{walletId}/transactions-decode: + post: + operationId: decodeTransaction + tags: ["Transactions New"] + summary: Decode + description: | +

status: stable

+ + Decode a serialized transaction, either freshly constructed, + partially signed or fully-signed. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiDecodeTransactionPostData + responses: *responsesDecodedTransaction + + /wallets/{walletId}/transactions-submit: + post: + operationId: submitTransaction + tags: ["Transactions New"] + summary: Submit + description: | +

status: stable

+ Submit a transaction that was already created and signed. + Fails for foreign transactions that is transactions which lack + the wallet's inputs and withdrawals. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiSignedTransactionEncoded + responses: *responsesPostExternalTransaction + + /wallets/{walletId}/addresses: + get: + operationId: listAddresses + tags: ["Addresses"] + summary: List + description: | +

status: stable

+ + Return a list of known addresses, ordered from newest to oldest + parameters: + - *parametersWalletId + - *parametersAddressState + responses: *responsesListAddresses + + /wallets/{walletId}/keys/{index}: + post: + operationId: postAccountKey + tags: ["Keys"] + summary: Create Account Public Key + description: | +

status: stable

+ Derive an account public key for any account index. For this key derivation to be possible, + the wallet must have been created from mnemonic. + + It is possible to use the optional `purpose` field to override that branch of the derivation path + with different hardened derivation index. If that field is omitted, the default purpose + for Cardano wallets (`1852H`) will be used. + + Note: Only _Hardened_ indexes are supported by this endpoint. + parameters: + - *parametersWalletId + - *parametersDerivationSegment + requestBody: + required: true + content: + application/json: + schema: *ApiPostAccountKeyDataWithPurpose + responses: *responsesPostAccountKey + + /wallets/{walletId}/keys: + get: + operationId: getAccountKey + tags: ["Keys"] + summary: Get Account Public Key + description: | +

status: stable

+ Retrieve the account public key of this wallet. + + To get an extended public key, instead of the public key, + use query parameter `format=extended`. For non-extended public key + use `format=non_extended` or omit query parameter. + + Note the returned key is bech32-encoded. To be used when restoring + a wallet with public account key only, one needs to pass the key + in hex-encoded form. The bech32 tool which is included + in cardano-wallet distribution can used on the command-line: + + + curl https://my.host/v2/wallets/1f8[...]/keys?format=extended' | jq -r . | bech32 + + + parameters: + - *parametersWalletId + responses: *responsesGetAccountKey + + /wallets/{walletId}/keys/{role}/{index}: + get: + operationId: getWalletKey + tags: ["Keys"] + summary: Get Public Key + description: | +

status: stable

+ Return a public key for a given role and derivation index. + + To get a hash of the public key, instead of the public key, + use query parameter `hash=true`. + + Note: Only `Soft` indexes are supported by this endpoint. + parameters: + - *parametersWalletId + - *parametersRole + - *parametersDerivationSegment + responses: *responsesGetShelleyKey + + /wallets/{walletId}/policy-id: + post: + operationId: postPolicyId + tags: ["Keys"] + summary: Create Policy Id + description: | +

status: stable

+ + Create policy id for the wallet and a given mint/burn script. + + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiPostPolicyIdData + responses: *responsesPostPolicyId + + /wallets/{walletId}/policy-key: + post: + operationId: postPolicyKey + tags: ["Keys"] + summary: Create Policy Key + description: | +

status: stable

+ + Create policy key for the wallet. + + In order to be able to mint/burn assets with `POST Construct` endpoint there needs to be + a policy key set for the wallet. Invoking this endpoint would be required for all wallets instantiated + before introducing mint/burn feature prior to making a mint/burn transaction from them. + + To get a hash of the policy key instead of the policy key, + use query parameter `hash=true`. + + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiPostPolicyKeyData + responses: *responsesPostPolicyKey + + get: + operationId: getPolicyKey + tags: ["Keys"] + summary: Get Policy Key + description: | +

status: stable

+ Return a policy key for a derivation index = 0. + + To get a hash of the policy key instead of the policy key, + use query parameter `hash=true`. + + parameters: + - *parametersWalletId + responses: *responsesGetPolicyKey + + /wallets/{walletId}/stake-keys: + get: + operationId: listStakeKeys + tags: ["Stake Pools"] + summary: List Stake Keys + description: | +

status: Experimental

+ + List stake-keys relevant to the wallet, and how much ada is associated with each. + parameters: + - *parametersWalletId + responses: *responsesListStakeKeys + + /stake-pools: + get: + operationId: listStakePools + tags: ["Stake Pools"] + summary: List + description: | +

status: stable

+ + List all known stake pools ordered by descending `non_myopic_member_rewards`. + The `non_myopic_member_rewards` — and thus the ordering — depends on the `?stake` query + parameter. + + Some pools _may_ also have metadata attached to them. + parameters: + - *parametersIntendedStakeAmount + responses: *responsesListStakePools + + /stake-pools/maintenance-actions: + get: + operationId: getMaintenanceActions + tags: ["Stake Pools"] + summary: View Maintenance Actions + description: | + Returns the current status of the stake pools maintenance actions. + responses: *responsesGetMaintenanceAction + + post: + operationId: postMaintenanceAction + tags: ["Stake Pools"] + summary: Trigger Maintenance Actions + description: | + Performs maintenance actions on stake pools, such + as triggering metadata garbage collection. + + Actions may not be instantaneous. + requestBody: + required: true + content: + application/json: + schema: *ApiMaintenanceActionPostData + responses: *responsesPostMaintenanceAction + + /wallets/{walletId}/delegation-fees: + get: + operationId: getDelegationFee + tags: ["Stake Pools"] + summary: Estimate Fee + # ADP-908 - Deprecated soon + deprecated: false + description: | +

status: stable

+ + Estimate fee for joining or leaving a stake pool. Note that it is an + estimation because a delegation induces a transaction for which coins + have to be selected randomly within the wallet. Because of this randomness, + fees can only be estimated. + parameters: + - *parametersWalletId + responses: *responsesGetDelegationFee + + /stake-pools/*/wallets/{walletId}: + delete: + operationId: quitStakePool + tags: ["Stake Pools"] + summary: Quit + description: | +

status: stable

+ + Stop delegating completely. The wallet's stake will become inactive. + + Any current rewards will automatically withdrawn. + + > ⚠️ Disclaimer ⚠️ + > + > This endpoint historically use to take a stake pool id as a path parameter. + > However, retiring from delegation is ubiquitous and not tied to a particular + > stake pool. For backward-compatibility reasons, sending stake pool ids as path + > parameter will still be accepted by the server but new integrations are + > encouraged to provide a placeholder asterisk `*` instead. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiWalletPassphrase + responses: *responsesQuitStakePool + + /stake-pools/{stakePoolId}/wallets/{walletId}: + put: + operationId: joinStakePool + tags: ["Stake Pools"] + summary: Join + description: | +

status: stable

+ + Delegate all (current and future) addresses from the given wallet to the given stake pool. + + Note: Bech32-encoded stake pool identifiers can vary in length. + + parameters: + - *parametersStakePoolId + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiWalletPassphrase + responses: *responsesJoinStakePool + + /dreps/{drepId}/wallets/{walletId}: + put: + operationId: joinDRep + tags: ["DReps"] + summary: Join + description: | +

status: stable

+ + Delegate all votes from the given wallet to the given DRep or + case abstain or no-confidence + + parameters: + - *parametersDRepId + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiWalletPassphrase + responses: *responsesJoinDRep + + /wallets/{walletId}/coin-selections/random: + post: + operationId: selectCoins + tags: ["Coin Selections"] + summary: Random + description: | +

status: stable

+ + Select coins to cover the given set of payments. + + Uses the + Random-Improve coin selection algorithm. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiSelectCoinsData + responses: *responsesSelectCoins + + /wallets/{walletId}/migrations: + post: + operationId: migrateShelleyWallet + tags: ["Migrations"] + summary: Migrate + description: | + Migrate the UTxO balance of this wallet to the given set of addresses. + + This operation will attempt to transfer as much of the wallet's balance + as possible to the given set of addresses, by creating and submitting + as many transactions as may be necessary to migrate the entire balance. + + In order to minimize the total transaction fee required, UTxO entries + are coalesced together to the greatest extent possible in the resulting + transactions. No attempt is made to preserve the wallet's UTxO + distribution. + + This operation is performed on a best-effort basis. If there is + insufficient ada available to pay for the entire UTxO set to be + migrated, then only a subset of the wallet's UTxO set will be migrated. + + A typical use of this operation would be to move all funds from an old + wallet to a new wallet, by providing addresses that belong to the new + wallet. + parameters: + - <<: *parametersWalletId + name: walletId + requestBody: + required: true + content: + application/json: + schema: *ApiShelleyWalletMigrationPostData + responses: *responsesMigrateWallet + + /wallets/{walletId}/migrations/plan: + post: + operationId: createShelleyWalletMigrationPlan + tags: ["Migrations"] + summary: Create a migration plan + description: | + Generate a plan for migrating the UTxO balance of this wallet to + another wallet, without executing the plan. + + This operation generates a plan that transfers as much of the wallet's + balance as possible, by creating as many selections as may be necessary + to migrate the entire balance. Each selection created is the basis for + a transaction. + + In order to minimize the total transaction fee required, UTxO entries + are coalesced together to the greatest extent possible in the resulting + selections. No attempt is made to preserve the wallet's UTxO + distribution. + + The plan is generated on a best-effort basis. If there is insufficient + ada available to pay for the entire UTxO set to be migrated, then only + a subset of the wallet's UTxO set will be included in the resultant + plan. + parameters: + - <<: *parametersWalletId + name: walletId + requestBody: + required: true + content: + application/json: + schema: *ApiWalletMigrationPlanPostData + responses: *responsesCreateWalletMigrationPlan + + /wallets/{walletId}/transactions-balance: + post: + operationId: balanceTransaction + tags: ["Transactions New"] + summary: Balance + description: | +

status: under development

+ Balance a transaction body of a given transaction, add needed inputs/outputs, + so as the transaction can be signed from the wallet. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiBalanceTransactionPostData + responses: *responsesBalanceTransaction + + /byron-wallets: + post: + operationId: postByronWallet + tags: ["Byron Wallets"] + summary: Restore + description: | +

status: stable

+ + Restore a Byron wallet from a mnemonic sentence or encrypted root private key (deprecated). + + **⚠️ WARNING ⚠️** + + The construction of random wallet in itself is **deprecated**, in particular the restoration from an encrypted root private key. + These endpoints exist to ease migrations from legacy software such as `cardano-sl` but should be avoided by new applications. + requestBody: + required: true + content: + application/json: + schema: *SomeByronWalletPostData + responses: *responsesPostByronWallet + + get: + operationId: listByronWallets + tags: ["Byron Wallets"] + summary: List + description: | +

status: stable

+ + Return a list of known Byron wallets, ordered from oldest to newest. + responses: *responsesListByronWallets + + /byron-wallets/{walletId}/assets: + get: + operationId: listByronAssets + tags: ["Byron Assets"] + summary: List Assets + description: | + List all assets associated with the wallet, and their metadata + if known. + + An asset is _associated_ with a wallet if it is involved in a + transaction of the wallet. + parameters: + - *parametersWalletId + responses: *responsesListAssets + + /byron-wallets/{walletId}/assets/{policyId}/{assetName}: + get: + operationId: getByronAsset + tags: ["Byron Assets"] + summary: Get Asset + description: | + Fetch a single asset from its `policy_id` and `asset_name`, + with its metadata if any. + + The asset must be associated with the wallet. + parameters: + - *parametersWalletId + - *parametersPolicyId + - *parametersAssetName + responses: *responsesGetAsset + + /byron-wallets/{walletId}/assets/{policyId}: + get: + operationId: getByronAssetDefault + tags: ["Byron Assets"] + summary: Get Asset (empty name) + description: | + Fetch the asset from `policy_id` with an empty name. + + The asset must be associated with the wallet. + parameters: + - *parametersWalletId + - *parametersPolicyId + responses: *responsesGetAsset + + /byron-wallets/{walletId}/statistics/utxos: + get: + operationId: getByronUTxOsStatistics + tags: ["Byron Wallets"] + summary: UTxO Statistics + description: | +

status: stable

+ + Return the UTxO distribution across the whole wallet, in the form of a histogram. + + ``` + │ + 100 ─ + │ + │ ┌───┐ + 10 ─ ┌───┐ │ │ ┌───┐ + │ ┌───┐ │ │ │ │ │ │ + │ │ │ │ │ │ │ ┌───┐ │ │ + 1 ─ ┌───┐ │ │ │ │ │ │ │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ │ + │ │ │ │ │ │ │ │ │ │ ╷ │ │ ╷ │ │ ╷ ╷ │ │ + └─┘ └─│───────│─┘ └─│─┘ └─│─┘ └─│─┘ └─│───────│─┘ └──── + 10μ₳ 100μ₳ 1000μ₳ 0.1₳ 1₳ 10₳ 100₳ + ``` + parameters: + - *parametersWalletId + responses: *responsesGetUTxOsStatistics + + /byron-wallets/{walletId}/utxo: + get: + operationId: getByronWalletUtxoSnapshot + tags: ["Byron Wallets"] + summary: A snapshot of the wallet's UTxO set + description: | + Generate a snapshot of the wallet's UTxO set. + + This endpoint is intended for debugging purposes. + parameters: + - *parametersWalletId + responses: *responsesGetWalletUtxoSnapshot + + /byron-wallets/{walletId}: + get: + operationId: getByronWallet + tags: ["Byron Wallets"] + summary: Get + description: | +

status: stable

+ + Return information about a Byron wallet. + parameters: + - *parametersWalletId + responses: *responsesGetByronWallet + + delete: + operationId: deleteByronWallet + tags: ["Byron Wallets"] + summary: Delete + description: | +

status: stable

+ + Delete a Byron wallet. + parameters: + - *parametersWalletId + responses: *responsesDeleteWallet + + put: + operationId: putByronWallet + tags: ["Byron Wallets"] + summary: Update Metadata + description: | +

status: stable

+ parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiWalletPutData + responses: *responsesPutWallet + + /byron-wallets/{walletId}/passphrase: + put: + operationId: putByronWalletPassphrase + tags: ["Byron Wallets"] + summary: Update Passphrase + description: | +

status: stable

+ parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiByronWalletPutPassphraseData + responses: *responsesPutWalletPassphrase + + /byron-wallets/{walletId}/addresses: + post: + operationId: createAddress + tags: ["Byron Addresses"] + summary: Create Address + description: | +

status: stable

+ + ⚠️ This endpoint is available for `random` wallets only. Any + attempt to call this endpoint on another type of wallet will result in + a `403 Forbidden` error from the server. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiPostRandomAddressData + responses: *responsesPostRandomAddress + + get: + operationId: listByronAddresses + tags: ["Byron Addresses"] + summary: List + description: | +

status: stable

+ + Return a list of known addresses, ordered from newest to oldest for sequential wallets. + Arbitrarily ordered for random wallets. + parameters: + - *parametersWalletId + - *parametersAddressState + responses: *responsesListAddresses + + put: + operationId: importAddresses + tags: ["Byron Addresses"] + summary: Import Addresses + description: | +

status: stable

+ + ⚠️ This endpoint is available for `random` wallets only. Any + attempt to call this endpoint on another type of wallet will result in + a `403 Forbidden` error from the server. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiPutAddressesData + responses: *responsesPutRandomAddresses + + /byron-wallets/{walletId}/addresses/{addressId}: + put: + operationId: importAddress + tags: ["Byron Addresses"] + summary: Import Address + description: | +

status: stable

+ + ⚠️ This endpoint is available for `random` wallets only. Any + attempt to call this endpoint on another type of wallet will result in + a `403 Forbidden` error from the server. + parameters: + - *parametersWalletId + - *parametersAddressId + responses: *responsesPutRandomAddress + + /byron-wallets/{walletId}/payment-fees: + post: + operationId: postByronTransactionFee + tags: ["Byron Transactions"] + summary: Estimate Fee + # ADP-908 - Deprecated soon + deprecated: false + description: | +

status: stable

+ + Estimate fee for the transaction. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiPostTransactionFeeDataByron + responses: *responsesPostTransactionFee + + /byron-wallets/{walletId}/transactions: + post: + operationId: postByronTransaction + tags: ["Byron Transactions"] + summary: Create + description: | +

status: stable

+ + Create and send transaction from the wallet. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiPostTransactionDataByron + responses: *responsesPostTransaction + + get: + operationId: listByronTransactions + tags: ["Byron Transactions"] + summary: List + description: | +

status: stable

+ + List all incoming and outgoing transactions for the given wallet. + parameters: + - *parametersWalletId + - *parametersStartDate + - *parametersEndDate + - *parametersSortOrder + - *parametersMaxCount + - *parametersAddress + responses: *responsesListTransactions + + /byron-wallets/{walletId}/transactions/{transactionId}: + get: + operationId: getByronTransaction + tags: ["Byron Transactions"] + summary: Get + description: | +

status: stable

+ + Get transaction by id. + parameters: + - *parametersWalletId + - *parametersTransactionId + responses: *responsesGetTransaction + + delete: + operationId: deleteByronTransaction + tags: ["Byron Transactions"] + summary: Forget + description: | +

status: stable

+ + Forget pending Byron transaction. Importantly, a transaction, when sent, + cannot be cancelled. One can only request forgetting about it + in order to try spending (concurrently) the same UTxO in another + transaction. But, the transaction may still show up later in a block + and therefore, appear in the wallet. + parameters: + - *parametersWalletId + - *parametersTransactionId + responses: *responsesDeleteTransaction + + /byron-wallets/{walletId}/coin-selections/random: + post: + operationId: byronSelectCoins + tags: ["Byron Coin Selections"] + summary: Random + description: | +

status: stable

+ + Select coins to cover the given set of payments. + + Uses the + Random-Improve coin selection algorithm. + + Note: Not supported for Byron random wallets. + + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiByronSelectCoinsData + responses: *responsesSelectCoins + + /byron-wallets/{walletId}/migrations: + post: + operationId: migrateByronWallet + tags: ["Byron Migrations"] + summary: Migrate + description: | + Migrate the UTxO balance of this wallet to the given set of addresses. + + This operation will attempt to transfer as much of the wallet's balance + as possible to the given set of addresses, by creating and submitting + as many transactions as may be necessary to migrate the entire balance. + + In order to minimize the total transaction fee required, UTxO entries + are coalesced together to the greatest extent possible in the resulting + transactions. No attempt is made to preserve the wallet's UTxO + distribution. + + This operation is performed on a best-effort basis. If there is + insufficient ada available to pay for the entire UTxO set to be + migrated, then only a subset of the wallet's UTxO set will be migrated. + + A typical use of this operation would be to move all funds from an old + wallet to a new wallet, by providing addresses that belong to the new + wallet. + parameters: + - <<: *parametersWalletId + name: walletId + requestBody: + required: true + content: + application/json: + schema: *ApiByronWalletMigrationPostData + responses: *responsesMigrateWallet + + /byron-wallets/{walletId}/migrations/plan: + post: + operationId: createByronWalletMigrationPlan + tags: ["Byron Migrations"] + summary: Create a migration plan + description: | + Generate a plan for migrating the UTxO balance of this wallet to + another wallet, without executing the plan. + + This operation generates a plan that transfers as much of the wallet's + balance as possible, by creating as many selections as may be necessary + to migrate the entire balance. Each selection created is the basis for + a transaction. + + In order to minimize the total transaction fee required, UTxO entries + are coalesced together to the greatest extent possible in the resulting + selections. No attempt is made to preserve the wallet's UTxO + distribution. + + The plan is generated on a best-effort basis. If there is insufficient + ada available to pay for the entire UTxO set to be migrated, then only + a subset of the wallet's UTxO set will be included in the resultant + plan. + parameters: + - <<: *parametersWalletId + name: walletId + requestBody: + required: true + content: + application/json: + schema: *ApiWalletMigrationPlanPostData + responses: *responsesCreateWalletMigrationPlan + + /network/information: + get: + operationId: getNetworkInformation + tags: ["Network"] + summary: Information + description: | +

status: stable

+ responses: *responsesGetNetworkInformation + + /network/clock: + get: + operationId: getNetworkClock + tags: ["Network"] + summary: Clock + description: | +

status: stable

+ parameters: + - <<: *parametersForceNtpCheck + name: forceNtpCheck + responses: *responsesGetNetworkClock + + /network/parameters: + get: + operationId: getNetworkParameters + tags: ["Network"] + summary: Parameters + description: | +

status: stable

+ + Returns the set of network parameters for the current epoch. + responses: *responsesGetNetworkParameters + + /proxy/transactions: + post: + operationId: postExternalTransaction + tags: ["Proxy"] + summary: Submit External Transaction + # ADP-908 - deprecated soon + deprecated: false + description: | +

status: stable

+ + Submits a transaction that was created and signed outside of cardano-wallet. + + NOTE: Unlike the `submitTransaction` endpoint, there are no + guarantees that a transaction accepted by this endpoint will + actually be included in the chain. It's up to the caller to + retry submission until the transaction is confirmed. + requestBody: + content: + application/octet-stream: + schema: *signedTransactionBlob + responses: *responsesPostExternalTransaction + + /addresses/{addressId}: + get: + operationId: inspectAddress + tags: ["Addresses"] + summary: Inspect Address + description: | +

status: stable

+ + Give useful information about the structure of a given address. + parameters: + - *parametersAddressId + responses: *responsesInspectAddress + + /addresses: + post: + operationId: postAnyAddress + tags: ["Addresses"] + summary: Construct Address + description: | +

status: stable

+ + Construct any address by specyfying credential for payment or delegation. + + In Cardano, Addresses are made of three parts: + + ``` + *---------*---------*-----------* + | NETWORK | PAYMENT | DELEGATION | + *---------*---------*-----------* + ``` + + The `NETWORK` part allows for distinguishing addresses between different networks like the mainnet or the testnet. It is implicitly + handled by the server without you having to worry about it. The `PAYMENT` and `DELEGATION` parts however can be constructed similarly, using + either: + + - A public key + - A script + + The script itself is either constructed out of a public key, one of two timelocks, or one of the three following primitives: + + - all + - any + - some + + The timelock can determine validity as respect to the slot. `active_from slot` means the script is valid from the specified slot + and onward. `active_until slot` means the script is valid until (not included) the specified slot. + + Each of which contains one or more script(s) that can be either keys or primitives, and so on. Schematically: + + ``` + ┏─────────┓ + SCRIPT = ──┬───────────────────────┤ pub key ├─────────────────────┬── + │ ┗─────────┛ │ + │ ┏──────────────────┓ │ + ├───────────────────────┤ ACTIVE_FROM slot ├──── ───────┤ + │ ┗──────────────────┛ │ + │ ┏───────────────────┓ │ + ├───────────────────────┤ ACTIVE_UNTIL slot ├───────────┤ + │ ┗───────────────────┛ │ + │ │ + │ ╭─────╮ ╭────────╮ │ + ├──┤ ALL ├───┤ SCRIPT ├─┬───────────────────────────────┤ + │ ╰─────╯ ^ ╰────────╯ │ │ + │ │ ╭───╮ │ │ + │ └───┤ , ├────┘ │ + │ ╰───╯ │ + │ ╭─────╮ ╭────────╮ │ + ├──┤ ANY ├───┤ SCRIPT ├─┬───────────────────────────────┤ + │ ╰─────╯ ^ ╰────────╯ │ │ + │ │ ╭───╮ │ │ + │ └───┤ , ├────┘ │ + │ ╰───╯ │ + │ ╭──────╮ ╭──────────╮ ┏───┓ ╭──────╮ ╭────────╮ │ + └──┤ SOME ├─┤ AT_LEAST ├─┤ n ├─┤ FROM ├───┤ SCRIPT ├─┬──┘ + ╰──────╯ ╰──────────╯ ┗───┛ ╰──────╯ ^ ╰────────╯ │ + │ ╭───╮ │ + └───┤ , ├────┘ + ╰───╯ + ``` + + requestBody: + content: + application/json: + schema: *ApiAddressData + responses: *responsesPostAnyAddress + + /settings: + put: + operationId: putSettings + tags: ["Settings"] + summary: Update settings + description: | +

status: stable

+ + Overwrite current settings. + requestBody: + required: true + content: + application/json: + schema: *ApiSettingsPutData + responses: *responsesPutSettings + + get: + operationId: getSettings + tags: ["Settings"] + summary: Get settings + description: | +

status: stable

+ + Return the current settings. + responses: *responsesGetSettings + + /smash/health: + get: + operationId: getCurrentSmashHealth + tags: ["Utils"] + summary: Current SMASH health + description: | + Get health status of the currently active SMASH server. + parameters: + - in: query + name: url + schema: *ApiSmashServer + required: false + description: check this url for health instead of the currently configured one + responses: *responsesGetSmashHealth + + /shared-wallets: + post: + operationId: postSharedWallet + tags: ["Shared Wallets"] + summary: Create + description: | +

status: stable

+ Create a shared wallet from either an account public key and script + templates or mnemonic and script templates. + + requestBody: + required: true + content: + application/json: + schema: *ApiSharedWalletPostData + responses: *responsesPostSharedWallet + + get: + operationId: listSharedWallets + tags: ["Shared Wallets"] + summary: List + description: | +

status: stable

+ + Return a list of known shared wallets, ordered from oldest to newest. + responses: *responsesListSharedWallets + + /shared-wallets/{walletId}: + get: + operationId: getSharedWallet + tags: ["Shared Wallets"] + summary: Get + description: | +

status: stable

+ Get a shared wallet for a given wallet id. + + parameters: + - *parametersWalletId + responses: *responsesGetSharedWallet + + delete: + operationId: deleteSharedWallet + tags: ["Shared Wallets"] + summary: Delete + description: | +

status: stable

+ parameters: + - *parametersWalletId + responses: *responsesDeleteWallet + + put: + operationId: putSharedWallet + tags: ["Shared Wallets"] + summary: Update Metadata + description: | +

status: stable

+ parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiWalletPutDataExtended + responses: *responsesPutSharedWallet + + /shared-wallets/{walletId}/statistics/utxos: + get: + operationId: getUTxOsStatisticsShared + tags: ["Shared Wallets"] + summary: UTxO Statistics + description: | +

status: stable

+ + Return the UTxO distribution across the whole wallet, in the form of a histogram. + + ``` + │ + 100 ─ + │ + │ ┌───┐ + 10 ─ ┌───┐ │ │ ┌───┐ + │ ┌───┐ │ │ │ │ │ │ + │ │ │ │ │ │ │ ┌───┐ │ │ + 1 ─ ┌───┐ │ │ │ │ │ │ │ │ │ │ + │ │ │ │ │ │ │ │ │ │ │ │ │ + │ │ │ │ │ │ │ │ │ │ ╷ │ │ ╷ │ │ ╷ ╷ │ │ + └─┘ └─│───────│─┘ └─│─┘ └─│─┘ └─│─┘ └─│───────│─┘ └──── + 10μ₳ 100μ₳ 1000μ₳ 0.1₳ 1₳ 10₳ 100₳ + ``` + parameters: + - *parametersWalletId + responses: *responsesGetUTxOsStatistics + + /shared-wallets/{walletId}/utxo: + get: + operationId: getSharedWalletUtxoSnapshot + tags: ["Shared Wallets"] + summary: A snapshot of the wallet's UTxO set + description: | + Generate a snapshot of the wallet's UTxO set. + + This endpoint is intended for debugging purposes. + parameters: + - *parametersWalletId + responses: *responsesGetWalletUtxoSnapshot + + /shared-wallets/{walletId}/payment-script-template: + patch: + operationId: patchSharedWalletInPayment + tags: ["Shared Wallets"] + summary: Update Payment + description: | +

status: stable

+ Update payment script template for a given shared wallet by + updating/adding account public key for cosigner. Updating the + shared wallet account key results in an error. Also updating is + enabled only for incomplete shared wallet, ie., the wallet that has + a missing account public key for any cosigner. + + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiSharedWalletPatchData + responses: *responsesPatchSharedWallet + + /shared-wallets/{walletId}/delegation-script-template: + patch: + operationId: patchSharedWalletInDelegation + tags: ["Shared Wallets"] + summary: Update Delegation + description: | +

status: stable

+ Update delegation script template for a given shared wallet by + updating/adding account public key for cosigner. Updating the + shared wallet account key results in an error. Also updating is + enabled only for incomplete shared wallet, ie., the wallet that has + a missing account public key for any cosigner. + + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiSharedWalletPatchData + responses: *responsesPatchSharedWallet + + /shared-wallets/{walletId}/transactions-construct: + post: + operationId: constructSharedTransaction + tags: ["Shared Transactions"] + summary: Construct + description: | +

status: stable

+ + Create a transaction to be signed from the shared wallet. + + Works for the following fields: + - payments + - metadata + - validity_interval + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiConstructTransactionData + responses: *responsesConstructTransaction + + /shared-wallets/{walletId}/transactions-decode: + post: + operationId: decodeSharedTransaction + tags: ["Shared Transactions"] + summary: Decode + description: | +

status: stable

+ + Decode a serialized transaction, either freshly constructed, + partially signed or fully-signed. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiDecodeTransactionPostData + responses: *responsesDecodedTransaction + + /shared-wallets/{walletId}/transactions-sign: + post: + operationId: signSharedTransaction + tags: ["Shared Transactions"] + summary: Sign + description: | +

status: stable

+ + Signs a serialised transaction, returning the modified + transaction. + + This endpoint will add new witnesses using the keys available + to this wallet. Any existing witnesses will remain in the + witness set. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiSignTransactionPostData + responses: *responsesSignTransaction + + /shared-wallets/{walletId}/transactions-submit: + post: + operationId: submitSharedTransaction + tags: ["Shared Transactions"] + summary: Submit + description: | +

status: stable

+ Submit a transaction that was already created and fully signed. + Fails for foreign transactions that is transactions which lack + the wallet's inputs and withdrawals. + parameters: + - *parametersWalletId + requestBody: + required: true + content: + application/json: + schema: *ApiSignedTransactionEncoded + responses: *responsesPostExternalTransaction + + /shared-wallets/{walletId}/transactions: + get: + operationId: listSharedTransactions + tags: ["Shared Transactions"] + summary: List + description: | +

status: stable

+ + Lists all incoming and outgoing wallet's transactions. + parameters: + - *parametersWalletId + - *parametersStartDate + - *parametersEndDate + - *parametersSortOrder + - *parametersMaxCount + - *parametersMinWithdrawal + - *parametersMetadataFormat + - *parametersAddress + responses: *responsesListTransactions + + /shared-wallets/{walletId}/transactions/{transactionId}: + get: + operationId: getSharedTransaction + tags: ["Shared Transactions"] + summary: Get + description: | +

status: stable

+ + Get transaction by id. + parameters: + - *parametersWalletId + - *parametersTransactionId + - *parametersMetadataFormat + responses: *responsesGetTransaction + + /shared-wallets/{walletId}/keys/{index}: + post: + operationId: postAccountKeyShared + tags: ["Shared Keys"] + summary: Create Account Public Key + description: | +

status: stable

+ Derive an account public key for any account index. For this key derivation to be possible, + the wallet must have been created from mnemonic. + + Note: Only _Hardened_ indexes are supported by this endpoint. + parameters: + - *parametersWalletId + - *parametersDerivationSegment + requestBody: + required: true + content: + application/json: + schema: *ApiPostAccountKeyData + responses: *responsesPostAccountKeyShared + + /shared-wallets/{walletId}/keys: + get: + operationId: getAccountKeyShared + tags: ["Shared Keys"] + summary: Get Account Public Key + description: | +

status: stable

+ Retrieve the account public key of this shared wallet. + + To get an extended public key, instead of the public key, + use query parameter `format=extended`. For non-extended public key + use `format=non_extended` or omit query parameter. + + parameters: + - *parametersWalletId + responses: *responsesGetAccountSharedKey + + /shared-wallets/{walletId}/keys/{role}/{index}: + get: + operationId: getSharedWalletKey + tags: ["Shared Keys"] + summary: Get Public Key + description: | +

status: stable

+ Return a public key for a given role and derivation index for + a shared wallet. + + To get a hash of the public key, instead of the public key, + use query parameter `hash=true`. + + Note: Only `Soft` indexes are supported by this endpoint. + parameters: + - *parametersWalletId + - *parametersRole + - *parametersDerivationSegment + - *parametersDerivationHash + responses: *responsesGetSharedKey + + /shared-wallets/{walletId}/addresses: + get: + operationId: listSharedAddresses + tags: ["Shared Addresses"] + summary: List + description: | +

status: stable

+ + Return a list of known addresses, ordered from newest to oldest + parameters: + - *parametersWalletId + - *parametersAddressState + responses: *responsesListAddresses + + /blocks/latest/header: + get: + operationId: getBlocksLatestHeader + tags: ["Node"] + summary: Block Header + description: | +

status: stable

+ + Return the latest block-header available at the chain source + responses: + <<: *responsesErr406 + 200: + description: OK + content: + application/json: + schema: *ApiBlockHeader \ No newline at end of file From 6ca500d5b796e689a4578edc969ee6f5395997be Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Tue, 31 Mar 2026 00:30:18 +0300 Subject: [PATCH 10/19] chore: remove alias regression test (fix lives in yaml3) (#6) The alias/excessive-aliasing fix is in oasdiff/yaml3; no test is needed at the kin-openapi level. Co-authored-by: Claude Sonnet 4.6 --- openapi3/alias_issue_test.go | 15 - openapi3/testdata/alias.yml | 8686 ---------------------------------- 2 files changed, 8701 deletions(-) delete mode 100644 openapi3/alias_issue_test.go delete mode 100644 openapi3/testdata/alias.yml diff --git a/openapi3/alias_issue_test.go b/openapi3/alias_issue_test.go deleted file mode 100644 index cf404b743..000000000 --- a/openapi3/alias_issue_test.go +++ /dev/null @@ -1,15 +0,0 @@ -package openapi3 - -import ( - "testing" - - "github.com/stretchr/testify/require" -) - -func TestAliasIssue(t *testing.T) { - // IncludeOrigin = true - loader := NewLoader() - _, err := loader.LoadFromFile("testdata/alias.yml") - require.NoError(t, err) - // require.Nil(t, doc) -} diff --git a/openapi3/testdata/alias.yml b/openapi3/testdata/alias.yml deleted file mode 100644 index 83493b3b5..000000000 --- a/openapi3/testdata/alias.yml +++ /dev/null @@ -1,8686 +0,0 @@ -openapi: 3.0.3 -info: - title: Cardano Wallet Backend API - version: v2025-12-15 - license: - name: Apache-2.0 - url: https://raw.githubusercontent.com/cardano-foundation/cardano-wallet/master/LICENSE - description: | -

- -

-externalDocs: - description: Need more? Click here to access our API guide and walkthrough. - url: https://cardano-foundation.github.io/cardano-wallet/ - -servers: - - url: https://localhost:8090/v2/ - -############################################################################# -# # -# FIELDS # -# # -############################################################################# - -x-date: &date - type: string - format: iso-8601-date-and-time - example: 2019-02-27T14:46:45Z - -x-slotNumber: &slotNumber - type: integer - description: The zero-based slot index within an epoch. - minimum: 0 - example: 1337 - -x-stakePoolsNumber: &stakePoolsNumber - type: integer - minimum: 0 - example: 100 - -x-numberOfSeconds: &numberOfSeconds - type: object - required: - - quantity - - unit - properties: - quantity: - type: number - minimum: 0.0 - example: 10.0 - unit: - type: string - enum: ["second"] - -x-epochNumber: &epochNumber - type: integer - description: An epoch is a time period which is divided into slots. - minimum: 0 - example: 14 - -x-epochInfo: &epochInfo - type: object - required: - - epoch_number - - epoch_start_time - properties: - epoch_number: *epochNumber - epoch_start_time: *date - -x-blockId: &blockId - description: The hash of a block - type: string - format: hex - maxLength: 64 - minLength: 64 - example: 3c07030e36bfffe67e2e2ec09e5293d384637cd2f004356ef320f3fe6c52041a - -x-absoluteSlot: &absoluteSlot - type: integer - description: The 0-based slot index starting from genesis of the blockchain. - minimum: 0 - example: 8086 - -x-witnessCount: &witnessCount - type: integer - description: The number of witnesses detected - minimum: 0 - maximum: 127 - -x-numberOfSlots: &numberOfSlots - type: object - required: - - quantity - - unit - properties: - quantity: - type: integer - minimum: 0 - example: 42000 - unit: - type: string - enum: ["slot"] - -x-numberOfBlocks: &numberOfBlocks - type: object - required: - - quantity - - unit - properties: - quantity: - type: integer - minimum: 0 - example: 1337 - unit: - type: string - enum: - - block - example: "block" - -x-genesis: &genesis - type: string - enum: ["from_genesis"] - example: "from_genesis" - -x-tip: &tip - type: string - enum: ["from_tip"] - example: "from_tip" - -x-blockReference: &blockReference - description: A reference to a particular time slot, and the block height at that point. - type: object - required: - - absolute_slot_number - - slot_number - - epoch_number - - time - - height - properties: - absolute_slot_number: *absoluteSlot - slot_number: *slotNumber - epoch_number: *epochNumber - time: *date - height: *numberOfBlocks - -x-chainPoint : &chainPoint - description: A reference to a particular block. - type: object - required: - - block_header_hash - - absolute_slot_number - properties: - block_header_hash: *blockId - absolute_slot_number: *absoluteSlot - -x-slotId: &slotId - description: A slot identifier, given by epoch number and local slot index. - type: object - required: - - epoch_number - - slot_number - properties: - epoch_number: *epochNumber - slot_number: *slotNumber - -x-slotReference: &slotReference - description: A reference to a particular time slot. - type: object - required: - - absolute_slot_number - - slot_number - - epoch_number - - time - properties: - absolute_slot_number: *absoluteSlot - epoch_number: *epochNumber - slot_number: *slotNumber - time: *date - -x-genesisBlock: &genesisBlock - description: A reference to a particular block. - type: object - required: - - slot_number - - epoch_number - properties: - slot_number: - <<: *slotNumber - maximum: 0 - example: 0 - epoch_number: - <<: *epochNumber - maximum: 0 - example: 0 - -x-percentage: &percentage - type: object - required: - - quantity - - unit - properties: - quantity: - type: number - minimum: 0 - maximum: 100 - example: 42 - unit: - type: string - enum: - - percent - -x-microseconds: µseconds - type: object - required: - - quantity - - unit - properties: - quantity: - type: number - example: 42 - unit: - type: string - enum: - - microsecond - -x-syncProgress: &syncProgress - type: object - required: - - status - properties: - status: - type: string - enum: - - ready - - syncing - - not_responding - progress: - <<: *percentage - description: | - - if: status == syncing -
- example: - status: ready - -x-syncClockProgress: &syncClockProgress - type: object - required: - - status - properties: - status: - type: string - enum: - - unavailable - - pending - - available - offset: - <<: *microseconds - description: | - - if: status == available -
- example: - status: pending - -x-amount: &amount - description: Coins, in Lovelace. Only relates to 'Ada'. Refer to `assets` for multi-assets wallets instead. - type: object - required: - - quantity - - unit - properties: - quantity: - type: integer - minimum: 0 - example: 42000000 - unit: - type: string - enum: - - lovelace - -x-stakeAddress: &stakeAddress - type: string - format: bech32 - example: stake1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2x - -x-addressId: &addressId - type: string - format: base58|bech32 - example: addr1sjck9mdmfyhzvjhydcjllgj9vjvl522w0573ncustrrr2rg7h9azg4cyqd36yyd48t5ut72hgld0fg2xfvz82xgwh7wal6g2xt8n996s3xvu5g - description: | - A sequence of characters that encodes (in Base58 or Bech32) a sequence of bytes - which represents an address on the Cardano blockchain. - Sequences in Base58 encoding are expected to be legacy Byron addresses, - whereas sequences in Bech32 encoding correspond to current Shelley addresses. - - For more details, see - [CIP-0019 — Cardano addresses](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0019) - . - -x-addressState: &addressState - type: string - enum: - - used - - unused - -x-txType: &txType - type: string - pattern: "^Tx AlonzoEra$" - -x-txDescription: &txDescription - description: A description of transaction - type: string - minLength: 0 - maxLength: 256 - example: "Asset minting transaction" - -x-txInNode: &txInNode - type: string - pattern: "^[0-9abcdef]+#[0-9]+$" - minLength: 66 - maxLength: 68 - example: 2f8cd2ef706e5500307636b8477198ee2f204c4181b53c507f46d195140493cb#1 - -x-dataHash: &dataHash - type: string - format: hex - minLength: 64 - maxLength: 64 - example: ca54c8836c475a77c6914b4fd598080acadb0f0067778773484d2c12ae7dc756 - -x-stakePoolMetadataUrl: &stakePoolMetadataUrl - description: A URL to the stake pool's website. - type: string - format: uri - pattern: "^https://.+" - maxLength: 250 - -x-stakePoolMetadataHash: &stakePoolMetadataHash - type: string - format: hex - minLength: 64 - maxLength: 64 - example: ca54c8836c475a77c6914b4fd598080acadb0f0067778773484d2c12ae7dc756 - -x-stakePoolOwner: &stakePoolOwner - type: string - format: bech32 - pattern: "^(ed25519_pk)1[0-9a-z]*$" - -x-adaQuantity: &adaQuantity - type: integer - minimum: 0 - maximum: 45000000000000000 - -x-assetQuantity: &assetQuantity - type: integer - description: | - Number of assets for the given `policy_id` and `asset_name`. - minimum: 0 - -x-assetValueNode: &assetValueNode - description: | - Map of asset values along with their quantities. - assetName in field name is expected (max length 64-character hex-encoded text) - type: object - additionalProperties: *assetQuantity - # Note: propertyNames pattern not supported in current OpenAPI version. - # propertyNames: - # pattern: '^(assetName)$' - example: - - {"asset1": 12, "asset2": 33} - -x-valueNode: &valueNode - nullable: false - oneOf: - - <<: *adaQuantity - title: ada coin - - <<: *assetValueNode - title: asset value - -x-valueNodes: &valueNodes - description: | - Map of values along with their quantities. Can be lovelace or asset. - In the former case 'lovelace' name is expected. - In the latter case assetPolicyId name is expected (56-character hex-encoded text) - type: object - additionalProperties: *valueNode - # Note: propertyNames pattern not supported in current OpenAPI version. - # propertyNames: - # pattern: '^(lovelace)|(assetPolicyId)$' - example: - - {"lovelace": 1423} - - {"lovelace": 1423, "7191ae0e1286891fe5c027a5dc041b7401689938e18e14ec83cf74fb": {"asset1": 12, "asset2": 33}} - -x-stakePoolId: &stakePoolId - type: string - format: hex|bech32 - example: pool1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm - description: A unique identifier for the pool. - -x-drepKeyHashNew: &drepKeyHashNew - type: string - format: bech32 - example: drep_vkh15k6929drl7xt0spvudgcxndryn4kmlzpk4meed0xhqe254czjh2 - description: | - DRep's verification key hash according to CIP-0105. - Replacing now deprecated 'drep' which is now used for drep credential. - pattern: "^(drep_vkh)1[0-9a-z]*$" - -x-drepKeyHash: &drepKeyHash - type: string - format: bech32 - example: drep1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm - description: | - DRep's key hash according to CIP-0105 (deprecated). - - DRep credential which is special byte prepended to script/key hash payload. - Introduced by CIP-0129 and the byte prepended is 0x22 and 0x23 for - key and script hash, respectively. - pattern: "^(drep)1[0-9a-z]*$" - -x-drepScriptHash: &drepScriptHash - type: string - format: bech32 - example: drep1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm - description: | - DRep's script hash according to CIP-0105. - pattern: "^(drep_script)1[0-9a-z]*$" - -x-walletAccountXPubkey: &walletAccountXPubkey - description: An extended account public key (public key + chain code) - type: string - format: hex - minLength: 128 - maxLength: 128 - example: 1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db11423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1 - -x-sharedWalletAccountXPubkey: &sharedWalletAccountXPubkey - description: An extended account public key (public key + chain code) of shared wallet - type: string - format: bech32 - pattern: "^(acct_shared_xvk)1[0-9a-z]*$" - -x-cosigner: &cosigner - type: string - pattern: "^(cosigner#)[0-9]+$" - -x-cosigners: &cosigners - description: Map of cosigners and their account public keys. Use key as in &cosigner, eg. "cosigner#" - type: object - additionalProperties: *sharedWalletAccountXPubkey - # Note: propertyNames pattern not supported in current OpenAPI version. - # propertyNames: - # pattern: '^(cosigner#)[0-9]+$' - example: - - {"cosigner#0": "acct_shared_xvk1z8kc04yh544ksc9h2yhp7p6qwpf6syv5qnm8sgnhdne5z2esht5cwssxsec2wzw3nhxm2d9ph4s6ldmqdvxa0zuxzmukpajhyc7flug3te037"} - -x-self: &self - type: string - enum: - - self - -x-accountPubkeyOrSelf: &accountPubkeyOrSelf - nullable: false - oneOf: - - <<: *sharedWalletAccountXPubkey - title: public key - - <<: *self - title: self - -x-cosignersEntry: &cosignersEntry - description: Map of cosigners and their account public keys. Use key as in &cosigner, eg. "cosigner#"or 'self' - type: object - additionalProperties: *accountPubkeyOrSelf - # Note: propertyNames pattern not supported in current OpenAPI version. - # propertyNames: - # pattern: '^(cosigner#)[0-9]+$' - example: - - {"cosigner#0": "acct_shared_xvk1z8kc04yh544ksc9h2yhp7p6qwpf6syv5qnm8sgnhdne5z2esht5cwssxsec2wzw3nhxm2d9ph4s6ldmqdvxa0zuxzmukpajhyc7flug3te037"} - - {"cosigner#0": "self"} - -x-walletId: &walletId - description: A unique identifier for the wallet - type: string - format: hex - maxLength: 40 - minLength: 40 - example: 2512a00e9653fe49a44a5886202e24d77eeb998f - -x-walletDiscovery: &walletDiscovery - description: Mechanism used for discovering addresses. - type: string - enum: - - random - - sequential - example: sequential - -x-oneChangeAddressMode: &oneChangeAddressMode - type: boolean - default: false - -x-restorationMode: &restorationMode - description: | - The wallet restoration mode determines since when the wallet should - be restored from the blockchain. - - cardano-wallet uses so-called `ChainSync` protocol under the hood to - scan the chain and restore its state from blocks and transactions. - [Ogmios](https://ogmios.dev/mini-protocols/local-chain-sync/) documentation provides a detailed - explanation of this underlying process. - oneOf: - - title: Restore from genesis - description: | - Restore the wallet from the genesis block. This will cause the wallet - to be restored from the very beginning of the blockchain, which is - expected to take a long time (several hours on mainnet). - <<: *genesis - - title: Restore from tip - description: | - Restore the wallet from the tip of the blockchain. The wallet queries - the current tip of the chain and then starts synchronizing from that point. - It waits for the _next block_ to appear before returning a result, which - on _mainnet_ will take an average of 30 seconds. - <<: *tip - - title: Restore from block - description: | - Restore the wallet after a specific _point_ identified by a block hash and - slot number. Note that any transaction which is part of that specified block - won't be restored. - <<: *chainPoint - -x-walletName: &walletName - type: string - maxLength: 255 - minLength: 1 - example: Alan's Wallet - -x-poolMetadataSource: &poolMetadataSource - description: | - Pool metadata source. This sets the metadata fetching strategy. - - Possible values are - * none -> no fetching - * direct -> direct fetching - * uri -> use SMASH server - type: string - pattern: '^(none|direct|https?:\/\/[a-zA-Z0-9-_~.]+(:[0-9]+)?/?)$' - example: https://smash.cardano-mainnet.iohk.io/ - -x-scriptHash: &scriptHash - description: A script hash - 28 bytes - type: string - format: bech32 - pattern: "^(script)1[0-9a-z]*$" - example: - - script1gr69m385thgvkrtspk73zmkwk537wxyxuevs2u9cukglvtlkz4k - -x-scriptIntegrityHash: &scriptIntegrityHash - description: A script data integrity hash - 32 bytes - type: string - format: bech32 - pattern: "^(script_data)1[0-9a-z]*$" - example: - - script_data16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7qau558d - -x-extraSignatureHash: &extraSignatureHash - description: An extra signature hash - 28 bytes - type: string - format: bech32 - pattern: "^(req_signer_vkh)1[0-9a-z]*$" - example: - - addr_keyhash1gr69m385thgvkrtspk73zmkwk537wxyxuevs2u9cukglvtlkz4k - -x-credentialPubKey: &credentialPubKey - description: A public key (public key without chain code) for credential - 32 bytes - type: string - format: bech32 - pattern: "^((addr_vk)|(stake_vk))1[0-9a-z]*$" - example: - - stake_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7qau558d - - addr_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7q3yvuv2 - -x-credentialExtendedPubKey: &credentialExtendedPubKey - description: An extended public key (public key with chain code) for credential - 64 bytes - type: string - format: bech32 - pattern: "^((addr_xvk)|(stake_xvk))1[0-9a-z]*$" - example: - - stake_xvk1qqqqzqqpqyqqzqgpqyqszqgpqqqqzqgpqqqqqqqpqyqqzqgqqqqqqqgpqqqqqqgqqyqszqqpqyqsqqqqqyqszqqqqqqqqqqpqqqqzqqgjanje - - addr_xvk1qyqqqqgqqyqsqqgqqyqsqqgqqqqszqqpqyqsqqgqqqqqqqgqqyqqqqqpqqqsqqqpqyqszqqpqqqszqgpqqqqzqgpqqqqqqqqqqqsqqqptg5dh - -x-credentialKeyHash: &credentialKeyHash - description: A key hash for credential - 28 bytes - type: string - format: bech32 - pattern: "^((addr_vkh)|(stake_vkh))1[0-9a-z]*$" - example: - - stake_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq - - addr_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq - -x-validationLevel: &validationLevel - description: | - Script validation level. Required validation sifts off scripts that would not - be accepted by the ledger. Recommended level filters out scripts that do not pass - required validation and additionally when: - * 'all' is non-empty - * there are redundant timelocks in a given level - * there are no duplicated verification keys in a given level - * 'at_least' coefficient is positive - * 'all', 'any' are non-empty and `'at_least' has no less elements in the list - than the coefficient after timelocks are filtered out. - - type: string - enum: - - required - - recommended - -x-anyAddress: &anyAddress - description: A Shelley address representing either enterprise, reward account or delegating address - type: string - format: bech32 - pattern: "^((addr)|(stake)|(addr_test)|(stake_test))1[0-9a-z]*$" - example: - - stake17xt2z3pa7etaxp7jurdg0m8jhsmtp4r2z56pd3a5q3jhxycdxzmx9 - - addr1wy5np0m5x03tax3kcdh6e2cet98qcfs80wtv4cyvl5taclc6dnd8e - - addr1xy5np0m5x03tax3kcdh6e2cet98qcfs80wtv4cyvl5tacluk59zrmajh6vra9cx6slk090pkkr2x59f5zmrmgpr9wvfs37hjk4 - -x-ScriptValue: &ScriptValue - oneOf: - - title: Key Hash - description: Leaf value for a script designating a required verification key hash. - type: string - format: bech32 - pattern: "^((addr_shared_vkh)|(stake_shared_vkh)|(policy_vkh))1[0-9a-z]*$" - - - title: All - type: object - required: - - all - properties: - all: - description: Script primitive for which all signing keys corresponding to all list elements' verification keys are expected to make the script valid. - type: array - minItems: 1 - items: - $ref: "#/components/schemas/ScriptValue" - - - title: Any - type: object - required: - - any - properties: - any: - description: Script primitive for which a signing key corresponding to any of the list elements' verification keys is expected to make the script valid. It is equivalent to `some` with `"at_least"=1`. - type: array - minItems: 1 - items: - $ref: "#/components/schemas/ScriptValue" - - - title: Some - type: object - required: - - some - properties: - some: - description: Script primitive for which at least a given number of signing keys corresponding to the list elements' verification keys are expected to make the script valid. - type: object - required: - - at_least - - from - properties: - at_least: - type: integer - minimum: 1 - maximum: 255 - from: - type: array - minItems: 1 - items: - $ref: "#/components/schemas/ScriptValue" - - - title: Active from slot - type: object - required: - - active_from - properties: - active_from: - description: Transaction is only valid starting at the specified slot number (`≥ active_from`). - type: integer - minimum: 0 - - - title: Active until slot - type: object - required: - - active_until - properties: - active_until: - description: Transaction is only valid before the specified slot number (`< active_until`). - type: integer - minimum: 0 - -# ScriptValueGeneral allows any key hash prefix, used in decoded transactions -# where scripts can come from any source (not just shared wallets) -x-ScriptValueGeneral: &ScriptValueGeneral - oneOf: - - title: Key Hash - description: Leaf value for a script designating a required verification key hash. - type: string - format: bech32 - pattern: "^((addr_shared_vkh)|(stake_shared_vkh)|(addr_vkh)|(stake_vkh)|(policy_vkh))1[0-9a-z]*$" - - - title: All - type: object - required: - - all - properties: - all: - description: Script primitive for which all signing keys corresponding to all list elements' verification keys are expected to make the script valid. - type: array - minItems: 1 - items: - $ref: "#/components/schemas/ScriptValueGeneral" - - - title: Any - type: object - required: - - any - properties: - any: - description: Script primitive for which a signing key corresponding to any of the list elements' verification keys is expected to make the script valid. It is equivalent to `some` with `"at_least"=1`. - type: array - minItems: 1 - items: - $ref: "#/components/schemas/ScriptValueGeneral" - - - title: Some - type: object - required: - - some - properties: - some: - description: Script primitive for which at least a given number of signing keys corresponding to the list elements' verification keys are expected to make the script valid. - type: object - required: - - at_least - - from - properties: - at_least: - type: integer - minimum: 1 - maximum: 255 - from: - type: array - minItems: 1 - items: - $ref: "#/components/schemas/ScriptValueGeneral" - - - title: Active from slot - type: object - required: - - active_from - properties: - active_from: - description: Transaction is only valid starting at the specified slot number (`≥ active_from`). - type: integer - minimum: 0 - - - title: Active until slot - type: object - required: - - active_until - properties: - active_until: - description: Transaction is only valid before the specified slot number (`< active_until`). - type: integer - minimum: 0 - -x-script: &script - <<: *ScriptValue - -x-ScriptTemplateValue: &ScriptTemplateValue - oneOf: - - title: Cosigner - description: Leaf value for a script designating a cosigner co-sharing the script. - type: string - pattern: "^(cosigner#)[0-9]*$" - - - title: All - type: object - required: - - all - properties: - all: - description: Script primitive for which all signing keys corresponding to all list cosigners' verification keys are expected to make the script valid. - type: array - minItems: 1 - items: - $ref: "#/components/schemas/ScriptTemplateValue" - - - title: Any - type: object - required: - - any - properties: - any: - description: Script primitive for which a signing key corresponding to any of the list cosigners' verification keys is expected to make the script valid. It is equivalent to `some` with `"at_least"=1`. - type: array - minItems: 1 - items: - $ref: "#/components/schemas/ScriptTemplateValue" - - - title: Some - type: object - required: - - some - properties: - some: - description: Script primitive for which at least a given number of signing keys corresponding to the list cosigners' verification keys are expected to make the script valid. - type: object - required: - - at_least - - from - properties: - at_least: - type: integer - minimum: 1 - maximum: 255 - from: - type: array - minItems: 1 - items: - $ref: "#/components/schemas/ScriptTemplateValue" - - - title: Active from slot - type: object - required: - - active_from - properties: - active_from: - description: Transaction is only valid starting at the specified slot number (`≥ active_from`). - type: integer - minimum: 0 - - - title: Active until slot - type: object - required: - - active_until - properties: - active_until: - description: Transaction is only valid before the specified slot number (`< active_until`). - type: integer - minimum: 0 - -x-scriptTemplate: &scriptTemplate - type: object - required: - - cosigners - - template - properties: - cosigners: *cosigners - template: *ScriptTemplateValue - -x-scriptTemplateEntry: &scriptTemplateEntry - type: object - required: - - cosigners - - template - properties: - cosigners: *cosignersEntry - template: *ScriptTemplateValue - -x-CredentialValue: &CredentialValue - nullable: false - oneOf: - - <<: *credentialPubKey - title: public key - - <<: *credentialExtendedPubKey - title: extended public key - - <<: *credentialKeyHash - title: key hash - - <<: *script - title: script - - <<: *scriptHash - title: script hash - example: - any: - - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq - - - stake_shared_vkh1nqc00hvlc6cq0sfhretk0rmzw8dywmusp8retuqnnxzajtzhjg5 - - - all: - - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq - - addr_shared_vkh1y3zl4nqgm96ankt96dsdhc86vd5geny0wr7hu8cpzdfcqskq2cp - - - any: - - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq - - all: - - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq - - addr_shared_vkh1y3zl4nqgm96ankt96dsdhc86vd5geny0wr7hu8cpzdfcqskq2cp - - - some: - at_least: 2 - from: - - addr_shared_vkh1zxt0uvrza94h3hv4jpv0ttddgnwkvdgeyq8jf9w30mcs6y8w3nq - - addr_shared_vkh1y3zl4nqgm96ankt96dsdhc86vd5geny0wr7hu8cpzdfcqskq2cp - -x-settings: &settings - description: Settings - type: object - required: - - pool_metadata_source - properties: - pool_metadata_source: - <<: *poolMetadataSource - description: | - Select stake pool metadata fetching strategy: - - `none` - metadata is not fetched at all, - - `direct` - metadata is fetched directly URLs registered on chain, - - `uri` - metadata is fetched from an external Stake-Pool Metadata Aggregation Server (SMASH) - - After update existing metadata will be dropped forcing it to re-sync automatically with the new setting. - -x-assetName: &assetName - type: string - description: | - The asset on-chain type which acts as a sub-identifier within a - policy. Although we call it "asset name", the value needn't be - text, and it could even be empty. - - For policies with a single fungible asset item, asset name is - typically an empty string. - - This value can be up to 32 bytes of arbitrary data (which is 64 - hexadecimal digits). - format: hex - maxLength: 64 - example: "" - -x-assetPolicyId: &assetPolicyId - type: string - description: | - A unique identifier of the asset's monetary policy. The policy - controls how assets of this kind are created and destroyed. - - The contents are the blake2b-224 hash of the monetary policy - script, encoded in hexadecimal. - format: hex - minLength: 56 - maxLength: 56 - example: 65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b - -x-assetFingerprint: &assetFingerprint - type: string - description: | - A user-facing short fingerprint which combines the `policy_id` and `asset_name` - to allow for an easier human comparison of assets. Note that it is generally - **not okay** to use this fingerprint as a unique identifier for it is not collision - resistant. Yet within the context of a single wallet, it makes for a (rather) - short user-facing comparison mean. - pattern: "^(asset)1[0-9a-z]*$" - maxLength: 44 - minLength: 44 - example: asset1rjklcrnsdzqp65wjgrg55sy9723kw09mlgvlc3 - -x-assetMetadataName: &assetMetadataName - type: string - maxLength: 50 - minLength: 1 - description: | - A human-readable name for the asset, intended for display in user - interfaces. - example: SwaggerCoin - -x-assetMetadataTicker: &assetMetadataTicker - type: string - maxLength: 5 - minLength: 2 - description: | - An optional human-readable very short name or acronym for the - asset, intended for display in user interfaces. If `ticker` is not - present, then `name` will be used, but it might be truncated to - fit within the available space. - example: SWAG - -x-assetMetadataDescription: &assetMetadataDescription - description: | - A human-readable description for the asset. Good for display in - user interfaces. - type: string - maxLength: 500 - -x-assetMetadataDecimals: &assetMetadataDecimals - type: integer - description: | - Defines a scaling factor for the asset of 10-n. The - decimals value _n_ is therefore the number of digits after the - decimal point for quantities of this token. - - It is up to API clients to use this metadata field to decimalize - asset quantities before displaying to users. The wallet backend - will always return unscaled token quantities as whole numbers. - minimum: 0 - maximum: 255 - example: 2 - -x-assetMetadataUrl: &assetMetadataUrl - description: | - A URL to the policy's owner(s) or the entity website in charge of the asset. - type: string - format: uri - pattern: "^https://.+" - maxLength: 250 - -x-assetMetadataLogo: &assetMetadataLogo - description: | - A base64-encoded `image/png` for displaying the asset. The end image can be expected - to be smaller than 64KB. - type: string - format: base64 - maxLength: 87400 - -x-assetMetadata: &assetMetadata - title: Native Assets Metadata - description: | - In the Mary era of Cardano, UTxO may contain native assets. These - assets are represented on-chain by opaque identifiers which are - meaningless to end-users. Therefore, user-facing metadata - regarding each token must be stored off-chain, in a metadata - registry. - - Token creators may publish metadata into the registry and client - applications can consume these metadata for display to end - users. This will work in a similar way to how it is done for stake - pool metadata. - type: object - additionalProperties: false - required: - - name - - description - properties: - name: *assetMetadataName - description: *assetMetadataDescription - ticker: *assetMetadataTicker - decimals: *assetMetadataDecimals - url: *assetMetadataUrl - logo: *assetMetadataLogo - -x-walletMnemonicSentence: &walletMnemonicSentence - description: A list of mnemonic words - type: array - minItems: 15 - maxItems: 24 - items: - type: string - format: bip-0039-mnemonic-word{english} - example: ["squirrel", "material", "silly", "twice", "direct", "slush", "pistol", "razor", "become", "junk", "kingdom", "flee", "squirrel", "silly", "twice"] - -x-walletSecondFactor: &walletSecondFactor - description: An optional passphrase used to encrypt the mnemonic sentence. - type: array - minItems: 9 - maxItems: 12 - items: - type: string - format: bip-0039-mnemonic-word{english} - example: ["squirrel", "material", "silly", "twice", "direct", "slush", "pistol", "razor", "become"] - -x-walletPassphrase: &walletPassphrase - description: A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds) - type: string - minLength: 10 - maxLength: 255 - example: Secure Passphrase - -x-keyExtended: &keyExtended - description: Determines whether extended (with chain code) or normal (without chain code) key is requested - type: string - enum: - - extended - - non_extended - -x-lenientPassphrase: &lenientPassphrase - description: A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds) - type: string - minLength: 0 - maxLength: 255 - example: Secure Passphrase - -x-walletPassphraseHash: &walletPassphraseHash - description: | - A hash of master passphrase. The hash should be an output of a Scrypt function with the following parameters: - - logN = 14 - - r = 8 - - p = 1 - type: string - format: hex - example: 31347c387c317c574342652b796362417576356c2b4258676a344a314c6343675375414c2f5653393661364e576a2b7550766655513d3d7c2f376738486c59723174734e394f6e4e753253302b6a65515a6b5437316b45414941366a515867386539493d - -x-walletEncryptedRootPrivateKey: &walletEncryptedRootPrivateKey - description: | - A root private key, encrypted using a given passphrase. The underlying key should contain: - - A private key - - A chain code - - A public key - type: string - format: hex - minLength: 256 - maxLength: 256 - -x-walletAddressPoolGap: &walletAddressPoolGap - description: | - Number of consecutive unused addresses allowed. - - **IMPORTANT DISCLAIMER:** Using values other than `20` automatically makes your wallet invalid with regards to BIP-44 address discovery. It means that you **will not** be able to fully restore - your wallet in a different software which is strictly following BIP-44. - - Beside, using large gaps is **not recommended** as it may induce important performance degradations. Use at your own risks. - - **IMPORTANT DISCLAIMER 2:** There is no way to `import` addresses generated outside (e.g. using cardano-addresses) into the wallet. - Wallet only discovers transactions on its used and unused addresses that are within its currently seen `address_pool_gap`. - Transactions on addresses that "belong" to the wallet but happen to be beyond its `address_pool_gap` will not be visible to the wallet. - This is a technical limitation of the industry standard [BIP-44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki). See also [CIP-1852](https://github.com/cardano-foundation/CIPs/blob/master/CIP-1852/CIP-1852.md). - - type: integer - minimum: 10 - maximum: 100000 - example: 20 - default: 20 - -x-walletState: &walletState - <<: *syncProgress - description: Whether a wallet is ready to use or still syncing - -x-walletBalance: &walletBalance - description: Wallet current Ada balance(s). - type: object - required: - - available - - reward - - total - properties: - available: - <<: *amount - description: Available Ada UTxO balance (funds that can be spent without condition). - reward: - <<: *amount - description: The Ada balance of the reward account for this wallet. - total: - <<: *amount - description: Total Ada balance (available balance plus pending change and reward balance). - -x-walletAsset: &walletAsset - description: | - An asset on the Cardano blockchain. An asset is uniquely identified by - its `policy_id` and `asset_name` (together, these form the _asset id_). - - Two assets with the same `asset_name` and `policy_id` are - interchangeable. Yet, different assets with a same `policy_id` but - different `asset_name` are treated as separate assets, as are two - assets with the same `asset_name` but different `policy_id`. - type: object - required: - - policy_id - - asset_name - - quantity - properties: - policy_id: *assetPolicyId - asset_name: *assetName - quantity: *assetQuantity - -x-walletAssets: &walletAssets - description: A flat list of assets (possibly empty). - type: array - items: *walletAsset - -x-walletAssetsBalance: &walletAssetsBalance - description: | - Current non-Ada asset holdings of the wallet. - - The amount of assets available to spend may be less than the total - unspent assets due to transaction change amounts which are yet to - be fully confirmed (pending). - type: object - required: - - available - - total - properties: - available: - <<: *walletAssets - description: | - Available UTxO asset balances (funds that can be spent without - condition). - total: - <<: *walletAssets - description: | - Total asset balances (available balances plus pending change balances). - -x-byronWalletBalance: &byronWalletBalance - description: Byron wallet's current balance(s) - type: object - required: - - available - - total - properties: - available: - <<: *amount - description: Available balance (funds that can be spent) - total: - <<: *amount - description: Total balance (available balance plus pending change) - -x-walletPassphraseInfo :: &walletPassphraseInfo - description: Information about the wallet's passphrase - type: object - required: - - last_updated_at - properties: - last_updated_at: *date - -x-transactionId: &transactionId - description: A unique identifier for this transaction - type: string - format: hex - maxLength: 64 - minLength: 64 - example: 1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1 - -x-datum: &datum - description: A datum hash. - type: string - format: hex - maxLength: 64 - minLength: 64 - example: 16f30f4e8d665d53eb4ab6028bd0ac971809d514c92d423856bc91c49e928faf - -x-transactionInsertedAt: &transactionInsertedAt - description: | - - if: status == in_ledger -
- Absolute time at which the transaction was inserted in a block. - <<: *blockReference - -x-transactionExpiresAt: &transactionExpiresAt - description: | - - if: status == pending OR status == expired -
- Absolute time and slot at which the pending transaction TTL (time to live) will lapse. - <<: *slotReference - -x-transactionPendingSince: &transactionPendingSince - description: | - - if: status == pending -
- The point in time at which a transaction became pending. - <<: *blockReference - -x-transactionDepth: &transactionDepth - description: | - - if: status == in_ledger -
- Current depth of the transaction in the local chain - <<: *numberOfBlocks - -x-transactionDirection: &transactionDirection - type: string - enum: - - outgoing - - incoming - -x-addresses: &addresses - description: A list of addresses - type: array - minItems: 1 - items: *addressId - -x-transactionInputs: &transactionInputs - description: | - A list of transaction inputs. - - `assets` and `address` are always present for `outgoing` - transactions but generally absent for `incoming` - transactions. This information is present on the Cardano explorer, - but is not tracked by the wallet. - type: array - minItems: 0 - items: - type: object - required: - - id - - index - properties: - address: *addressId - amount: *amount - assets: *walletAssets - id: *transactionId - index: - type: integer - minimum: 0 - -x-referenceInput: &referenceInput - description: | - A reference input. - type: object - required: - - id - - index - properties: - id: *transactionId - index: - type: integer - minimum: 0 - -x-transactionCollateral: &transactionCollateral - description: | - A list of transaction inputs used for collateral. - type: array - minItems: 0 - items: - type: object - required: - - id - - index - properties: - address: *addressId - amount: *amount - id: *transactionId - index: - type: integer - minimum: 0 - -x-derivationSegment: &derivationSegment - description: | - An individual segment within a derivation path. - - The `H` suffix indicates a _Hardened_ child private key, which - means that children of this key cannot be derived from the public - key. Indices without a `H` suffix are called _Soft_. - type: string - example: 1852H - -x-derivationPath: &derivationPath - description: A path for deriving a child key from a parent key. - type: array - minItems: 1 - items: *derivationSegment - -x-transactionOutputs: &transactionOutputs - description: | - A list of target outputs with amounts specified. - - When creating a new transaction, the wallet software ensures that all - user-specified transaction outputs have ada amounts that satisfy the ledger - minimum UTxO rule: - - - If a user-specified transaction output has an ada `amount` that is - **zero**, the wallet software will automatically assign a minimal amount - of ada to the output so that it satisfies the ledger minimum UTxO rule. - - - If a user-specified transaction output has an ada `amount` that is - **non-zero**, the wallet software will verify that the specified amount - is large enough to satisfy the ledger minimum UTxO rule. If the amount is - not large enough, the wallet software will return a `utxo_too_small` - error, together with a revised ada amount that does satisfy the minimum - UTxO rule. - - type: array - minItems: 0 - items: - type: object - required: - - address - - amount - properties: - address: *addressId - amount: *amount - assets: *walletAssets - -x-transactionCollateralOutputs: &transactionCollateralOutputs - description: A list of collateral return outputs with amounts specified. - type: array - minItems: 0 - maxItems: 1 - items: - type: object - required: - - address - - amount - properties: - address: *addressId - amount: *amount - assets: *walletAssets - -x-delegationAction: &delegationAction - description: | - A delegation action. - - Pool id is only required for "join". - type: object - required: - - action - properties: - action: - type: string - enum: ["quit", "join"] - pool: *stakePoolId - -x-delegationTarget: &delegationTarget - <<: *stakePoolId - description: A unique Stake-Pool identifier (present only if status = `delegating`) - -x-rewardAccountPath: &rewardAccountPath - type: array - minItems: 5 - maxItems: 5 - items: - type: string - -x-certificate: &certificate - description: | - A delegation certificate belonging to wallet - - Only for 'join_pool' the 'pool' property is required. - type: object - required: - - certificate_type - - reward_account_path - properties: - certificate_type: - type: string - enum: ["join_pool", "quit_pool", "register_reward_account"] - pool: - <<: *stakePoolId - reward_account_path: - <<: *rewardAccountPath - -x-certificateNotOurs: &certificateNotOurs - description: | - A delegation certificate not belonging to wallet - - Only for 'join_pool' the 'pool' property is required. - type: object - required: - - certificate_type - - reward_account - properties: - certificate_type: - type: string - enum: ["join_pool_external", "quit_pool_external", "register_reward_account_external"] - pool: - <<: *stakePoolId - reward_account: - <<: *stakeAddress - -x-otherCertificate: &otherCertificate - type: object - required: - - certificate_type - properties: - certificate_type: - type: string - enum: ["mir", "genesis"] - -x-transactionRedemptionRequest: &transactionRedemptionRequest - <<: *walletMnemonicSentence - description: | - When provided, attempts to withdraw rewards from the default stake address - corresponding to the given mnemonic. - - Should the rewards be null or too small to be worth withdrawing (i.e. the - cost of adding them into the transaction is more than their own intrinsic - value), the server will reject the request with a - `withdrawal_not_beneficial` error. - - withdrawal field | reward balance | result - --- | --- | --- - any recovery phrase | too small | x Error 403 `withdrawal_not_beneficial` - any recovery phrase | big enough | ✓ withdrawal generated - -x-transactionWithdrawalRequestSelf: &transactionWithdrawalRequestSelf - type: string - enum: ["self"] - description: | - When provided, instruments the server to automatically withdraw rewards from the source wallet when they are deemed - sufficient (i.e. they contribute to the balance for at least as much as they cost). - - As a consequence, the resulting transaction may or may not have a withdrawal object. Summarizing: - - withdrawal field | reward balance | result - --- | --- | --- - `null` | too small | ✓ no withdrawals generated - `null` | big enough | ✓ no withdrawals generated - `"self"` | too small | ✓ no withdrawals generated - `"self"` | big enough | ✓ withdrawal generated - -x-transactionWithdrawals: &transactionWithdrawals - description: A list of withdrawals from stake addresses. - type: array - minItems: 0 - items: - type: object - additionalProperties: false - required: - - stake_address - - amount - properties: - stake_address: *stakeAddress - amount: *amount - -x-ours: &ours - type: string - enum: ["ours"] - description: | - Used when withdrawal or output is ours. - -x-transactionWithdrawalsGeneral: &transactionWithdrawalsGeneral - description: | - A list of withdrawals from stake addresses. Withdrawal belonging to the wallet - is underlined. - type: array - minItems: 0 - items: - type: object - additionalProperties: false - required: - - stake_address - - amount - properties: - stake_address: *stakeAddress - amount: *amount - context: *ours - -x-softIndex: &softIndex - type: integer - minimum: 0 - maximum: 2147483647 - description: A soft derivation index. - -x-multiDelegationAction: &multiDelegationAction - description: | - A delegation action for a given stake key denoted by its soft index. - Pool id is only required for "join". - Stake key index are required for both actions. - oneOf: - - type: object - required: - - join - properties: - join: - type: object - required: - - pool - - stake_key_index - properties: - pool: *stakePoolId - stake_key_index: *derivationSegment - - type: object - required: - - quit - properties: - quit: - type: object - required: - - stake_key_index - properties: - stake_key_index: *derivationSegment - -x-transactionDelegations: &transactionDelegations - description: | -

status: stable

- - A list of staking actions (joining, rejoining or leaving from stake pools). - Using '0H' stake key index is supported at this moment. This will change with - multi-account support. - Only one delegation action can be used. - type: array - minItems: 0 - items: - <<: *multiDelegationAction - -x-transactionChange: &transactionChange - description: A list of transaction change outputs. - type: array - minItems: 0 - items: - type: object - required: - - address - - amount - - derivation_path - properties: - address: *addressId - amount: *amount - assets: *walletAssets - derivation_path: *derivationPath - -x-transactionResolvedInputs: &transactionResolvedInputs - description: A list of transaction inputs - type: array - items: - type: object - required: - - id - - index - - address - - amount - - derivation_path - properties: - address: *addressId - amount: *amount - assets: *walletAssets - id: *transactionId - derivation_path: *derivationPath - index: - type: integer - minimum: 0 - -x-transactionInputsOutsideWallet: &transactionInputsOutsideWallet - description: | - A transaction input not belonging to a given wallet. - type: object - required: - - id - - index - properties: - id: *transactionId - index: - type: integer - minimum: 0 - -x-transactionInputsInsideWallet: &transactionInputsInsideWallet - description: | - A transaction input belonging to a given wallet. - type: object - required: - - id - - index - - address - - amount - - derivation_path - properties: - address: *addressId - amount: *amount - assets: *walletAssets - id: *transactionId - derivation_path: *derivationPath - index: - type: integer - minimum: 0 - -x-transactionInputsGeneral: &transactionInputsGeneral - type: array - minItems: 0 - items: - oneOf: - - <<: *transactionInputsOutsideWallet - title: tx inputs without source not belonging to a given wallet - - <<: *transactionInputsInsideWallet - title: tx inputs belonging to a given wallet - -x-transactionOutputsOutsideWallet: &transactionOutputsOutsideWallet - description: | - A transaction output not belonging to the wallet - type: object - required: - - address - - amount - properties: - address: *addressId - amount: *amount - assets: *walletAssets - -x-transactionOutputsInsideWallet: &transactionOutputsInsideWallet - description: | - A transaction output not belonging to the wallet - type: object - required: - - address - - amount - - derivation_path - properties: - address: *addressId - amount: *amount - assets: *walletAssets - derivation_path: *derivationPath - -x-transactionOutputsGeneral: &transactionOutputsGeneral - type: array - minItems: 0 - items: - oneOf: - - <<: *transactionOutputsOutsideWallet - title: tx outputs not belonging to a given wallet - - <<: *transactionOutputsInsideWallet - title: tx outputs belonging to a given wallet - -x-transactionCollateralOutputsGeneral: &transactionCollateralOutputsGeneral - type: array - minItems: 0 - maxItems: 1 - items: - oneOf: - - <<: *transactionOutputsOutsideWallet - title: tx outputs not belonging to a given wallet - - <<: *transactionOutputsInsideWallet - title: tx outputs belonging to a given wallet - -x-transactionResolvedCollateral: &transactionResolvedCollateral - description: A list of transaction inputs used for collateral - type: array - items: - type: object - required: - - id - - index - - address - - amount - - derivation_path - properties: - address: *addressId - amount: *amount - id: *transactionId - derivation_path: *derivationPath - index: - type: integer - minimum: 0 - -x-transactionResolvedWithdrawals: &transactionResolvedWithdrawals - description: A list of withdrawals from stake addresses. - type: array - minItems: 0 - items: - type: object - additionalProperties: false - required: - - stake_address - - derivation_path - - amount - properties: - stake_address: *stakeAddress - derivation_path: *derivationPath - amount: *amount - -x-serialisedTransactionBase64: &serialisedTransactionBase64 - description: | - The CBOR-encoded transaction, represented in base64 encoding. - This always includes the transaction body and the witness set, even if the - latter is empty. - type: string - format: base64 - -x-serialisedTransactionHex: &serialisedTransactionHex - description: | - The CBOR-encoded transaction, represented in hexadecimal encoding (base-16). - This always includes the transaction body and the witness set, even if the - latter is empty. - type: string - format: hex - -x-serialisedTransactionEncoded: &serialisedTransactionEncoded - description: | - The CBOR-encoded transaction, represented in either hex or base64 encoding. - This always includes the transaction body and the witness set, even if the - latter is empty. - type: string - format: "base64|base16" - -x-signedTransactionBlob: &signedTransactionBlob - description: Signed transaction message binary blob. - type: string - format: binary - -x-transactionBodyBlob: &transactionBodyBlob - description: CBOR-encoded transaction body - type: string - format: binary - -x-transactionStatus: &transactionStatus - description: | - Current transaction status. - - ``` - *-----------* - ---> | PENDING |----------------* - *-----------* | - | | - V V - *-----------* *-----------* - | |----------> EXPIRED | - | | (ttl) *-----------* - | SUBMITTED | - | <----------------* - | | | - *-----------* (rollback) - | | - (in ledger) *-----------* - | | | - *---------------> IN_LEDGER | - | | - *-----------* - ``` - type: string - enum: - - pending - - submitted - - in_ledger - - expired - -x-transactionSerializedMetadata: &transactionSerializedMetadata - type: string - format: base64 - description: Transaction metadata, serialized according to the expected on-chain binary format, base64-encoded. - -x-transactionMetadata: &transactionMetadata - description: | - **⚠️ WARNING ⚠️** - - _Please note that metadata provided in a transaction will be - stored on the blockchain forever. Make sure not to include any sensitive data, - in particular personally identifiable information (PII)._ - - Extra application data attached to the transaction. - - Cardano allows users and developers to embed their own - authenticated metadata when submitting transactions. Metadata can - be expressed as a JSON object with some restrictions: - - 1. All top-level keys must be integers between `0` and `2^64 - 1`. - - 2. Each metadata value is tagged with its type. - - 3. Strings must be at most 64 bytes when UTF-8 encoded. - - 4. Bytestrings are hex-encoded, with a maximum length of 64 bytes. - - Metadata aren't stored as JSON on the Cardano blockchain but are - instead stored using a compact binary encoding (CBOR). - - The binary encoding of metadata values supports three simple types: - - * Integers in the range `-(2^64 - 1)` to `2^64 - 1` - * Strings (UTF-8 encoded) - * Bytestrings - - And two compound types: - - * Lists of metadata values - * Mappings from metadata values to metadata values - - It is possible to transform any JSON object into this schema. - - However, if your application uses floating point values, they will - need to be converted somehow, according to your - requirements. Likewise for `null` or `bool` values. When reading - metadata from chain, be aware that integers may exceed the - javascript numeric range, and may need special "bigint" parsing. - - # with oneOf we get errors about the 2 schema being both valid - # anyOf seems broken trying to find properties - anyOf: - - type: object - title: full - nullable: true - additionalProperties: - $ref: "#/components/schemas/TransactionMetadataValue" - example: - 0: { "string": "cardano" } - 1: { "int": 14 } - 2: { "bytes": "2512a00e9653fe49a44a5886202e24d77eeb998f" } - 3: { "list": [ { "int": 14 }, { "int": 42 }, { "string": "1337" } ] } - 4: { "map": [{ "k": { "string": "key" }, "v": { "string": "value" }}, { "k": { "int": 14 }, "v": { "int": 42 } }] } - - type: object - title: simple - nullable: true - additionalProperties: - $ref: "#/components/schemas/TransactionMetadataValueNoSchema" - example: - 0: "cardano" - 1: 14 - 2: [14, 42 , "1337" ] - 3: {"key1": "value" , "key2": 42 } - - # Note: propertyNames pattern not supported in current OpenAPI version. - # propertyNames: - # pattern: '^[0-9]+$' - -x-encryptionMethod: &encryptionMethod - type: string - enum: - - basic - -x-encryptMetadata: &encryptMetadata - description: | - If used then metadata in a transaction is going to be encrypted by - AES 256 using CBC mode which is a default method (called base). - PBKDF2 password stretching is used to get a 32-byte secret key and a 16-byte - initialization vector required in the cipher. - PBKDF2 encryption algorithm using HMAC with the SHA256 hash algorithm is employed, - and 10000 iterations to get key and iv pair are used. - Cipher algorithm uses 8-byte salt, PKCS#7 padding as specified in - https://datatracker.ietf.org/doc/html/rfc5652#section-6.3 is applied. - Only metadata value under `msg` field is encrypted. If `msg` field is missing error - will be emitted. - Metadata encryption is in accordance to CIP 83 (https://cips.cardano.org/cips/cip83/). - type: object - required: - - passphrase - properties: - method: *encryptionMethod - passphrase: *lenientPassphrase - -x-transactionTTL: &transactionTTL - description: | - The TTL (time to live) is the time period in which the transaction - will be accepted into node mempools. - - After the TTL has lapsed, the transaction is considered - expired. At this point, nodes will give up on broadcasting the - transaction, and the wallet will release the funds allocated to - the transaction so they can be used for other payments. - - The TTL should be long enough that the transaction has time to be - propagated through the network and confirmed, but short enough so - that - in the event of failures - UTxO are returned to the wallet - in a timely manner. - - The TTL value is given in seconds. It will be converted to a slot - number internally. - - If the TTL is not provided for a payment, a reasonable default - value will be used. - - <<: *numberOfSeconds - -x-validityBound: &validityBound - oneOf: - - <<: *numberOfSeconds - title: number of seconds - - <<: *numberOfSlots - title: number of slots - -x-stakePoolApparentPerformance: &stakePoolApparentPerformance - description: | - Apparent performance of the stake pool over past epochs. This indicator is computed - using data available to the server. In particular, the server can't reliably know the - stake distribution of past epochs without being during those epochs. The performance - are therefore an average measure that is more accurate for servers that are online - often. - - The performance is a float with double-precision which is _typically_ within `0` and `1`: - - - `0` means that a pool is not performing well. - - `1` means that a pool is performing _as expected_. - - above `1` means the pool is performing beyond expectations. - - Pools that are lucky enough to win most of their slots early in the epoch will tend to look - like they're over-performing for a while. Having a wallet regularly connected to the network - would harmonize the performance and give better results. - - type: number - minimum: 0 - example: 0.5053763440860215 - -x-stakePoolMetadata: &stakePoolMetadata - description: | - Information about the stake pool. - type: object - required: - - ticker - - name - - homepage - additionalProperties: false - properties: - ticker: - type: string - minLength: 3 - maxLength: 5 - example: IOHK - name: - type: string - minLength: 1 - maxLength: 50 - description: - type: string - maxLength: 255 - homepage: - type: string - format: uri - example: https://iohk.io - -x-stakePoolRetirement: &stakePoolRetirement - <<: *epochInfo - description: | - The epoch in which a stake pool retires. - - May be omitted if the wallet hasn't yet found a retirement certificate - for this stake pool. - -x-stakePoolPledge: &stakePoolPledge - <<: *amount - description: | - Minimal stake amount that a stake pool is willing to honor. - - May be omitted if the wallet hasn't found the pool's registration cerificate yet. - -x-stakePoolCost: &stakePoolCost - <<: *amount - description: | - Estimated cost set by the pool operator when registering his pool. - This fixed cost is taken from each reward earned by the pool before splitting rewards between stakeholders. - - May be omitted if the wallet hasn't found the pool's registration cerificate yet. - -x-stakePoolMargin: &stakePoolMargin - <<: *percentage - description: | - Variable margin on the total reward given to an operator before splitting rewards between stakeholders. - - May be omitted if the wallet hasn't found the pool's registration cerificate yet. - -x-stakePoolSaturation: &stakePoolSaturation - type: number - minimum: 0 - description: | - Saturation-level of the pool based on the desired number of pools aimed by the network. - A value above `1` indicates that the pool is saturated. - - The `non_myopic_member_rewards` take oversaturation into account, as specified by the [specs](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec). - - The saturation is based on the live `relative_stake`. The saturation at the end of epoch e, - will affect the rewards paid out at the end of epoch e+3. - - example: 0.74 - -x-non-myopic-member-rewards: &nonMyopicMemberRewards - <<: *amount - description: | - The rewards the wallet can expect to receive at the end of an epoch, in the long term, if delegating to - this pool. - - For more details, see the - [Design Specification for Delegation and Incentives in Cardano](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec) - document. - -x-stakePoolMetrics: &stakePoolMetrics - type: object - required: - - relative_stake - - non_myopic_member_rewards - - produced_blocks - - saturation - properties: - non_myopic_member_rewards: *nonMyopicMemberRewards - relative_stake: - <<: *percentage - description: | - The live pool stake relative to the *total* stake. - - For more details, see the section "Relative Stake: Active vs Total" in - [Design Specification for Delegation and Incentives in Cardano](https://hydra.iohk.io/job/Cardano/cardano-ledger-specs/delegationDesignSpec/latest/download-by-type/doc-pdf/delegation_design_spec). - saturation: *stakePoolSaturation - produced_blocks: - <<: *numberOfBlocks - description: Number of blocks produced by a given stake pool in its lifetime. - -x-stakePoolFlag: &stakePoolFlag - type: string - enum: - - delisted - -x-stakePoolFlags: &stakePoolFlags - type: array - description: | - Various flags applicable to stake pools. Possible flags: - - | flag | description | - | --- | --- | - | delisted | The pool is marked as delisted on a configured SMASH server; metadata for this pool have therefore been dropped. | - items: *stakePoolFlag - -x-networkInformationSyncProgress: &networkInformationSyncProgress - <<: *syncProgress - description: | - Estimated synchronization progress of the node with the underlying network. Note that this may - change quite arbitrarily as the node may switch to shorter or longer chain forks. - -x-networkClockSyncProgress: &networkClockSyncProgress - <<: *syncClockProgress - description: | - The status progress of syncing local ntp client aiming to get ntp offset. - -x-networkInformationNtpStatus: &networkInformationNtpStatus - type: object - description: | - [Network Time Protocol](https://en.wikipedia.org/wiki/Network_Time_Protocol) information of the server. - - **Important:** This piece of information only makes sense when the server runs on the same host machine as the node. - required: - - status - properties: - status: - type: string - enum: - - available - - unavailable - - pending - offset: - type: object - description: | - - if: status == available -
- Drift offset of the local clock. - required: - - quantity - - unit - properties: - quantity: - type: integer - example: 14 - unit: - type: string - enum: - - microsecond - -x-networkInformationNodeTip: &networkInformationNodeTip - <<: *blockReference - description: Underlying node's tip - -x-networkInformationProtocolUpdate: &networkInformationProtocolUpdate - type: string - description: | - Whether protocol updates have been submitted and accepted by the network. - enum: - - up_to_date - - update_available - -x-delegationStatus: &delegationStatus - type: string - enum: - - not_delegating - - delegating - - voting - - delegating_and_voting - -x-addressIndex: &addressIndex - type: number - minimum: 0 - # 2 ^ 32 - 1, whole range (soft and hard) for random addresses: - maximum: 4294967295 - description: | - An address derivation index. - -x-gCStatus :: &gCStatus - -x-deposits: &deposits - description: A list of deposits associated with a transaction. - type: array - minItems: 0 - items: *amount - -x-minimumCoins: &minimumCoins - description: | - A list of minimum coin values that each output in a payment must satisfy. The values themselves depends on two things: - - - (a) Some updatable protocol parameters fixed by the network. - - (b) The nature of the outputs (i.e. the kind of assets it includes). - - The list is a direct 1:1 mapping of the requested outputs. Said differently, it has the **same number of items** and **items - are ordered in the same way** as **requested outputs** are ordered. In the case where there's no explicitly requested outputs (e.g. - when calculating fee for delegation), this list is empty. - - For example, an output containing only `Ada` may require to be of at least `1 Ada`. An output containing only an hypothetical `AppleCoin` - may require to also carry a minimum of `1.2 Ada`. Note that no matter what, a minimum coin value is always given in Lovelace / Ada. - - > ℹ️ This mechanism is used by the protocol to protect against flooding of the network with worthless assets. By requiring a minimum coin value to every - UTxO, they are given an intrinsic value indexed itself on the value of Ada. - type: array - minItems: 0 - items: *amount - -x-collateralInputCount: &collateralInputCount - type: integer - minimum: 0 - example: 3 - -x-collateralPercentage: &collateralPercentage - type: integer - minimum: 0 - -x-maximumTokenBundleSize: &maximumTokenBundleSize - type: object - description: | - The maximum size of a serialized `TokenBundle`. The concept was added in Mary where - it was hard-coded to 4000 bytes. In Alonzo it was made an updateable protocol parameter (`_maxValSize`). - required: - - quantity - - unit - properties: - quantity: - type: number - minimum: 0 - example: 4000 - unit: - type: string - enum: - - byte - -x-txScriptValidity: &txScriptValidity - description: | - Indicates whether the phase-2 monetary policy script (e.g. Plutus script) - used in the transaction validated or not. Validity may be null if this - transaction was from an era that doesn't support phase-2 monetary policy - scripts, or is a pending transaction (we don't know if validation passed or - failed until the transaction hits the ledger). - nullable: true - type: string - enum: - - valid - - invalid - -x-rationalAsPair: &rationalAsPair - type: object - required: - - denominator - - numerator - properties: - denominator: - type: integer - minimum: 0 - numerator: - type: integer - minimum: 0 - -x-rationalAsNumber: &rationalAsNumber - type: number # NOTE: intended to be 'integer', but logic to serialize as rationalAsPair is missing. - minimum: 0 - -x-rational: &rational - nullable: false - oneOf: - - <<: *rationalAsNumber - title: rational as number - - <<: *rationalAsPair - title: rational as denominator and numerator - -x-executionUnitPrices: &executionUnitPrices - type: object - description: | - The price of time unit and memory unit used for calculating a fee of a script execution. - required: - - step_price - - memory_unit_price - properties: - step_price: *rational - memory_unit_price: *rational - -############################################################################# -# # -# DEFINITIONS # -# # -############################################################################# - -components: - schemas: - ApiAddressWithPath: &ApiAddressWithPath - type: object - required: - - id - - state - - derivation_path - properties: - id: *addressId - state: *addressState - derivation_path: *derivationPath - - ApiAddressInspect: &ApiAddressInspect - type: object - required: - - address_style - - stake_reference - properties: - address_style: - type: string - enum: - - Shelley - - Icarus - - Byron - stake_reference: - type: string - enum: - - none - - by value - - by pointer - network_tag: - description: Can be null for 'Icarus' and 'Byron' styles. - type: integer - minimum: 0 - spending_key_hash: - type: string - format: base16 - minLength: 56 - maxLength: 56 - spending_key_bech32: - type: string - format: bech32 - stake_key_hash: - type: string - format: base16 - minLength: 56 - maxLength: 56 - stake_key_bech32: - type: string - format: bech32 - script_hash: - type: string - format: base16 - minLength: 64 - maxLength: 64 - script_hash_bech32: - type: string - format: bech32 - pointer: - type: object - additionalProperties: false - required: - - slot_num - - transaction_index - - output_index - properties: - slot_num: - type: integer - minimum: 0 - transaction_index: - type: integer - minimum: 0 - output_index: - type: integer - minimum: 0 - address_root: - description: Only for 'Icarus' and 'Byron' styles. - type: string - format: base16 - derivation_path: - description: Only for 'Byron' style. - type: string - format: base16 - address_type: - description: | - The raw type field of the address. - - Details about possible address types are following (refer also to [cddl](https://github.com/IntersectMBO/cardano-ledger/blob/master/eras/alonzo/test-suite/cddl-files/alonzo.cddl)). - - | address_type | binary prefix | Meaning | - | ------------ |:--------------:|:--------------------------------------------------------:| - | 0 | 0000 | base address: keyhash28,keyhash28 | - | 1 | 0001 | base address: scripthash28,keyhash28 | - | 2 | 0010 | base address: keyhash28,scripthash28 | - | 3 | 0011 | base address: scripthash28,scripthash28 | - | 4 | 0100 | pointer address: keyhash28, 3 variable length uint | - | 5 | 0101 | pointer address: scripthash28, 3 variable length uint | - | 6 | 0110 | enterprise address: keyhash28 | - | 7 | 0111 | enterprise address: scripthash28 | - | 8 | 1000 | byron/icarus | - | 14 | 1110 | reward account: keyhash28 | - | 15 | 1111 | reward account: scripthash28 | - type: integer - minimum: 0 - maximum: 15 - - ApiNetworkTip: &ApiNetworkTip - <<: *slotReference - description: The time slot corresponding the network tip. - - ApiEra: &ApiEra - type: string - enum: - - byron - - shelley - - allegra - - mary - - alonzo - - babbage - - conway - - NetworkInfo: &NetworkInfo - type: object - required: - - protocol_magic - - network_id - properties: - protocol_magic: - description: The unique magic number defining the network the wallet is working on. - type: integer - network_id: - description: A name just distinguishing mainnet from testnets - type: string - enum: - - mainnet - - testnet - - ApiNetworkInformation: &ApiNetworkInformation - type: object - required: - - sync_progress - - node_tip - - node_era - - network_info - - wallet_mode - properties: - sync_progress: *networkInformationSyncProgress - node_tip: *networkInformationNodeTip - network_tip: *ApiNetworkTip - next_epoch: *epochInfo - node_era: *ApiEra - network_info: *NetworkInfo - wallet_mode: - type: string - enum: - - light - - node - - ApiNetworkClock: &ApiNetworkClock - <<: *networkInformationNtpStatus - - nullableEpochInfo: &nullableEpochInfo - <<: *epochInfo - nullable: True - - ApiEraInfo: &ApiEraInfo - type: object - properties: - byron: *nullableEpochInfo - shelley: *nullableEpochInfo - allegra: *nullableEpochInfo - mary: *nullableEpochInfo - alonzo: *nullableEpochInfo - babbage: *nullableEpochInfo - conway: *nullableEpochInfo - description: | - - If and when each era started or will start. - - The object is keyed by era names. The values either describe the epoch boundary - when the era starts (can be in the future or in the past), or are null if not yet - confirmed on-chain. - - If you need to know the current era, see the `node_era` field of - `GET /network/information`. - - > Due to complications with our current tooling, we cannot mark the era names - > as required, but the keys are in fact always present. - - ApiNetworkParameters: &ApiNetworkParameters - type: object - required: - - genesis_block_hash - - blockchain_start_time - - slot_length - - epoch_length - - security_parameter - - active_slot_coefficient - - decentralization_level - - desired_pool_number - - eras - - maximum_collateral_input_count - - maximum_token_bundle_size - properties: - genesis_block_hash: *blockId - blockchain_start_time: *date - slot_length: *numberOfSeconds - epoch_length: *numberOfSlots - security_parameter: *numberOfBlocks - active_slot_coefficient: *percentage - decentralization_level: *percentage - desired_pool_number: *stakePoolsNumber - eras: *ApiEraInfo - maximum_collateral_input_count: - <<: *collateralInputCount - description: | - The maximum number of collateral inputs that can be used in a single - transaction. - minimum_collateral_percentage: - <<: *collateralPercentage - description: | - The minimum required amount of collateral as a percentage of the - total transaction fee. - maximum_token_bundle_size: - <<: *maximumTokenBundleSize - execution_unit_prices: - <<: *executionUnitPrices - - ApiSelectCoinsPayments: &ApiSelectCoinsPayments - type: object - required: - - payments - properties: - payments: *transactionOutputs - withdrawal: *transactionWithdrawalRequestSelf - metadata: *transactionMetadata - - ApiSelectCoinsRedemption: &ApiSelectCoinsRedemption - type: object - required: - - payments - - withdrawal - properties: - payments: *transactionOutputs - withdrawal: *transactionRedemptionRequest - metadata: *transactionMetadata - - ApiSelectCoinsAction: &ApiSelectCoinsAction - type: object - required: - - delegation_action - properties: - delegation_action: *delegationAction - - ApiSelectCoinsData: &ApiSelectCoinsData - type: object - oneOf: - - title: Normal payment - <<: *ApiSelectCoinsPayments - - title: Delegation - <<: *ApiSelectCoinsAction - - title: Reward redemption - <<: *ApiSelectCoinsRedemption - - ApiByronSelectCoinsData: &ApiByronSelectCoinsData - type: object - required: - - payments - properties: - payments: *transactionOutputs - - ApiCoinSelection: &ApiCoinSelection - type: object - required: - - inputs - - outputs - - change - properties: - inputs: *transactionResolvedInputs - outputs: *transactionOutputs - change: *transactionChange - collateral: *transactionResolvedCollateral - withdrawals: *transactionResolvedWithdrawals - certificates: - type: array - items: *certificate - deposits_taken: *deposits - deposits_returned: *deposits - metadata: *transactionSerializedMetadata - - ApiGCStatus: &ApiGCStatus - type: object - description: | - Gives an indication if metadata GC checking for delisted pools - has run and if so, when. - - Possible values are: - - not_applicable -> we're currently not querying a SMASH server for metadata - - not_started -> the GC hasn't started yet, try again in a short while - - restarting -> the GC thread is currently restarting, try again in short while - - has_run -> the GC has run successfully - - When 'status' is 'restarting' or 'has_run' then the field 'last_run' - is set to the last GC time in UTC. - required: - - status - properties: - status: - type: string - enum: - - not_applicable - - not_started - - restarting - - has_run - last_run: *date - - ApiMaintenanceActionPostData: &ApiMaintenanceActionPostData - type: object - required: - - maintenance_action - description: | - The maintenance action to carry out, current values are - - gc_stake_pools -> trigger looking up delisted pools from the remote SMASH server - properties: - maintenance_action: - type: string - enum: ['gc_stake_pools'] - - ApiMaintenanceAction: &ApiMaintenanceAction - type: object - required: - - gc_stake_pools - properties: - gc_stake_pools: *ApiGCStatus - - ApiStakePool: &ApiStakePool - type: object - required: - - id - - metrics - - cost - - margin - - pledge - - flags - properties: - id: *stakePoolId - metrics: *stakePoolMetrics - cost: *stakePoolCost - margin: *stakePoolMargin - pledge: *stakePoolPledge - metadata: *stakePoolMetadata - retirement: *stakePoolRetirement - flags: *stakePoolFlags - - ApiFee: &ApiFee - type: object - required: - - estimated_min - - estimated_max - - minimum_coins - - deposit - properties: - estimated_min: *amount - estimated_max: *amount - minimum_coins: *minimumCoins - deposit: *amount - - ApiPutAddressesData: &ApiPutAddressesData - type: object - required: - - addresses - properties: - addresses: - <<: *addresses - description: The imported addresses. - - ApiVerificationKeyShelley: &ApiVerificationKeyShelley - type: string - format: bech32 - pattern: "^((addr_vk)|(stake_vk)|(addr_vkh)|(stake_vkh))1[0-9a-z]*$" - - ApiVerificationKeyShared: &ApiVerificationKeyShared - type: string - format: bech32 - pattern: "^((addr_shared_vk)|(stake_shared_vk)|(addr_shared_vkh)|(stake_shared_vkh))1[0-9a-z]*$" - - ApiAccountKey: &ApiAccountKey - type: string - format: bech32 - pattern: "^((acct_xvk)|(acct_vk)|(acct_shared_xvk)|(acct_shared_vk))1[0-9a-z]*$" - - ApiAccountKeyShared: &ApiAccountKeyShared - type: string - format: bech32 - pattern: "^((acct_shared_xvk)|(acct_shared_vk))1[0-9a-z]*$" - - ApiPolicyKey: &ApiPolicyKey - type: string - format: bech32 - pattern: "^((policy_vk)|(policy_vkh))1[0-9a-z]*$" - - ApiPostPolicyKeyData: &ApiPostPolicyKeyData - type: object - required: - - passphrase - properties: - passphrase: *walletPassphrase - - ApiPolicyId: &ApiPolicyId - type: object - required: - - policy_id - properties: - policy_id: *assetPolicyId - - ApiPostPolicyIdData: &ApiPostPolicyIdData - type: object - required: - - policy_script_template - properties: - policy_script_template: *ScriptTemplateValue - - ApiTxId: &ApiTxId - type: object - required: - - id - properties: - id: *transactionId - - ApiSerialisedTransaction: &ApiSerialisedTransaction - description: | - An encoded transaction. - required: - - transaction - properties: - transaction: *serialisedTransactionEncoded - - ApiSerialisedTransactionEncoded: &ApiSerialisedTransactionEncoded - description: | - An encoded transaction. - required: - - transaction - properties: - transaction: *serialisedTransactionEncoded - - ApiTokenAmountFingerprint: &ApiTokenAmountFingerprint - type: object - required: - - asset_name - - quantity - - fingerprint - properties: - asset_name: *assetName - quantity: *assetQuantity - fingerprint: *assetFingerprint - - PlutusScriptInfo: &PlutusScriptInfo - type: object - required: - - language_version - - script_hash - properties: - language_version: - type: string - enum: ["v1", "v2"] - script_hash: - type: string - format: hex - minLength: 56 - maxLength: 56 - - AnyScript: &AnyScript - oneOf: - - type: object - title: native script - required: - - script_type - - script - properties: - script_type: - type: string - enum: ["native"] - script: *ScriptValue - reference: *referenceInput - - type: object - title: plutus script - required: - - script_type - - script_info - properties: - script_type: - type: string - enum: ["plutus"] - script_info: *PlutusScriptInfo - reference: *referenceInput - - type: object - title: reference script - required: - - script_type - - script_hash - - references - properties: - script_type: - type: string - enum: ["reference script"] - script_hash: - type: string - format: hex - minLength: 56 - maxLength: 56 - references: - type: array - minItems: 1 - items: *referenceInput - - AnyExplicitScript: &AnyExplicitScript - oneOf: - - type: object - title: native script - required: - - script_type - - script - properties: - script_type: - type: string - enum: ["native"] - script: *ScriptValueGeneral - reference: *referenceInput - - type: object - title: plutus script - required: - - script_type - - script_info - properties: - script_type: - type: string - enum: ["plutus"] - script_info: *PlutusScriptInfo - reference: *referenceInput - - ApiTokens: &ApiTokens - type: object - required: - - policy_id - - policy_script - - assets - properties: - policy_id: *assetPolicyId - policy_script: *AnyScript - assets: - type: array - minItems: 1 - items: *ApiTokenAmountFingerprint - - ApiAssetMintBurn: &ApiAssetMintBurn - type: object - required: - - tokens - properties: - tokens: - type: array - minItems: 0 - items: *ApiTokens - wallet_policy_key_hash: *ApiPolicyKey - wallet_policy_key_index: *derivationSegment - - ApiConstructTransaction: &ApiConstructTransaction - type: object - required: - - transaction - - coin_selection - - fee - properties: - transaction: *serialisedTransactionEncoded - coin_selection: *ApiCoinSelection - fee: *amount - - ApiInputsGeneral: &ApiInputsGeneral - <<: *transactionInputsGeneral - description: | - Inputs that could be external or belong to the wallet. - - ApiOutputsGeneral: &ApiOutputsGeneral - <<: *transactionOutputsGeneral - description: | - Outputs that could be external or belong to the wallet. - - ApiCollateralOutputsGeneral: &ApiCollateralOutputsGeneral - <<: *transactionCollateralOutputsGeneral - description: | - Outputs that could be external or belong to the wallet. - - ApiWithdrawalsGeneral: &ApiWithdrawalsGeneral - <<: *transactionWithdrawalsGeneral - description: | - Withdrawals that could be external or belong to the wallet. - - ApiStakePoolMetadata: &ApiStakePoolMetadata - type: object - required: - - url - - hash - properties: - url: *stakePoolMetadataUrl - hash: *stakePoolMetadataHash - - ApiRegisterPool: &ApiRegisterPool - type: object - required: - - certificate_type - - pool_id - - pool_owners - - pool_margin - - pool_cost - - pool_pledge - properties: - certificate_type: - type: string - enum: ["register_pool"] - pool_id: *stakePoolId - pool_owners: - type: array - minItems: 0 - items: *stakePoolOwner - pool_margin: *stakePoolMargin - pool_cost: *stakePoolCost - pool_pledge: *stakePoolPledge - pool_metadata: *ApiStakePoolMetadata - - ApiDeregisterPool: &ApiDeregisterPool - type: object - required: - - certificate_type - - pool_id - - retirement_epoch - properties: - certificate_type: - type: string - enum: ["deregister_pool"] - pool_id: *stakePoolId - retirement_epoch: *epochNumber - - ApiCertificate: &ApiCertificate - description: | - Any certificate that could occur in an arbitrary transaction: - might be related to delegation, pool activities, genesis or MIR. - oneOf: - - <<: *certificate - title: delegation certificate belonging to the wallet - - <<: *certificateNotOurs - title: delegation certificate not belonging to the wallet - - <<: *ApiRegisterPool - title: pool registration certificate - - <<: *ApiDeregisterPool - title: pool deregistration certificate - - <<: *otherCertificate - title: genesis or MIR certificate - - ApiValidityIntervalExplicit: &ApiValidityIntervalExplicit - type: object - required: - - invalid_before - - invalid_hereafter - properties: - invalid_before: *numberOfSlots - invalid_hereafter: *numberOfSlots - - ApiWitnessCount: &ApiWitnessCount - description: | - Specifies the number of verification key and bootstrap wintesses. - As scripts act as witnesses they are also included. Scripts can be specified - and spent in a given transaction or defined to be consumed later. - In the latter case they are defined in transaction outputs (feature possible from Babbage era) - in one transaction and referenced in other later transaction(s). The script referencing - is realized via including of reference in a reference input. If reference script - is present here it included the form of the script and reference to be used later, - ie. tx id and index of tx out where the script was included. - type: object - required: - - verification_key - - scripts - - bootstrap - properties: - verification_key: *witnessCount - scripts: - type: array - minItems: 0 - items: *AnyExplicitScript - bootstrap: *witnessCount - - ApiDecodedTransaction: &ApiDecodedTransaction - type: object - required: - - id - - fee - - inputs - - outputs - - withdrawals - - mint - - burn - - certificates - - witness_count - properties: - id: *transactionId - fee: *amount - inputs: *ApiInputsGeneral - outputs: *ApiOutputsGeneral - collateral: *ApiInputsGeneral - collateral_outputs: *ApiCollateralOutputsGeneral - withdrawals: *ApiWithdrawalsGeneral - mint: *ApiAssetMintBurn - burn: *ApiAssetMintBurn - certificates: - type: array - minItems: 0 - items: *ApiCertificate - metadata: *transactionMetadata - deposits_taken: *deposits - deposits_returned: *deposits - script_validity: *txScriptValidity - validity_interval: *ApiValidityIntervalExplicit - witness_count: *ApiWitnessCount - - ApiTransaction: &ApiTransaction - type: object - required: - - id - - amount - - fee - - deposit_taken - - deposit_returned - - direction - - inputs - - outputs - - withdrawals - - status - properties: - id: *transactionId - amount: - <<: *amount - description: | - An amount of Ada spent or received, from the perspective of the wallet. - - That is, for outgoing transaction, it represents the amount of Ada consumed - as inputs including the amount of Ada spent as fees or deposits. - - For incoming transaction, it represents the total amount of Ada received to - addresses that belong to the wallet. - fee: *amount - deposit_taken: *amount - deposit_returned: *amount - inserted_at: *transactionInsertedAt - expires_at: *transactionExpiresAt - pending_since: *transactionPendingSince - depth: *transactionDepth - direction: *transactionDirection - inputs: *transactionInputs - outputs: *transactionOutputs - collateral: *transactionCollateral - collateral_outputs: *transactionCollateralOutputs - withdrawals: *transactionWithdrawals - status: *transactionStatus - metadata: *transactionMetadata - script_validity: *txScriptValidity - certificates: - type: array - minItems: 0 - items: *ApiCertificate - mint: *ApiAssetMintBurn - burn: *ApiAssetMintBurn - validity_interval: *ApiValidityIntervalExplicit - script_integrity: *scriptIntegrityHash - extra_signatures: - type: array - minItems: 0 - items: *extraSignatureHash - - x-txBody: &txBody - oneOf: - - <<: *serialisedTransactionBase64 - title: Serialized transaction body - - x-txWits: &txWitnesses - type: array - items: *serialisedTransactionBase64 - title: Serialized transaction witnesses - - ApiSignedTransaction: &ApiSignedTransaction - <<: *ApiSerialisedTransaction - description: | - The result of signing a transaction (serialized and encoded). - - ApiSignedTransactionEncoded: &ApiSignedTransactionEncoded - <<: *ApiSerialisedTransactionEncoded - description: | - The result of signing a transaction (serialized and encoded). - - ApiDRep: &ApiDRep - description: | - Decentralized representative (DRep) - that the wallet is delegating its vote to. - One can abstain, give no confidence vote, - or vote for a representative specified by a key hash or script hash. - Vote delegation can be done together with stake delegation action. - nullable: false - type: string - oneOf: - - enum: - - abstain - - no_confidence - title: casting a default vote - - <<: *drepKeyHash - title: vote to a drep represented by key hash (deprecated) - - <<: *drepScriptHash - title: vote to a drep represented by script hash - - <<: *drepKeyHashNew - title: vote to a drep represented by key hash - - ApiWalletDelegationNext: &ApiWalletDelegationNext - type: object - description: Next delegation status becomes active at the start of the second epoch after the corresponding delegation certificate was discovered. The exact moment is specified by changes_at - required: - - status - - changes_at - properties: - status: *delegationStatus - target: *delegationTarget - voting: *ApiDRep - changes_at: *epochInfo - example: - status: not_delegating - changes_at: - epoch_number: 14 - epoch_start_time: 2020-01-22T10:06:39.037Z - - ApiWalletDelegation: &ApiWalletDelegation - description: Delegation settings - type: object - required: - - active - - next - properties: - active: - type: object - description: Currently active delegation status. - required: - - status - properties: - status: *delegationStatus - target: *delegationTarget - voting: *ApiDRep - example: - status: delegating - target: 1423856bc91c49e928f6f30f4e8d665d53eb4ab6028bd0ac971809d514c92db1 - next: - type: array - items: *ApiWalletDelegationNext - - ApiWallet: &ApiWallet - type: object - required: - - id - - address_pool_gap - - balance - - assets - - delegation - - name - - state - - tip - properties: - id: *walletId - address_pool_gap: *walletAddressPoolGap - balance: *walletBalance - assets: *walletAssetsBalance - delegation: *ApiWalletDelegation - name: *walletName - passphrase: *walletPassphraseInfo - state: *walletState - tip: *blockReference - - ApiByronWallet: &ApiByronWallet - type: object - required: - - id - - balance - - assets - - discovery - - name - - state - - tip - properties: - id: *walletId - balance: *byronWalletBalance - assets: *walletAssetsBalance - discovery: *walletDiscovery - name: *walletName - passphrase: *walletPassphraseInfo - state: *walletState - tip: *blockReference - - ApiWalletPostData: &ApiWalletPostData - type: object - description: Restore from root private key - required: - - name - - mnemonic_sentence - - passphrase - properties: - name: *walletName - mnemonic_sentence: *walletMnemonicSentence - mnemonic_second_factor: *walletSecondFactor - passphrase: *walletPassphrase - address_pool_gap: *walletAddressPoolGap - one_change_address_mode: *oneChangeAddressMode - restoration_mode: *restorationMode - - ApiAccountPostData: &ApiAccountPostData - type: object - description: Restore from account public key - required: - - name - - account_public_key - properties: - name: *walletName - account_public_key: *walletAccountXPubkey - address_pool_gap: *walletAddressPoolGap - restoration_mode: *restorationMode - - ApiWalletOrAccountPostData: &ApiWalletOrAccountPostData - type: object - oneOf: - - <<: *ApiWalletPostData - title: shelley - - <<: *ApiAccountPostData - title: shelley (from xpub) - - ApiActiveSharedWallet: &ApiActiveSharedWallet - type: object - required: - - id - - name - - account_index - - address_pool_gap - - payment_script_template - - balance - - assets - - delegation - - state - - tip - properties: - id: *walletId - name: *walletName - account_index: *derivationSegment - address_pool_gap: *walletAddressPoolGap - passphrase: *walletPassphraseInfo - payment_script_template: *scriptTemplate - delegation_script_template: *scriptTemplate - balance: *walletBalance - assets: *walletAssetsBalance - delegation: *ApiWalletDelegation - state: *walletState - tip: *blockReference - - ApiIncompleteSharedWallet: &ApiIncompleteSharedWallet - type: object - required: - - id - - name - - account_index - - address_pool_gap - - payment_script_template - - state - properties: - id: *walletId - name: *walletName - account_index: *derivationSegment - address_pool_gap: *walletAddressPoolGap - payment_script_template: *scriptTemplate - delegation_script_template: *scriptTemplate - state: - type: object - required: - - status - properties: - status: - description: | - An incomplete shared wallet does not have a complete set - of keys, so the only possible status is `incomplete`. - type: string - enum: - - incomplete - - ApiSharedWallet: &ApiSharedWallet - type: object - oneOf: - - title: Incomplete shared wallet (collecting account public keys for each co-signer) - <<: *ApiIncompleteSharedWallet - - title: Active shared wallet (account public keys for each co-signers is collected) - <<: *ApiActiveSharedWallet - - ApiSharedWalletPostDataFromMnemonics: &ApiSharedWalletPostDataFromMnemonics - type: object - required: - - name - - mnemonic_sentence - - passphrase - - account_index - - payment_script_template - properties: - name: *walletName - mnemonic_sentence: *walletMnemonicSentence - mnemonic_second_factor: *walletSecondFactor - passphrase: *walletPassphrase - account_index: *derivationSegment - payment_script_template: *scriptTemplateEntry - delegation_script_template: *scriptTemplateEntry - script_validation: *validationLevel - one_change_address_mode: *oneChangeAddressMode - - ApiSharedWalletPostDataFromAccountPubX: &ApiSharedWalletPostDataFromAccountPubX - type: object - required: - - name - - account_public_key - - account_index - - payment_script_template - properties: - name: *walletName - account_public_key: *sharedWalletAccountXPubkey - account_index: *derivationSegment - payment_script_template: *scriptTemplateEntry - delegation_script_template: *scriptTemplateEntry - script_validation: *validationLevel - - ApiSharedWalletPostData: &ApiSharedWalletPostData - type: object - oneOf: - - title: Create shared wallet from mnemonics - <<: *ApiSharedWalletPostDataFromMnemonics - - title: Create shared wallet from account public key - <<: *ApiSharedWalletPostDataFromAccountPubX - - ApiSharedWalletPatchData: &ApiSharedWalletPatchData - <<: *cosigners - - ApiAsset: &ApiAsset - type: object - required: - - policy_id - - fingerprint - - asset_name - properties: - policy_id: *assetPolicyId - asset_name: *assetName - fingerprint: *assetFingerprint - metadata: *assetMetadata - metadata_error: - type: string - description: | - If there was an error fetching metadata from the server, - this will be set to one of `fetch` or `parse`, to indicate - the kind of error. - enum: - - fetch - - parse - - ApiWalletMigrationBalance: &ApiWalletMigrationBalance - type: object - required: - - ada - - assets - properties: - ada: *amount - assets: *walletAssets - - ApiWalletMigrationPlan: &ApiWalletMigrationPlan - type: object - required: - - selections - - total_fee - - balance_leftover - - balance_selected - properties: - selections: - type: array - items: *ApiCoinSelection - description: | - The complete set of selections required for a migration. - - Each selection is the basis for a single transaction. - - The ordering of selections within the list is not significant. - After conversion into transactions, the transactions can be - broadcast to the network in any order to perform the migration. - total_fee: - <<: *amount - description: | - The total amount to be paid in fees for a migration. - - This is the total sum of the fees of the individual selections. - balance_leftover: - <<: *ApiWalletMigrationBalance - description: | - The total balance of assets that **cannot** be migrated. - - The **ada** component of this balance is the total sum of all dust - ada entries in the UTxO set. An ada entry is considered to be dust - if its value is not large enough to pay for the marginal cost of - including it in a transaction. - - The **assets** component of this balance is the total sum of all - non-ada assets that cannot currently be migrated. Tokens of a - non-ada asset cannot be migrated if there is insufficient ada - available to pay for their inclusion in a transaction. - balance_selected: - <<: *ApiWalletMigrationBalance - description: | - The total balance of assets that **can** be migrated. - - ApiWalletPassphrase: &ApiWalletPassphrase - type: object - required: - - passphrase - properties: - passphrase: - <<: *lenientPassphrase - description: The source wallet's master passphrase. - - ApiWalletMigrationPlanPostData: &ApiWalletMigrationPlanPostData - type: object - required: - - addresses - properties: - addresses: - <<: *addresses - description: The recipient addresses. - - ApiByronWalletMigrationPostData: &ApiByronWalletMigrationPostData - type: object - required: - - passphrase - - addresses - properties: - passphrase: - <<: *lenientPassphrase - description: The wallet's master passphrase. - addresses: - <<: *addresses - description: The recipient addresses. - - ApiShelleyWalletMigrationPostData: &ApiShelleyWalletMigrationPostData - type: object - required: - - passphrase - - addresses - properties: - passphrase: - <<: *walletPassphrase - description: The wallet's master passphrase. - addresses: - <<: *addresses - description: The recipient addresses. - - ApiWalletUtxoSnapshotEntry: &ApiWalletUtxoSnapshotEntry - type: object - required: - - ada - - assets - properties: - ada: - <<: *amount - description: | - The ada quantity associated with this UTxO entry. - assets: - <<: *walletAssets - description: | - The set of non-ada assets associated with this UTxO entry. - - ApiWalletUtxoSnapshot: &ApiWalletUtxoSnapshot - type: object - required: - - entries - properties: - entries: - type: array - items: *ApiWalletUtxoSnapshotEntry - minItems: 0 - description: | - The complete set of UTxO entries associated with a wallet. - - ApiWalletUTxOsStatistics: &ApiWalletUTxOsStatistics - type: object - required: - - total - - scale - - distribution - properties: - total: *amount - scale: - type: string - enum: - - log10 - distribution: - type: object - additionalProperties: - type: integer - example: - total: - quantity: 42000000 - unit: lovelace - scale: log10 - distribution: - 10: 1 - 100: 0 - 1000: 8 - 10000: 14 - 100000: 32 - 1000000: 3 - 10000000: 0 - 100000000: 12 - 1000000000: 0 - 10000000000: 0 - 100000000000: 0 - 1000000000000: 0 - 10000000000000: 0 - 100000000000000: 0 - 1000000000000000: 0 - 10000000000000000: 0 - 45000000000000000: 0 - - ApiWalletSignData: &ApiWalletSignData - type: object - required: - - passphrase - - metadata - properties: - passphrase: *lenientPassphrase - metadata: *transactionMetadata - - ApiScript: &ApiScript - <<: *script - - ApiPubKey: &ApiPubKey - <<: *credentialPubKey - - AnyAddress: &AnyAddress - type: object - required: - - address - properties: - address: *anyAddress - - ApiCredential: &ApiCredential - <<: *CredentialValue - - ApiAddressData: &ApiAddressData - type: object - nullable: false - properties: - payment: *ApiCredential - stake: - <<: *ApiCredential - example: stake_vk16apaenn9ut6s40lcw3l8v68xawlrlq20z2966uzcx8jmv2q9uy7qau558d - validation: *validationLevel - - ApiByronWalletRandomPostData: &ApiByronWalletRandomPostData - type: object - required: - - name - - mnemonic_sentence - - passphrase - properties: - style: - type: string - enum: ["random"] - name: *walletName - passphrase: *walletPassphrase - mnemonic_sentence: - <<: *walletMnemonicSentence - minItems: 12 - maxItems: 24 - - ApiByronWalletRandomXPrvPostData: &ApiByronWalletRandomXPrvPostData - type: object - description: patate - required: - - name - - encrypted_root_private_key - - passphrase_hash - properties: - style: - type: string - enum: ["random"] - name: *walletName - encrypted_root_private_key: - <<: *walletEncryptedRootPrivateKey - deprecated: true - - passphrase_hash: - <<: *walletPassphraseHash - deprecated: true - - ApiByronWalletIcarusPostData: &ApiByronWalletIcarusPostData - type: object - required: - - name - - mnemonic_sentence - - passphrase - properties: - style: - type: string - enum: ["icarus"] - name: *walletName - passphrase: *walletPassphrase - mnemonic_sentence: - <<: *walletMnemonicSentence - minItems: 12 - maxItems: 24 - - ApiByronWalletTrezorPostData: &ApiByronWalletTrezorPostData - type: object - required: - - name - - mnemonic_sentence - - passphrase - properties: - style: - type: string - enum: ["trezor"] - name: *walletName - passphrase: *walletPassphrase - mnemonic_sentence: - <<: *walletMnemonicSentence - minItems: 12 - maxItems: 24 - - ApiByronWalletLedgerPostData: &ApiByronWalletLedgerPostData - type: object - required: - - name - - mnemonic_sentence - - passphrase - properties: - style: - type: string - enum: ["ledger"] - name: *walletName - passphrase: *walletPassphrase - mnemonic_sentence: - <<: *walletMnemonicSentence - minItems: 12 - maxItems: 24 - - ApiWalletPutData: &ApiWalletPutData - type: object - properties: - name: *walletName - - ApiWalletPutDataExtended: &ApiWalletPutDataExtended - type: object - properties: - name: *walletName - one_change_address_mode: *oneChangeAddressMode - - ApiPostAccountKeyData: &ApiPostAccountKeyData - type: object - required: - - passphrase - - format - properties: - passphrase: *walletPassphrase - format: *keyExtended - - ApiPostAccountKeyDataWithPurpose: &ApiPostAccountKeyDataWithPurpose - type: object - required: - - passphrase - - format - properties: - passphrase: *walletPassphrase - format: *keyExtended - purpose: *derivationSegment - - ApiSettingsPutData: &ApiSettingsPutData - type: object - properties: - settings: *settings - - ApiSmashServer: &ApiSmashServer - type: string - pattern: '^https?:\/\/[a-zA-Z0-9-_~.]+(:[0-9]+)?/?$' - example: https://smash.cardano-mainnet.iohk.io/ - description: A base SMASH uri without endpoint path. - - ApiHealthCheck: &ApiHealthCheck - type: object - required: - - health - properties: - health: - type: string - enum: ["available", "unavailable", "unreachable", "no_smash_configured"] - description: | - The status of the SMASH server. Possible values are: - - health | description - --- | --- - `"available"` | server is awaiting your requests - `"unavailable"` | server is running, but currently unavailable, try again in a short time - `"unreachable"` | server could not be reached or didn't return a health status - `"no_smash_configured"` | SMASH is currently not configured, adjust the Settings first - - ApiWalletPutPassphraseOldPassphraseData: &ApiWalletPutPassphraseOldPassphraseData - type: object - required: - - old_passphrase - - new_passphrase - properties: - old_passphrase: - <<: *walletPassphrase - description: The current master passphrase. - new_passphrase: - <<: *walletPassphrase - description: A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds). - - ApiWalletPutPassphraseMnemonicData: &ApiWalletPutPassphraseMnemonicData - type: object - required: - - mnemonic_sentence - - new_passphrase - properties: - mnemonic_second_factor: *walletSecondFactor - mnemonic_sentence: - <<: *walletMnemonicSentence - description: The mnemonic list of words to restore the wallet - new_passphrase: - <<: *walletPassphrase - description: The new master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds) - - ApiWalletPutPassphraseData: &ApiWalletPutPassphraseData - type: object - oneOf: - - <<: *ApiWalletPutPassphraseOldPassphraseData - title: "providing old passphrase" - - <<: *ApiWalletPutPassphraseMnemonicData - title: "providing mnemonic" - - ApiByronWalletPutPassphraseData: &ApiByronWalletPutPassphraseData - type: object - required: - - new_passphrase - properties: - old_passphrase: - <<: *lenientPassphrase - description: The current passphrase if present. - new_passphrase: - <<: *walletPassphrase - description: A master passphrase to lock and protect the wallet for sensitive operation (e.g. sending funds). - - ApiDecodeTransactionPostData: &ApiDecodeTransactionPostData - type: object - required: - - transaction - properties: - decrypt_metadata: - <<: *encryptMetadata - description: The metadata passphrase for decryption. - transaction: *serialisedTransactionEncoded - - ApiSignTransactionPostData: &ApiSignTransactionPostData - type: object - required: - - passphrase - - transaction - properties: - passphrase: - <<: *lenientPassphrase - description: The wallet's master passphrase. - transaction: *serialisedTransactionEncoded - encoding: - type: string - enum: ["base16", "base64"] - description: Encoding of transaction CBOR returned in response (base64 by default). - - # ADP-908 Deprecated - ApiPostTransactionDataByron: &ApiPostTransactionDataByron - type: object - required: - - payments - - passphrase - properties: - payments: *transactionOutputs - passphrase: - <<: *lenientPassphrase - description: The wallet's master passphrase. - - # ADP-908 Deprecated - ApiPostTransactionData: &ApiPostTransactionData - type: object - required: - - payments - - passphrase - properties: - passphrase: - <<: *lenientPassphrase - description: The wallet's master passphrase. - payments: *transactionOutputs - withdrawal: *transactionWithdrawalRequestSelf - metadata: *transactionMetadata - time_to_live: *transactionTTL - - # ADP-908 Deprecated - ApiPostRedemptionData: &ApiPostRedemptionData - type: object - required: - - payments - - passphrase - - withdrawal - properties: - passphrase: - <<: *lenientPassphrase - description: The wallet's master passphrase. - payments: *transactionOutputs - withdrawal: *transactionRedemptionRequest - - # ADP-910 Deprecated - ApiPostTransactionFeeDataByron: &ApiPostTransactionFeeDataByron - type: object - required: - - payments - properties: - payments: *transactionOutputs - - # ADP-910 Deprecated - ApiPostTransactionFeeData: &ApiPostTransactionFeeData - type: object - required: - - payments - properties: - payments: *transactionOutputs - withdrawal: *transactionWithdrawalRequestSelf - metadata: *transactionMetadata - time_to_live: *transactionTTL - - # ADP-910 Deprecated - ApiPostRedemptionFeeData: &ApiPostRedemptionFeeData - type: object - required: - - payments - - withdrawal - properties: - payments: *transactionOutputs - withdrawal: *transactionRedemptionRequest - - ApiPostRandomAddressData: &ApiPostRandomAddressData - type: object - required: - - passphrase - properties: - passphrase: *lenientPassphrase - address_index: *addressIndex - - ApiValidityInterval: &ApiValidityInterval - description: | - Specify only invalid_before or invalid_hereafter or both. - - Please note that, if not set, the default values are: - - `"invalid_before": {"quantity":0, "unit":"slot"}` - - `"invalid_hereafter":{"quantity":7200, "unit":"second"}` - - Which translates to 2h transaction TTL. - type: object - properties: - invalid_before: *validityBound - invalid_hereafter: *validityBound - - ApiPaymentDestination: &ApiPaymentDestination - <<: *transactionOutputs - - ApiMintData: &ApiMintData - type: object - required: - - quantity - properties: - receiving_address: *addressId - quantity: *assetQuantity - - ApiBurnData: &ApiBurnData - type: object - required: - - quantity - properties: - quantity: *assetQuantity - - ApiMintBurnOperation: &ApiMintBurnOperation - type: object - oneOf: - - title: "mint" - properties: - mint: *ApiMintData - - title: "burn" - properties: - burn: *ApiBurnData - - ApiMintBurnData: &ApiMintBurnData - oneOf: - - type: object - title: minting via script template - required: - - operation - - policy_script_template - properties: - policy_script_template: *ScriptTemplateValue - asset_name: *assetName - operation: *ApiMintBurnOperation - - type: object - title: minting via script reference - required: - - operation - - reference_input - - policy_id - properties: - reference_input: *referenceInput - policy_id: *assetPolicyId - asset_name: *assetName - operation: *ApiMintBurnOperation - - ApiConstructTransactionData: &ApiConstructTransactionData - description: At least one field needs to be chosen - type: object - properties: - payments: *ApiPaymentDestination - withdrawal: *transactionWithdrawalRequestSelf - metadata: *transactionMetadata - encrypt_metadata: *encryptMetadata - mint_burn: - type: array - items: *ApiMintBurnData - minItems: 1 - description: | - An entry for each unique asset to be minted and/or burned, - containing helpful information. - vote: *ApiDRep - delegations: *transactionDelegations - validity_interval: *ApiValidityInterval - reference_policy_script_template: - <<: *ScriptTemplateValue - description: | - Optional policy script template that could be used as a script reference - in another transaction. - In the current transaction, the script will be included as - the first output (`index = 0`). - The script is constructed by replacing the cosigner - with the policy public key of the wallet. - In future transactions, the reference script can be used - by any wallet multiple times - by referencing the current transaction `id` and `index = 0`. - The script template must contain a single cosigner only, but it may include time locks. - encoding: - type: string - enum: ["base16", "base64"] - description: Encoding of transaction CBOR returned in response (base64 by default). - - CredentialValue: *CredentialValue - - ScriptValue: *ScriptValue - - ScriptValueGeneral: *ScriptValueGeneral - - ScriptTemplateValue: *ScriptTemplateValue - - # https://github.com/IntersectMBO/cardano-ledger/blob/8d836e61bb88bda4a6a5c00694735928390067a1/shelley/chain-and-ledger/executable-spec/src/Shelley/Spec/Ledger/MetaData.hs#L48-L65 - TransactionMetadataValue: &TransactionMetadataValue - oneOf: - - title: String - type: object - required: - - string - properties: - string: - type: string - maxLength: 64 - - - title: Int - type: object - required: - - int - properties: - int: - type: integer - - - title: ByteString - type: object - required: - - bytes - properties: - bytes: - type: string - pattern: "^[0-9a-fA-F]*$" - maxLength: 128 - - - title: List - type: object - required: - - list - properties: - list: - type: array - items: - $ref: "#/components/schemas/TransactionMetadataValue" - - - title: Map - type: object - required: - - map - properties: - map: - type: array - items: - type: object - nullable: true - properties: - k: - $ref: "#/components/schemas/TransactionMetadataValue" - v: - $ref: "#/components/schemas/TransactionMetadataValue" - - TransactionMetadataValueNoSchema: &TransactionMetadataValueNoSchema - oneOf: - - title: String - type: string - - - title: Int - type: integer - - - title: List - type: array - items: - $ref: "#/components/schemas/TransactionMetadataValueNoSchema" - - - title: Map - type: object - additionalProperties: - $ref: "#/components/schemas/TransactionMetadataValueNoSchema" - - ApiGetSettings: &ApiGetSettings - type: object - required: - - pool_metadata_source - properties: - pool_metadata_source: *poolMetadataSource - - SomeByronWalletPostData: &SomeByronWalletPostData - oneOf: - - <<: *ApiByronWalletRandomPostData - title: random - - <<: *ApiByronWalletIcarusPostData - title: icarus - - <<: *ApiByronWalletTrezorPostData - title: trezor - - <<: *ApiByronWalletLedgerPostData - title: ledger - - <<: *ApiAccountPostData - title: icarus/trezor/ledger (from xpub) - - <<: *ApiByronWalletRandomXPrvPostData - title: random (from xprv) - - ApiOurStakeKey: &ApiOurStakeKey - type: object - required: - - index - - key - - stake - - reward_balance - - delegation - properties: - index: *softIndex - key: *stakeAddress - stake: *amount - reward_balance: *amount - delegation: *ApiWalletDelegation - - ApiForeignStakeKey: &ApiForeignStakeKey - type: object - required: - - key - - stake - - reward_balance - properties: - key: *stakeAddress - stake: *amount - reward_balance: *amount - ApiNullStakeKey: &ApiNullStakeKey - type: object - required: - - stake - properties: - stake: *amount - description: | - The absence of a stake key. The `stake` field shows how much of the wallet funds - are not associated with an identifiable stake key. - - Most likely, these funds are associated with enterprise addresses lacking staking rights. - But they /could/ also be associate with more rare types of addresses like pointer addresses. - ApiStakeKeys: &ApiStakeKeys - type: object - required: - - ours - - foreign - - "none" - properties: - ours: - type: array - items: *ApiOurStakeKey - description: | - Stake keys belonging to the wallet. - foreign: - type: array - items: *ApiForeignStakeKey - description: | - Stake keys found in the wallet's UTxO, but does not belong to the wallet. - - "none": *ApiNullStakeKey - - ApiRedeemerSpending: &ApiRedeemerSpending - type: object - required: - - purpose - - data - - input - properties: - purpose: - type: string - enum: ["spending"] - data: - type: string - format: base16 - input: - type: object - required: - - id - - index - properties: - id: *transactionId - index: - type: integer - minimum: 0 - - ApiRedeemerMinting: &ApiRedeemerMinting - type: object - required: - - purpose - - data - - policy_id - properties: - purpose: - type: string - enum: ["minting"] - data: - type: string - format: base16 - policy_id: - type: string - format: hex - maxLength: 56 - - ApiRedeemerRewarding: &ApiRedeemerRewarding - type: object - required: - - purpose - - data - - stake_address - properties: - purpose: - type: string - enum: ["rewarding"] - data: - type: string - format: base16 - stake_address: *stakeAddress - - ApiRedeemer: &ApiRedeemer - oneOf: - - title: spending - <<: *ApiRedeemerSpending - - - title: minting - <<: *ApiRedeemerMinting - - - title: rewarding - <<: *ApiRedeemerRewarding - - ApiBalanceTransactionPostData: &ApiBalanceTransactionPostData - type: object - required: - - transaction - properties: - transaction: *serialisedTransactionEncoded - inputs: - description: | - Mapping from inputs (`id`, `ix`) in the supplied `transaction` binary to outputs (`amount`, `assets`, ...). It is not required to include inputs present in the `cardano-node` UTxO, as `cardano-wallet` will automatically query for them. - - In other words, this field can be left empty unless the supplied `transaction` contains inputs referring to pending transactions. - type: array - items: - type: object - required: - - id - - index - - address - - amount - - assets - properties: - id: *transactionId - index: - type: integer - minimum: 0 - address: *addressId - amount: *amount - datum: *datum - assets: *walletAssets - redeemers: - description: A list of redeemers data with their purpose. The redeemers in the `transaction` binary will be overwritten by this value. - type: array - items: *ApiRedeemer - encoding: - type: string - enum: ["base16", "base64"] - description: Encoding of transaction CBOR returned in response (base64 by default). - - ApiBlockHeader: &ApiBlockHeader - description: | - A Block Header. - required: - - header_hash - - slot_no - - block_height - properties: - header_hash: *blockId - slot_no: *numberOfSlots - block_height: *numberOfBlocks - -############################################################################# -# # -# PARAMETERS # -# # -############################################################################# - -x-parametersWalletId: ¶metersWalletId - in: path - name: walletId - required: true - schema: - type: string - format: hex - maxLength: 40 - minLength: 40 - -x-parametersIntendedStakeAmount: ¶metersIntendedStakeAmount - in: query - name: stake - required: true - schema: - type: integer - minimum: 0 - maximum: 45000000000000000 # 45 B ada (in Lovelace) - description: | - The stake the user intends to delegate in Lovelace. Required. - -x-parametersTransactionId: ¶metersTransactionId - in: path - name: transactionId - required: true - schema: - type: string - format: hex - maxLength: 64 - minLength: 64 - -x-parametersStakePoolId: ¶metersStakePoolId - in: path - name: stakePoolId - required: true - schema: - type: string - format: hex|bech32 - -x-parametersAddressId: ¶metersAddressId - in: path - name: addressId - required: true - schema: - type: string - format: base58 - example: DdzFFzCqrhtCNjPk5Lei7E1FxnoqMoAYtJ8VjAWbFmDb614nNBWBwv3kt6QHJa59cGezzf6piMWsbK7sWRB5sv325QqWdRuusMqqLdMt - -x-parametersRole: ¶metersRole - in: path - name: role - required: true - schema: - type: string - enum: - - utxo_external - - utxo_internal - - mutable_account - -x-parametersDerivationSegment: ¶metersDerivationSegment - in: path - name: index - required: true - schema: *derivationSegment - -x-parametersDerivationHash: ¶metersDerivationHash - in: query - name: hash - schema: - type: boolean - default: false - description: | - Whether to return the key hash instead of the key. - -x-parametersStartDate: ¶metersStartDate - in: query - name: start - description: | - An optional start time in ISO 8601 date-and-time format. Basic and - extended formats are both accepted. Times can be local (with a - timezone offset) or UTC. - - If both a start time and an end time are specified, then the start - time must not be later than the end time. - - Example: `2008-08-08T08:08:08Z` - schema: - type: string - format: ISO 8601 - -x-parametersEndDate: ¶metersEndDate - in: query - name: end - description: | - An optional end time in ISO 8601 date-and-time format. Basic and - extended formats are both accepted. Times can be local (with a - timezone offset) or UTC. - - If both a start time and an end time are specified, then the start - time must not be later than the end time. - - Example: `2008-08-08T08:08:08Z` - schema: - type: string - format: ISO 8601 - -x-parametersSortOrder: ¶metersSortOrder - in: query - name: order - description: An optional sort order. - schema: - type: string - enum: - - ascending - - descending - default: descending - -x-parametersMaxCount: ¶metersMaxCount - in: query - name: max_count - description: | - An optional maximum count. - schema: - type: integer - minimum: 1 - -x-parametersAddress: ¶metersAddress - in: query - name: address - description: | - An optional address. - If given, the list of transactions will be filtered - to only contain transactions that refer to this address in their inputs or outputs. - This may exclude transactions whose inputs reference outside transactions - that are not part of the transaction history of the wallet. - schema: *addressId - -x-parametersAddressState: ¶metersAddressState - in: query - name: state - description: An optional filter on the address state. - schema: - type: string - enum: - - used - - unused - -x-parametersForceNtpCheck: ¶metersForceNtpCheck - in: query - name: forceNtpCheck - allowEmptyValue: true - description: | - NTP checks are cached for short duration to avoid sending too many queries to the central NTP servers. In some cases however, a client may want to force a new check. - - When this flag is set, the request **will block** until NTP server responds or will timeout after a while without any answer from the NTP server. - schema: - type: boolean - -x-parametersMetadataFormat: ¶metersMetadataFormat - in: query - name: simple-metadata - schema: - type: boolean - allowEmptyValue: true - description: | - When present (or equal to true) in the query, the metadata format for the - transaction(s) in the output will be untyped plain json as specified in - [CIP 25](https://cips.cardano.org/cips/cip25/) - -x-parametersMinWithdrawal: ¶metersMinWithdrawal - in: query - name: minWithdrawal - description: | - Returns only transactions that have at least one withdrawal above the given amount. - This is particularly useful when set to `1` in order to list the withdrawal history of a wallet. - schema: - type: integer - minimum: 1 - -x-parametersPolicyId: ¶metersPolicyId - in: path - name: policyId - required: true - schema: - type: string - format: hex - maxLength: 56 - minLength: 56 - -x-parametersAssetName: ¶metersAssetName - in: path - name: assetName - required: true - schema: - type: string - format: hex - maxLength: 64 - -x-parametersDRepId: ¶metersDRepId - in: path - name: drepId - required: true - schema: *ApiDRep - -############################################################################# -# # -# RESPONSES # -# # -############################################################################# - -x-responsesErr: &responsesErr - type: object - required: - - message - - code - properties: - message: - type: string - description: A descriptive error message. - code: - type: string - description: A specific error code for this error, more precise than HTTP ones. - example: an_error_code - -x-errNotFound: &errNotFound - <<: *responsesErr - title: not_found - properties: - message: - type: string - description: A descriptive error message. - code: - type: string - enum: ['not_found'] - -x-errSoftDerivationRequired: &errSoftDerivationRequired - <<: *responsesErr - title: not_found - properties: - message: - type: string - description: A descriptive error message. - code: - type: string - enum: ['soft_derivation_required'] - -x-errHardenedDerivationRequired: &errHardenedDerivationRequired - <<: *responsesErr - title: not_found - properties: - message: - type: string - description: | - Occurs when hardened derivation is required and soft index is used - (without suffix 'H'). - code: - type: string - enum: ['hardened_derivation_required'] - -x-errNoUtxosAvailable: &errNoUtxosAvailable - <<: *responsesErr - title: no_utxos_available - properties: - message: - type: string - description: | - Indicates that the wallet has no unspent transaction outputs (UTxOs) - available. A transaction must spend at least one UTxO in order to be - accepted for inclusion on the Cardano blockchain. - code: - type: string - enum: ['no_utxos_available'] - -x-errWalletNotInitialized: &errWalletNotInitialized - <<: *responsesErr - title: wallet_not_initialized - properties: - message: - type: string - description: | - May occur when the database for the requested wallet is not initialized. - code: - type: string - enum: ['wallet_not_initialized'] - -x-errNoSuchWallet: &errNoSuchWallet - <<: *responsesErr - title: no_such_wallet - properties: - message: - type: string - description: | - May occur when a given walletId does not match with any known - wallets (because it has been deleted, or has never existed). - code: - type: string - enum: ['no_such_wallet'] - info: - type: object - required: - - wallet_id - properties: - wallet_id: *walletId - -x-errNoSuchTransaction: &errNoSuchTransaction - <<: *responsesErr - title: no_such_transaction - properties: - message: - type: string - description: May occur when a given transactionId does not match with any known transactions. - code: - type: string - enum: ['no_such_transaction'] - info: - type: object - required: - - transaction_id - properties: - transaction_id: *transactionId - -x-errTransactionAlreadyInLedger: &errTransactionAlreadyInLedger - <<: *responsesErr - title: transaction_already_in_ledger - properties: - message: - type: string - description: Occurs when attempting to delete a transaction which is neither pending nor expired. - code: - type: string - enum: ['transaction_already_in_ledger'] - info: - type: object - required: - - transaction_id - properties: - transaction_id: *transactionId - -x-errWalletAlreadyExists: &errWalletAlreadyExists - <<: *responsesErr - title: wallet_already_exists - properties: - message: - type: string - description: May occur when a otherwise valid request would yield a wallet that already exists. - code: - type: string - enum: ['wallet_already_exists'] - -x-errNoRootKey: &errNoRootKey - <<: *responsesErr - title: no_root_key - properties: - message: - type: string - description: May occur when an action require a signing key but the wallet has only access to verification keys. - code: - type: string - enum: ['no_root_key'] - -x-errWalletMetadataNotFound: &errWalletMetadataNotFound - <<: *responsesErr - title: wallet_metadata_not_found - properties: - message: - type: string - description: | - Indicates that it was not possible to find any metadata for the given - wallet within the database. - - May occur when a shared wallet has not yet become active after being in - the incomplete state. - code: - type: string - enum: ['wallet_metadata_not_found'] - -x-errWrongEncryptionPassphrase: &errWrongEncryptionPassphrase - <<: *responsesErr - title: wrong_encryption_passphrase - properties: - message: - type: string - description: May occur when the given spending passphrase is wrong. - code: - type: string - enum: ['wrong_encryption_passphrase'] - info: - type: object - required: - - wallet_id - properties: - wallet_id: *walletId - -x-errWrongMnemonic: &errWrongMnemonic - <<: *responsesErr - title: wrong_mnemonics - properties: - message: - type: string - description: May occur when the given mnemonic is wrong. - code: - type: string - enum: ['wrong_mnemonic'] - -x-errMalformedTxPayload: &errMalformedTxPayload - <<: *responsesErr - title: malformed_tx_payload - properties: - message: - type: string - description: May occur when submitting a malformed serialized transaction. - code: - type: string - enum: ['malformed_tx_payload'] - -x-errMempoolIsFull: &errMempoolIsFull - <<: *responsesErr - title: mempool_is_full - properties: - message: - type: string - description: May occur when submitting a serialized transaction to a node with full mempool. - code: - type: string - enum: [mempool_is_full] - -x-errTokensMintedButNotSpentOrBurned: &errTokensMintedButNotSpentOrBurned - <<: *responsesErr - title: tokens_minted_but_not_spent_or_burned - properties: - message: - type: string - description: | - Returned when a user mints funds but does not spend or burn them all. - code: - type: string - enum: ['tokens_minted_but_not_spent_or_burned'] - -# TODO: Map this error to the place it belongs. -x-errKeyNotFoundForAddress: &errKeyNotFoundForAddress - <<: *responsesErr - title: key_not_found_for_address - properties: - message: - type: string - description: Should never happen unless the server screwed up and has lost track of previously known addresses. - code: - type: string - enum: ['key_not_found_for_address'] - -x-errNotEnoughMoney: &errNotEnoughMoney - <<: *responsesErr - title: not_enough_money - properties: - message: - type: string - description: | - Indicates that there's not enough money in the wallet for the operation - to succeed. - - The 'shortfall' object indicates the additional quantity of each asset - that would be needed in order for the operation to succeed. - code: - type: string - enum: ['not_enough_money'] - info: - type: object - required: - - shortfall - properties: - shortfall: - description: | - The additional quantity of each asset that would be needed in order - for the operation to succeed. - type: object - required: - - ada - - assets - properties: - ada: *amount - assets: *walletAssets - -x-errInsufficientCollateral: &errInsufficientCollateral - <<: *responsesErr - title: insufficient_collateral - properties: - message: - type: string - description: | - May occur when the total balance of pure ada UTxOs in the wallet is - insufficient to cover the minimum collateral amount required for a - transaction requiring collateral. - code: - type: string - enum: ['insufficient_collateral'] - -x-errTransactionIsTooBig: &errTransactionIsTooBig - <<: *responsesErr - title: transaction_is_too_big - properties: - message: - type: string - description: May occur when the wallet can't cover for all requested outputs without making the transaction too large. - code: - type: string - enum: ['transaction_is_too_big'] - -x-errCreatedMultidelegationTransaction: &errCreatedMultidelegationTransaction - <<: *responsesErr - title: created_multidelegation_transaction - properties: - message: - type: string - description: Occurs when more than 1 delegation action is included in a transaction. - code: - type: string - enum: ['created_multidelegation_transaction'] - -x-errCreatedMultiaccountTransaction: &errCreatedMultiaccountTransaction - <<: *responsesErr - title: created_multiaccount_transaction - properties: - message: - type: string - description: Occurs when a delegation action does not use '0H' account. - code: - type: string - enum: ['created_multiaccount_transaction'] - -x-errCreatedWrongPolicyScriptTemplate: &errCreatedWrongPolicyScriptTemplate - <<: *responsesErr - title: created_wrong_policy_script_template - properties: - message: - type: string - description: | - Occurs when a policy script template either does not pass validation - or has more than one cosigner. - code: - type: string - enum: ['created_wrong_policy_script_template'] - -x-errAssetNameTooLong: &errAssetNameTooLong - <<: *responsesErr - title: asset_name_too_long - properties: - message: - type: string - description: Occurs when an asset name exceeds 32 bytes in length. - code: - type: string - enum: ['asset_name_too_long'] - -x-errMintOrBurnAssetQuantityOutOfBounds: &errMintOrBurnAssetQuantityOutOfBounds - <<: *responsesErr - title: mint_or_burn_asset_quantity_out_of_bounds - properties: - message: - type: string - description: | - Occurs when attempting to mint or burn an asset quantity that is not - greater than zero or exceeds 9223372036854775807 (2^63 - 1). - code: - type: string - enum: ['mint_or_burn_asset_quantity_out_of_bounds'] - -x-errInvalidValidityBounds: &errInvalidValidityBounds - <<: *responsesErr - title: invalid_validity_bounds - properties: - message: - type: string - description: | - Occurs when attempting to create a transaction with invalid validity - bounds. The 'invalid_before' bound must precede the 'invalid_hereafter' - bound, and the given time values must not be negative. - code: - type: string - enum: ['invalid_validity_bounds'] - -x-errValidityIntervalNotInsideScriptTimelock: &errValidityIntervalNotInsideScriptTimelock - <<: *responsesErr - title: validity_interval_not_inside_script_timelock - properties: - message: - type: string - description: | - Occurs when attempting to create a transaction with a validity interval - that is not a subinterval of an associated script's timelock interval. - code: - type: string - enum: ['validity_interval_not_inside_script_timelock'] - -x-errSharedWalletIncomplete: &errSharedWalletIncomplete - <<: *responsesErr - title: shared_wallet_incomplete - properties: - message: - type: string - description: | - Occurs when attempting to create a transaction for an incomplete shared wallet. - code: - type: string - enum: ['shared_wallet_incomplete'] - -x-errDelegationInvalid: &errDelegationInvalid - <<: *responsesErr - title: staking_invalid - properties: - message: - type: string - description: | - Occurs when attempting to create a delegation transaction for a shared wallet - without a delegation script template. - code: - type: string - enum: ['staking_invalid'] - -x-errVotingInInvalidEra: &errVotingInInvalidEra - <<: *responsesErr - title: voting_in_invalid_era - properties: - message: - type: string - description: | - Occurs when attempting to create a transaction that has voting - before Conway era. - code: - type: string - enum: ['voting_in_invalid_era'] - -x-errWithdrawalNotPossibleWithoutVote: &errWithdrawalNotPossibleWithoutVote - <<: *responsesErr - title: withdrawal_not_possible_without_vote - properties: - message: - type: string - description: | - Occurs when attempting to create a transaction that contains withdrawals - but previous voting was not performed (in Conway era onwards). - code: - type: string - enum: ['withdrawal_not_possible_without_vote'] - -x-errInvalidMetadataEncryption: &errInvalidMetadataEncryption - <<: *responsesErr - title: invalid_metadata_encryption - properties: - message: - type: string - description: | - The supplied metadata object is not compatible with the format - specified by CIP-83 (https://cips.cardano.org/cip/CIP-83). - code: - type: string - enum: ['invalid_metadata_encryption'] - -x-errInvalidMetadataDecryption: &errInvalidMetadataDecryption - <<: *responsesErr - title: invalid_metadata_decryption - properties: - message: - type: string - description: | - The supplied encrypted metadata object is not compatible with standard - specified by CIP-83 (https://cips.cardano.org/cip/CIP-83). - code: - type: string - enum: ['invalid_metadata_decryption'] - -x-errInputsDepleted: &errInputsDepleted - <<: *responsesErr - title: inputs_depleted - properties: - message: - type: string - description: May occur when there's enough money to pay for a payment, but not enough UTxO to allow for paying each output independently. - code: - type: string - enum: ['inputs_depleted'] - -x-errCannotCoverFee: &errCannotCoverFee - <<: *responsesErr - title: cannot_cover_fee - properties: - message: - type: string - description: May occur when a transaction can't be balanced for fees. - code: - type: string - enum: ['cannot_cover_fee'] - -x-errInvalidCoinSelection: &errInvalidCoinSelection - <<: *responsesErr - title: invalid_coin_selection - properties: - message: - type: string - description: Should never happen unless the server screwed up with the creation of a coin selection. - code: - type: string - enum: ['invalid_coin_selection'] - -x-errOutputTokenBundleSizeExceedsLimit: &errOutputTokenBundleSizeExceedsLimit - <<: *responsesErr - title: output_token_bundle_size_exceeds_limit - properties: - message: - type: string - description: | - Returned when a user-specified transaction output contains a token - bundle whose serialized length exceeds the limit supported by the - protocol. - code: - type: string - enum: ['output_token_bundle_size_exceeds_limit'] - info: - type: object - required: - - address - - bundle_size - properties: - address: *addressId - bundle_size: - type: integer - minimum: 0 - -x-errOutputTokenQuantityExceedsLimit: &errOutputTokenQuantityExceedsLimit - <<: *responsesErr - title: output_token_quantity_exceeds_limit - properties: - message: - type: string - description: | - Returned when a user-specified transaction output contains, for some - asset, a token quantity that exceeds the limit supported by the - protocol. - code: - type: string - enum: ['output_token_quantity_exceeds_limit'] - info: - type: object - required: - - address - - policy_id - - asset_name - - quantity - - max_quantity - properties: - address: *addressId - policy_id: *assetPolicyId - asset_name: *assetName - quantity: *assetQuantity - max_quantity: *assetQuantity - -x-errSharedWalletActive: &errSharedWalletActive - <<: *responsesErr - title: shared_wallet_active - properties: - message: - type: string - description: | - Returned when a user tries to add cosigner key to a shared wallet - that is active, not incomplete anymore. - code: - type: string - enum: ['shared_wallet_active'] - -x-errSharedWalletNoDelegationTemplate: &errSharedWalletNoDelegationTemplate - <<: *responsesErr - title: shared_wallet_no_delegation_template - properties: - message: - type: string - description: | - Returned when a user tries to add cosigner key to a shared wallet - for delegation, but the shared wallet misses the delegation template. - code: - type: string - enum: ['shared_wallet_no_delegation_template'] - -x-errSharedWalletKeyAlreadyExists: &errSharedWalletKeyAlreadyExists - <<: *responsesErr - title: shared_wallet_key_already_exists - properties: - message: - type: string - description: | - Returned when a user tries to add cosigner key to a shared wallet - but the same key is already present in a given template. - code: - type: string - enum: ['shared_wallet_key_already_exists'] - -x-errSharedWalletNoSuchCosigner: &errSharedWalletNoSuchCosigner - <<: *responsesErr - title: shared_wallet_no_such_cosigner - properties: - message: - type: string - description: | - Returned when a user tries to add cosigner key to a shared wallet - in script template that misses the cosigner. - code: - type: string - enum: ['shared_wallet_no_such_cosigner'] - info: - type: object - required: - - cosigner_index - - credential_type - properties: - cosigner_index: - type: integer - minimum: 0 - maximum: 255 - credential_type: - type: string - enum: - - delegation - - payment - -x-errSharedWalletCannotUpdateKey: &errSharedWalletCannotUpdateKey - <<: *responsesErr - title: shared_wallet_cannot_update_key - properties: - message: - type: string - description: | - Returned when a user tries to update cosigner key that contains a key of a shared wallet. - Only other cosigner keys can be updated. - code: - type: string - enum: ['shared_wallet_cannot_update_key'] - -x-errSharedWalletScriptTemplateInvalid: &errSharedWalletScriptTemplateInvalid - <<: *responsesErr - title: shared_wallet_script_template_invalid - properties: - message: - type: string - description: | - Returned when a user tries to create a shared wallet with script template - that does not pass validation. - code: - type: string - enum: ['shared_wallet_script_template_invalid'] - -# TODO: Map this error to the place it belongs. -x-errNetworkUnreachable: &errNetworkUnreachable - <<: *responsesErr - title: network_unreachable - properties: - message: - type: string - description: May occur when the connection with the node is lost or not responding. - code: - type: string - enum: ['network_unreachable'] - -# TODO: Map this error to the place it belongs. -x-errNetworkMisconfigured: &errNetworkMisconfigured - <<: *responsesErr - title: network_misconfigured - properties: - message: - type: string - description: May occur when trying to connect to a wrong network (e.g. testnet instead of mainnet). - code: - type: string - enum: ['network_misconfigured'] - -# TODO: Map this error to the place it belongs. -x-errNetworkQueryFailed: &errNetworkQueryFailed - <<: *responsesErr - title: network_query_failed - properties: - message: - type: string - description: Occurs when a ledger query fails in an unexpected manner. - code: - type: string - enum: ['network_query_failed'] - -x-errCreatedInvalidTransaction: &errCreatedInvalidTransaction - <<: *responsesErr - title: created_invalid_transaction - properties: - message: - type: string - description: Should never happen unless the server screwed up with the creation of transaction. - code: - type: string - enum: ['created_invalid_transaction'] - -x-errForeignTransaction: &errForeignTransaction - <<: *responsesErr - title: foreign_transaction - properties: - message: - type: string - description: Occurs when a transaction to be submitted does have neither input, output nor withdrawal belonging to a given wallet. - code: - type: string - enum: ['foreign_transaction'] - -x-errMissingWitnessesInTransaction: &errMissingWitnessesInTransaction - <<: *responsesErr - title: missing_witnesses_in_transaction - properties: - message: - type: string - description: Occurs when a transaction to be submitted is not fully signed. - code: - type: string - enum: ['missing_witnesses_in_transaction'] - info: - type: object - required: - - detected_number_of_key_wits - - expected_number_of_key_wits - properties: - detected_number_of_key_wits: - type: integer - minimum: 0 - expected_number_of_key_wits: - type: integer - minimum: 0 - -x-errRejectedByCoreNode: &errRejectedByCoreNode - <<: *responsesErr - title: rejected_by_core_node - properties: - message: - type: string - description: Should never happen unless the server screwed up with the creation of transaction. - code: - type: string - enum: ['rejected_by_core_node'] - -x-errBadRequest: &errBadRequest - <<: *responsesErr - title: bad_request - properties: - message: - type: string - description: | - May occur when a request is not well-formed; that is, it fails to parse - successfully. This could be the case when some required parameters - are missing or, when malformed values are provided. - code: - type: string - enum: ['bad_request'] - -x-errNodeNotYetInRecentEra: &errNodeNotYetInRecentEra - <<: *responsesErr - title: node_not_yet_in_recent_era - description: Occurs when the operation requires the node to be in a recent era, but is not. - properties: - message: - type: string - code: - type: string - enum: ['node_not_yet_in_recent_era'] - info: - type: object - required: - - node_era - - recent_eras - properties: - node_era: *ApiEra - recent_eras: - type: array - items: *ApiEra - -x-errTxNotInNodeEra: &errTxNotInNodeEra - <<: *responsesErr - title: tx_not_in_node_era - properties: - message: - type: string - description: The transaction could be deserialised, just not in the era of the local node. - code: - type: string - enum: ["tx_not_in_node_era"] - -x-errBalanceTxConflictingNetworks: &errBalanceTxConflictingNetworks - <<: *responsesErr - title: balance_tx_conflicting_networks - deprecated: true # TODO: Remove this error as soon as bump.sh allows us to - properties: - message: - type: string - description: | - There are withdrawals for multiple networks - (e.g. both mainnet and testnet) in the provided transaction. - This makes no sense, and I'm confused. - code: - type: string - enum: ["balance_tx_conflicting_networks"] - -x-errTranslationByronTxOutInContext: &errTranslationByronTxOutInContext - <<: *responsesErr - title: translation_byron_tx_out_in_context - properties: - message: - type: string - description: | - The given transaction contains a Byron-style TxOut which i not supported when executing - Plutus scripts. - code: - type: string - enum: ["translation_byron_tx_out_in_context"] - -x-errBalanceTxInlinePlutusV3ScriptNotSupportedInBabbage: &errBalanceTxInlinePlutusV3ScriptNotSupportedInBabbage - <<: *responsesErr - title: balance_tx_inline_plutus_v3_script_not_supported_in_babbage - properties: - message: - type: string - description: | - Inline Plutus V3 scripts are not supported in Babbage. - code: - type: string - enum: ["balance_tx_inline_plutus_v3_script_not_supported_in_babbage"] - -x-errBalanceTxExistingCollateral: &errBalanceTxExistingCollateral - <<: *responsesErr - title: balance_tx_existing_collateral - properties: - message: - type: string - description: I cannot balance transactions with pre-defined collateral. - code: - type: string - enum: ["balance_tx_existing_collateral"] - -x-errBalanceTxExistingKeyWitnesses: &errBalanceTxExistingKeyWitnesses - <<: *responsesErr - title: balance_tx_existing_key_witnesses - properties: - message: - type: string - description: | - The transaction could not be balanced, because it contains - existing key-witnesses which would be invalid after - the transaction body is modified. - Please sign the transaction after it is balanced instead. - code: - type: string - enum: ["balance_tx_existing_key_witnesses"] - -x-errBalanceTxExistingReturnCollateral: &errBalanceTxExistingReturnCollateral - <<: *responsesErr - title: balance_tx_existing_collateral_return_outputs - properties: - message: - type: string - description: | - Balancing transactions with pre-defined collateral return outputs - is not yet supported. - code: - type: string - enum: ["balance_tx_existing_collateral_return_outputs"] - -x-errBalanceTxExistingTotalCollateral: &errBalanceTxExistingTotalCollateral - <<: *responsesErr - title: balance_tx_existing_total_collateral - properties: - message: - type: string - description: | - I cannot balance transactions with pre-defined total collateral. - code: - type: string - enum: ["balance_tx_existing_total_collateral"] - -x-errBalanceTxInternalError: &errBalanceTxInternalError - <<: *responsesErr - title: balance_tx_internal_error - properties: - message: - type: string - description: | - Balancing transaction failed for an internal reason. - code: - type: string - enum: ["balance_tx_internal_error"] - -x-errBalanceTxUnderestimatedFee: &errBalanceTxUnderestimatedFee - <<: *responsesErr - title: balance_tx_underestimated_fee - properties: - message: - type: string - description: | - I have somehow underestimated the fee of the transaction - and cannot finish balancing. - code: - type: string - enum: ["balance_tx_underestimated_fee"] - -x-errMethodNotAllowed: &errMethodNotAllowed - <<: *responsesErr - title: method_not_allowed - properties: - message: - type: string - description: May occur when sending a request on a wrong endpoint. - code: - type: string - enum: ['method_not_allowed'] - -x-errNotAcceptable: &errNotAcceptable - <<: *responsesErr - title: not_acceptable - properties: - message: - type: string - description: May occur when providing an invalid 'Accept' header. - code: - type: string - enum: ['not_acceptable'] - -x-errUnsupportedMediaType: &errUnsupportedMediaType - <<: *responsesErr - title: unsupported_media_type - properties: - message: - type: string - description: May occur when providing an invalid 'Content-Type' header. - code: - type: string - enum: ['unsupported_media_type'] - -# TODO: Map this error to the place it belongs. -x-errUnexpectedError: &errUnexpectedError - <<: *responsesErr - title: unexpected_error - properties: - message: - type: string - description: Should never occur, unless the server screwed up badly. - code: - type: string - enum: ['unexpected_error'] - -x-errStartTimeLaterThanEndTime: &errStartTimeLaterThanEndTime - <<: *responsesErr - title: start_time_later_than_end_time - properties: - message: - type: string - description: May occur when a provided time-range is unsound. - code: - type: string - enum: ['start_time_later_than_end_time'] - info: - type: object - required: - - start_time - - end_time - properties: - start_time: *date - end_time: *date - -# TODO: Map this error to the place it belongs. -x-errUnableToDetermineCurrentEpoch: &errUnableToDetermineCurrentEpoch - <<: *responsesErr - title: unable_to_determine_current_epoch - properties: - message: - type: string - description: May occur under rare circumstances if the underlying node isn't enough synced with the network. - code: - type: string - enum: ['unable_to_determine_current_epoch'] - -# TODO: Map this error to the place it belongs. -x-errNotSynced: &errNotSynced - <<: *responsesErr - title: not_synced - properties: - message: - type: string - description: May occur under rare circumstances if the underlying node isn't enough synced with the network. - code: - type: string - enum: ['not_synced'] - -# TODO: Map this error to the place it belongs. -x-errNothingToMigrate: &errNothingToMigrate - <<: *responsesErr - title: nothing_to_migrate - properties: - message: - type: string - description: May occur when trying to migrate a wallet that is empty or full of dust. - code: - type: string - enum: ['nothing_to_migrate'] - -x-errNoSuchPool: &errNoSuchPool - <<: *responsesErr - title: no_such_pool - properties: - message: - type: string - description: May occur when a given poolId does not match any known pool. - code: - type: string - enum: ['no_such_pool'] - info: - type: object - required: - - pool_id - properties: - pool_id: *stakePoolId - -x-errPoolAlreadyJoined: &errPoolAlreadyJoined - <<: *responsesErr - title: pool_already_joined - properties: - message: - type: string - description: May occur when a given poolId matches the current delegation preferences of the wallet's account (not in Conway onwards provided different vote was also casted). - code: - type: string - enum: ['pool_already_joined'] - -x-errPoolAlreadyJoinedSameVote: &errPoolAlreadyJoinedSameVote - <<: *responsesErr - title: pool_already_joined_same_vote - properties: - message: - type: string - description: May occur in Conway onwards when a given poolId matches the current delegation preferences of the wallet's account and also the same vote was cast. - code: - type: string - enum: ['pool_already_joined_same_vote'] - -x-errSameVote: &errSameVote - <<: *responsesErr - title: same_vote - properties: - message: - type: string - description: May occur in Conway onwards when the same vote was cast. - code: - type: string - enum: ['same_vote'] - -x-errNotDelegatingTo: &errNotDelegatingTo - <<: *responsesErr - title: not_delegating_to - properties: - message: - type: string - description: May occur when trying to quit a pool on an account that isn't delegating. - code: - type: string - enum: ['not_delegating_to'] - -# TODO: Map this error to the place it belongs. -x-errNotImplemented: &errNotImplemented - <<: *responsesErr - title: not_implemented - properties: - message: - type: string - description: May occur when reaching an endpoint under construction. - code: - type: string - enum: ['not_implemented'] - -# TODO: Map this error to the place it belongs. -x-errWalletNotResponding: &errWalletNotResponding - <<: *responsesErr - title: wallet_not_responding - properties: - message: - type: string - description: Should never occur unless something really wrong happened causing a background worker to die. - code: - type: string - enum: ['wallet_not_responding'] - -# TODO: Map this error to the place it belongs. -x-errAddressAlreadyExists: &errAddressAlreadyExists - <<: *responsesErr - title: address_already_exists - properties: - message: - type: string - description: May occur when trying to import an address that is already known of the wallet's account. - code: - type: string - enum: ['address_already_exists'] - -x-errInvalidWalletType: &errInvalidWalletType - <<: *responsesErr - title: invalid_wallet_type - properties: - message: - type: string - description: May occur when trying to perform an operation not supported by this type of wallet. - code: - type: string - enum: ['invalid_wallet_type'] - -x-errMissingPolicyPublicKey: &errMissingPolicyPublicKey - <<: *responsesErr - title: missing_policy_public_key - properties: - message: - type: string - description: Occurs when trying to construct with minting/burning on shelley wallet without policy public key. - code: - type: string - enum: ['missing_policy_public_key'] - -x-errQueryParamMissing: &errQueryParamMissing - <<: *responsesErr - title: query_param_missing - properties: - message: - type: string - description: May occur when an endpoint requires the presence of a query parameter that is missing. - code: - type: string - enum: ['query_param_missing'] - -x-errNonNullRewards: &errNonNullRewards - <<: *responsesErr - title: non_null_rewards - properties: - message: - type: string - description: May occur when trying to unregister a stake key that still has rewards attached to it. - code: - type: string - enum: ['non_null_rewards'] - -x-errMissingRewardAccount: &errMissingRewardAccount - <<: *responsesErr - title: missing_reward_account - properties: - message: - type: string - description: May occur when there is a missing reward account but wallet participates in staking. - code: - type: string - enum: ['missing_reward_account'] - -x-errUtxoTooSmall: &errUtxoTooSmall - <<: *responsesErr - title: utxo_too_small - properties: - message: - type: string - description: - Occurs when a requested output has a quantity of lovelace that is below - the minimum required by the ledger. - code: - type: string - enum: ['utxo_too_small'] - info: - type: object - required: - - tx_output_index - - tx_output_lovelace_specified - - tx_output_lovelace_required_minimum - properties: - tx_output_index: - type: integer - minimum: 0 - tx_output_lovelace_specified: *amount - tx_output_lovelace_required_minimum: *amount - -x-errMinWithdrawalWrong: &errMinWithdrawalWrong - <<: *responsesErr - title: min_withdrawal_wrong - properties: - message: - type: string - description: May occur when trying to withdraw less than the minimal UTxO value. - code: - type: string - enum: ['min_withdrawal_wrong'] - -x-errAlreadyWithdrawing: &errAlreadyWithdrawing - <<: *responsesErr - title: already_withdrawing - properties: - message: - type: string - description: May occur when submitting a withdrawal while another withdrawal is pending. - code: - type: string - enum: ['already_withdrawing'] - -# TODO: Map this error to the place it belongs. -x-errWithdrawalNotBeneficial: &errWithdrawalNotBeneficial - <<: *responsesErr - title: withdrawal_not_beneficial - properties: - message: - type: string - description: | - Occurs when the cost of withdrawing a reward balance would be greater - than the reward balance itself. - code: - type: string - enum: ['withdrawal_not_beneficial'] - -# TODO: Map this error to the place it belongs. -x-errPastHorizon: &errPastHorizon - <<: *responsesErr - title: past_horizon - properties: - message: - type: string - description: May occur in rare cases when converting slot to time can't be done, typically near hard-forks. - code: - type: string - enum: ['past_horizon'] - -# TODO: Map this error to the place it belongs. -x-errUnableToAssignInputOutput: &errUnableToAssignInputOutput - <<: *responsesErr - title: unable_to_assign_input_output - properties: - message: - type: string - description: Should never occur unless the server screwed up with a coin selection. - code: - type: string - enum: ['unable_to_assign_input_output'] - -x-errAssetNotPresent: &errAssetNotPresent - <<: *responsesErr - title: asset_not_present - properties: - message: - type: string - description: | - Occurs when requesting information about an asset which is not - involved in any transaction related to the wallet. - code: - type: string - enum: ['asset_not_present'] - -x-errTransactionAlreadyBalanced: &errTransactionAlreadyBalanced - <<: *responsesErr - title: transaction_already_balanced - properties: - message: - type: string - description: | - Occurs when a transaction is already balanced. - code: - type: string - enum: ['transaction_already_balanced'] - -x-errRedeemerScriptFailure: &errRedeemerScriptFailure - <<: *responsesErr - title: redeemer_script_failure - properties: - message: - type: string - description: | - Occurs when balancing transaction with failing scripts. - code: - type: string - enum: ['redeemer_script_failure'] - -x-errRedeemerTargetNotFound: &errRedeemerTargetNotFound - <<: *responsesErr - title: redeemer_target_not_found - properties: - message: - type: string - description: | - Occurs when balancing transaction with reedemers that point to unknown entities. - code: - type: string - enum: ['redeemer_target_not_found'] - -x-errUnresolvedInputs: &errUnresolvedInputs - <<: *responsesErr - title: unresolved_inputs - properties: - message: - type: string - description: | - There are inputs in the transaction for which the corresponding outputs - could not be found. - code: - type: string - enum: ['unknown_inputs'] - -x-errUnresolvedRefunds: &errUnresolvedRefunds - <<: *responsesErr - title: unresolved_refunds - properties: - message: - type: string - description: | - There are stake key deregistration certificates in the transaction for which corresponding - deposit amounts could not be found. - code: - type: string - enum: ['unresolved_refunds'] - -x-errRedeemerInvalidData: &errRedeemerInvalidData - <<: *responsesErr - title: redeemer_invalid_data - properties: - message: - type: string - description: | - Occurs when data in provided redeemers do not decode to valid Plutus data. - code: - type: string - enum: ['redeemer_invalid_data'] - -x-errTranslationError: &errTranslationError - <<: *responsesErr - title: translation_error - properties: - message: - type: string - description: | - Occurs when any data in a provided transaction cannot be translated in a given era - code: - type: string - enum: ['translation_error'] - -x-errExistingKeyWitnesses: &errExistingKeyWitnesses - <<: *responsesErr - title: existing_key_witnesses - properties: - message: - type: string - description: | - Occurs when trying to balance a transaction that already has key witnesses. - code: - type: string - enum: ['existing_key_witnesses'] - -x-errInputResolutionConflicts: &errInputResolutionConflicts - <<: *responsesErr - title: input_resolution_conflicts - properties: - message: - type: string - description: | - At least one of the provided inputs has an - asset quantity or address that is different from that - recorded in the wallet's UTxO set. - code: - type: string - enum: ['input_resolution_conflicts'] - -x-errBlockHeaderNotFound: &errBlockHeaderNotFound - <<: *responsesErr - title: block_header_not_found - properties: - message: - type: string - description: | - Occurs when trying to retrieve a block header - that is not in the local node's chain. - code: - type: string - enum: ['block_header_not_found'] - -x-errUnsupportedEra: &errUnsupportedEra - <<: *responsesErr - title: unsupported_era - properties: - message: - type: string - code: - type: string - enum: ['unsupported_era'] - info: - type: object - required: - - unsupported_era - - supported_eras - properties: - unsupported_era: *ApiEra - supported_eras: - type: array - items: *ApiEra - -x-responsesErr400: &responsesErr400 - 400: - description: Bad Request - content: - application/json: - schema: *errBadRequest - -x-responsesErr403: &responsesErr403 - 403: - description: Forbidden - content: - application/json: - schema: *responsesErr - -x-responsesErr404: &responsesErr404 - 404: - description: Not Found - content: - application/json: - schema: *responsesErr - -x-responsesErr406: &responsesErr406 - 406: - description: Not Acceptable - content: - application/json: - schema: *errNotAcceptable - -x-responsesErr409: &responsesErr409 - 409: - description: Conflict - content: - application/json: - schema: *responsesErr - -x-responsesErr410: &responsesErr410 - 410: - description: Gone - content: - application/json: - schema: *responsesErr - -x-responsesErr415: &responsesErr415 - 415: - description: Unsupported Media Type - content: - application/json: - schema: *responsesErr - -x-responsesErr423: &responsesErr423 - 423: - description: Locked - content: - application/json: - schema: *responsesErr - -x-responsesErr425MempoolIsFull: &responsesErr425MempoolIsFull - 425: - description: Mempool is Full - content: - application/json: - schema: *errMempoolIsFull - -x-responsesErr404WalletNotFound: &responsesErr404WalletNotFound - 404: - description: Not Found - content: - application/json: - schema: *errNoSuchWallet - -x-responsesErr404WalletNotInitialized: &responsesErr404WalletNotInitialized - 404: - description: Wallet not yet initialized - content: - application/json: - schema: *errWalletNotInitialized - -x-responsesErr503WalletMetadataNotFound: &responsesErr503WalletMetadataNotFound - 503: - description: No meta - content: - application/json: - schema: *errWalletMetadataNotFound - -x-responsesErr409WalletAlreadyExists: &responsesErr409WalletAlreadyExists - 409: - description: Conflict - content: - application/json: - schema: *errWalletAlreadyExists - -x-responsesErr415UnsupportedMediaType: &responsesErr415UnsupportedMediaType - 415: - description: Unsupported Media Type - content: - application/json: - schema: *errUnsupportedMediaType - -x-responsesListWallets: &responsesListWallets - <<: *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: - type: array - items: *ApiWallet - -x-responsesListSharedWallets: &responsesListSharedWallets - <<: *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: - type: array - items: *ApiSharedWallet - -x-responsesErr404AssetNotPresent: &responsesErr404AssetNotPresent - 404: - description: Not Found - content: - application/json: - schema: *errAssetNotPresent - -x-responsesListAssets: &responsesListAssets - <<: *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: - type: array - items: *ApiAsset - -x-responsesGetAsset: &responsesGetAsset - <<: - - *responsesErr404AssetNotPresent - - *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: *ApiAsset - -x-responsesListByronWallets: &responsesListByronWallets - <<: *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: - type: array - items: *ApiByronWallet - -x-responsesGetUTxOsStatistics: &responsesGetUTxOsStatistics - <<: - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: *ApiWalletUTxOsStatistics - -x-responsesGetWalletUtxoSnapshot: &responsesGetWalletUtxoSnapshot - <<: - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: *ApiWalletUtxoSnapshot - -x-responsesPostWallet: &responsesPostWallet - <<: - - *responsesErr400 - - *responsesErr406 - - *responsesErr409WalletAlreadyExists - - *responsesErr415UnsupportedMediaType - 201: - description: Created - content: - application/json: - schema: *ApiWallet - -x-responsesPostSharedWallet: &responsesPostSharedWallet - <<: - - *responsesErr400 - - *responsesErr406 - - *responsesErr409WalletAlreadyExists - - *responsesErr415UnsupportedMediaType - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errSharedWalletScriptTemplateInvalid - 500: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errMissingRewardAccount - 201: - description: Created - content: - application/json: - schema: *ApiSharedWallet - -x-responsesPostByronWallet: &responsesPostByronWallet - <<: - - *responsesErr400 - - *responsesErr406 - - *responsesErr409 - - *responsesErr415 - 201: - description: Created - content: - application/json: - schema: *ApiByronWallet - -x-responsesGetWallet: &responsesGetWallet - <<: - - *responsesErr400 - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: *ApiWallet - -x-responsesGetByronWallet: &responsesGetByronWallet - <<: - - *responsesErr404 - - *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: *ApiByronWallet - -x-responsesGetSharedWallet: &responsesGetSharedWallet - <<: - - *responsesErr400 - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: *ApiSharedWallet - -x-responsesPatchSharedWallet: &responsesPatchSharedWallet - <<: - - *responsesErr400 - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - - *responsesErr503WalletMetadataNotFound - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errSharedWalletKeyAlreadyExists - - <<: *errSharedWalletNoDelegationTemplate - - <<: *errSharedWalletActive - - <<: *errSharedWalletNoSuchCosigner - - <<: *errSharedWalletCannotUpdateKey - 200: - description: Ok - content: - application/json: - schema: *ApiSharedWallet - -x-responsesCreateWalletMigrationPlan: &responsesCreateWalletMigrationPlan - <<: - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - 403: - description: Forbidden - content: - application/json: - schema: *errNothingToMigrate - 202: - description: Accepted - content: - application/json: - schema: *ApiWalletMigrationPlan - -x-responsesMigrateWallet: &responsesMigrateWallet - <<: - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errNothingToMigrate - - <<: *errNoRootKey - - <<: *errWrongEncryptionPassphrase - 202: - description: Accepted - content: - application/json: - schema: - type: array - items: *ApiTransaction - minItems: 1 - -x-responsesDeleteWallet: &responsesDeleteWallet - <<: - - *responsesErr400 - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - 204: - description: No Content - -x-responsesForceResyncWallet: &responsesForceResyncWallet - <<: - - *responsesErr400 - - *responsesErr403 - - *responsesErr404 - - *responsesErr406 - - *responsesErr415 - 204: - description: No Content - -x-responsesPutWallet: &responsesPutWallet - <<: - - *responsesErr400 - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - 200: - description: Ok - content: - application/json: - schema: *ApiWallet - -x-responsesPutSharedWallet: &responsesPutSharedWallet - <<: - - *responsesErr400 - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - 200: - description: Ok - content: - application/json: - schema: *ApiSharedWallet - -x-responsesPutWalletPassphrase: &responsesPutWalletPassphrase - <<: - - *responsesErr400 - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errNoRootKey - - <<: *errWrongEncryptionPassphrase - - <<: *errWrongMnemonic - 204: - description: No Content - -x-responsesSelectCoins: &responsesSelectCoins - <<: - - *responsesErr400 - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errAlreadyWithdrawing - - <<: *errUtxoTooSmall - - <<: *errNoUtxosAvailable - - <<: *errNotEnoughMoney - - <<: *errInsufficientCollateral - - <<: *errCannotCoverFee - - <<: *errInputsDepleted - - <<: *errInvalidCoinSelection - - <<: *errOutputTokenQuantityExceedsLimit - - <<: *errOutputTokenBundleSizeExceedsLimit - 200: - description: OK - content: - application/json: - schema: *ApiCoinSelection - -x-responsesDeleteTransaction: &responsesDeleteTransaction - <<: - - *responsesErr406 - 403: - description: Forbidden - content: - application/json: - schema: *errTransactionAlreadyInLedger - 404: - description: Not Found - content: - application/json: - schema: - oneOf: - - <<: *errNoSuchWallet - - <<: *errWalletNotInitialized - - <<: *errNoSuchTransaction - 204: - description: No Content - -x-responsesListTransactions: &responsesListTransactions - <<: - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - 400: - description: Bad Request - content: - application/json: - schema: - oneOf: - - <<: *errMinWithdrawalWrong - - <<: *errStartTimeLaterThanEndTime - 200: - description: Ok - headers: - Content-Range: - schema: - type: string - format: inserted-at {range-start}-{range-end}/{total} - content: - application/json: - schema: - type: array - items: *ApiTransaction -x-responsesGetTransaction: &responsesGetTransaction - 404: - description: Not Found - content: - application/json: - schema: - oneOf: - - <<: *errNoSuchWallet - - <<: *errWalletNotInitialized - - <<: *errNoSuchTransaction - <<: *responsesErr406 - 200: - description: OK - content: - application/json: - schema: *ApiTransaction - -# ADP-908 Deprecated -x-responsesPostTransaction: &responsesPostTransaction - <<: - - *responsesErr400 - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - - *responsesErr425MempoolIsFull - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errInvalidWalletType - - <<: *errAlreadyWithdrawing - - <<: *errUtxoTooSmall - - <<: *errCannotCoverFee - - <<: *errNoUtxosAvailable - - <<: *errNotEnoughMoney - - <<: *errInsufficientCollateral - - <<: *errTransactionIsTooBig - - <<: *errNoRootKey - - <<: *errWrongEncryptionPassphrase - - <<: *errUnsupportedEra - 202: - description: Accepted - content: - application/json: - schema: *ApiTransaction - -x-responsesConstructTransaction: &responsesConstructTransaction - <<: - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - 400: - description: Bad Request - content: - application/json: - schema: - oneOf: - - <<: *errBadRequest - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errInvalidWalletType - - <<: *errAlreadyWithdrawing - - <<: *errUtxoTooSmall - - <<: *errCannotCoverFee - - <<: *errNoUtxosAvailable - - <<: *errNotEnoughMoney - - <<: *errInsufficientCollateral - - <<: *errTransactionIsTooBig - - <<: *errCreatedMultidelegationTransaction - - <<: *errCreatedMultiaccountTransaction - - <<: *errCreatedWrongPolicyScriptTemplate - - <<: *errAssetNameTooLong - - <<: *errMintOrBurnAssetQuantityOutOfBounds - - <<: *errInvalidValidityBounds - - <<: *errValidityIntervalNotInsideScriptTimelock - - <<: *errSharedWalletIncomplete - - <<: *errDelegationInvalid - - <<: *errVotingInInvalidEra - - <<: *errWithdrawalNotPossibleWithoutVote - - <<: *errInvalidMetadataEncryption - - <<: *errSameVote - 202: - description: Accepted - content: - application/json: - schema: *ApiConstructTransaction - -x-responsesSignTransaction: &responsesSignTransaction - <<: - - *responsesErr400 - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errNoRootKey - - <<: *errWrongEncryptionPassphrase - 202: - description: Accepted - content: - application/json: - schema: *ApiSignedTransaction - -x-responsesDecodedTransaction: &responsesDecodedTransaction - <<: - - *responsesErr400 - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errInvalidMetadataDecryption - 202: - description: Accepted - content: - application/json: - schema: *ApiDecodedTransaction - -x-responsesSubmitTransaction: &responsesSubmitTransaction - <<: - - *responsesErr400 - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - 202: - description: Accepted - content: - application/json: - schema: *ApiTxId - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errForeignTransaction - - <<: *errMissingWitnessesInTransaction - - <<: *errCreatedMultidelegationTransaction - -x-responsesPostExternalTransaction: &responsesPostExternalTransaction - <<: - - *responsesErr400 - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - - *responsesErr425MempoolIsFull - 202: - description: Accepted - content: - application/json: - schema: *ApiTxId - -x-responsesPostAnyAddress: &responsesPostAnyAddress - <<: - - *responsesErr400 - - *responsesErr406 - - *responsesErr415 - 202: - description: Accepted - content: - application/json: - schema: *AnyAddress - -x-responsesPostTransactionFee: &responsesPostTransactionFee - <<: - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - 400: - description: Bad Request - content: - application/json: - schema: - oneOf: - - <<: *errBadRequest - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errInvalidWalletType - - <<: *errAlreadyWithdrawing - - <<: *errUtxoTooSmall - - <<: *errCannotCoverFee - - <<: *errNoUtxosAvailable - - <<: *errNotEnoughMoney - - <<: *errInsufficientCollateral - - <<: *errInputsDepleted - - <<: *errInvalidCoinSelection - - <<: *errOutputTokenQuantityExceedsLimit - - <<: *errOutputTokenBundleSizeExceedsLimit - - <<: *errTransactionIsTooBig - 202: - description: Accepted - content: - application/json: - schema: *ApiFee - -x-responsesGetDelegationFee: &responsesGetDelegationFee - <<: - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - 403: - description: Forbidden - content: - application/json: - schema: *errCannotCoverFee - 200: - description: Ok - content: - application/json: - schema: *ApiFee - -x-responsesListAddresses: &responsesListAddresses - <<: - - *responsesErr400 - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: - type: array - items: *ApiAddressWithPath - -x-responsesGetShelleyKey: &responsesGetShelleyKey - <<: - - *responsesErr400 - - *responsesErr404 - - *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: *ApiVerificationKeyShelley - -x-responsesPostPolicyKey: &responsesPostPolicyKey - <<: - - *responsesErr400 - - *responsesErr406 - - *responsesErr415 - 202: - description: Accepted - content: - application/json: - schema: *ApiPolicyKey - -x-responsesPostPolicyId: &responsesPostPolicyId - <<: - - *responsesErr400 - - *responsesErr406 - - *responsesErr415 - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errInvalidWalletType - - <<: *errMissingPolicyPublicKey - - <<: *errCreatedWrongPolicyScriptTemplate - 202: - description: Accepted - content: - application/json: - schema: *ApiPolicyId - -x-responsesGetPolicyKey: &responsesGetPolicyKey - <<: - - *responsesErr400 - - *responsesErr404 - - *responsesErr406 - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errInvalidWalletType - - <<: *errMissingPolicyPublicKey - 200: - description: Ok - content: - application/json: - schema: *ApiPolicyKey - -x-responsesGetSharedKey: &responsesGetSharedKey - <<: - - *responsesErr400 - - *responsesErr404 - - *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: *ApiVerificationKeyShared - -x-responsesGetAccountSharedKey: &responsesGetAccountSharedKey - <<: - - *responsesErr400 - - *responsesErr404 - - *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: *ApiAccountKeyShared - -x-responsesPostAccountKey: &responsesPostAccountKey - <<: - - *responsesErr400 - - *responsesErr406 - - *responsesErr415 - 202: - description: Accepted - content: - application/json: - schema: *ApiAccountKey - -x-responsesGetAccountKey: &responsesGetAccountKey - <<: - - *responsesErr400 - - *responsesErr404 - - *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: *ApiAccountKey - -x-responsesPostAccountKeyShared: &responsesPostAccountKeyShared - <<: - - *responsesErr400 - - *responsesErr406 - - *responsesErr415 - 202: - description: Accepted - content: - application/json: - schema: *ApiAccountKeyShared - -x-responsesListStakePools: &responsesListStakePools - 400: - description: Bad Request - content: - application/json: - schema: *errQueryParamMissing - 200: - description: Ok - content: - application/json: - schema: - type: array - items: *ApiStakePool - -x-responsesListStakeKeys: &responsesListStakeKeys - 200: - description: Ok - content: - application/json: - schema: *ApiStakeKeys - -x-responsesPostMaintenanceAction: &responsesPostMaintenanceAction - <<: - - *responsesErr404 - 204: - description: No Content - -x-responsesGetMaintenanceAction: &responsesGetMaintenanceAction - 200: - description: Ok - content: - application/json: - schema: - <<: *ApiMaintenanceAction - -x-responsesJoinStakePool: &responsesJoinStakePool - <<: - - *responsesErr400 - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errCannotCoverFee - - <<: *errNoRootKey - - <<: *errNoUtxosAvailable - - <<: *errWrongEncryptionPassphrase - - <<: *errPoolAlreadyJoined - - <<: *errPoolAlreadyJoinedSameVote - - <<: *errSameVote - 404: - description: Not Found - content: - application/json: - schema: - oneOf: - - <<: *errNoSuchWallet - - <<: *errWalletNotInitialized - - <<: *errNoSuchPool - 202: - description: Accepted - content: - application/json: - schema: *ApiTransaction - -x-responsesJoinDRep: &responsesJoinDRep - <<: - - *responsesErr400 - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errCannotCoverFee - - <<: *errNoRootKey - - <<: *errNoUtxosAvailable - - <<: *errWrongEncryptionPassphrase - - <<: *errSameVote - 404: - description: Not Found - content: - application/json: - schema: - oneOf: - - <<: *errNoSuchWallet - - <<: *errWalletNotInitialized - - <<: *errNoSuchPool - 202: - description: Accepted - content: - application/json: - schema: *ApiTransaction - -x-responsesQuitStakePool: &responsesQuitStakePool - <<: - - *responsesErr400 - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errCannotCoverFee - - <<: *errNoRootKey - - <<: *errNoUtxosAvailable - - <<: *errWrongEncryptionPassphrase - - <<: *errNotDelegatingTo - - <<: *errNonNullRewards - 202: - description: Accepted - content: - application/json: - schema: *ApiTransaction - -x-responsesGetNetworkInformation: &responsesGetNetworkInformation - <<: - - *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: *ApiNetworkInformation - -x-responsesGetNetworkClock: &responsesGetNetworkClock - <<: - - *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: *ApiNetworkClock - -x-responsesGetNetworkParameters: &responsesGetNetworkParameters - <<: - - *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: *ApiNetworkParameters - -x-responsesPostRandomAddress: &responsesPostRandomAddress - <<: - - *responsesErr400 - - *responsesErr403 - - *responsesErr406 - - *responsesErr415 - 201: - description: Created - content: - application/json: - schema: *ApiAddressWithPath - -x-responsesPutRandomAddress: &responsesPutRandomAddress - <<: - - *responsesErr400 - - *responsesErr403 - 204: - description: No Content - -x-responsesPutRandomAddresses: &responsesPutRandomAddresses - <<: - - *responsesErr400 - - *responsesErr403 - 204: - description: No Content - -x-responsesInspectAddress: &responsesInspectAddress - <<: - - *responsesErr400 - 200: - description: Ok - content: - application/json: - schema: *ApiAddressInspect - -x-responsesPutSettings: &responsesPutSettings - <<: - - *responsesErr400 - - *responsesErr415UnsupportedMediaType - 204: - description: No Content - -x-responsesGetSettings: &responsesGetSettings - 200: - description: Ok - content: - application/json: - schema: *ApiGetSettings - -x-responsesPostSignatures: &responsesPostSignatures - <<: - - *responsesErr400 - - *responsesErr406 - - *responsesErr415 - 200: - description: OK - content: - application/octet-stream: - schema: - type: string - format: binary - -x-responsesGetSmashHealth: &responsesGetSmashHealth - <<: - - *responsesErr400 - - *responsesErr406 - 200: - description: Ok - content: - application/json: - schema: *ApiHealthCheck - -x-responsesBalanceTransaction: &responsesBalanceTransaction - 400: - description: Bad Request - content: - application/json: - schema: - oneOf: - - <<: *errBadRequest - - <<: *errRedeemerScriptFailure - - <<: *errRedeemerTargetNotFound - - <<: *errRedeemerInvalidData - - <<: *errTranslationError - - <<: *errUnresolvedInputs - - <<: *errInputResolutionConflicts - 403: - description: Forbidden - content: - application/json: - schema: - oneOf: - - <<: *errAlreadyWithdrawing - - <<: *errNodeNotYetInRecentEra - - <<: *errBalanceTxConflictingNetworks - - <<: *errBalanceTxExistingCollateral - - <<: *errBalanceTxExistingKeyWitnesses - - <<: *errBalanceTxExistingReturnCollateral - - <<: *errBalanceTxExistingTotalCollateral - - <<: *errBalanceTxInternalError - - <<: *errCannotCoverFee - - <<: *errInsufficientCollateral - - <<: *errInvalidWalletType - - <<: *errNoUtxosAvailable - - <<: *errNotEnoughMoney - - <<: *errTransactionAlreadyBalanced - - <<: *errTransactionIsTooBig - - <<: *errUtxoTooSmall - - <<: *errTxNotInNodeEra - - <<: *errBalanceTxInlinePlutusV3ScriptNotSupportedInBabbage - - <<: *errTranslationByronTxOutInContext - <<: - - *responsesErr404WalletNotFound - - *responsesErr404WalletNotInitialized - - *responsesErr406 - - *responsesErr415UnsupportedMediaType - 202: - description: Accepted - content: - application/json: - schema: *ApiSerialisedTransaction - -############################################################################# -# # -# PATHS # -# # -############################################################################# - -x-tagGroups: - - name: Shelley (Sequential) - tags: - - Wallets - - Assets - - Addresses - - Coin Selections - - Transactions - - Transactions New - - Migrations - - Stake Pools - - DReps - - Keys - - - name: Shelley (Shared Wallets) - tags: - - Shared Wallets - - Shared Keys - - Shared Addresses - - Shared Transactions - - - name: Byron (Random) - tags: - - Byron Wallets - - Byron Assets - - Byron Addresses - - Byron Coin Selections - - Byron Transactions - - Byron Migrations - - - name: Miscellaneous - tags: - - Utils - - Network - - Proxy - - Settings - - Experimental - - Node - -paths: - /wallets/{walletId}/signatures/{role}/{index}: - post: - operationId: signMetadata - tags: ["Experimental"] - summary: Sign Metadata - description: | -

status: experimental

- - **⚠️ WARNING ⚠️** - - This endpoint is experimental and for internal use in the Catalyst project. This - functionality will be refined in the forthcoming future and the interface is likely - to change in **NON-BACKWARD COMPATIBLE WAYS**. - - Note: Only `Soft` indexes are supported by this endpoint. - parameters: - - *parametersWalletId - - *parametersRole - - *parametersDerivationSegment - requestBody: - required: true - content: - application/json: - schema: *ApiWalletSignData - responses: *responsesPostSignatures - - /wallets: - post: - operationId: postWallet - tags: ["Wallets"] - summary: Create / Restore - description: | -

status: stable

- - Create and restore a wallet from a mnemonic sentence or account public key. - requestBody: - required: true - content: - application/json: - schema: *ApiWalletOrAccountPostData - responses: *responsesPostWallet - - get: - operationId: listWallets - tags: ["Wallets"] - summary: List - description: | -

status: stable

- - Return a list of known wallets, ordered from oldest to newest. - responses: *responsesListWallets - - /wallets/{walletId}/assets: - get: - operationId: listAssets - tags: ["Assets"] - summary: List Assets - description: | - List all assets associated with the wallet, and their metadata - if known. - - An asset is _associated_ with a wallet if, at one point in history, - it was spendable by the wallet. - parameters: - - *parametersWalletId - responses: *responsesListAssets - - /wallets/{walletId}/assets/{policyId}/{assetName}: - get: - operationId: getAsset - tags: ["Assets"] - summary: Get Asset - description: | - Fetch a single asset from its `policy_id` and `asset_name`, - with its metadata if any. - - The asset must be associated with the wallet. - parameters: - - *parametersWalletId - - *parametersPolicyId - - *parametersAssetName - responses: *responsesGetAsset - - /wallets/{walletId}/assets/{policyId}: - get: - operationId: getAssetDefault - tags: ["Assets"] - summary: Get Asset (empty name) - description: | - Fetch the asset from `policy_id` with an empty name. - - The asset must be associated with the wallet. - parameters: - - *parametersWalletId - - *parametersPolicyId - responses: *responsesGetAsset - - /wallets/{walletId}/statistics/utxos: - get: - operationId: getUTxOsStatistics - tags: ["Wallets"] - summary: UTxO Statistics - description: | -

status: stable

- - Return the UTxO distribution across the whole wallet, in the form of a histogram. - - ``` - │ - 100 ─ - │ - │ ┌───┐ - 10 ─ ┌───┐ │ │ ┌───┐ - │ ┌───┐ │ │ │ │ │ │ - │ │ │ │ │ │ │ ┌───┐ │ │ - 1 ─ ┌───┐ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ │ │ │ │ │ │ ╷ │ │ ╷ │ │ ╷ ╷ │ │ - └─┘ └─│───────│─┘ └─│─┘ └─│─┘ └─│─┘ └─│───────│─┘ └──── - 10μ₳ 100μ₳ 1000μ₳ 0.1₳ 1₳ 10₳ 100₳ - ``` - parameters: - - *parametersWalletId - responses: *responsesGetUTxOsStatistics - - /wallets/{walletId}/utxo: - get: - operationId: getWalletUtxoSnapshot - tags: ["Wallets"] - summary: A snapshot of the wallet's UTxO set - description: | - Generate a snapshot of the wallet's UTxO set. - - This endpoint is intended for debugging purposes. - parameters: - - *parametersWalletId - responses: *responsesGetWalletUtxoSnapshot - - /wallets/{walletId}: - get: - operationId: getWallet - tags: ["Wallets"] - summary: Get - description: | -

status: stable

- parameters: - - *parametersWalletId - responses: *responsesGetWallet - - delete: - operationId: deleteWallet - tags: ["Wallets"] - summary: Delete - description: | -

status: stable

- parameters: - - *parametersWalletId - responses: *responsesDeleteWallet - - put: - operationId: putWallet - tags: ["Wallets"] - summary: Update Metadata - description: | -

status: stable

- parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiWalletPutDataExtended - responses: *responsesPutWallet - - /wallets/{walletId}/passphrase: - put: - operationId: putWalletPassphrase - tags: ["Wallets"] - summary: Update Passphrase - description: | -

status: stable

- parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiWalletPutPassphraseData - responses: *responsesPutWalletPassphrase - - /wallets/{walletId}/payment-fees: - post: - operationId: postTransactionFee - tags: ["Transactions"] - summary: Estimate Fee - # ADP-908 - Deprecated soon - deprecated: false - description: | -

status: stable

- - Estimate fee for the transaction. The estimate is made by - assembling multiple transactions and analyzing the - distribution of their fees. The estimated_max is the highest - fee observed, and the estimated_min is the fee which is lower - than at least 90% of the fees observed. - - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: - oneOf: - - <<: *ApiPostTransactionFeeData - title: "payment" - - <<: *ApiPostRedemptionFeeData - title: "redemption" - responses: *responsesPostTransactionFee - - /wallets/{walletId}/transactions: - post: - operationId: postTransaction - tags: ["Transactions"] - summary: Create - # ADP-908 - Deprecated soon - deprecated: false - description: | -

status: stable

- - Create and send transaction from the wallet. - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: - oneOf: - - <<: *ApiPostTransactionData - title: "payment" - - <<: *ApiPostRedemptionData - title: "redemption" - responses: *responsesPostTransaction - - get: - operationId: listTransactions - tags: ["Transactions"] - summary: List - description: | -

status: stable

- - Lists all incoming and outgoing wallet's transactions. - parameters: - - *parametersWalletId - - *parametersStartDate - - *parametersEndDate - - *parametersSortOrder - - *parametersMaxCount - - *parametersMinWithdrawal - - *parametersMetadataFormat - - *parametersAddress - responses: *responsesListTransactions - - /wallets/{walletId}/transactions/{transactionId}: - get: - operationId: getTransaction - tags: ["Transactions"] - summary: Get - description: | -

status: stable

- - Get transaction by id. - parameters: - - *parametersWalletId - - *parametersTransactionId - - *parametersMetadataFormat - responses: *responsesGetTransaction - - delete: - operationId: deleteTransaction - tags: ["Transactions"] - summary: Forget - description: | -

status: stable

- - Forget pending transaction. Importantly, a transaction, when sent, - cannot be cancelled. One can only request forgetting about it - in order to try spending (concurrently) the same UTxO in another - transaction. But, the transaction may still show up later in a block - and therefore, appear in the wallet. - parameters: - - *parametersWalletId - - *parametersTransactionId - responses: *responsesDeleteTransaction - - /wallets/{walletId}/transactions-construct: - post: - operationId: constructTransaction - tags: ["Transactions New"] - summary: Construct - description: | -

status: stable

- - Create a transaction to be signed from the wallet. - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiConstructTransactionData - responses: *responsesConstructTransaction - - /wallets/{walletId}/transactions-sign: - post: - operationId: signTransaction - tags: ["Transactions New"] - summary: Sign - description: | -

status: stable

- - Signs a serialised transaction either hex-encoded or base64-encoded, - returning the modified transaction. - - This endpoint will add new witnesses using the keys available - to this wallet. Any existing witnesses will remain in the - witness set. - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiSignTransactionPostData - responses: *responsesSignTransaction - - /wallets/{walletId}/transactions-decode: - post: - operationId: decodeTransaction - tags: ["Transactions New"] - summary: Decode - description: | -

status: stable

- - Decode a serialized transaction, either freshly constructed, - partially signed or fully-signed. - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiDecodeTransactionPostData - responses: *responsesDecodedTransaction - - /wallets/{walletId}/transactions-submit: - post: - operationId: submitTransaction - tags: ["Transactions New"] - summary: Submit - description: | -

status: stable

- Submit a transaction that was already created and signed. - Fails for foreign transactions that is transactions which lack - the wallet's inputs and withdrawals. - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiSignedTransactionEncoded - responses: *responsesPostExternalTransaction - - /wallets/{walletId}/addresses: - get: - operationId: listAddresses - tags: ["Addresses"] - summary: List - description: | -

status: stable

- - Return a list of known addresses, ordered from newest to oldest - parameters: - - *parametersWalletId - - *parametersAddressState - responses: *responsesListAddresses - - /wallets/{walletId}/keys/{index}: - post: - operationId: postAccountKey - tags: ["Keys"] - summary: Create Account Public Key - description: | -

status: stable

- Derive an account public key for any account index. For this key derivation to be possible, - the wallet must have been created from mnemonic. - - It is possible to use the optional `purpose` field to override that branch of the derivation path - with different hardened derivation index. If that field is omitted, the default purpose - for Cardano wallets (`1852H`) will be used. - - Note: Only _Hardened_ indexes are supported by this endpoint. - parameters: - - *parametersWalletId - - *parametersDerivationSegment - requestBody: - required: true - content: - application/json: - schema: *ApiPostAccountKeyDataWithPurpose - responses: *responsesPostAccountKey - - /wallets/{walletId}/keys: - get: - operationId: getAccountKey - tags: ["Keys"] - summary: Get Account Public Key - description: | -

status: stable

- Retrieve the account public key of this wallet. - - To get an extended public key, instead of the public key, - use query parameter `format=extended`. For non-extended public key - use `format=non_extended` or omit query parameter. - - Note the returned key is bech32-encoded. To be used when restoring - a wallet with public account key only, one needs to pass the key - in hex-encoded form. The bech32 tool which is included - in cardano-wallet distribution can used on the command-line: - - - curl https://my.host/v2/wallets/1f8[...]/keys?format=extended' | jq -r . | bech32 - - - parameters: - - *parametersWalletId - responses: *responsesGetAccountKey - - /wallets/{walletId}/keys/{role}/{index}: - get: - operationId: getWalletKey - tags: ["Keys"] - summary: Get Public Key - description: | -

status: stable

- Return a public key for a given role and derivation index. - - To get a hash of the public key, instead of the public key, - use query parameter `hash=true`. - - Note: Only `Soft` indexes are supported by this endpoint. - parameters: - - *parametersWalletId - - *parametersRole - - *parametersDerivationSegment - responses: *responsesGetShelleyKey - - /wallets/{walletId}/policy-id: - post: - operationId: postPolicyId - tags: ["Keys"] - summary: Create Policy Id - description: | -

status: stable

- - Create policy id for the wallet and a given mint/burn script. - - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiPostPolicyIdData - responses: *responsesPostPolicyId - - /wallets/{walletId}/policy-key: - post: - operationId: postPolicyKey - tags: ["Keys"] - summary: Create Policy Key - description: | -

status: stable

- - Create policy key for the wallet. - - In order to be able to mint/burn assets with `POST Construct` endpoint there needs to be - a policy key set for the wallet. Invoking this endpoint would be required for all wallets instantiated - before introducing mint/burn feature prior to making a mint/burn transaction from them. - - To get a hash of the policy key instead of the policy key, - use query parameter `hash=true`. - - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiPostPolicyKeyData - responses: *responsesPostPolicyKey - - get: - operationId: getPolicyKey - tags: ["Keys"] - summary: Get Policy Key - description: | -

status: stable

- Return a policy key for a derivation index = 0. - - To get a hash of the policy key instead of the policy key, - use query parameter `hash=true`. - - parameters: - - *parametersWalletId - responses: *responsesGetPolicyKey - - /wallets/{walletId}/stake-keys: - get: - operationId: listStakeKeys - tags: ["Stake Pools"] - summary: List Stake Keys - description: | -

status: Experimental

- - List stake-keys relevant to the wallet, and how much ada is associated with each. - parameters: - - *parametersWalletId - responses: *responsesListStakeKeys - - /stake-pools: - get: - operationId: listStakePools - tags: ["Stake Pools"] - summary: List - description: | -

status: stable

- - List all known stake pools ordered by descending `non_myopic_member_rewards`. - The `non_myopic_member_rewards` — and thus the ordering — depends on the `?stake` query - parameter. - - Some pools _may_ also have metadata attached to them. - parameters: - - *parametersIntendedStakeAmount - responses: *responsesListStakePools - - /stake-pools/maintenance-actions: - get: - operationId: getMaintenanceActions - tags: ["Stake Pools"] - summary: View Maintenance Actions - description: | - Returns the current status of the stake pools maintenance actions. - responses: *responsesGetMaintenanceAction - - post: - operationId: postMaintenanceAction - tags: ["Stake Pools"] - summary: Trigger Maintenance Actions - description: | - Performs maintenance actions on stake pools, such - as triggering metadata garbage collection. - - Actions may not be instantaneous. - requestBody: - required: true - content: - application/json: - schema: *ApiMaintenanceActionPostData - responses: *responsesPostMaintenanceAction - - /wallets/{walletId}/delegation-fees: - get: - operationId: getDelegationFee - tags: ["Stake Pools"] - summary: Estimate Fee - # ADP-908 - Deprecated soon - deprecated: false - description: | -

status: stable

- - Estimate fee for joining or leaving a stake pool. Note that it is an - estimation because a delegation induces a transaction for which coins - have to be selected randomly within the wallet. Because of this randomness, - fees can only be estimated. - parameters: - - *parametersWalletId - responses: *responsesGetDelegationFee - - /stake-pools/*/wallets/{walletId}: - delete: - operationId: quitStakePool - tags: ["Stake Pools"] - summary: Quit - description: | -

status: stable

- - Stop delegating completely. The wallet's stake will become inactive. - - Any current rewards will automatically withdrawn. - - > ⚠️ Disclaimer ⚠️ - > - > This endpoint historically use to take a stake pool id as a path parameter. - > However, retiring from delegation is ubiquitous and not tied to a particular - > stake pool. For backward-compatibility reasons, sending stake pool ids as path - > parameter will still be accepted by the server but new integrations are - > encouraged to provide a placeholder asterisk `*` instead. - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiWalletPassphrase - responses: *responsesQuitStakePool - - /stake-pools/{stakePoolId}/wallets/{walletId}: - put: - operationId: joinStakePool - tags: ["Stake Pools"] - summary: Join - description: | -

status: stable

- - Delegate all (current and future) addresses from the given wallet to the given stake pool. - - Note: Bech32-encoded stake pool identifiers can vary in length. - - parameters: - - *parametersStakePoolId - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiWalletPassphrase - responses: *responsesJoinStakePool - - /dreps/{drepId}/wallets/{walletId}: - put: - operationId: joinDRep - tags: ["DReps"] - summary: Join - description: | -

status: stable

- - Delegate all votes from the given wallet to the given DRep or - case abstain or no-confidence - - parameters: - - *parametersDRepId - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiWalletPassphrase - responses: *responsesJoinDRep - - /wallets/{walletId}/coin-selections/random: - post: - operationId: selectCoins - tags: ["Coin Selections"] - summary: Random - description: | -

status: stable

- - Select coins to cover the given set of payments. - - Uses the - Random-Improve coin selection algorithm. - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiSelectCoinsData - responses: *responsesSelectCoins - - /wallets/{walletId}/migrations: - post: - operationId: migrateShelleyWallet - tags: ["Migrations"] - summary: Migrate - description: | - Migrate the UTxO balance of this wallet to the given set of addresses. - - This operation will attempt to transfer as much of the wallet's balance - as possible to the given set of addresses, by creating and submitting - as many transactions as may be necessary to migrate the entire balance. - - In order to minimize the total transaction fee required, UTxO entries - are coalesced together to the greatest extent possible in the resulting - transactions. No attempt is made to preserve the wallet's UTxO - distribution. - - This operation is performed on a best-effort basis. If there is - insufficient ada available to pay for the entire UTxO set to be - migrated, then only a subset of the wallet's UTxO set will be migrated. - - A typical use of this operation would be to move all funds from an old - wallet to a new wallet, by providing addresses that belong to the new - wallet. - parameters: - - <<: *parametersWalletId - name: walletId - requestBody: - required: true - content: - application/json: - schema: *ApiShelleyWalletMigrationPostData - responses: *responsesMigrateWallet - - /wallets/{walletId}/migrations/plan: - post: - operationId: createShelleyWalletMigrationPlan - tags: ["Migrations"] - summary: Create a migration plan - description: | - Generate a plan for migrating the UTxO balance of this wallet to - another wallet, without executing the plan. - - This operation generates a plan that transfers as much of the wallet's - balance as possible, by creating as many selections as may be necessary - to migrate the entire balance. Each selection created is the basis for - a transaction. - - In order to minimize the total transaction fee required, UTxO entries - are coalesced together to the greatest extent possible in the resulting - selections. No attempt is made to preserve the wallet's UTxO - distribution. - - The plan is generated on a best-effort basis. If there is insufficient - ada available to pay for the entire UTxO set to be migrated, then only - a subset of the wallet's UTxO set will be included in the resultant - plan. - parameters: - - <<: *parametersWalletId - name: walletId - requestBody: - required: true - content: - application/json: - schema: *ApiWalletMigrationPlanPostData - responses: *responsesCreateWalletMigrationPlan - - /wallets/{walletId}/transactions-balance: - post: - operationId: balanceTransaction - tags: ["Transactions New"] - summary: Balance - description: | -

status: under development

- Balance a transaction body of a given transaction, add needed inputs/outputs, - so as the transaction can be signed from the wallet. - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiBalanceTransactionPostData - responses: *responsesBalanceTransaction - - /byron-wallets: - post: - operationId: postByronWallet - tags: ["Byron Wallets"] - summary: Restore - description: | -

status: stable

- - Restore a Byron wallet from a mnemonic sentence or encrypted root private key (deprecated). - - **⚠️ WARNING ⚠️** - - The construction of random wallet in itself is **deprecated**, in particular the restoration from an encrypted root private key. - These endpoints exist to ease migrations from legacy software such as `cardano-sl` but should be avoided by new applications. - requestBody: - required: true - content: - application/json: - schema: *SomeByronWalletPostData - responses: *responsesPostByronWallet - - get: - operationId: listByronWallets - tags: ["Byron Wallets"] - summary: List - description: | -

status: stable

- - Return a list of known Byron wallets, ordered from oldest to newest. - responses: *responsesListByronWallets - - /byron-wallets/{walletId}/assets: - get: - operationId: listByronAssets - tags: ["Byron Assets"] - summary: List Assets - description: | - List all assets associated with the wallet, and their metadata - if known. - - An asset is _associated_ with a wallet if it is involved in a - transaction of the wallet. - parameters: - - *parametersWalletId - responses: *responsesListAssets - - /byron-wallets/{walletId}/assets/{policyId}/{assetName}: - get: - operationId: getByronAsset - tags: ["Byron Assets"] - summary: Get Asset - description: | - Fetch a single asset from its `policy_id` and `asset_name`, - with its metadata if any. - - The asset must be associated with the wallet. - parameters: - - *parametersWalletId - - *parametersPolicyId - - *parametersAssetName - responses: *responsesGetAsset - - /byron-wallets/{walletId}/assets/{policyId}: - get: - operationId: getByronAssetDefault - tags: ["Byron Assets"] - summary: Get Asset (empty name) - description: | - Fetch the asset from `policy_id` with an empty name. - - The asset must be associated with the wallet. - parameters: - - *parametersWalletId - - *parametersPolicyId - responses: *responsesGetAsset - - /byron-wallets/{walletId}/statistics/utxos: - get: - operationId: getByronUTxOsStatistics - tags: ["Byron Wallets"] - summary: UTxO Statistics - description: | -

status: stable

- - Return the UTxO distribution across the whole wallet, in the form of a histogram. - - ``` - │ - 100 ─ - │ - │ ┌───┐ - 10 ─ ┌───┐ │ │ ┌───┐ - │ ┌───┐ │ │ │ │ │ │ - │ │ │ │ │ │ │ ┌───┐ │ │ - 1 ─ ┌───┐ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ │ │ │ │ │ │ ╷ │ │ ╷ │ │ ╷ ╷ │ │ - └─┘ └─│───────│─┘ └─│─┘ └─│─┘ └─│─┘ └─│───────│─┘ └──── - 10μ₳ 100μ₳ 1000μ₳ 0.1₳ 1₳ 10₳ 100₳ - ``` - parameters: - - *parametersWalletId - responses: *responsesGetUTxOsStatistics - - /byron-wallets/{walletId}/utxo: - get: - operationId: getByronWalletUtxoSnapshot - tags: ["Byron Wallets"] - summary: A snapshot of the wallet's UTxO set - description: | - Generate a snapshot of the wallet's UTxO set. - - This endpoint is intended for debugging purposes. - parameters: - - *parametersWalletId - responses: *responsesGetWalletUtxoSnapshot - - /byron-wallets/{walletId}: - get: - operationId: getByronWallet - tags: ["Byron Wallets"] - summary: Get - description: | -

status: stable

- - Return information about a Byron wallet. - parameters: - - *parametersWalletId - responses: *responsesGetByronWallet - - delete: - operationId: deleteByronWallet - tags: ["Byron Wallets"] - summary: Delete - description: | -

status: stable

- - Delete a Byron wallet. - parameters: - - *parametersWalletId - responses: *responsesDeleteWallet - - put: - operationId: putByronWallet - tags: ["Byron Wallets"] - summary: Update Metadata - description: | -

status: stable

- parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiWalletPutData - responses: *responsesPutWallet - - /byron-wallets/{walletId}/passphrase: - put: - operationId: putByronWalletPassphrase - tags: ["Byron Wallets"] - summary: Update Passphrase - description: | -

status: stable

- parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiByronWalletPutPassphraseData - responses: *responsesPutWalletPassphrase - - /byron-wallets/{walletId}/addresses: - post: - operationId: createAddress - tags: ["Byron Addresses"] - summary: Create Address - description: | -

status: stable

- - ⚠️ This endpoint is available for `random` wallets only. Any - attempt to call this endpoint on another type of wallet will result in - a `403 Forbidden` error from the server. - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiPostRandomAddressData - responses: *responsesPostRandomAddress - - get: - operationId: listByronAddresses - tags: ["Byron Addresses"] - summary: List - description: | -

status: stable

- - Return a list of known addresses, ordered from newest to oldest for sequential wallets. - Arbitrarily ordered for random wallets. - parameters: - - *parametersWalletId - - *parametersAddressState - responses: *responsesListAddresses - - put: - operationId: importAddresses - tags: ["Byron Addresses"] - summary: Import Addresses - description: | -

status: stable

- - ⚠️ This endpoint is available for `random` wallets only. Any - attempt to call this endpoint on another type of wallet will result in - a `403 Forbidden` error from the server. - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiPutAddressesData - responses: *responsesPutRandomAddresses - - /byron-wallets/{walletId}/addresses/{addressId}: - put: - operationId: importAddress - tags: ["Byron Addresses"] - summary: Import Address - description: | -

status: stable

- - ⚠️ This endpoint is available for `random` wallets only. Any - attempt to call this endpoint on another type of wallet will result in - a `403 Forbidden` error from the server. - parameters: - - *parametersWalletId - - *parametersAddressId - responses: *responsesPutRandomAddress - - /byron-wallets/{walletId}/payment-fees: - post: - operationId: postByronTransactionFee - tags: ["Byron Transactions"] - summary: Estimate Fee - # ADP-908 - Deprecated soon - deprecated: false - description: | -

status: stable

- - Estimate fee for the transaction. - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiPostTransactionFeeDataByron - responses: *responsesPostTransactionFee - - /byron-wallets/{walletId}/transactions: - post: - operationId: postByronTransaction - tags: ["Byron Transactions"] - summary: Create - description: | -

status: stable

- - Create and send transaction from the wallet. - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiPostTransactionDataByron - responses: *responsesPostTransaction - - get: - operationId: listByronTransactions - tags: ["Byron Transactions"] - summary: List - description: | -

status: stable

- - List all incoming and outgoing transactions for the given wallet. - parameters: - - *parametersWalletId - - *parametersStartDate - - *parametersEndDate - - *parametersSortOrder - - *parametersMaxCount - - *parametersAddress - responses: *responsesListTransactions - - /byron-wallets/{walletId}/transactions/{transactionId}: - get: - operationId: getByronTransaction - tags: ["Byron Transactions"] - summary: Get - description: | -

status: stable

- - Get transaction by id. - parameters: - - *parametersWalletId - - *parametersTransactionId - responses: *responsesGetTransaction - - delete: - operationId: deleteByronTransaction - tags: ["Byron Transactions"] - summary: Forget - description: | -

status: stable

- - Forget pending Byron transaction. Importantly, a transaction, when sent, - cannot be cancelled. One can only request forgetting about it - in order to try spending (concurrently) the same UTxO in another - transaction. But, the transaction may still show up later in a block - and therefore, appear in the wallet. - parameters: - - *parametersWalletId - - *parametersTransactionId - responses: *responsesDeleteTransaction - - /byron-wallets/{walletId}/coin-selections/random: - post: - operationId: byronSelectCoins - tags: ["Byron Coin Selections"] - summary: Random - description: | -

status: stable

- - Select coins to cover the given set of payments. - - Uses the - Random-Improve coin selection algorithm. - - Note: Not supported for Byron random wallets. - - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiByronSelectCoinsData - responses: *responsesSelectCoins - - /byron-wallets/{walletId}/migrations: - post: - operationId: migrateByronWallet - tags: ["Byron Migrations"] - summary: Migrate - description: | - Migrate the UTxO balance of this wallet to the given set of addresses. - - This operation will attempt to transfer as much of the wallet's balance - as possible to the given set of addresses, by creating and submitting - as many transactions as may be necessary to migrate the entire balance. - - In order to minimize the total transaction fee required, UTxO entries - are coalesced together to the greatest extent possible in the resulting - transactions. No attempt is made to preserve the wallet's UTxO - distribution. - - This operation is performed on a best-effort basis. If there is - insufficient ada available to pay for the entire UTxO set to be - migrated, then only a subset of the wallet's UTxO set will be migrated. - - A typical use of this operation would be to move all funds from an old - wallet to a new wallet, by providing addresses that belong to the new - wallet. - parameters: - - <<: *parametersWalletId - name: walletId - requestBody: - required: true - content: - application/json: - schema: *ApiByronWalletMigrationPostData - responses: *responsesMigrateWallet - - /byron-wallets/{walletId}/migrations/plan: - post: - operationId: createByronWalletMigrationPlan - tags: ["Byron Migrations"] - summary: Create a migration plan - description: | - Generate a plan for migrating the UTxO balance of this wallet to - another wallet, without executing the plan. - - This operation generates a plan that transfers as much of the wallet's - balance as possible, by creating as many selections as may be necessary - to migrate the entire balance. Each selection created is the basis for - a transaction. - - In order to minimize the total transaction fee required, UTxO entries - are coalesced together to the greatest extent possible in the resulting - selections. No attempt is made to preserve the wallet's UTxO - distribution. - - The plan is generated on a best-effort basis. If there is insufficient - ada available to pay for the entire UTxO set to be migrated, then only - a subset of the wallet's UTxO set will be included in the resultant - plan. - parameters: - - <<: *parametersWalletId - name: walletId - requestBody: - required: true - content: - application/json: - schema: *ApiWalletMigrationPlanPostData - responses: *responsesCreateWalletMigrationPlan - - /network/information: - get: - operationId: getNetworkInformation - tags: ["Network"] - summary: Information - description: | -

status: stable

- responses: *responsesGetNetworkInformation - - /network/clock: - get: - operationId: getNetworkClock - tags: ["Network"] - summary: Clock - description: | -

status: stable

- parameters: - - <<: *parametersForceNtpCheck - name: forceNtpCheck - responses: *responsesGetNetworkClock - - /network/parameters: - get: - operationId: getNetworkParameters - tags: ["Network"] - summary: Parameters - description: | -

status: stable

- - Returns the set of network parameters for the current epoch. - responses: *responsesGetNetworkParameters - - /proxy/transactions: - post: - operationId: postExternalTransaction - tags: ["Proxy"] - summary: Submit External Transaction - # ADP-908 - deprecated soon - deprecated: false - description: | -

status: stable

- - Submits a transaction that was created and signed outside of cardano-wallet. - - NOTE: Unlike the `submitTransaction` endpoint, there are no - guarantees that a transaction accepted by this endpoint will - actually be included in the chain. It's up to the caller to - retry submission until the transaction is confirmed. - requestBody: - content: - application/octet-stream: - schema: *signedTransactionBlob - responses: *responsesPostExternalTransaction - - /addresses/{addressId}: - get: - operationId: inspectAddress - tags: ["Addresses"] - summary: Inspect Address - description: | -

status: stable

- - Give useful information about the structure of a given address. - parameters: - - *parametersAddressId - responses: *responsesInspectAddress - - /addresses: - post: - operationId: postAnyAddress - tags: ["Addresses"] - summary: Construct Address - description: | -

status: stable

- - Construct any address by specyfying credential for payment or delegation. - - In Cardano, Addresses are made of three parts: - - ``` - *---------*---------*-----------* - | NETWORK | PAYMENT | DELEGATION | - *---------*---------*-----------* - ``` - - The `NETWORK` part allows for distinguishing addresses between different networks like the mainnet or the testnet. It is implicitly - handled by the server without you having to worry about it. The `PAYMENT` and `DELEGATION` parts however can be constructed similarly, using - either: - - - A public key - - A script - - The script itself is either constructed out of a public key, one of two timelocks, or one of the three following primitives: - - - all - - any - - some - - The timelock can determine validity as respect to the slot. `active_from slot` means the script is valid from the specified slot - and onward. `active_until slot` means the script is valid until (not included) the specified slot. - - Each of which contains one or more script(s) that can be either keys or primitives, and so on. Schematically: - - ``` - ┏─────────┓ - SCRIPT = ──┬───────────────────────┤ pub key ├─────────────────────┬── - │ ┗─────────┛ │ - │ ┏──────────────────┓ │ - ├───────────────────────┤ ACTIVE_FROM slot ├──── ───────┤ - │ ┗──────────────────┛ │ - │ ┏───────────────────┓ │ - ├───────────────────────┤ ACTIVE_UNTIL slot ├───────────┤ - │ ┗───────────────────┛ │ - │ │ - │ ╭─────╮ ╭────────╮ │ - ├──┤ ALL ├───┤ SCRIPT ├─┬───────────────────────────────┤ - │ ╰─────╯ ^ ╰────────╯ │ │ - │ │ ╭───╮ │ │ - │ └───┤ , ├────┘ │ - │ ╰───╯ │ - │ ╭─────╮ ╭────────╮ │ - ├──┤ ANY ├───┤ SCRIPT ├─┬───────────────────────────────┤ - │ ╰─────╯ ^ ╰────────╯ │ │ - │ │ ╭───╮ │ │ - │ └───┤ , ├────┘ │ - │ ╰───╯ │ - │ ╭──────╮ ╭──────────╮ ┏───┓ ╭──────╮ ╭────────╮ │ - └──┤ SOME ├─┤ AT_LEAST ├─┤ n ├─┤ FROM ├───┤ SCRIPT ├─┬──┘ - ╰──────╯ ╰──────────╯ ┗───┛ ╰──────╯ ^ ╰────────╯ │ - │ ╭───╮ │ - └───┤ , ├────┘ - ╰───╯ - ``` - - requestBody: - content: - application/json: - schema: *ApiAddressData - responses: *responsesPostAnyAddress - - /settings: - put: - operationId: putSettings - tags: ["Settings"] - summary: Update settings - description: | -

status: stable

- - Overwrite current settings. - requestBody: - required: true - content: - application/json: - schema: *ApiSettingsPutData - responses: *responsesPutSettings - - get: - operationId: getSettings - tags: ["Settings"] - summary: Get settings - description: | -

status: stable

- - Return the current settings. - responses: *responsesGetSettings - - /smash/health: - get: - operationId: getCurrentSmashHealth - tags: ["Utils"] - summary: Current SMASH health - description: | - Get health status of the currently active SMASH server. - parameters: - - in: query - name: url - schema: *ApiSmashServer - required: false - description: check this url for health instead of the currently configured one - responses: *responsesGetSmashHealth - - /shared-wallets: - post: - operationId: postSharedWallet - tags: ["Shared Wallets"] - summary: Create - description: | -

status: stable

- Create a shared wallet from either an account public key and script - templates or mnemonic and script templates. - - requestBody: - required: true - content: - application/json: - schema: *ApiSharedWalletPostData - responses: *responsesPostSharedWallet - - get: - operationId: listSharedWallets - tags: ["Shared Wallets"] - summary: List - description: | -

status: stable

- - Return a list of known shared wallets, ordered from oldest to newest. - responses: *responsesListSharedWallets - - /shared-wallets/{walletId}: - get: - operationId: getSharedWallet - tags: ["Shared Wallets"] - summary: Get - description: | -

status: stable

- Get a shared wallet for a given wallet id. - - parameters: - - *parametersWalletId - responses: *responsesGetSharedWallet - - delete: - operationId: deleteSharedWallet - tags: ["Shared Wallets"] - summary: Delete - description: | -

status: stable

- parameters: - - *parametersWalletId - responses: *responsesDeleteWallet - - put: - operationId: putSharedWallet - tags: ["Shared Wallets"] - summary: Update Metadata - description: | -

status: stable

- parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiWalletPutDataExtended - responses: *responsesPutSharedWallet - - /shared-wallets/{walletId}/statistics/utxos: - get: - operationId: getUTxOsStatisticsShared - tags: ["Shared Wallets"] - summary: UTxO Statistics - description: | -

status: stable

- - Return the UTxO distribution across the whole wallet, in the form of a histogram. - - ``` - │ - 100 ─ - │ - │ ┌───┐ - 10 ─ ┌───┐ │ │ ┌───┐ - │ ┌───┐ │ │ │ │ │ │ - │ │ │ │ │ │ │ ┌───┐ │ │ - 1 ─ ┌───┐ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ │ │ │ │ │ │ │ │ ╷ │ │ ╷ │ │ ╷ ╷ │ │ - └─┘ └─│───────│─┘ └─│─┘ └─│─┘ └─│─┘ └─│───────│─┘ └──── - 10μ₳ 100μ₳ 1000μ₳ 0.1₳ 1₳ 10₳ 100₳ - ``` - parameters: - - *parametersWalletId - responses: *responsesGetUTxOsStatistics - - /shared-wallets/{walletId}/utxo: - get: - operationId: getSharedWalletUtxoSnapshot - tags: ["Shared Wallets"] - summary: A snapshot of the wallet's UTxO set - description: | - Generate a snapshot of the wallet's UTxO set. - - This endpoint is intended for debugging purposes. - parameters: - - *parametersWalletId - responses: *responsesGetWalletUtxoSnapshot - - /shared-wallets/{walletId}/payment-script-template: - patch: - operationId: patchSharedWalletInPayment - tags: ["Shared Wallets"] - summary: Update Payment - description: | -

status: stable

- Update payment script template for a given shared wallet by - updating/adding account public key for cosigner. Updating the - shared wallet account key results in an error. Also updating is - enabled only for incomplete shared wallet, ie., the wallet that has - a missing account public key for any cosigner. - - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiSharedWalletPatchData - responses: *responsesPatchSharedWallet - - /shared-wallets/{walletId}/delegation-script-template: - patch: - operationId: patchSharedWalletInDelegation - tags: ["Shared Wallets"] - summary: Update Delegation - description: | -

status: stable

- Update delegation script template for a given shared wallet by - updating/adding account public key for cosigner. Updating the - shared wallet account key results in an error. Also updating is - enabled only for incomplete shared wallet, ie., the wallet that has - a missing account public key for any cosigner. - - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiSharedWalletPatchData - responses: *responsesPatchSharedWallet - - /shared-wallets/{walletId}/transactions-construct: - post: - operationId: constructSharedTransaction - tags: ["Shared Transactions"] - summary: Construct - description: | -

status: stable

- - Create a transaction to be signed from the shared wallet. - - Works for the following fields: - - payments - - metadata - - validity_interval - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiConstructTransactionData - responses: *responsesConstructTransaction - - /shared-wallets/{walletId}/transactions-decode: - post: - operationId: decodeSharedTransaction - tags: ["Shared Transactions"] - summary: Decode - description: | -

status: stable

- - Decode a serialized transaction, either freshly constructed, - partially signed or fully-signed. - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiDecodeTransactionPostData - responses: *responsesDecodedTransaction - - /shared-wallets/{walletId}/transactions-sign: - post: - operationId: signSharedTransaction - tags: ["Shared Transactions"] - summary: Sign - description: | -

status: stable

- - Signs a serialised transaction, returning the modified - transaction. - - This endpoint will add new witnesses using the keys available - to this wallet. Any existing witnesses will remain in the - witness set. - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiSignTransactionPostData - responses: *responsesSignTransaction - - /shared-wallets/{walletId}/transactions-submit: - post: - operationId: submitSharedTransaction - tags: ["Shared Transactions"] - summary: Submit - description: | -

status: stable

- Submit a transaction that was already created and fully signed. - Fails for foreign transactions that is transactions which lack - the wallet's inputs and withdrawals. - parameters: - - *parametersWalletId - requestBody: - required: true - content: - application/json: - schema: *ApiSignedTransactionEncoded - responses: *responsesPostExternalTransaction - - /shared-wallets/{walletId}/transactions: - get: - operationId: listSharedTransactions - tags: ["Shared Transactions"] - summary: List - description: | -

status: stable

- - Lists all incoming and outgoing wallet's transactions. - parameters: - - *parametersWalletId - - *parametersStartDate - - *parametersEndDate - - *parametersSortOrder - - *parametersMaxCount - - *parametersMinWithdrawal - - *parametersMetadataFormat - - *parametersAddress - responses: *responsesListTransactions - - /shared-wallets/{walletId}/transactions/{transactionId}: - get: - operationId: getSharedTransaction - tags: ["Shared Transactions"] - summary: Get - description: | -

status: stable

- - Get transaction by id. - parameters: - - *parametersWalletId - - *parametersTransactionId - - *parametersMetadataFormat - responses: *responsesGetTransaction - - /shared-wallets/{walletId}/keys/{index}: - post: - operationId: postAccountKeyShared - tags: ["Shared Keys"] - summary: Create Account Public Key - description: | -

status: stable

- Derive an account public key for any account index. For this key derivation to be possible, - the wallet must have been created from mnemonic. - - Note: Only _Hardened_ indexes are supported by this endpoint. - parameters: - - *parametersWalletId - - *parametersDerivationSegment - requestBody: - required: true - content: - application/json: - schema: *ApiPostAccountKeyData - responses: *responsesPostAccountKeyShared - - /shared-wallets/{walletId}/keys: - get: - operationId: getAccountKeyShared - tags: ["Shared Keys"] - summary: Get Account Public Key - description: | -

status: stable

- Retrieve the account public key of this shared wallet. - - To get an extended public key, instead of the public key, - use query parameter `format=extended`. For non-extended public key - use `format=non_extended` or omit query parameter. - - parameters: - - *parametersWalletId - responses: *responsesGetAccountSharedKey - - /shared-wallets/{walletId}/keys/{role}/{index}: - get: - operationId: getSharedWalletKey - tags: ["Shared Keys"] - summary: Get Public Key - description: | -

status: stable

- Return a public key for a given role and derivation index for - a shared wallet. - - To get a hash of the public key, instead of the public key, - use query parameter `hash=true`. - - Note: Only `Soft` indexes are supported by this endpoint. - parameters: - - *parametersWalletId - - *parametersRole - - *parametersDerivationSegment - - *parametersDerivationHash - responses: *responsesGetSharedKey - - /shared-wallets/{walletId}/addresses: - get: - operationId: listSharedAddresses - tags: ["Shared Addresses"] - summary: List - description: | -

status: stable

- - Return a list of known addresses, ordered from newest to oldest - parameters: - - *parametersWalletId - - *parametersAddressState - responses: *responsesListAddresses - - /blocks/latest/header: - get: - operationId: getBlocksLatestHeader - tags: ["Node"] - summary: Block Header - description: | -

status: stable

- - Return the latest block-header available at the chain source - responses: - <<: *responsesErr406 - 200: - description: OK - content: - application/json: - schema: *ApiBlockHeader \ No newline at end of file From ada8d2d73e8551f6a1801070385720c457c87ab0 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Tue, 31 Mar 2026 13:15:29 +0300 Subject: [PATCH 11/19] =?UTF-8?q?bump:=20yaml=20and=20yaml3=20to=20v0.0.4?= =?UTF-8?q?=20=E2=80=94=20preserve=20=5F=5Forigin=5F=5F=20in=20alias-expan?= =?UTF-8?q?ded=20mappings?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- go.mod | 4 ++-- go.sum | 12 ++++-------- 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/go.mod b/go.mod index 1c9053614..63907a1ac 100644 --- a/go.mod +++ b/go.mod @@ -6,8 +6,8 @@ require ( github.com/go-openapi/jsonpointer v0.21.0 github.com/gorilla/mux v1.8.0 github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 - github.com/oasdiff/yaml v0.0.3 - github.com/oasdiff/yaml3 v0.0.3 + github.com/oasdiff/yaml v0.0.4 + github.com/oasdiff/yaml3 v0.0.4 github.com/perimeterx/marshmallow v1.1.5 github.com/stretchr/testify v1.9.0 github.com/woodsbury/decimal128 v1.3.0 diff --git a/go.sum b/go.sum index 00c494ca7..50d05a537 100644 --- a/go.sum +++ b/go.sum @@ -18,14 +18,10 @@ github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0 github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc= github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 h1:RWengNIwukTxcDr9M+97sNutRR1RKhG96O6jWumTTnw= github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826/go.mod h1:TaXosZuwdSHYgviHp1DAtfrULt5eUgsSMsZf+YrPgl8= -github.com/oasdiff/yaml v0.0.2 h1:sKQkI6JmuBgie+7geGJGbYvRaMoLIk4NqPgbXxOnunM= -github.com/oasdiff/yaml v0.0.2/go.mod h1:rKaD4gBtiSjZLsrvo4vw3YR8aR8vKeAAkysJI3d8tdo= -github.com/oasdiff/yaml v0.0.3 h1:IORGNY4IZ1+SKFSUuu288zE/33JYxx0FWp3ZTqn+Hdc= -github.com/oasdiff/yaml v0.0.3/go.mod h1:cGJc1tLIzdmJs4PPPJsLHDh2j1bEgJLDyZ02wyp5tvg= -github.com/oasdiff/yaml3 v0.0.2 h1:KAbH+Qi4aT7PQbG4AASP25Yob3u+VyAVjLrTHaR/FOE= -github.com/oasdiff/yaml3 v0.0.2/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= -github.com/oasdiff/yaml3 v0.0.3 h1:AoDWNMgx8ND5gmaxeUSX4LjrlxrYB6CGzKdVi/1zAPQ= -github.com/oasdiff/yaml3 v0.0.3/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= +github.com/oasdiff/yaml v0.0.4 h1:airPco4LbUoK4nbVwu+wwkRg2WarLC96cgBhgN93fsE= +github.com/oasdiff/yaml v0.0.4/go.mod h1:EaJ6/lcrRLK+syawtvtrHdbrrln4/SUmQw6aBTIlaMs= +github.com/oasdiff/yaml3 v0.0.4 h1:U5RTQZpBmsbcyCFlzPVuMctk6Jme6lOrbl0jJoOovMw= +github.com/oasdiff/yaml3 v0.0.4/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= github.com/perimeterx/marshmallow v1.1.5 h1:a2LALqQ1BlHM8PZblsDdidgv1mWi1DgC2UmX50IvK2s= github.com/perimeterx/marshmallow v1.1.5/go.mod h1:dsXbUu8CRzfYP5a87xpp0xq9S3u0Vchtcl8we9tYaXw= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= From d0253c3b7c6ab8e90e17054587b0a3aad6e642dd Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Tue, 31 Mar 2026 14:12:02 +0300 Subject: [PATCH 12/19] fix: strip __origin__ from extension values to prevent spurious diffs Extension values are map[string]any, so the YAML decoder injects __origin__ into them. Without stripping it, two specs loaded from different file paths produce different extension values, causing spurious diffs. Call stripExtensionsOrigin after delete(Extensions, originKey) in all 21 UnmarshalJSON implementations, including the root T type. Co-Authored-By: Claude Sonnet 4.6 --- openapi3/components.go | 1 + openapi3/contact.go | 1 + openapi3/discriminator.go | 1 + openapi3/encoding.go | 1 + openapi3/example.go | 1 + openapi3/external_docs.go | 1 + openapi3/info.go | 1 + openapi3/license.go | 1 + openapi3/link.go | 1 + openapi3/media_type.go | 1 + openapi3/openapi3.go | 2 ++ openapi3/operation.go | 1 + openapi3/origin.go | 10 +++++++ openapi3/origin_test.go | 33 ++++++++++++++++++++++++ openapi3/parameter.go | 1 + openapi3/path_item.go | 1 + openapi3/request_body.go | 1 + openapi3/response.go | 1 + openapi3/schema.go | 1 + openapi3/security_scheme.go | 3 +++ openapi3/server.go | 2 ++ openapi3/tag.go | 1 + openapi3/testdata/origin/extensions.yaml | 10 +++++++ openapi3/xml.go | 1 + 24 files changed, 78 insertions(+) create mode 100644 openapi3/testdata/origin/extensions.yaml diff --git a/openapi3/components.go b/openapi3/components.go index 890671aa7..eac75ab4a 100644 --- a/openapi3/components.go +++ b/openapi3/components.go @@ -96,6 +96,7 @@ func (components *Components) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "schemas") delete(x.Extensions, "parameters") delete(x.Extensions, "headers") diff --git a/openapi3/contact.go b/openapi3/contact.go index 2ade3c68c..241ea0ef9 100644 --- a/openapi3/contact.go +++ b/openapi3/contact.go @@ -53,6 +53,7 @@ func (contact *Contact) UnmarshalJSON(data []byte) error { _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "name") delete(x.Extensions, "url") delete(x.Extensions, "email") diff --git a/openapi3/discriminator.go b/openapi3/discriminator.go index faf53dcd3..90fc3b228 100644 --- a/openapi3/discriminator.go +++ b/openapi3/discriminator.go @@ -61,6 +61,7 @@ func (discriminator *Discriminator) UnmarshalJSON(data []byte) error { _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "propertyName") delete(x.Extensions, "mapping") if len(x.Extensions) == 0 { diff --git a/openapi3/encoding.go b/openapi3/encoding.go index a6d849925..2cab939a4 100644 --- a/openapi3/encoding.go +++ b/openapi3/encoding.go @@ -92,6 +92,7 @@ func (encoding *Encoding) UnmarshalJSON(data []byte) error { _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "contentType") delete(x.Extensions, "headers") delete(x.Extensions, "style") diff --git a/openapi3/example.go b/openapi3/example.go index 5dde01788..884a21e19 100644 --- a/openapi3/example.go +++ b/openapi3/example.go @@ -61,6 +61,7 @@ func (example *Example) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "summary") delete(x.Extensions, "description") delete(x.Extensions, "value") diff --git a/openapi3/external_docs.go b/openapi3/external_docs.go index 7ff435ff6..2c082b1ff 100644 --- a/openapi3/external_docs.go +++ b/openapi3/external_docs.go @@ -51,6 +51,7 @@ func (e *ExternalDocs) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "description") delete(x.Extensions, "url") if len(x.Extensions) == 0 { diff --git a/openapi3/info.go b/openapi3/info.go index ed5710e04..31ff91814 100644 --- a/openapi3/info.go +++ b/openapi3/info.go @@ -64,6 +64,7 @@ func (info *Info) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "title") delete(x.Extensions, "description") delete(x.Extensions, "termsOfService") diff --git a/openapi3/license.go b/openapi3/license.go index eb47fc385..440b3d762 100644 --- a/openapi3/license.go +++ b/openapi3/license.go @@ -47,6 +47,7 @@ func (license *License) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "name") delete(x.Extensions, "url") if len(x.Extensions) == 0 { diff --git a/openapi3/link.go b/openapi3/link.go index 483750cac..54694d949 100644 --- a/openapi3/link.go +++ b/openapi3/link.go @@ -69,6 +69,7 @@ func (link *Link) UnmarshalJSON(data []byte) error { _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "operationRef") delete(x.Extensions, "operationId") delete(x.Extensions, "description") diff --git a/openapi3/media_type.go b/openapi3/media_type.go index 92e92e4e9..c0edcf9c1 100644 --- a/openapi3/media_type.go +++ b/openapi3/media_type.go @@ -103,6 +103,7 @@ func (mediaType *MediaType) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "schema") delete(x.Extensions, "example") delete(x.Extensions, "examples") diff --git a/openapi3/openapi3.go b/openapi3/openapi3.go index ed8a016c5..77ebe494c 100644 --- a/openapi3/openapi3.go +++ b/openapi3/openapi3.go @@ -116,6 +116,8 @@ func (doc *T) UnmarshalJSON(data []byte) error { delete(x.Extensions, "servers") delete(x.Extensions, "tags") delete(x.Extensions, "externalDocs") + delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) if len(x.Extensions) == 0 { x.Extensions = nil } diff --git a/openapi3/operation.go b/openapi3/operation.go index f32836e68..dd10405b5 100644 --- a/openapi3/operation.go +++ b/openapi3/operation.go @@ -118,6 +118,7 @@ func (operation *Operation) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "tags") delete(x.Extensions, "summary") delete(x.Extensions, "description") diff --git a/openapi3/origin.go b/openapi3/origin.go index dbddbe675..ea0ae15fa 100644 --- a/openapi3/origin.go +++ b/openapi3/origin.go @@ -42,3 +42,13 @@ func stripOriginFromAny(v any) any { return v } } + +// stripExtensionsOrigin removes __origin__ from every value in an extensions +// map. Extension values are any-typed objects, so the YAML decoder injects +// __origin__ into them. Without stripping it, two specs loaded from different +// file paths would report spurious diffs in their extension values. +func stripExtensionsOrigin(ext map[string]any) { + for k, v := range ext { + ext[k] = stripOriginFromAny(v) + } +} diff --git a/openapi3/origin_test.go b/openapi3/origin_test.go index 79fcdad01..84a28d318 100644 --- a/openapi3/origin_test.go +++ b/openapi3/origin_test.go @@ -517,6 +517,39 @@ components: line 0: mapping key "__origin__" already defined at line 17`, err.Error()) } +// TestOrigin_ExtensionValuesStripped verifies that __origin__ metadata injected +// by the YAML decoder is not present in any-typed extension values. +// Regression test: extension values that are YAML objects received __origin__ +// from the yaml3 decoder but it was never stripped, causing spurious diffs +// between specs loaded from different file paths. +func TestOrigin_ExtensionValuesStripped(t *testing.T) { + loader := NewLoader() + + IncludeOrigin = true + defer unsetIncludeOrigin() + + doc, err := loader.LoadFromFile("testdata/origin/extensions.yaml") + require.NoError(t, err) + + val, ok := doc.Extensions["x-object-extension"] + require.True(t, ok, "x-object-extension must be present") + + m, ok := val.(map[string]any) + require.True(t, ok, "x-object-extension value must be a map") + + require.NotContains(t, m, originKey, "__origin__ must be stripped from extension object values") + + // Also verify stripping works for a nested type (Info), covering the 20 + // per-type UnmarshalJSON call sites with a single representative case. + infoVal, ok := doc.Info.Extensions["x-info-extension"] + require.True(t, ok, "x-info-extension must be present") + + infoMap, ok := infoVal.(map[string]any) + require.True(t, ok, "x-info-extension value must be a map") + + require.NotContains(t, infoMap, originKey, "__origin__ must be stripped from nested extension object values") +} + func TestOrigin_WithExternalRef(t *testing.T) { loader := NewLoader() loader.IsExternalRefsAllowed = true diff --git a/openapi3/parameter.go b/openapi3/parameter.go index ceea1f2e0..363094e5b 100644 --- a/openapi3/parameter.go +++ b/openapi3/parameter.go @@ -218,6 +218,7 @@ func (parameter *Parameter) UnmarshalJSON(data []byte) error { _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "name") delete(x.Extensions, "in") delete(x.Extensions, "description") diff --git a/openapi3/path_item.go b/openapi3/path_item.go index 983978616..8f8da8fb7 100644 --- a/openapi3/path_item.go +++ b/openapi3/path_item.go @@ -100,6 +100,7 @@ func (pathItem *PathItem) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "$ref") delete(x.Extensions, "summary") delete(x.Extensions, "description") diff --git a/openapi3/request_body.go b/openapi3/request_body.go index 6c15ba051..e82f678bc 100644 --- a/openapi3/request_body.go +++ b/openapi3/request_body.go @@ -110,6 +110,7 @@ func (requestBody *RequestBody) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "description") delete(x.Extensions, "required") delete(x.Extensions, "content") diff --git a/openapi3/response.go b/openapi3/response.go index b87324a28..786726208 100644 --- a/openapi3/response.go +++ b/openapi3/response.go @@ -174,6 +174,7 @@ func (response *Response) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "description") delete(x.Extensions, "headers") delete(x.Extensions, "content") diff --git a/openapi3/schema.go b/openapi3/schema.go index 954c4c144..f90345cde 100644 --- a/openapi3/schema.go +++ b/openapi3/schema.go @@ -414,6 +414,7 @@ func (schema *Schema) UnmarshalJSON(data []byte) error { _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "oneOf") delete(x.Extensions, "anyOf") delete(x.Extensions, "allOf") diff --git a/openapi3/security_scheme.go b/openapi3/security_scheme.go index b874ccaec..cb0fc86a6 100644 --- a/openapi3/security_scheme.go +++ b/openapi3/security_scheme.go @@ -102,6 +102,7 @@ func (ss *SecurityScheme) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "type") delete(x.Extensions, "description") delete(x.Extensions, "name") @@ -274,6 +275,7 @@ func (flows *OAuthFlows) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "implicit") delete(x.Extensions, "password") delete(x.Extensions, "clientCredentials") @@ -366,6 +368,7 @@ func (flow *OAuthFlow) UnmarshalJSON(data []byte) error { _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "authorizationUrl") delete(x.Extensions, "tokenUrl") delete(x.Extensions, "refreshUrl") diff --git a/openapi3/server.go b/openapi3/server.go index 9415cb23c..40c8464f8 100644 --- a/openapi3/server.go +++ b/openapi3/server.go @@ -116,6 +116,7 @@ func (server *Server) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "url") delete(x.Extensions, "description") delete(x.Extensions, "variables") @@ -288,6 +289,7 @@ func (serverVariable *ServerVariable) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "enum") delete(x.Extensions, "default") delete(x.Extensions, "description") diff --git a/openapi3/tag.go b/openapi3/tag.go index 841161ec0..401893936 100644 --- a/openapi3/tag.go +++ b/openapi3/tag.go @@ -77,6 +77,7 @@ func (t *Tag) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "name") delete(x.Extensions, "description") delete(x.Extensions, "externalDocs") diff --git a/openapi3/testdata/origin/extensions.yaml b/openapi3/testdata/origin/extensions.yaml new file mode 100644 index 000000000..769e09a24 --- /dev/null +++ b/openapi3/testdata/origin/extensions.yaml @@ -0,0 +1,10 @@ +openapi: 3.0.1 +info: + title: Test API + version: v1 + x-info-extension: + env: staging +x-object-extension: + foo: bar + count: 42 +paths: {} diff --git a/openapi3/xml.go b/openapi3/xml.go index e960249d3..543b32def 100644 --- a/openapi3/xml.go +++ b/openapi3/xml.go @@ -60,6 +60,7 @@ func (xml *XML) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) delete(x.Extensions, originKey) + stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "name") delete(x.Extensions, "namespace") delete(x.Extensions, "prefix") From a34d0de371c1387951222f384581ddacbbdae14e Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Thu, 2 Apr 2026 11:51:34 +0300 Subject: [PATCH 13/19] =?UTF-8?q?fix:=20move=20IncludeOrigin=20to=20Loader?= =?UTF-8?q?=20field=20=E2=80=94=20eliminates=20concurrent-request=20race?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The package-level IncludeOrigin global was set without cleanup in HTTP handlers, permanently contaminating all subsequent requests on the same process. Add Loader.IncludeOrigin as the safe per-loader alternative; each unmarshal call ORs it with the global for backward compatibility. Co-Authored-By: Claude Sonnet 4.6 --- go.mod | 2 +- go.sum | 4 +- openapi3/loader.go | 22 +++-- openapi3/marsh.go | 6 +- openapi3/origin.go | 214 +++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 236 insertions(+), 12 deletions(-) diff --git a/go.mod b/go.mod index 63907a1ac..746a0c3a1 100644 --- a/go.mod +++ b/go.mod @@ -6,7 +6,7 @@ require ( github.com/go-openapi/jsonpointer v0.21.0 github.com/gorilla/mux v1.8.0 github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 - github.com/oasdiff/yaml v0.0.4 + github.com/oasdiff/yaml v0.0.5-beta.1 github.com/oasdiff/yaml3 v0.0.4 github.com/perimeterx/marshmallow v1.1.5 github.com/stretchr/testify v1.9.0 diff --git a/go.sum b/go.sum index 50d05a537..eaf674e67 100644 --- a/go.sum +++ b/go.sum @@ -18,8 +18,8 @@ github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0 github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc= github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 h1:RWengNIwukTxcDr9M+97sNutRR1RKhG96O6jWumTTnw= github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826/go.mod h1:TaXosZuwdSHYgviHp1DAtfrULt5eUgsSMsZf+YrPgl8= -github.com/oasdiff/yaml v0.0.4 h1:airPco4LbUoK4nbVwu+wwkRg2WarLC96cgBhgN93fsE= -github.com/oasdiff/yaml v0.0.4/go.mod h1:EaJ6/lcrRLK+syawtvtrHdbrrln4/SUmQw6aBTIlaMs= +github.com/oasdiff/yaml v0.0.5-beta.1 h1:xCTUYEOtU5qqX3rYm2T0W5Wf60VVEvWw6RUYR2W54NI= +github.com/oasdiff/yaml v0.0.5-beta.1/go.mod h1:EaJ6/lcrRLK+syawtvtrHdbrrln4/SUmQw6aBTIlaMs= github.com/oasdiff/yaml3 v0.0.4 h1:U5RTQZpBmsbcyCFlzPVuMctk6Jme6lOrbl0jJoOovMw= github.com/oasdiff/yaml3 v0.0.4/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= github.com/perimeterx/marshmallow v1.1.5 h1:a2LALqQ1BlHM8PZblsDdidgv1mWi1DgC2UmX50IvK2s= diff --git a/openapi3/loader.go b/openapi3/loader.go index 1e9e648fd..714529a07 100644 --- a/openapi3/loader.go +++ b/openapi3/loader.go @@ -15,9 +15,9 @@ import ( "strings" ) -// IncludeOrigin specifies whether to include the origin of the OpenAPI elements -// Set this to true before loading a spec to include the origin of the OpenAPI elements -// Note it is global and affects all loaders +// IncludeOrigin specifies whether to include the origin of the OpenAPI elements. +// Deprecated: set Loader.IncludeOrigin instead. This global is read by NewLoader +// for backward compatibility but is not safe for concurrent use. var IncludeOrigin = false func foundUnresolvedRef(ref string) error { @@ -33,6 +33,11 @@ type Loader struct { // IsExternalRefsAllowed enables visiting other files IsExternalRefsAllowed bool + // IncludeOrigin enables recording the file/line/column of each OpenAPI element. + // Prefer this over the package-level IncludeOrigin global, which is not safe for + // concurrent use. + IncludeOrigin bool + // ReadFromURIFunc allows overriding the any file/URL reading func ReadFromURIFunc ReadFromURIFunc @@ -53,7 +58,8 @@ type Loader struct { // NewLoader returns an empty Loader func NewLoader() *Loader { return &Loader{ - Context: context.Background(), + Context: context.Background(), + IncludeOrigin: IncludeOrigin, } } @@ -108,7 +114,7 @@ func (loader *Loader) loadSingleElementFromURI(ref string, rootPath *url.URL, el if err != nil { return nil, err } - if err := unmarshal(data, element, IncludeOrigin, resolvedPath); err != nil { + if err := unmarshal(data, element, loader.IncludeOrigin || IncludeOrigin, resolvedPath); err != nil { return nil, err } @@ -144,7 +150,7 @@ func (loader *Loader) LoadFromIoReader(reader io.Reader) (*T, error) { func (loader *Loader) LoadFromData(data []byte) (*T, error) { loader.resetVisitedPathItemRefs() doc := &T{} - if err := unmarshal(data, doc, IncludeOrigin, nil); err != nil { + if err := unmarshal(data, doc, loader.IncludeOrigin || IncludeOrigin, nil); err != nil { return nil, err } if err := loader.ResolveRefsIn(doc, nil); err != nil { @@ -173,7 +179,7 @@ func (loader *Loader) loadFromDataWithPathInternal(data []byte, location *url.UR doc := &T{} loader.visitedDocuments[uri] = doc - if err := unmarshal(data, doc, IncludeOrigin, location); err != nil { + if err := unmarshal(data, doc, loader.IncludeOrigin || IncludeOrigin, location); err != nil { return nil, err } @@ -427,7 +433,7 @@ func (loader *Loader) resolveComponent(doc *T, ref string, path *url.URL, resolv if err2 != nil { return nil, nil, err } - if err2 = unmarshal(data, &cursor, IncludeOrigin, path); err2 != nil { + if err2 = unmarshal(data, &cursor, loader.IncludeOrigin || IncludeOrigin, path); err2 != nil { return nil, nil, err } if cursor, err2 = drill(cursor); err2 != nil || cursor == nil { diff --git a/openapi3/marsh.go b/openapi3/marsh.go index 0299a34a4..5686a3ae1 100644 --- a/openapi3/marsh.go +++ b/openapi3/marsh.go @@ -30,9 +30,13 @@ func unmarshal(data []byte, v any, includeOrigin bool, location *url.URL) error if location != nil { file = location.Path } - if yamlErr = yaml.UnmarshalWithOrigin(data, v, yaml.OriginOpt{Enabled: includeOrigin, File: file}); yamlErr == nil { + originOpt := yaml.OriginOpt{Enabled: includeOrigin, File: file} + tree, err := yaml.UnmarshalWithOriginTree(data, v, originOpt) + if err == nil { + applyOrigins(v, tree) return nil } + yamlErr = err // If both unmarshaling attempts fail, return a new error that includes both errors return fmt.Errorf("failed to unmarshal data: json error: %v, yaml error: %v", jsonErr, yamlErr) diff --git a/openapi3/origin.go b/openapi3/origin.go index ea0ae15fa..38e4d6c2f 100644 --- a/openapi3/origin.go +++ b/openapi3/origin.go @@ -1,7 +1,16 @@ package openapi3 +import ( + "reflect" + "strings" + + "github.com/oasdiff/yaml" +) + const originKey = "__origin__" +var originPtrType = reflect.TypeOf((*Origin)(nil)) + // Origin contains the origin of a collection. // Key is the location of the collection itself. // Fields is a map of the location of each scalar field in the collection. @@ -20,6 +29,211 @@ type Location struct { Name string `json:"name,omitempty" yaml:"name,omitempty"` } +// originFromMap converts a raw map[string]any (as extracted by yaml.extractOrigins) +// into an *Origin struct without a JSON round-trip. +func originFromMap(m map[string]any) *Origin { + if m == nil { + return nil + } + o := &Origin{} + if key, ok := m["key"].(map[string]any); ok { + loc := locationFromMap(key) + o.Key = &loc + } + if fields, ok := m["fields"].(map[string]any); ok { + o.Fields = make(map[string]Location, len(fields)) + for k, v := range fields { + if fm, ok := v.(map[string]any); ok { + o.Fields[k] = locationFromMap(fm) + } + } + } + if sequences, ok := m["sequences"].(map[string]any); ok { + o.Sequences = make(map[string][]Location, len(sequences)) + for k, v := range sequences { + if items, ok := v.([]any); ok { + locs := make([]Location, len(items)) + for i, item := range items { + if im, ok := item.(map[string]any); ok { + locs[i] = locationFromMap(im) + } + } + o.Sequences[k] = locs + } + } + } + return o +} + +func locationFromMap(m map[string]any) Location { + loc := Location{} + if v, ok := m["file"].(string); ok { + loc.File = v + } + if v, ok := m["line"]; ok { + switch n := v.(type) { + case int: + loc.Line = n + case uint64: + loc.Line = int(n) + } + } + if v, ok := m["column"]; ok { + switch n := v.(type) { + case int: + loc.Column = n + case uint64: + loc.Column = int(n) + } + } + if v, ok := m["name"].(string); ok { + loc.Name = v + } + return loc +} + +// applyOrigins walks a Go struct tree and a parallel OriginTree, setting +// Origin fields on each struct from the extracted origin data. +func applyOrigins(v any, tree *yaml.OriginTree) { + if tree == nil { + return + } + applyOriginsToValue(reflect.ValueOf(v), tree) +} + +func applyOriginsToValue(val reflect.Value, tree *yaml.OriginTree) { + // Keep track of the last pointer so we can pass it to struct handlers + // (needed for calling methods like Map() on maplike types). + var ptr reflect.Value + for val.Kind() == reflect.Ptr || val.Kind() == reflect.Interface { + if val.IsNil() { + return + } + if val.Kind() == reflect.Ptr { + ptr = val + } + val = val.Elem() + } + + switch val.Kind() { + case reflect.Struct: + applyOriginsToStruct(val, ptr, tree) + case reflect.Map: + applyOriginsToMap(val, tree) + case reflect.Slice: + applyOriginsToSlice(val, tree) + } +} + +func applyOriginsToStruct(val reflect.Value, ptr reflect.Value, tree *yaml.OriginTree) { + typ := val.Type() + + // Set Origin field if tagged with json:"__origin__" or json:"-" (maplike types). + // Skip *Ref types which have Origin with no json tag — those pass through to Value. + if tree.Origin != nil { + if sf, ok := typ.FieldByName("Origin"); ok && sf.Type == originPtrType { + tag := sf.Tag.Get("json") + if strings.Contains(tag, originKey) || tag == "-" { + if m, ok := tree.Origin.(map[string]any); ok { + val.FieldByName("Origin").Set(reflect.ValueOf(originFromMap(m))) + } + } + } + } + + // Recurse into exported struct fields using json tags + for i := 0; i < typ.NumField(); i++ { + sf := typ.Field(i) + if !sf.IsExported() { + continue + } + tag := jsonTagName(sf) + if tag == "" || tag == "-" { + continue + } + childTree := tree.Fields[tag] + if childTree != nil { + applyOriginsToValue(val.Field(i), childTree) + } + } + + // Handle wrapper types whose inner struct has no json tag: + // - *Ref types (e.g. SchemaRef, ResponseRef) have a "Value" field + // - AdditionalProperties has a "Schema" field + // The origin tree data applies to the inner struct, not a sub-key. + for _, fieldName := range []string{"Value", "Schema"} { + vf := val.FieldByName(fieldName) + if !vf.IsValid() || vf.Kind() != reflect.Ptr || vf.IsNil() { + continue + } + sf, _ := typ.FieldByName(fieldName) + if sf.Tag.Get("json") == "" { + applyOriginsToValue(vf, tree) + } + } + + // Handle "maplike" types (Paths, Responses, Callback) whose items are + // stored in an unexported map accessible via a Map() method. + // Use the original pointer (if available) since dereferenced values + // are not addressable. + receiver := val + if ptr.IsValid() { + receiver = ptr + } else if val.CanAddr() { + receiver = val.Addr() + } + if receiver.Kind() == reflect.Ptr { + if mapMethod := receiver.MethodByName("Map"); mapMethod.IsValid() { + results := mapMethod.Call(nil) + if len(results) == 1 { + applyOriginsToMap(results[0], tree) + } + } + } +} + +func applyOriginsToMap(val reflect.Value, tree *yaml.OriginTree) { + if tree.Fields == nil { + return + } + for _, key := range val.MapKeys() { + childTree := tree.Fields[key.String()] + if childTree == nil { + continue + } + elem := val.MapIndex(key) + // Map values are not addressable. For pointer-typed values we can + // recurse directly. For value types we must copy, apply, and set back. + if elem.Kind() == reflect.Ptr || elem.Kind() == reflect.Interface { + applyOriginsToValue(elem, childTree) + } else if elem.Kind() == reflect.Struct { + // Copy to a settable value + cp := reflect.New(elem.Type()).Elem() + cp.Set(elem) + applyOriginsToStruct(cp, reflect.Value{}, childTree) + val.SetMapIndex(key, cp) + } + } +} + +func applyOriginsToSlice(val reflect.Value, tree *yaml.OriginTree) { + for i := 0; i < val.Len() && i < len(tree.Items); i++ { + if tree.Items[i] != nil { + applyOriginsToValue(val.Index(i), tree.Items[i]) + } + } +} + +// jsonTagName returns the JSON field name from a struct field's json tag. +func jsonTagName(f reflect.StructField) string { + tag := f.Tag.Get("json") + if tag == "" { + return "" + } + name, _, _ := strings.Cut(tag, ",") + return name +} + // stripOriginFromAny recursively removes the __origin__ key from any // map[string]any value. This is needed for interface{}/any-typed fields // (e.g. Schema.Enum, Schema.Default, Parameter.Example) that have no From 498005a778d6ad887d647a8e693f31e9d54c8309 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Thu, 2 Apr 2026 12:36:39 +0300 Subject: [PATCH 14/19] feat: parse compact []any origin sequence format from yaml3 Replace originFromMap with originFromSeq to handle the new flat sequence format: [key_name, key_line, key_col, nf, f1_name, f1_delta, f1_col, ..., ns, s1_name, s1_count, ...]. File is now stored in OriginTree rather than repeated per location. Also extend the Value/Schema pass-through in applyOriginsToStruct to cover AdditionalProperties.Schema (no json tag), and add toInt helper for yaml int types (int vs uint64). Co-Authored-By: Claude Sonnet 4.6 --- openapi3/origin.go | 118 ++++++++++++++++++++++++++------------------- 1 file changed, 68 insertions(+), 50 deletions(-) diff --git a/openapi3/origin.go b/openapi3/origin.go index 38e4d6c2f..539c26cf3 100644 --- a/openapi3/origin.go +++ b/openapi3/origin.go @@ -29,67 +29,85 @@ type Location struct { Name string `json:"name,omitempty" yaml:"name,omitempty"` } -// originFromMap converts a raw map[string]any (as extracted by yaml.extractOrigins) -// into an *Origin struct without a JSON round-trip. -func originFromMap(m map[string]any) *Origin { - if m == nil { +// originFromSeq parses the compact []any sequence produced by yaml3's addOrigin. +// +// Format: [key_name, key_line, key_col, nf, f1_name, f1_delta, f1_col, ..., ns, s1_name, s1_count, s1_l0_delta, s1_c0, ...] +// +// file is the source file for all locations (stored in the OriginTree, not in the sequence). +func originFromSeq(s []any, file string) *Origin { + // Need at least: key_name, key_line, key_col, nf, ns + if len(s) < 5 { return nil } - o := &Origin{} - if key, ok := m["key"].(map[string]any); ok { - loc := locationFromMap(key) - o.Key = &loc + keyName, _ := s[0].(string) + keyLine := toInt(s[1]) + keyCol := toInt(s[2]) + + o := &Origin{ + Key: &Location{ + File: file, + Line: keyLine, + Column: keyCol, + Name: keyName, + }, } - if fields, ok := m["fields"].(map[string]any); ok { - o.Fields = make(map[string]Location, len(fields)) - for k, v := range fields { - if fm, ok := v.(map[string]any); ok { - o.Fields[k] = locationFromMap(fm) + + idx := 3 + nf := toInt(s[idx]) + idx++ + if nf > 0 && idx+nf*3 <= len(s) { + o.Fields = make(map[string]Location, nf) + for i := 0; i < nf; i++ { + fname, _ := s[idx].(string) + delta := toInt(s[idx+1]) + col := toInt(s[idx+2]) + o.Fields[fname] = Location{ + File: file, + Line: keyLine + delta, + Column: col, + Name: fname, } + idx += 3 } } - if sequences, ok := m["sequences"].(map[string]any); ok { - o.Sequences = make(map[string][]Location, len(sequences)) - for k, v := range sequences { - if items, ok := v.([]any); ok { - locs := make([]Location, len(items)) - for i, item := range items { - if im, ok := item.(map[string]any); ok { - locs[i] = locationFromMap(im) - } - } - o.Sequences[k] = locs + + if idx >= len(s) { + return o + } + ns := toInt(s[idx]) + idx++ + if ns > 0 { + o.Sequences = make(map[string][]Location, ns) + for i := 0; i < ns; i++ { + if idx >= len(s) { + break + } + sname, _ := s[idx].(string) + idx++ + count := toInt(s[idx]) + idx++ + locs := make([]Location, count) + for j := 0; j < count && idx+1 < len(s); j++ { + delta := toInt(s[idx]) + col := toInt(s[idx+1]) + locs[j] = Location{File: file, Line: keyLine + delta, Column: col} + idx += 2 } + o.Sequences[sname] = locs } } return o } -func locationFromMap(m map[string]any) Location { - loc := Location{} - if v, ok := m["file"].(string); ok { - loc.File = v - } - if v, ok := m["line"]; ok { - switch n := v.(type) { - case int: - loc.Line = n - case uint64: - loc.Line = int(n) - } - } - if v, ok := m["column"]; ok { - switch n := v.(type) { - case int: - loc.Column = n - case uint64: - loc.Column = int(n) - } - } - if v, ok := m["name"].(string); ok { - loc.Name = v +// toInt converts yaml integer types (int, uint64) to int. +func toInt(v any) int { + switch n := v.(type) { + case int: + return n + case uint64: + return int(n) } - return loc + return 0 } // applyOrigins walks a Go struct tree and a parallel OriginTree, setting @@ -134,8 +152,8 @@ func applyOriginsToStruct(val reflect.Value, ptr reflect.Value, tree *yaml.Origi if sf, ok := typ.FieldByName("Origin"); ok && sf.Type == originPtrType { tag := sf.Tag.Get("json") if strings.Contains(tag, originKey) || tag == "-" { - if m, ok := tree.Origin.(map[string]any); ok { - val.FieldByName("Origin").Set(reflect.ValueOf(originFromMap(m))) + if s, ok := tree.Origin.([]any); ok { + val.FieldByName("Origin").Set(reflect.ValueOf(originFromSeq(s, tree.File))) } } } From 1bf705c9b509bc3cb69c4a1daad462e05eec073e Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Thu, 2 Apr 2026 18:14:18 +0300 Subject: [PATCH 15/19] feat: update originFromSeq for file-at-index-0 format, add Origin.UnmarshalJSON The compact __origin__ sequence now carries the file path at index 0. Update originFromSeq to read file from s[0] (remove file parameter). Add Origin.UnmarshalJSON so __origin__ can be parsed directly during JSON decoding when the caller does not use UnmarshalWithOriginTree. Also add float64 handling in toInt for JSON-decoded []any sequences. Co-Authored-By: Claude Sonnet 4.6 --- openapi3/origin.go | 41 +++++++++++++++++++++++++++++------------ 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/openapi3/origin.go b/openapi3/origin.go index 539c26cf3..e51d95ac2 100644 --- a/openapi3/origin.go +++ b/openapi3/origin.go @@ -1,6 +1,7 @@ package openapi3 import ( + "encoding/json" "reflect" "strings" @@ -31,17 +32,16 @@ type Location struct { // originFromSeq parses the compact []any sequence produced by yaml3's addOrigin. // -// Format: [key_name, key_line, key_col, nf, f1_name, f1_delta, f1_col, ..., ns, s1_name, s1_count, s1_l0_delta, s1_c0, ...] -// -// file is the source file for all locations (stored in the OriginTree, not in the sequence). -func originFromSeq(s []any, file string) *Origin { - // Need at least: key_name, key_line, key_col, nf, ns - if len(s) < 5 { +// Format: [file, key_name, key_line, key_col, nf, f1_name, f1_delta, f1_col, ..., ns, s1_name, s1_count, s1_l0_delta, s1_c0, ...] +func originFromSeq(s []any) *Origin { + // Need at least: file, key_name, key_line, key_col, nf, ns + if len(s) < 6 { return nil } - keyName, _ := s[0].(string) - keyLine := toInt(s[1]) - keyCol := toInt(s[2]) + file, _ := s[0].(string) + keyName, _ := s[1].(string) + keyLine := toInt(s[2]) + keyCol := toInt(s[3]) o := &Origin{ Key: &Location{ @@ -52,7 +52,7 @@ func originFromSeq(s []any, file string) *Origin { }, } - idx := 3 + idx := 4 nf := toInt(s[idx]) idx++ if nf > 0 && idx+nf*3 <= len(s) { @@ -99,13 +99,30 @@ func originFromSeq(s []any, file string) *Origin { return o } -// toInt converts yaml integer types (int, uint64) to int. +// UnmarshalJSON parses the compact []any sequence produced by yaml3's addOrigin. +// This allows __origin__ to be decoded directly during JSON unmarshaling without +// a separate applyOrigins pass when the caller does not use UnmarshalWithOriginTree. +func (o *Origin) UnmarshalJSON(data []byte) error { + var seq []any + if err := json.Unmarshal(data, &seq); err != nil { + return err + } + if parsed := originFromSeq(seq); parsed != nil { + *o = *parsed + } + return nil +} + +// toInt converts numeric types to int. Handles int/uint64 from YAML decoding +// and float64 from JSON decoding of []any sequences. func toInt(v any) int { switch n := v.(type) { case int: return n case uint64: return int(n) + case float64: + return int(n) } return 0 } @@ -153,7 +170,7 @@ func applyOriginsToStruct(val reflect.Value, ptr reflect.Value, tree *yaml.Origi tag := sf.Tag.Get("json") if strings.Contains(tag, originKey) || tag == "-" { if s, ok := tree.Origin.([]any); ok { - val.FieldByName("Origin").Set(reflect.ValueOf(originFromSeq(s, tree.File))) + val.FieldByName("Origin").Set(reflect.ValueOf(originFromSeq(s))) } } } From cf971e53a423a0df28d95eff64255986ab101a35 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Thu, 2 Apr 2026 18:22:26 +0300 Subject: [PATCH 16/19] chore: bump yaml to v0.0.7, yaml3 to v0.0.5 Picks up the integer-key OriginTree fix (HTTP response codes like 200) and the compact __origin__ format with file path at index 0. Co-Authored-By: Claude Sonnet 4.6 --- go.mod | 4 ++-- go.sum | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/go.mod b/go.mod index 746a0c3a1..608e66177 100644 --- a/go.mod +++ b/go.mod @@ -6,8 +6,8 @@ require ( github.com/go-openapi/jsonpointer v0.21.0 github.com/gorilla/mux v1.8.0 github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 - github.com/oasdiff/yaml v0.0.5-beta.1 - github.com/oasdiff/yaml3 v0.0.4 + github.com/oasdiff/yaml v0.0.7 + github.com/oasdiff/yaml3 v0.0.5 github.com/perimeterx/marshmallow v1.1.5 github.com/stretchr/testify v1.9.0 github.com/woodsbury/decimal128 v1.3.0 diff --git a/go.sum b/go.sum index eaf674e67..84cdfe157 100644 --- a/go.sum +++ b/go.sum @@ -18,10 +18,10 @@ github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0 github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc= github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 h1:RWengNIwukTxcDr9M+97sNutRR1RKhG96O6jWumTTnw= github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826/go.mod h1:TaXosZuwdSHYgviHp1DAtfrULt5eUgsSMsZf+YrPgl8= -github.com/oasdiff/yaml v0.0.5-beta.1 h1:xCTUYEOtU5qqX3rYm2T0W5Wf60VVEvWw6RUYR2W54NI= -github.com/oasdiff/yaml v0.0.5-beta.1/go.mod h1:EaJ6/lcrRLK+syawtvtrHdbrrln4/SUmQw6aBTIlaMs= -github.com/oasdiff/yaml3 v0.0.4 h1:U5RTQZpBmsbcyCFlzPVuMctk6Jme6lOrbl0jJoOovMw= -github.com/oasdiff/yaml3 v0.0.4/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= +github.com/oasdiff/yaml v0.0.7 h1:r/BR4tqb+W/5fSV6RknYrfBa+PSZnRRvZ/nUnDdepFQ= +github.com/oasdiff/yaml v0.0.7/go.mod h1:EaJ6/lcrRLK+syawtvtrHdbrrln4/SUmQw6aBTIlaMs= +github.com/oasdiff/yaml3 v0.0.5 h1:jD51TPEvs+yDMkb3Yl2Q5SVpjU7GZze4oHZSEC5/w+4= +github.com/oasdiff/yaml3 v0.0.5/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= github.com/perimeterx/marshmallow v1.1.5 h1:a2LALqQ1BlHM8PZblsDdidgv1mWi1DgC2UmX50IvK2s= github.com/perimeterx/marshmallow v1.1.5/go.mod h1:dsXbUu8CRzfYP5a87xpp0xq9S3u0Vchtcl8we9tYaXw= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= From fd9dc09ce7972584fab1b776d4e7685d0fd87773 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Thu, 2 Apr 2026 18:26:11 +0300 Subject: [PATCH 17/19] fix: parse sequence item value in originFromSeq for named Location lookup Sequence items now encode (value_str, delta, col); update parser to set Location.Name from the value string so NewSourceFromSequenceItem can match required/enum items by value. Co-Authored-By: Claude Sonnet 4.6 --- openapi3/origin.go | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/openapi3/origin.go b/openapi3/origin.go index e51d95ac2..042b7dc9d 100644 --- a/openapi3/origin.go +++ b/openapi3/origin.go @@ -87,11 +87,12 @@ func originFromSeq(s []any) *Origin { count := toInt(s[idx]) idx++ locs := make([]Location, count) - for j := 0; j < count && idx+1 < len(s); j++ { - delta := toInt(s[idx]) - col := toInt(s[idx+1]) - locs[j] = Location{File: file, Line: keyLine + delta, Column: col} - idx += 2 + for j := 0; j < count && idx+2 < len(s); j++ { + name, _ := s[idx].(string) + delta := toInt(s[idx+1]) + col := toInt(s[idx+2]) + locs[j] = Location{File: file, Line: keyLine + delta, Column: col, Name: name} + idx += 3 } o.Sequences[sname] = locs } From a2f879941f3f6738d2f465b64bd2eb76e8b41aaa Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Thu, 2 Apr 2026 18:26:31 +0300 Subject: [PATCH 18/19] chore: bump yaml3 to v0.0.6 (sequence item value encoding) Co-Authored-By: Claude Sonnet 4.6 --- go.mod | 2 +- go.sum | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/go.mod b/go.mod index 608e66177..8bae30651 100644 --- a/go.mod +++ b/go.mod @@ -7,7 +7,7 @@ require ( github.com/gorilla/mux v1.8.0 github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 github.com/oasdiff/yaml v0.0.7 - github.com/oasdiff/yaml3 v0.0.5 + github.com/oasdiff/yaml3 v0.0.6 github.com/perimeterx/marshmallow v1.1.5 github.com/stretchr/testify v1.9.0 github.com/woodsbury/decimal128 v1.3.0 diff --git a/go.sum b/go.sum index 84cdfe157..cd935d9e2 100644 --- a/go.sum +++ b/go.sum @@ -20,8 +20,8 @@ github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 h1:RWengNIwukTxcDr9 github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826/go.mod h1:TaXosZuwdSHYgviHp1DAtfrULt5eUgsSMsZf+YrPgl8= github.com/oasdiff/yaml v0.0.7 h1:r/BR4tqb+W/5fSV6RknYrfBa+PSZnRRvZ/nUnDdepFQ= github.com/oasdiff/yaml v0.0.7/go.mod h1:EaJ6/lcrRLK+syawtvtrHdbrrln4/SUmQw6aBTIlaMs= -github.com/oasdiff/yaml3 v0.0.5 h1:jD51TPEvs+yDMkb3Yl2Q5SVpjU7GZze4oHZSEC5/w+4= -github.com/oasdiff/yaml3 v0.0.5/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= +github.com/oasdiff/yaml3 v0.0.6 h1:459QJwIK3pqFs91pIbH/XxCld0ugHd4/F8xHkFjaJPo= +github.com/oasdiff/yaml3 v0.0.6/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= github.com/perimeterx/marshmallow v1.1.5 h1:a2LALqQ1BlHM8PZblsDdidgv1mWi1DgC2UmX50IvK2s= github.com/perimeterx/marshmallow v1.1.5/go.mod h1:dsXbUu8CRzfYP5a87xpp0xq9S3u0Vchtcl8we9tYaXw= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= From d1f8901d4ca07b74a57c1609d1f9909b1e2d8477 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Sat, 4 Apr 2026 21:17:14 +0300 Subject: [PATCH 19/19] cleanup: remove dead origin-stripping code now handled by extractOrigins MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit extractOrigins strips __origin__ before JSON marshaling, making the following per-type calls in UnmarshalJSON unreachable: - stripExtensionsOrigin(x.Extensions) — 21 call sites - stripOriginFromAny(...) on any-typed fields (Schema.Enum/Default/Example, Link.RequestBody, Example.Value, MediaType.Example, Parameter.Example) - if k == originKey { ... } blocks in maplike.go (Responses, Paths, Callback) - popOrigin() in stringmap.go replaced with delete(m, originKey), then removed entirely since __origin__ never reaches these unmarshalers Also adds origin tests: RequiredSequence, YAMLAlias, Headers, IntegerStatusCode, Disabled, AnyFieldsStripped, MaplikeNoOriginKey, WithExternalRef (uncommented assertions), and a bulk LoadAllTestdata test that loads 26 specs with IncludeOrigin=true to catch regressions. Co-Authored-By: Claude Sonnet 4.6 --- openapi3/callback.go | 2 +- openapi3/components.go | 2 - openapi3/contact.go | 2 - openapi3/content.go | 2 +- openapi3/discriminator.go | 2 - openapi3/encoding.go | 4 +- openapi3/example.go | 5 +- openapi3/external_docs.go | 2 - openapi3/header.go | 2 +- openapi3/info.go | 2 - openapi3/license.go | 2 - openapi3/link.go | 5 +- openapi3/maplike.go | 33 -- openapi3/media_type.go | 3 - openapi3/openapi3.go | 2 - openapi3/operation.go | 2 - openapi3/origin.go | 32 -- openapi3/origin_load_test.go | 57 +++ openapi3/origin_test.go | 367 +++++++++++++----- openapi3/parameter.go | 5 +- openapi3/path_item.go | 2 - openapi3/request_body.go | 4 +- openapi3/response.go | 4 +- openapi3/schema.go | 10 +- openapi3/security_requirements.go | 2 +- openapi3/security_scheme.go | 8 +- openapi3/server.go | 6 +- openapi3/stringmap.go | 42 +- openapi3/tag.go | 2 - openapi3/testdata/origin/alias.yaml | 25 ++ openapi3/testdata/origin/any_fields.yaml | 42 ++ openapi3/testdata/origin/components.yaml | 80 ++++ openapi3/testdata/origin/headers.yaml | 19 + .../testdata/origin/required_sequence.yaml | 23 ++ openapi3/xml.go | 2 - 35 files changed, 535 insertions(+), 269 deletions(-) create mode 100644 openapi3/origin_load_test.go create mode 100644 openapi3/testdata/origin/alias.yaml create mode 100644 openapi3/testdata/origin/any_fields.yaml create mode 100644 openapi3/testdata/origin/components.yaml create mode 100644 openapi3/testdata/origin/headers.yaml create mode 100644 openapi3/testdata/origin/required_sequence.yaml diff --git a/openapi3/callback.go b/openapi3/callback.go index 31f4e4be2..a3e168404 100644 --- a/openapi3/callback.go +++ b/openapi3/callback.go @@ -56,6 +56,6 @@ func (callback *Callback) Validate(ctx context.Context, opts ...ValidationOption // UnmarshalJSON sets Callbacks to a copy of data. func (callbacks *Callbacks) UnmarshalJSON(data []byte) (err error) { - *callbacks, _, err = unmarshalStringMapP[CallbackRef](data) + *callbacks, err = unmarshalStringMapP[CallbackRef](data) return } diff --git a/openapi3/components.go b/openapi3/components.go index eac75ab4a..fe25f06fd 100644 --- a/openapi3/components.go +++ b/openapi3/components.go @@ -95,8 +95,6 @@ func (components *Components) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "schemas") delete(x.Extensions, "parameters") delete(x.Extensions, "headers") diff --git a/openapi3/contact.go b/openapi3/contact.go index 241ea0ef9..269db2f7f 100644 --- a/openapi3/contact.go +++ b/openapi3/contact.go @@ -52,8 +52,6 @@ func (contact *Contact) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "name") delete(x.Extensions, "url") delete(x.Extensions, "email") diff --git a/openapi3/content.go b/openapi3/content.go index 73e301e05..64db65f65 100644 --- a/openapi3/content.go +++ b/openapi3/content.go @@ -125,6 +125,6 @@ func (content Content) Validate(ctx context.Context, opts ...ValidationOption) e // UnmarshalJSON sets Content to a copy of data. func (content *Content) UnmarshalJSON(data []byte) (err error) { - *content, _, err = unmarshalStringMapP[MediaType](data) + *content, err = unmarshalStringMapP[MediaType](data) return } diff --git a/openapi3/discriminator.go b/openapi3/discriminator.go index 90fc3b228..ca215bcb4 100644 --- a/openapi3/discriminator.go +++ b/openapi3/discriminator.go @@ -60,8 +60,6 @@ func (discriminator *Discriminator) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "propertyName") delete(x.Extensions, "mapping") if len(x.Extensions) == 0 { diff --git a/openapi3/encoding.go b/openapi3/encoding.go index 2cab939a4..bd0108a0d 100644 --- a/openapi3/encoding.go +++ b/openapi3/encoding.go @@ -29,7 +29,7 @@ type Encodings map[string]*Encoding // UnmarshalJSON sets Encodings to a copy of data, stripping __origin__ metadata. func (encodings *Encodings) UnmarshalJSON(data []byte) (err error) { - *encodings, _, err = unmarshalStringMapP[Encoding](data) + *encodings, err = unmarshalStringMapP[Encoding](data) return } @@ -91,8 +91,6 @@ func (encoding *Encoding) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "contentType") delete(x.Extensions, "headers") delete(x.Extensions, "style") diff --git a/openapi3/example.go b/openapi3/example.go index 884a21e19..22422c31f 100644 --- a/openapi3/example.go +++ b/openapi3/example.go @@ -60,8 +60,6 @@ func (example *Example) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "summary") delete(x.Extensions, "description") delete(x.Extensions, "value") @@ -70,7 +68,6 @@ func (example *Example) UnmarshalJSON(data []byte) error { x.Extensions = nil } *example = Example(x) - example.Value = stripOriginFromAny(example.Value) return nil } @@ -90,6 +87,6 @@ func (example *Example) Validate(ctx context.Context, opts ...ValidationOption) // UnmarshalJSON sets Examples to a copy of data. func (examples *Examples) UnmarshalJSON(data []byte) (err error) { - *examples, _, err = unmarshalStringMapP[ExampleRef](data) + *examples, err = unmarshalStringMapP[ExampleRef](data) return } diff --git a/openapi3/external_docs.go b/openapi3/external_docs.go index 2c082b1ff..672dd9174 100644 --- a/openapi3/external_docs.go +++ b/openapi3/external_docs.go @@ -50,8 +50,6 @@ func (e *ExternalDocs) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "description") delete(x.Extensions, "url") if len(x.Extensions) == 0 { diff --git a/openapi3/header.go b/openapi3/header.go index 6b23db52e..a37bcc44e 100644 --- a/openapi3/header.go +++ b/openapi3/header.go @@ -97,6 +97,6 @@ func (header *Header) Validate(ctx context.Context, opts ...ValidationOption) er // UnmarshalJSON sets Headers to a copy of data. func (headers *Headers) UnmarshalJSON(data []byte) (err error) { - *headers, _, err = unmarshalStringMapP[HeaderRef](data) + *headers, err = unmarshalStringMapP[HeaderRef](data) return } diff --git a/openapi3/info.go b/openapi3/info.go index 31ff91814..fd6af3f2e 100644 --- a/openapi3/info.go +++ b/openapi3/info.go @@ -63,8 +63,6 @@ func (info *Info) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "title") delete(x.Extensions, "description") delete(x.Extensions, "termsOfService") diff --git a/openapi3/license.go b/openapi3/license.go index 440b3d762..755b5d93f 100644 --- a/openapi3/license.go +++ b/openapi3/license.go @@ -46,8 +46,6 @@ func (license *License) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "name") delete(x.Extensions, "url") if len(x.Extensions) == 0 { diff --git a/openapi3/link.go b/openapi3/link.go index 54694d949..72a2e7e1e 100644 --- a/openapi3/link.go +++ b/openapi3/link.go @@ -68,8 +68,6 @@ func (link *Link) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "operationRef") delete(x.Extensions, "operationId") delete(x.Extensions, "description") @@ -80,7 +78,6 @@ func (link *Link) UnmarshalJSON(data []byte) error { x.Extensions = nil } *link = Link(x) - link.RequestBody = stripOriginFromAny(link.RequestBody) return nil } @@ -100,6 +97,6 @@ func (link *Link) Validate(ctx context.Context, opts ...ValidationOption) error // UnmarshalJSON sets Links to a copy of data. func (links *Links) UnmarshalJSON(data []byte) (err error) { - *links, _, err = unmarshalStringMapP[LinkRef](data) + *links, err = unmarshalStringMapP[LinkRef](data) return } diff --git a/openapi3/maplike.go b/openapi3/maplike.go index 36aa244de..ac723b4d4 100644 --- a/openapi3/maplike.go +++ b/openapi3/maplike.go @@ -124,17 +124,6 @@ func (responses *Responses) UnmarshalJSON(data []byte) (err error) { continue } - if k == originKey { - var data []byte - if data, err = json.Marshal(v); err != nil { - return - } - if err = json.Unmarshal(data, &x.Origin); err != nil { - return - } - continue - } - var data []byte if data, err = json.Marshal(v); err != nil { return @@ -265,17 +254,6 @@ func (callback *Callback) UnmarshalJSON(data []byte) (err error) { continue } - if k == originKey { - var data []byte - if data, err = json.Marshal(v); err != nil { - return - } - if err = json.Unmarshal(data, &x.Origin); err != nil { - return - } - continue - } - var data []byte if data, err = json.Marshal(v); err != nil { return @@ -406,17 +384,6 @@ func (paths *Paths) UnmarshalJSON(data []byte) (err error) { continue } - if k == originKey { - var data []byte - if data, err = json.Marshal(v); err != nil { - return - } - if err = json.Unmarshal(data, &x.Origin); err != nil { - return - } - continue - } - var data []byte if data, err = json.Marshal(v); err != nil { return diff --git a/openapi3/media_type.go b/openapi3/media_type.go index c0edcf9c1..6aada3567 100644 --- a/openapi3/media_type.go +++ b/openapi3/media_type.go @@ -102,8 +102,6 @@ func (mediaType *MediaType) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "schema") delete(x.Extensions, "example") delete(x.Extensions, "examples") @@ -112,7 +110,6 @@ func (mediaType *MediaType) UnmarshalJSON(data []byte) error { x.Extensions = nil } *mediaType = MediaType(x) - mediaType.Example = stripOriginFromAny(mediaType.Example) return nil } diff --git a/openapi3/openapi3.go b/openapi3/openapi3.go index 77ebe494c..ed8a016c5 100644 --- a/openapi3/openapi3.go +++ b/openapi3/openapi3.go @@ -116,8 +116,6 @@ func (doc *T) UnmarshalJSON(data []byte) error { delete(x.Extensions, "servers") delete(x.Extensions, "tags") delete(x.Extensions, "externalDocs") - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) if len(x.Extensions) == 0 { x.Extensions = nil } diff --git a/openapi3/operation.go b/openapi3/operation.go index dd10405b5..c26e260de 100644 --- a/openapi3/operation.go +++ b/openapi3/operation.go @@ -117,8 +117,6 @@ func (operation *Operation) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "tags") delete(x.Extensions, "summary") delete(x.Extensions, "description") diff --git a/openapi3/origin.go b/openapi3/origin.go index 042b7dc9d..7deb26e28 100644 --- a/openapi3/origin.go +++ b/openapi3/origin.go @@ -270,35 +270,3 @@ func jsonTagName(f reflect.StructField) string { return name } -// stripOriginFromAny recursively removes the __origin__ key from any -// map[string]any value. This is needed for interface{}/any-typed fields -// (e.g. Schema.Enum, Schema.Default, Parameter.Example) that have no -// dedicated UnmarshalJSON to consume the origin metadata injected by -// the YAML origin-tracking loader. -func stripOriginFromAny(v any) any { - switch x := v.(type) { - case map[string]any: - delete(x, originKey) - for k, val := range x { - x[k] = stripOriginFromAny(val) - } - return x - case []any: - for i, val := range x { - x[i] = stripOriginFromAny(val) - } - return x - default: - return v - } -} - -// stripExtensionsOrigin removes __origin__ from every value in an extensions -// map. Extension values are any-typed objects, so the YAML decoder injects -// __origin__ into them. Without stripping it, two specs loaded from different -// file paths would report spurious diffs in their extension values. -func stripExtensionsOrigin(ext map[string]any) { - for k, v := range ext { - ext[k] = stripOriginFromAny(v) - } -} diff --git a/openapi3/origin_load_test.go b/openapi3/origin_load_test.go new file mode 100644 index 000000000..51159186c --- /dev/null +++ b/openapi3/origin_load_test.go @@ -0,0 +1,57 @@ +package openapi3 + +import ( + "context" + "testing" + + "github.com/stretchr/testify/require" +) + +// TestOrigin_LoadAllTestdata verifies that enabling origin tracking does not +// break loading of any spec in the testdata directory. It catches regressions +// where __origin__ leaks into fields and causes unmarshal failures or panics. +func TestOrigin_LoadAllTestdata(t *testing.T) { + specs := []struct { + name string + file string + externalRefs bool + }{ + {name: "spec", file: "testdata/spec.yaml", externalRefs: true}, + {name: "main", file: "testdata/main.yaml", externalRefs: true}, + {name: "link-example", file: "testdata/link-example.yaml"}, + {name: "lxkns", file: "testdata/lxkns.yaml"}, + {name: "303bis", file: "testdata/303bis/service.yaml", externalRefs: true}, + {name: "issue638/test1", file: "testdata/issue638/test1.yaml", externalRefs: true}, + {name: "issue638/test2", file: "testdata/issue638/test2.yaml", externalRefs: true}, + {name: "refInRefInProperty", file: "testdata/refInRefInProperty/openapi.yaml", externalRefs: true}, + {name: "circularRef2", file: "testdata/circularRef2/circular2.yaml", externalRefs: true}, + {name: "origin/simple", file: "testdata/origin/simple.yaml"}, + {name: "origin/parameters", file: "testdata/origin/parameters.yaml"}, + {name: "origin/security", file: "testdata/origin/security.yaml"}, + {name: "origin/components", file: "testdata/origin/components.yaml"}, + {name: "origin/extensions", file: "testdata/origin/extensions.yaml"}, + {name: "origin/alias", file: "testdata/origin/alias.yaml"}, + {name: "origin/any_fields", file: "testdata/origin/any_fields.yaml"}, + {name: "origin/required_sequence", file: "testdata/origin/required_sequence.yaml"}, + {name: "origin/headers", file: "testdata/origin/headers.yaml"}, + {name: "origin/example", file: "testdata/origin/example.yaml"}, + {name: "origin/example_with_array", file: "testdata/origin/example_with_array.yaml"}, + {name: "origin/external", file: "testdata/origin/external.yaml", externalRefs: true}, + {name: "origin/additional_properties", file: "testdata/origin/additional_properties.yaml"}, + {name: "origin/request_body", file: "testdata/origin/request_body.yaml"}, + {name: "origin/xml", file: "testdata/origin/xml.yaml"}, + {name: "origin/external_docs", file: "testdata/origin/external_docs.yaml"}, + } + + for _, tc := range specs { + t.Run(tc.name, func(t *testing.T) { + loader := NewLoader() + loader.IncludeOrigin = true + loader.IsExternalRefsAllowed = tc.externalRefs + loader.Context = context.Background() + + _, err := loader.LoadFromFile(tc.file) + require.NoError(t, err) + }) + } +} diff --git a/openapi3/origin_test.go b/openapi3/origin_test.go index 84a28d318..b475a1fc1 100644 --- a/openapi3/origin_test.go +++ b/openapi3/origin_test.go @@ -7,17 +7,10 @@ import ( "github.com/stretchr/testify/require" ) -func unsetIncludeOrigin() { - IncludeOrigin = false -} - func TestOrigin_Info(t *testing.T) { loader := NewLoader() loader.IsExternalRefsAllowed = true - - IncludeOrigin = true - defer unsetIncludeOrigin() - + loader.IncludeOrigin = true loader.Context = context.Background() doc, err := loader.LoadFromFile("testdata/origin/simple.yaml") @@ -55,10 +48,7 @@ func TestOrigin_Info(t *testing.T) { func TestOrigin_Paths(t *testing.T) { loader := NewLoader() loader.IsExternalRefsAllowed = true - - IncludeOrigin = true - defer unsetIncludeOrigin() - + loader.IncludeOrigin = true loader.Context = context.Background() doc, err := loader.LoadFromFile("testdata/origin/simple.yaml") @@ -100,10 +90,7 @@ func TestOrigin_Paths(t *testing.T) { func TestOrigin_RequestBody(t *testing.T) { loader := NewLoader() loader.IsExternalRefsAllowed = true - - IncludeOrigin = true - defer unsetIncludeOrigin() - + loader.IncludeOrigin = true loader.Context = context.Background() doc, err := loader.LoadFromFile("testdata/origin/request_body.yaml") @@ -134,10 +121,7 @@ func TestOrigin_RequestBody(t *testing.T) { func TestOrigin_Responses(t *testing.T) { loader := NewLoader() loader.IsExternalRefsAllowed = true - - IncludeOrigin = true - defer unsetIncludeOrigin() - + loader.IncludeOrigin = true loader.Context = context.Background() doc, err := loader.LoadFromFile("testdata/origin/simple.yaml") @@ -178,10 +162,7 @@ func TestOrigin_Responses(t *testing.T) { func TestOrigin_Parameters(t *testing.T) { loader := NewLoader() loader.IsExternalRefsAllowed = true - - IncludeOrigin = true - defer unsetIncludeOrigin() - + loader.IncludeOrigin = true loader.Context = context.Background() doc, err := loader.LoadFromFile("testdata/origin/parameters.yaml") @@ -220,10 +201,7 @@ func TestOrigin_Parameters(t *testing.T) { func TestOrigin_SchemaInAdditionalProperties(t *testing.T) { loader := NewLoader() loader.IsExternalRefsAllowed = true - - IncludeOrigin = true - defer unsetIncludeOrigin() - + loader.IncludeOrigin = true loader.Context = context.Background() doc, err := loader.LoadFromFile("testdata/origin/additional_properties.yaml") @@ -255,10 +233,7 @@ func TestOrigin_SchemaInAdditionalProperties(t *testing.T) { func TestOrigin_ExternalDocs(t *testing.T) { loader := NewLoader() loader.IsExternalRefsAllowed = true - - IncludeOrigin = true - defer unsetIncludeOrigin() - + loader.IncludeOrigin = true loader.Context = context.Background() doc, err := loader.LoadFromFile("testdata/origin/external_docs.yaml") @@ -298,10 +273,7 @@ func TestOrigin_ExternalDocs(t *testing.T) { func TestOrigin_Security(t *testing.T) { loader := NewLoader() loader.IsExternalRefsAllowed = true - - IncludeOrigin = true - defer unsetIncludeOrigin() - + loader.IncludeOrigin = true loader.Context = context.Background() doc, err := loader.LoadFromFile("testdata/origin/security.yaml") @@ -359,10 +331,7 @@ func TestOrigin_Security(t *testing.T) { func TestOrigin_Example(t *testing.T) { loader := NewLoader() loader.IsExternalRefsAllowed = true - - IncludeOrigin = true - defer unsetIncludeOrigin() - + loader.IncludeOrigin = true loader.Context = context.Background() doc, err := loader.LoadFromFile("testdata/origin/example.yaml") @@ -397,10 +366,7 @@ func TestOrigin_Example(t *testing.T) { func TestOrigin_XML(t *testing.T) { loader := NewLoader() loader.IsExternalRefsAllowed = true - - IncludeOrigin = true - defer unsetIncludeOrigin() - + loader.IncludeOrigin = true loader.Context = context.Background() doc, err := loader.LoadFromFile("testdata/origin/xml.yaml") @@ -436,38 +402,53 @@ func TestOrigin_XML(t *testing.T) { base.Origin.Fields["prefix"]) } -func TestStripOriginFromAny_Slice(t *testing.T) { - // Simulates what the YAML origin-tracking loader produces for example - // values that contain arrays of objects. - input := map[string]any{ - "name": "test", - "items": []any{ - map[string]any{ - "__origin__": map[string]any{"file": "a.yaml", "line": 1}, - "id": 1, - }, - map[string]any{ - "__origin__": map[string]any{"file": "a.yaml", "line": 2}, - "id": 2, - }, - }, - } +// TestOrigin_AnyFieldsStripped verifies that __origin__ is absent from all +// any-typed fields (Schema.Enum, Schema.Default, Schema.Example, +// Parameter.Example, MediaType.Example, Link.RequestBody) after loading. +// These fields have no dedicated UnmarshalJSON; extractOrigins strips +// __origin__ before JSON marshaling so it never reaches these values. +func TestOrigin_AnyFieldsStripped(t *testing.T) { + loader := NewLoader() + loader.IncludeOrigin = true + doc, err := loader.LoadFromFile("testdata/origin/any_fields.yaml") + require.NoError(t, err) - result := stripOriginFromAny(input) - m := result.(map[string]any) - items := m["items"].([]any) - for _, item := range items { - itemMap := item.(map[string]any) - require.NotContains(t, itemMap, "__origin__") + op := doc.Paths.Find("/items").Get + resp := op.Responses.Value("200").Value + + // Parameter.Example + paramEx := op.Parameters[0].Value.Example.(map[string]any) + require.NotContains(t, paramEx, originKey, "Parameter.Example must not contain __origin__") + + // MediaType.Example + mediaEx := resp.Content["application/json"].Example.(map[string]any) + require.NotContains(t, mediaEx, originKey, "MediaType.Example must not contain __origin__") + + schema := resp.Content["application/json"].Schema.Value + + // Schema.Default + schemaDefault := schema.Default.(map[string]any) + require.NotContains(t, schemaDefault, originKey, "Schema.Default must not contain __origin__") + + // Schema.Example + schemaEx := schema.Example.(map[string]any) + require.NotContains(t, schemaEx, originKey, "Schema.Example must not contain __origin__") + + // Schema.Enum items + for i, v := range schema.Enum { + m, ok := v.(map[string]any) + require.True(t, ok, "Schema.Enum[%d] must be a map", i) + require.NotContains(t, m, originKey, "Schema.Enum[%d] must not contain __origin__", i) } + + // Link.RequestBody + linkRB := resp.Links["self"].Value.RequestBody.(map[string]any) + require.NotContains(t, linkRB, originKey, "Link.RequestBody must not contain __origin__") } func TestOrigin_ExampleWithArrayValue(t *testing.T) { loader := NewLoader() - - IncludeOrigin = true - defer unsetIncludeOrigin() - + loader.IncludeOrigin = true doc, err := loader.LoadFromFile("testdata/origin/example_with_array.yaml") require.NoError(t, err) @@ -507,9 +488,7 @@ components: ` loader := NewLoader() - - IncludeOrigin = true - defer unsetIncludeOrigin() + loader.IncludeOrigin = true _, err := loader.LoadFromData([]byte(data)) require.Error(t, err) @@ -524,9 +503,7 @@ components: // between specs loaded from different file paths. func TestOrigin_ExtensionValuesStripped(t *testing.T) { loader := NewLoader() - - IncludeOrigin = true - defer unsetIncludeOrigin() + loader.IncludeOrigin = true doc, err := loader.LoadFromFile("testdata/origin/extensions.yaml") require.NoError(t, err) @@ -553,9 +530,7 @@ func TestOrigin_ExtensionValuesStripped(t *testing.T) { func TestOrigin_WithExternalRef(t *testing.T) { loader := NewLoader() loader.IsExternalRefsAllowed = true - - IncludeOrigin = true - defer unsetIncludeOrigin() + loader.IncludeOrigin = true loader.Context = context.Background() @@ -564,25 +539,217 @@ func TestOrigin_WithExternalRef(t *testing.T) { base := doc.Paths.Find("/subscribe").Post.RequestBody.Value.Content["application/json"].Schema.Value.Properties["name"].Value require.NotNil(t, base.XML.Origin) - require.Equal(t, base.XML.Origin.Key.File, "testdata/origin/external-schema.yaml") - // require.Equal(t, - // &Location{ - // Line: 1, - // Column: 1, - // }, - // base.Origin.Key) - - // require.Equal(t, - // Location{ - // Line: 2, - // Column: 3, - // }, - // base.Origin.Fields["namespace"]) - - // require.Equal(t, - // Location{ - // Line: 3, - // Column: 3, - // }, - // base.Origin.Fields["prefix"]) + require.Equal(t, + &Location{ + File: "testdata/origin/external-schema.yaml", + Line: 2, + Column: 1, + Name: "xml", + }, + base.XML.Origin.Key) + + require.Equal(t, + Location{ + File: "testdata/origin/external-schema.yaml", + Line: 3, + Column: 3, + Name: "namespace", + }, + base.XML.Origin.Fields["namespace"]) + + require.Equal(t, + Location{ + File: "testdata/origin/external-schema.yaml", + Line: 4, + Column: 3, + Name: "prefix", + }, + base.XML.Origin.Fields["prefix"]) +} + +// TestOrigin_MaplikeNoOriginKey verifies that __origin__ does not appear as a +// map key in Responses, Paths, or Callback maplike types after loading. +// The if k == originKey blocks in their UnmarshalJSON were removed; this +// confirms extractOrigins strips __origin__ before it reaches those iterators. +func TestOrigin_MaplikeNoOriginKey(t *testing.T) { + loader := NewLoader() + loader.IncludeOrigin = true + doc, err := loader.LoadFromFile("testdata/origin/simple.yaml") + require.NoError(t, err) + + // Paths map must not contain __origin__ as a path key + require.Nil(t, doc.Paths.Find(originKey), "Paths must not contain __origin__ as a key") + + // Responses map must not contain __origin__ as a status code key + op := doc.Paths.Find("/partner-api/test/some-method").Get + require.Nil(t, op.Responses.Value(originKey), "Responses must not contain __origin__ as a key") +} + +func TestOrigin_NoSpuriousOriginsInComponents(t *testing.T) { + loader := NewLoader() + loader.IncludeOrigin = true + + doc, err := loader.LoadFromFile("testdata/origin/components.yaml") + + require.Nil(t, doc.Components.Schemas[originKey]) + require.Nil(t, doc.Components.Parameters[originKey]) + require.Nil(t, doc.Components.Headers[originKey]) + require.Nil(t, doc.Components.RequestBodies[originKey]) + require.Nil(t, doc.Components.Responses[originKey]) + require.Nil(t, doc.Components.SecuritySchemes[originKey]) + require.Nil(t, doc.Components.Examples[originKey]) + require.Nil(t, doc.Components.Links[originKey]) + require.Nil(t, doc.Components.Callbacks[originKey]) + + require.NoError(t, err) +} + +// TestOrigin_RequiredSequence verifies that Origin.Sequences records the +// file/line/column of each item in a required: [...] list. +// These locations are used by NewSourceFromSequenceItem to pinpoint +// breaking changes to individual required field names. +func TestOrigin_RequiredSequence(t *testing.T) { + loader := NewLoader() + loader.IncludeOrigin = true + + doc, err := loader.LoadFromFile("testdata/origin/required_sequence.yaml") + require.NoError(t, err) + + schema := doc.Paths.Find("/items").Post.RequestBody.Value.Content["application/json"].Schema.Value + require.NotNil(t, schema.Origin) + + // "required" must appear in Fields (it's a sequence-valued field) + require.Contains(t, schema.Origin.Fields, "required") + + // Sequences must record per-item locations for "required" + seqLocs, ok := schema.Origin.Sequences["required"] + require.True(t, ok, "Origin.Sequences must contain 'required'") + require.Len(t, seqLocs, 2) + + require.Equal(t, Location{ + File: "testdata/origin/required_sequence.yaml", + Line: 14, + Column: 19, + Name: "name", + }, seqLocs[0]) + + require.Equal(t, Location{ + File: "testdata/origin/required_sequence.yaml", + Line: 15, + Column: 19, + Name: "age", + }, seqLocs[1]) +} + +// TestOrigin_YAMLAlias verifies that a schema referenced via YAML alias loads +// without error and carries origin metadata from the anchor definition. +// Multiple aliases of the same anchor must not produce duplicate __origin__ keys. +func TestOrigin_YAMLAlias(t *testing.T) { + loader := NewLoader() + loader.IncludeOrigin = true + + doc, err := loader.LoadFromFile("testdata/origin/alias.yaml") + require.NoError(t, err) + + anchor := doc.Components.Schemas["Base"].Value + alias1 := doc.Components.Schemas["Alias1"].Value + alias2 := doc.Components.Schemas["Alias2"].Value + + // All three point to the same anchor node, so origin reflects the anchor location. + anchorLoc := &Location{ + File: "testdata/origin/alias.yaml", + Line: 7, + Column: 5, + Name: "Base", + } + require.Equal(t, anchorLoc, anchor.Origin.Key) + require.Equal(t, anchorLoc, alias1.Origin.Key) + require.Equal(t, anchorLoc, alias2.Origin.Key) +} + +// TestOrigin_Headers verifies that response header origin is tracked correctly. +func TestOrigin_Headers(t *testing.T) { + loader := NewLoader() + loader.IncludeOrigin = true + + doc, err := loader.LoadFromFile("testdata/origin/headers.yaml") + require.NoError(t, err) + + headers := doc.Paths.Find("/items").Get.Responses.Value("200").Value.Headers + + require.Equal(t, + &Location{ + File: "testdata/origin/headers.yaml", + Line: 12, + Column: 13, + Name: "X-Rate-Limit", + }, + headers["X-Rate-Limit"].Value.Origin.Key) + + require.Equal(t, + Location{ + File: "testdata/origin/headers.yaml", + Line: 13, + Column: 15, + Name: "description", + }, + headers["X-Rate-Limit"].Value.Origin.Fields["description"]) + + require.Equal(t, + &Location{ + File: "testdata/origin/headers.yaml", + Line: 16, + Column: 13, + Name: "X-Request-Id", + }, + headers["X-Request-Id"].Value.Origin.Key) +} + +// TestOrigin_IntegerStatusCode verifies that response origin is tracked when +// HTTP status codes are written as bare integers (200:) rather than quoted +// strings ("200":). Bare integers produce map[interface{}]interface{} in the +// YAML decoder, which required a dedicated fix in extractOrigins. +func TestOrigin_IntegerStatusCode(t *testing.T) { + loader := NewLoader() + loader.IncludeOrigin = true + + doc, err := loader.LoadFromFile("testdata/origin/parameters.yaml") + require.NoError(t, err) + + resp200 := doc.Paths.Find("/api/test").Get.Responses.Value("200").Value + require.NotNil(t, resp200.Origin) + require.Equal(t, + &Location{ + File: "testdata/origin/parameters.yaml", + Line: 14, + Column: 9, + Name: "200", + }, + resp200.Origin.Key) + + resp201 := doc.Paths.Find("/api/test").Post.Responses.Value("201").Value + require.NotNil(t, resp201.Origin) + require.Equal(t, + &Location{ + File: "testdata/origin/parameters.yaml", + Line: 18, + Column: 9, + Name: "201", + }, + resp201.Origin.Key) +} + +// TestOrigin_Disabled verifies that all Origin fields are nil when +// IncludeOrigin is false (the default), ensuring no overhead in the common case. +func TestOrigin_Disabled(t *testing.T) { + loader := NewLoader() + // IncludeOrigin defaults to false + + doc, err := loader.LoadFromFile("testdata/origin/required_sequence.yaml") + require.NoError(t, err) + + schema := doc.Paths.Find("/items").Post.RequestBody.Value.Content["application/json"].Schema.Value + require.Nil(t, schema.Origin) + require.Nil(t, doc.Info.Origin) + require.Nil(t, doc.Paths.Origin) } diff --git a/openapi3/parameter.go b/openapi3/parameter.go index 363094e5b..a5d244795 100644 --- a/openapi3/parameter.go +++ b/openapi3/parameter.go @@ -217,8 +217,6 @@ func (parameter *Parameter) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "name") delete(x.Extensions, "in") delete(x.Extensions, "description") @@ -237,7 +235,6 @@ func (parameter *Parameter) UnmarshalJSON(data []byte) error { } *parameter = Parameter(x) - parameter.Example = stripOriginFromAny(parameter.Example) return nil } @@ -421,6 +418,6 @@ func (parameter *Parameter) Validate(ctx context.Context, opts ...ValidationOpti // UnmarshalJSON sets ParametersMap to a copy of data. func (parametersMap *ParametersMap) UnmarshalJSON(data []byte) (err error) { - *parametersMap, _, err = unmarshalStringMapP[ParameterRef](data) + *parametersMap, err = unmarshalStringMapP[ParameterRef](data) return } diff --git a/openapi3/path_item.go b/openapi3/path_item.go index 8f8da8fb7..d14bbed54 100644 --- a/openapi3/path_item.go +++ b/openapi3/path_item.go @@ -99,8 +99,6 @@ func (pathItem *PathItem) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "$ref") delete(x.Extensions, "summary") delete(x.Extensions, "description") diff --git a/openapi3/request_body.go b/openapi3/request_body.go index e82f678bc..f95e31b19 100644 --- a/openapi3/request_body.go +++ b/openapi3/request_body.go @@ -109,8 +109,6 @@ func (requestBody *RequestBody) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "description") delete(x.Extensions, "required") delete(x.Extensions, "content") @@ -142,6 +140,6 @@ func (requestBody *RequestBody) Validate(ctx context.Context, opts ...Validation // UnmarshalJSON sets RequestBodies to a copy of data. func (requestBodies *RequestBodies) UnmarshalJSON(data []byte) (err error) { - *requestBodies, _, err = unmarshalStringMapP[RequestBodyRef](data) + *requestBodies, err = unmarshalStringMapP[RequestBodyRef](data) return } diff --git a/openapi3/response.go b/openapi3/response.go index 786726208..115c811a0 100644 --- a/openapi3/response.go +++ b/openapi3/response.go @@ -173,8 +173,6 @@ func (response *Response) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "description") delete(x.Extensions, "headers") delete(x.Extensions, "content") @@ -232,6 +230,6 @@ func (response *Response) Validate(ctx context.Context, opts ...ValidationOption // UnmarshalJSON sets ResponseBodies to a copy of data. func (responseBodies *ResponseBodies) UnmarshalJSON(data []byte) (err error) { - *responseBodies, _, err = unmarshalStringMapP[ResponseRef](data) + *responseBodies, err = unmarshalStringMapP[ResponseRef](data) return } diff --git a/openapi3/schema.go b/openapi3/schema.go index f90345cde..c59aefa95 100644 --- a/openapi3/schema.go +++ b/openapi3/schema.go @@ -413,8 +413,6 @@ func (schema *Schema) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "oneOf") delete(x.Extensions, "anyOf") delete(x.Extensions, "allOf") @@ -470,12 +468,6 @@ func (schema *Schema) UnmarshalJSON(data []byte) error { *schema = Schema(x) - for i, v := range schema.Enum { - schema.Enum[i] = stripOriginFromAny(v) - } - schema.Default = stripOriginFromAny(schema.Default) - schema.Example = stripOriginFromAny(schema.Example) - if schema.Format == "date" { // This is a fix for: https://github.com/oasdiff/kin-openapi/issues/697 if eg, ok := schema.Example.(string); ok { @@ -2282,6 +2274,6 @@ func unsupportedFormat(format string) error { // UnmarshalJSON sets Schemas to a copy of data. func (schemas *Schemas) UnmarshalJSON(data []byte) (err error) { - *schemas, _, err = unmarshalStringMapP[SchemaRef](data) + *schemas, err = unmarshalStringMapP[SchemaRef](data) return } diff --git a/openapi3/security_requirements.go b/openapi3/security_requirements.go index 6af80e8b3..d5310d87a 100644 --- a/openapi3/security_requirements.go +++ b/openapi3/security_requirements.go @@ -52,6 +52,6 @@ func (security *SecurityRequirement) Validate(ctx context.Context, opts ...Valid // UnmarshalJSON sets SecurityRequirement to a copy of data. func (security *SecurityRequirement) UnmarshalJSON(data []byte) (err error) { - *security, _, err = unmarshalStringMap[[]string](data) + *security, err = unmarshalStringMap[[]string](data) return } diff --git a/openapi3/security_scheme.go b/openapi3/security_scheme.go index cb0fc86a6..df09bd468 100644 --- a/openapi3/security_scheme.go +++ b/openapi3/security_scheme.go @@ -101,8 +101,6 @@ func (ss *SecurityScheme) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "type") delete(x.Extensions, "description") delete(x.Extensions, "name") @@ -274,8 +272,6 @@ func (flows *OAuthFlows) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "implicit") delete(x.Extensions, "password") delete(x.Extensions, "clientCredentials") @@ -367,8 +363,6 @@ func (flow *OAuthFlow) UnmarshalJSON(data []byte) error { } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "authorizationUrl") delete(x.Extensions, "tokenUrl") delete(x.Extensions, "refreshUrl") @@ -440,6 +434,6 @@ func (flow *OAuthFlow) validate(ctx context.Context, typ oAuthFlowType, opts ... // UnmarshalJSON sets SecuritySchemes to a copy of data. func (securitySchemes *SecuritySchemes) UnmarshalJSON(data []byte) (err error) { - *securitySchemes, _, err = unmarshalStringMapP[SecuritySchemeRef](data) + *securitySchemes, err = unmarshalStringMapP[SecuritySchemeRef](data) return } diff --git a/openapi3/server.go b/openapi3/server.go index 40c8464f8..df0fafe9f 100644 --- a/openapi3/server.go +++ b/openapi3/server.go @@ -115,8 +115,6 @@ func (server *Server) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "url") delete(x.Extensions, "description") delete(x.Extensions, "variables") @@ -240,7 +238,7 @@ type ServerVariables map[string]*ServerVariable // UnmarshalJSON sets ServerVariables to a copy of data, stripping __origin__ metadata. func (serverVariables *ServerVariables) UnmarshalJSON(data []byte) (err error) { - *serverVariables, _, err = unmarshalStringMapP[ServerVariable](data) + *serverVariables, err = unmarshalStringMapP[ServerVariable](data) return } @@ -288,8 +286,6 @@ func (serverVariable *ServerVariable) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "enum") delete(x.Extensions, "default") delete(x.Extensions, "description") diff --git a/openapi3/stringmap.go b/openapi3/stringmap.go index 10e7e6de0..5cd68a5dc 100644 --- a/openapi3/stringmap.go +++ b/openapi3/stringmap.go @@ -7,56 +7,46 @@ type StringMap[V any] map[string]V // UnmarshalJSON sets StringMap to a copy of data. func (stringMap *StringMap[V]) UnmarshalJSON(data []byte) (err error) { - *stringMap, _, err = unmarshalStringMap[V](data) + *stringMap, err = unmarshalStringMap[V](data) return } // unmarshalStringMapP unmarshals given json into a map[string]*V -func unmarshalStringMapP[V any](data []byte) (map[string]*V, *Origin, error) { +func unmarshalStringMapP[V any](data []byte) (map[string]*V, error) { var m map[string]any if err := json.Unmarshal(data, &m); err != nil { - return nil, nil, err - } - - origin, err := popOrigin(m, originKey) - if err != nil { - return nil, nil, err + return nil, err } result := make(map[string]*V, len(m)) for k, v := range m { value, err := deepCast[V](v) if err != nil { - return nil, nil, err + return nil, err } result[k] = value } - return result, origin, nil + return result, nil } // unmarshalStringMap unmarshals given json into a map[string]V -func unmarshalStringMap[V any](data []byte) (map[string]V, *Origin, error) { +func unmarshalStringMap[V any](data []byte) (map[string]V, error) { var m map[string]any if err := json.Unmarshal(data, &m); err != nil { - return nil, nil, err - } - - origin, err := popOrigin(m, originKey) - if err != nil { - return nil, nil, err + return nil, err } result := make(map[string]V, len(m)) for k, v := range m { value, err := deepCast[V](v) if err != nil { - return nil, nil, err + return nil, err } result[k] = *value } - return result, origin, nil + return result, nil } // deepCast casts any value to a value of type V. @@ -72,17 +62,3 @@ func deepCast[V any](value any) (*V, error) { } return &result, nil } - -// popOrigin removes the origin from the map and returns it. -func popOrigin(m map[string]any, key string) (*Origin, error) { - if !IncludeOrigin { - return nil, nil - } - - origin, err := deepCast[Origin](m[key]) - if err != nil { - return nil, err - } - delete(m, key) - return origin, nil -} diff --git a/openapi3/tag.go b/openapi3/tag.go index 401893936..f5d6accbb 100644 --- a/openapi3/tag.go +++ b/openapi3/tag.go @@ -76,8 +76,6 @@ func (t *Tag) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "name") delete(x.Extensions, "description") delete(x.Extensions, "externalDocs") diff --git a/openapi3/testdata/origin/alias.yaml b/openapi3/testdata/origin/alias.yaml new file mode 100644 index 000000000..9ab85fe2f --- /dev/null +++ b/openapi3/testdata/origin/alias.yaml @@ -0,0 +1,25 @@ +openapi: 3.0.0 +info: + title: Alias Test + version: 1.0.0 +components: + schemas: + Base: &base + type: object + properties: + id: + type: integer + name: + type: string + Alias1: *base + Alias2: *base +paths: + /items: + get: + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/Alias1" diff --git a/openapi3/testdata/origin/any_fields.yaml b/openapi3/testdata/origin/any_fields.yaml new file mode 100644 index 000000000..88d55b893 --- /dev/null +++ b/openapi3/testdata/origin/any_fields.yaml @@ -0,0 +1,42 @@ +openapi: 3.0.0 +info: + title: Any Fields Test + version: 1.0.0 +paths: + /items: + get: + parameters: + - name: filter + in: query + example: + env: production + region: us-east + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + example: + id: 1 + name: example + schema: + type: object + default: + status: active + count: 0 + example: + status: active + count: 42 + enum: + - status: active + count: 1 + - status: inactive + count: 0 + links: + self: + operationId: getItem + requestBody: + id: 1 + name: test diff --git a/openapi3/testdata/origin/components.yaml b/openapi3/testdata/origin/components.yaml new file mode 100644 index 000000000..6c4accbc3 --- /dev/null +++ b/openapi3/testdata/origin/components.yaml @@ -0,0 +1,80 @@ +openapi: 3.0.1 +info: + title: Test API + version: v1 +components: + schemas: + SomeObject: + type: object + properties: + code: + type: integer + text: + type: string + parameters: + SomeParameter: + name: some-parameter + in: query + schema: + type: string + headers: + SomeHeader: + description: Some header + schema: + type: string + requestBodies: + SomeRequestBody: + description: Some request body + content: + application/json: + schema: + type: object + properties: + code: + type: integer + text: + type: string + responses: + SomeResponse: + description: Some response + content: + application/json: + schema: + type: object + properties: + code: + type: integer + text: + type: string + securitySchemes: + SomeSecurityScheme: + type: http + scheme: basic + examples: + SomeExample: + summary: Some example + value: + code: 123 + text: Some text + links: + SomeLink: + description: Some link + operationId: someOperation + callbacks: + SomeCallback: + '{$request.query.callbackUrl}': + post: + requestBody: + description: Some callback request body + content: + application/json: + schema: + type: object + properties: + code: + type: integer + text: + type: string + responses: + "200": + description: OK \ No newline at end of file diff --git a/openapi3/testdata/origin/headers.yaml b/openapi3/testdata/origin/headers.yaml new file mode 100644 index 000000000..e92928ad3 --- /dev/null +++ b/openapi3/testdata/origin/headers.yaml @@ -0,0 +1,19 @@ +openapi: 3.0.0 +info: + title: Headers Test + version: 1.0.0 +paths: + /items: + get: + responses: + "200": + description: OK + headers: + X-Rate-Limit: + description: Rate limit per hour + schema: + type: integer + X-Request-Id: + description: Unique request ID + schema: + type: string diff --git a/openapi3/testdata/origin/required_sequence.yaml b/openapi3/testdata/origin/required_sequence.yaml new file mode 100644 index 000000000..778a32601 --- /dev/null +++ b/openapi3/testdata/origin/required_sequence.yaml @@ -0,0 +1,23 @@ +openapi: 3.0.0 +info: + title: Required Sequence Test + version: 1.0.0 +paths: + /items: + post: + requestBody: + content: + application/json: + schema: + type: object + required: + - name + - age + properties: + name: + type: string + age: + type: integer + responses: + "200": + description: OK diff --git a/openapi3/xml.go b/openapi3/xml.go index 543b32def..4719c8ff8 100644 --- a/openapi3/xml.go +++ b/openapi3/xml.go @@ -59,8 +59,6 @@ func (xml *XML) UnmarshalJSON(data []byte) error { return unmarshalError(err) } _ = json.Unmarshal(data, &x.Extensions) - delete(x.Extensions, originKey) - stripExtensionsOrigin(x.Extensions) delete(x.Extensions, "name") delete(x.Extensions, "namespace") delete(x.Extensions, "prefix")