From 8571ed1e9f9a5f26e92d2469316d7997d61ec093 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Tue, 13 Feb 2024 17:26:55 +1000 Subject: [PATCH 1/5] CAP-51: Small tweaks (#1442) * CAP-51: Add client data JSON example * CAP-51: Small tweaks --- core/cap-0051.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/core/cap-0051.md b/core/cap-0051.md index e349e8401..f0c417933 100644 --- a/core/cap-0051.md +++ b/core/cap-0051.md @@ -190,13 +190,9 @@ Regarding base64 url encoding, it is possible to embed a small and efficient fixed width base64 url encoder into a contract. Regarding JSON, it has not been proven feasible to include a complete JSON -decoder or encoder, but given the JSON format, it is feasible to search the -client data JSON for the base64 url encoded challenge surrounded by `"`, and -then surrounded by either `:`, `,`, ` `, `{`, or `}`. Assuming consistency with -which clients produce the client data JSON it is also possible to check the -prefix of the client data JSON contains an exact format including the base64 url -encoded challenge. **(TODO: This paragraph is incorrect and needs replacing with -nother solution.)** +decoder or encoder, and as such implementing webauthn verification is also +dependent on the addition of a JSON host function interface that is out-of-scope +of this proposal. ## Protocol Upgrade Transition @@ -231,7 +227,7 @@ reasons, such as resource cost or privacy. ### Audited Implementations The only ECDSA secp256r1 pure-Rust crates that the Soroban environment could -embed are the [p256] and [ECDSA] crates. The two crates have never been +embed are the [p256] and [ecdsa] crates. The two crates have never been independently audited. ## Test Cases @@ -244,5 +240,5 @@ None yet. But will be tracked by [stellar/rs-sorovan-env#807] if implemented. [Webauthn]: https://www.w3.org/TR/webauthn-2/ [p256]: https://crates.io/crates/p256 -[ECDSA]: https://crates.io/crates/ECDSA +[ecdsa]: https://crates.io/crates/ecdsa [stellar/rs-soroban-env#807]: https://github.com/stellar/rs-soroban-env/issues/807 From 471cad2c0f597a7f35e47a580ac2d02543ac4ab6 Mon Sep 17 00:00:00 2001 From: Jake Urban <10968980+JakeUrban@users.noreply.github.com> Date: Wed, 14 Feb 2024 16:18:03 -0800 Subject: [PATCH 2/5] SEP-1: Add `contract` field to `CURRENCIES` list (#1437) --- ecosystem/sep-0001.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/ecosystem/sep-0001.md b/ecosystem/sep-0001.md index ec9b1503f..5542ec365 100644 --- a/ecosystem/sep-0001.md +++ b/ecosystem/sep-0001.md @@ -6,8 +6,8 @@ Title: Stellar Info File Author: stellar.org Status: Active Created: 2017-10-30 -Updated: 2022-05-27 -Version: 2.5.0 +Updated: 2024-02-01 +Version: 2.6.0 ``` ## Simple Summary @@ -114,11 +114,14 @@ The public key in the verification photo should be the issuing public key for th These fields go in the `stellar.toml` `[[CURRENCIES]]` list, one set of fields for each currency supported. Complete all applicable fields, and exclude any that don't apply. +Currencies can be Stellar Assets that have been issued by a Stellar account and share the same common behaviors, or custom token contracts that satisfy the SEP-41 interface but implementation and behavior is customizable. + Field | Requirements | Description ------|--------------|------------ -code | string (<= 12 char) | Token code +code | string (<= 12 char) | Token code. Required. +issuer | `G...` string | Stellar public key of the issuing account. Required for tokens that are Stellar Assets. Omitted if the token is not a Stellar asset. +contract | `C...` string | Contract ID of the token contract. The token must be compatible with the [SEP-41 Token Interface](sep-0041.md) to be defined here. Required for tokens that are not Stellar Assets. Omitted if the token is a Stellar Asset. code_template | string (<= 12 char) | A pattern with `?` as a single character wildcard. Allows a `[[CURRENCIES]]` entry to apply to multiple assets that share the same info. An example is futures, where the only difference between issues is the date of the contract. E.g. `CORN????????` to match codes such as `CORN20180604`. -issuer | `G...` string | Token issuer Stellar public key status | string | Status of token. One of `live`, `dead`, `test`, or `private`. Allows issuer to mark whether token is dead/for testing/for private use or is live and should be listed in live exchanges. display_decimals | int (0 to 7) | Preference for number of decimals to show when a client displays currency balance name | string (<= 20 char) | A short name for the token From 6565084955838e8028bda5428b281d22158b50d6 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Tue, 20 Feb 2024 15:24:46 -0800 Subject: [PATCH 3/5] CAP-52: Add first draft for base64 on Soroban (#1443) --- core/cap-0052.md | 208 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 core/cap-0052.md diff --git a/core/cap-0052.md b/core/cap-0052.md new file mode 100644 index 000000000..aa396a124 --- /dev/null +++ b/core/cap-0052.md @@ -0,0 +1,208 @@ +``` +CAP: 0052 +Title: Smart Contract Host Functionality: Base64 Encoding/Decoding +Working Group: + Owner: Leigh McCulloch <@leighmcculloch> + Authors: Leigh McCulloch <@leighmcculloch> + Consulted: +Status: Draft +Created: 2023-02-15 +Discussion: TBD +Protocol version: TBD +``` + +## Simple Summary + +Support base64 encoding/decoding in Soroban contracts via the exported host +interface. + +## Motivation + +Base64 encoding/decoding is a common encoding of binary data, especially within +data formatted as JSON. Encoding and decoding base64 is something that can be +done in contract code under the limits known today, relatively efficiently. + +For example, a single small encode of 32 bytes to 43 bytes is about 200,000 +instructions and about 460 bytes of additional code. + +Even though base64 encoding can be done relatively easily for the case of small +data, in applications that need to encode or decode larger amounts of data it +quickly become a larger percentage of an applications work. + +Additionally, even if efficient, this is a common standard that is simple to +encode host side and available in many standard libraries today. + +An expected use of the base64 encode/decode is in the implementation of a +webauthn contract, where base64 url encoding is used. + +### Goals Alignment + +This CAP is aligned with the following Stellar Network Goals: + +- The Stellar Network should make it easy for developers of Stellar projects to + create highly usable products + +## Abstract + +This proposal adds two functions to the Soroban environment's exported interface +that accepts the parameters for configuring a variant of base64, and encode and +decode bytes to and from base64 as specified in [RFC4648]. + +## Specification + +A new function `base64_encode` with export name `n` in module `b` is added to +the Soroban environment's exported interface. It accepts an `alphabet`, +`padding`, and returns the bytes encoded in base64. + +Another new function `base64_decode` with export name `o` in module `b` is added +to the Soroban environment's exported interface. It accepts an `alphabet`, +`padding`, and returns the bytes decoded. If the decode fails for any reason it +returns an `ScError`. + +For both functions the parameters behave the same. + +Parameter `alphabet` specifies the alphabet used by the encoder and decoder. The +symbols `std` or `url` are accepted, where they map respectively to the standard +alphabet and the URL and filename friendly alphabet as specified in [RFC4648]. + +Parameter `padding` specifies the padding character with the same limitations on +valid values as specified in [RFC4648]. The padding character is 8-bit, and is +stored in the lower 8-bits of the U32Val type. If the padding value of +0xffffffff is used it indicates no padding is to be used when encoding, and no +padding is required when decoding, but padding is permitted, unless strict is +specified. + +Parameter `strict` specifies for decoding whether incomplete, non-existent, or +present-when-unspected padding should be considered an error. If strict is +specified then any padding that doesn't exactly match the padding that's +required would cause an error. + +```diff mddiffcheck.ignore=true mddiffcheck.base=v20.1.0 +--- a/soroban-env-common/env.json ++++ b/soroban-env-common/env.json +@@ -1890,6 +1890,38 @@ + ], + "return": "U32Val", + "docs": "Return the index of a Symbol in an array of linear-memory byte-slices, or trap if not found." ++ }, ++ { ++ "export": "n", ++ "name": "base64_encode", ++ "args": [ ++ { ++ "name": "input", ++ "type": "BytesObject" ++ }, ++ { ++ "name": "alphabet", ++ "type": "Symbol" ++ }, ++ { ++ "name": "padding", ++ "type": "U32Val" ++ } ++ ], ++ "return": "BytesObject", ++ "docs": "Base64 encodes as specified in RFC4648 the input BytesObject, using the alphabet specified as a symbol 'std' or 'url' that respectively encode with the standard alphabet or the URL/filename-safe alphabet, padded with the u8 byte stored in the low 8-bits of the padding U32Val, or not padded if the padding is 0xffffffff, returning a BytesObject with the encoded value." ++ }, ++ { ++ "export": "o", ++ "name": "base64_decode", ++ "args": [ ++ { ++ "name": "input", ++ "type": "BytesObject" ++ }, ++ { ++ "name": "alphabet", ++ "type": "Symbol" ++ }, ++ { ++ "name": "padding", ++ "type": "U32Val" ++ }, ++ { ++ "name": "strict", ++ "type": "Bool" ++ } ++ ], ++ "return": "BytesObject", ++ "docs": "Base64 decodes as specified in RFC4648 the input BytesObject, using the alphabet specified as a symbol 'std' or 'url' that respectively encode with the standard alphabet or the URL/filename-safe alphabet, expecting padding with the u8 byte stored in the low 8-bits of the padding U32Val, or not padded if the padding is 0xffffffff, returning a BytesObject with the encoded value. If strict is specified, decoding fails if trailing padding is not exactly the number of bits required to pad. If decoding fails, the function returns ScError." + } + ] + }, +``` + +### Design Rationale + +#### Alphabet + +The alphabet's included are commonly used. Standard base64 encoding is most +commonly used in applications. Base64 url encoding is less commonly used, but is +used in the webauthn standard. + +No custom alphabets are supported because their use is rare, however support for +custom alphabets could be added in the future by allowing for a 64 byte String +or Bytes value to be passed as the alphabet instead of a Symbol. The use of +Symbol to signal `std` or `url` is compact and efficient for known alphabets and +makes those selections distinct from the provision of a custom String alphabet +in the future. + +#### Webauthn / Passkeys + +The base64 encode/decode interface is largely motivated by the webauthn use +case. Webauthn involves an application and device holding a key and using that +key for authentication and authorization. The messages that Webauthn signs are +JSON and contain a base64 url encoded challenge value. + +To implement Webauthn on Stellar in Soroban custom account contracts the +challenge would be the hash of an authorization entry. Webauthn base64 url +encodes it and the contract that does verification would either need to be able +to decode the challenge value to compare with the value it expects, or be able +to encode the value it expects to compare with the encoded value found in the +JSON message. + +For example, a client data JSON: +```json +{ + "type":"webauthn.get", + "challenge":"hJHFvaaoU7qkcH9kML46shLL_btpYGCA6ty3ie0M1Qw", + "origin":"http://localhost:4507", + "crossOrigin":false +} +``` + +## Protocol Upgrade Transition + +### Backwards Incompatibilities + +This proposal is completely backwards compatible. + +### Resource Utilization + +#### Metering + +The new functions must be appropriately metered. + +## Security + +### Strict + +Some applications that use base64 require that their base64 decoders are strict +in regards to the presence or non-presence of padding. Applications that fall +into this category may be applications that need to ensure that data encoded +always has a single representation in the encoded form. For this reason it is +relatively important that the variants supported include the ability to require +that decoding fail if indicated by the application that strict decoding is +required. + +## Test Cases + +None yet. + +## Implementation + +None yet. + +[Webauthn]: https://www.w3.org/TR/webauthn-2/ +[RFC4648]: https://rfc-editor.org/rfc/rfc4648.html From c521ed4dc070e198f9eae9edb7464b2d6d60cfb0 Mon Sep 17 00:00:00 2001 From: Gleb Date: Wed, 21 Feb 2024 11:05:18 -0800 Subject: [PATCH 4/5] [SEP-6] Add location_id to withdrawal (#1433) * Add location_id * Updates --- ecosystem/sep-0006.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/ecosystem/sep-0006.md b/ecosystem/sep-0006.md index e760ab49f..5aa6873f7 100644 --- a/ecosystem/sep-0006.md +++ b/ecosystem/sep-0006.md @@ -6,8 +6,8 @@ Title: Deposit and Withdrawal API Author: SDF Status: Active (Interactive components are deprecated in favor of SEP-24) Created: 2017-10-30 -Updated: 2024-01-25 -Version 3.25.0 +Updated: 2024-02-09 +Version 3.26.0 ``` ## Simple Summary @@ -420,6 +420,7 @@ Request Parameters: | `country_code` | string | (optional) The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code of the user's current address. This field may be necessary for the anchor to determine what KYC information is necessary to collect. | | `claimable_balance_supported` | string | (optional) `true` if the client supports receiving deposit transactions as a claimable balance, `false` otherwise. | | `customer_id` | string | (optional) id of an off-chain account (managed by the anchor) associated with this user's Stellar account (identified by the JWT's `sub` field). If the anchor supports [SEP-12], the `customer_id` field should match the [SEP-12] customer's id. `customer_id` should be passed only when the off-chain id is know to the client, but the relationship between this id and the user's Stellar account is not known to the Anchor. | +| `location_id` | string | (optional) optional) id of the chosen location to drop off cash | The request parameters also must include the required fields from the `/info` endpoint. @@ -726,6 +727,7 @@ Request parameters: | `refund_memo` | string | (optional) The memo the anchor must use when sending refund payments back to the user. If not specified, the anchor should use the same memo used by the user to send the original payment. If specified, `refund_memo_type` must also be specified. | | `refund_memo_type` | string | (optional) The type of the `refund_memo`. Can be `id`, `text`, or `hash`. See the [memos](https://developers.stellar.org/docs/encyclopedia/memos) documentation for more information. If specified, `refund_memo` must also be specified. | | `customer_id` | string | (optional) id of an off-chain account (managed by the anchor) associated with this user's Stellar account (identified by the JWT's `sub` field). If the anchor supports [SEP-12], the `customer_id` field should match the [SEP-12] customer's id. `customer_id` should be passed only when the off-chain id is know to the client, but the relationship between this id and the user's Stellar account is not known to the Anchor. | +| `location_id` | string | (optional) id of the chosen location to pick up cash | The request parameters also must include the required fields from the `/info` endpoint. @@ -828,6 +830,7 @@ Request Parameters: | `country_code` | string | (optional) The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code of the user's current address. This field may be necessary for the anchor to determine what KYC information is necessary to collect. | | `claimable_balance_supported` | string | (optional) `true` if the client supports receiving deposit transactions as a claimable balance, `false` otherwise. | | `customer_id` | string | (optional) id of an off-chain account (managed by the anchor) associated with this user's Stellar account (identified by the JWT's `sub` field). If the anchor supports [SEP-12], the `customer_id` field should match the [SEP-12] customer's id. `customer_id` should be passed only when the off-chain id is know to the client, but the relationship between this id and the user's Stellar account is not known to the Anchor. | +| `location_id` | string | (optional) optional) id of the chosen location to drop off cash | Examples: @@ -882,6 +885,7 @@ Request parameters: | `refund_memo` | (optional) The memo the anchor must use when sending refund payments back to the user. If not specified, the anchor should use the same memo used by the user to send the original payment. If specified, `refund_memo_type` must also be specified. | | `refund_memo_type` | (optional) The type of the `refund_memo`. Can be `id`, `text`, or `hash`. See the [memos](https://developers.stellar.org/docs/encyclopedia/memos) documentation for more information. If specified, `refund_memo` must also be specified. | | `customer_id` | string | (optional) id of an off-chain account (managed by the anchor) associated with this user's Stellar account (identified by the JWT's `sub` field). If the anchor supports [SEP-12], the `customer_id` field should match the [SEP-12] customer's id. `customer_id` should be passed only when the off-chain id is know to the client, but the relationship between this id and the user's Stellar account is not known to the Anchor. | +| `location_id` | string | (optional) id of the chosen location to pick up cash | Example: @@ -1757,6 +1761,7 @@ object containing an error message. ## Changelog +- `v3.26.0`: Add `location_id` to deposit/withdrawal requests ([#1433](https://github.com/stellar/stellar-protocol/pull/1433)) - `v3.25.0` Add `fee_details` field to the transaction object [#1429](https://github.com/stellar/stellar-protocol/pull/1429) - `v3.24.1`: Get required KYC fields from transaction object only From 773af47397a6a40372a5ece81a467ee2d18a1ff7 Mon Sep 17 00:00:00 2001 From: Gleb Date: Wed, 21 Feb 2024 11:06:43 -0800 Subject: [PATCH 5/5] [PARTNER-69] Add support passing card details via SEP-9 (#1430) * Partner-69: Allow to pass card details * Card details * Update changelog * Update changelog description * Address PR comments * Update field name * Prettier * Remove card.type --- ecosystem/sep-0009.md | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/ecosystem/sep-0009.md b/ecosystem/sep-0009.md index 9a917e024..0abe3e789 100644 --- a/ecosystem/sep-0009.md +++ b/ecosystem/sep-0009.md @@ -6,8 +6,8 @@ Title: Standard KYC Fields Author: stellar.org Status: Active Created: 2018-07-27 -Updated: 2023-11-02 -Version 1.14.0 +Updated: 2024-01-15 +Version 1.15.0 ``` ## Simple Summary @@ -148,8 +148,33 @@ single multi-line string in the `address` field. This allows any address in the number of fields. If address parsing is necessary, parsing will be easier since the country, city, and postal code are already separate fields. +## Card fields + +To pass card (such as credit card) details to the application, the client should pass card details via an object defined +below. Note, that it's possible to either pass card details to the application, or the token, representing the card. +This token may be fetched from a third-party source prior, for example, it can be a +[Stripe token](https://stripe.com/docs/api/tokens/create_card), or any other service offering similar functionality may +be used. When token is used, application should notify clients about the type of the token that it is expecting to +receive. Usually, application would require either `token`, or set of: `number`, `expiration_date`, `cvc` and +`holder_name` to be provided, but some applications may require extra fields. + +| Name | Type | Description | +| ------------------------ | ------ | ------------------------------------------------------------------------------------------- | +| `card.number` | string | Card number | +| `card.expiration_date` | date | Expiration month and year in YY-MM format (e.g. `29-11`, November 2029) | +| `card.cvc` | string | CVC number (Digits on the back of the card) | +| `card.holder_name` | string | Name of the card holder | +| `card.network` | string | Brand of the card/network it operates within (e.g. Visa, Mastercard, AmEx, etc.) | +| `card.postal_code` | string | Billing address postal code | +| `card.country_code` | string | Billing address country code in ISO 3166-1 alpha-2 code (e.g. US) | +| `card.state_or_province` | string | Name of state/province/region/prefecture is ISO 3166-2 format | +| `card.city` | string | Name of city/town | +| `card.address` | string | Entire address (country, state, postal code, street address, etc...) as a multi-line string | +| `card.token` | string | Token representation of the card in some external payment system (e.g. Stripe) | + ## Changelog +- `v1.15.0`: Add fields for card details ([#1430](https://github.com/stellar/stellar-protocol/pull/1430)). - `v1.14.0`: Add `referral_id` field ([#1418](https://github.com/stellar/stellar-protocol/pull/1418)). - `v1.13.0`: Add `crypto` related fields to financial account fields section. ([#1382](https://github.com/stellar/stellar-protocol/pull/1382))