<commit_before># Settle

An experimental project aiming to extend the Stellar Netowrk with a strong
notion of identity in order to ease online payment and trust.

# Facts

Facts are created on public FactServices using the following API, `type` and
`value` are strings whose validation is left to the discretion of the fact
service:

```
curl -XPOST https://$domain/facts \
  -H Public-Key: ASD1... \
  -H Signature: $signature(payload) \
  -d type=$type \
  -d value=$value
```

The FactService returns a JSON body representing the newly created fact:

```
{
  "id": "fact_1a1ed89jh10dj0123",
  "type": "email",
  "value": "<EMAIL>",
  "operation_xdr": "..."
}
```

Facts are stored as Stellar accounts Data fields using the following format as
key `fact:$domain:$type` and the unique `$id` returned by the FactService as
value:

```
{
  ...
  "fact:settl.eu:email": "fact_1a1ed89jh10dj0123",
  ...
}

```

Facts can be verified by other Stellar accounts representing official or
unofficial entities using the following public endpoints:

```
curl -XPOST https://settl.eu/facts/$id/signatures \
  -H Public-Key: ASD2... \
  -H Signature: $signature($id)
```

Returning a JSON body representing the newly created signature:
```
{
  "id": "signature_d9ceqw09dfwife0wef",
  "public_key": "ASD...",
  "signature": "sca239afsd0..."
}
```

Facts and Signatures can be retrieved publicly using the following endpoints:

```
curl -XGET https://settl.eu/facts/$id
curl -XGET https://settl.eu/facts/$id/signatures?cursor=signature_d9ceqw09dfwife0wef&limit=42
```

Facts and signatures can be deleted by their creator using the `DELETE` verb:

```
curl -XDELETE https://sett.eu/facts/$id \
  -H Public-Key: ASD1... \
  -H Signature: $signature($id)

curl -XDELETE https://sett.eu/facts/$fact_id/singatures/$signature_id \
  -H Public-Key: ASD2... \
  -H Signature: $signature($id)
```

# Settle Fact Types

- `name`: Full name of a individual, company or organization.
- `email`: Fully qualified email address.
- `url`: Fully qualified URL.
- `phone`: Fully qualified phone number.
- `twitter`: Twitter handle.
- `hashed_bank_account`: The hash of a bank account number using the Stellar
   account public key as nonce.
- `hashed_tax_id`: The hash of the Tax ID (SSN, EIN, ...) using the Stellar
   account public key as nonce.
<commit_msg>Updates to the Fact API<commit_after># Settl

An experimental project aiming to extend the Stellar Netowrk with a strong
notion of identity in order to ease online payment and trust.

# Facts

Facts are typed values related to an entity along with a list of certifying
entities signatures asserting that the fact is true. Facts are created on
public FactServices using the following API. `type` and `value` are strings
whose validation is left to the discretion of the service. Once created, a fact
type and value is immutable. Facts can only be created by the entity they
relate to.

```
curl -XPOST https://settl.net/facts \
  -d type=$type \
  -d value=$value \
  -d public_key=$pk0 \
  -d signature=$sig(action=assert&entity=$pk0&type=$type&value=$value)
```

The service returns a JSON body representing the newly created assertion:

```
{
  "id": "fact_1a1ed89jh10dj0123_PK0...",
  "entity": "PK0...",
  "type": "email",
  "value": "<EMAIL>",
  "operation_xdr": "..."
  "signatures": [{
    "id": "signature_d9ceqw09dfwife0wef",
    "public_key": "PK0...",
    "signature": "sca239afsd0..."
  }],
  "revocations": []
}
```
Creating a fact implicitely assert that the fact is true.

Facts are then publicized as Stellar accounts Data fields using the following
format as key `fact:$domain:$type` and the unique `$id` returned by the
FactService as value:

```
{
  ...
  "fact:settl.net:email": "fact_1a1ed89jh10dj0123_PK0...",
  ...
}

```
It is invalid to publicize a fact that does not rely to the entiy publicizing
it.  Fore easy validation without querying the FactService, fact IDs include
the public key of the entity they relate to.

Facts can be signed and certified true by other Stellar accounts representing
official or unofficial entities using the following public endpoints:

```
curl -XPOST https://settl.net/facts/$id/signatures \
  -d public_key=$pk1
  -d signature=$sig(action=assert&entity=$pk0&type=$type&value=$value)
```

Returning a JSON body representing the newly created signature:
```
{
  "id": "signature_d9ceqw09dfwife0wef",
  "public_key": "ASD...",
  "signature": "sca239afsd0..."
}
```

Facts and Signatures can be retrieved publicly using the following endpoints:

```
curl -XGET https://settl.net/facts/$id
```

Facts signatures (and indirectly facts) can be revoked using the following API.
Once a revocation is made, it permanently invalidates all previous and future
signatures on this particular fact. If the fact owner revokes it, it
permanently hides the fact from the FactService API, effectively making the
fact invalid.

```
curl -XPOST https://sett.eu/facts/$id/revocations \
  -d public_key=$pk0 \
  -d signature=$sig(action=revoke&entity=$pk0&type=$type&value=$value)
```

# Settl Fact Types

- `name`: Full name of a individual, company or organization.
- `email`: Fully qualified email address.
- `url`: Fully qualified URL.
- `phone`: Fully qualified phone number.
- `twitter`: Twitter handle.
- `hashed_bank_account`: The hash of a bank account number using the Stellar
   account public key as nonce.
- `hashed_tax_id`: The hash of the Tax ID (SSN, EIN, ...) using the Stellar
   account public key as nonce.

{'fraction_non_alphanumeric': 0.1191992720655141, 'fraction_numerical': 0.015286624203821656, 'mean_word_length': 4.0561177552897885, 'pattern_counts': {'":': 22, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1478809', 'n_tokens_mistral': 1879, 'n_tokens_neox': 1696, 'n_words': 646}