Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs and examples for sat recursive endpoint #2735

Merged
merged 6 commits into from
Nov 24, 2023
Merged

Add docs and examples for sat recursive endpoint #2735

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
64910b6
Add docs and examples for sat recursive endpoint
raphjaph Nov 23, 2023
76a4eb1
move to separate examples section
raphjaph Nov 23, 2023
66f475f
quick fix
raphjaph Nov 23, 2023
3a10ef5
Merge branch 'master' into add-sat-recursive-docs
raphjaph Nov 24, 2023
0b7c68e
be more explicit
raphjaph Nov 24, 2023
4f52615
Merge branch 'master' into add-sat-recursive-docs
raphjaph Nov 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 61 additions & 2 deletions docs/src/inscriptions/recursion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,70 @@ The recursive endpoints are:
- `/r/blockhash`: latest block hash.
- `/r/blockhash/<HEIGHT>`: block hash at given block height.
- `/r/blocktime`: UNIX time stamp of latest block.
- `/r/metadata/<INSCRIPTION_ID>`: returns a JSON string containing the hex-encoded CBOR metadata.
- `/r/metadata/<INSCRIPTION_ID>`: JSON string containing the
hex-encoded CBOR metadata.
- `/r/sat/<SAT_NUMBER>`: the first 100 inscription ids on a sat.
- `/r/sat/<SAT_NUMBER>/<PAGE>`: the set of 100 inscription ids on `<PAGE>`.
- `/r/sat/<SAT_NUMBER>/at/<INDEX>`: the inscription id at `<INDEX>` of all
inscriptions on a sat. `<INDEX>` may be a negative number to index from the
back. `0` being the first and `-1` being the most recent for example.

Responses from the above recursive endpoints are JSON. For backwards compatibility additional endpoints are supported, some of which return plain-text responses.
Note: `<SAT_NUMBER>` only allows the actual number of a sat no other sat
notations like degree, percentile or decimal. We may expand to allow those in
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this difficult to implement? The traditional /sat endpoint didn't care which notation used and I'm using that quite a bit. A point in the right direction and I could take a stab at it

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We talked about how that adds complexity for other people needing to implement all those notations in their explorer to make this recursive endpoint. To avoid other explorers potentially not supporting certain inscriptions we went with just the sat number for now.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fair enough, easy to convert on the other end anyways will just do that for now 🫡

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it's always easy to add the other notations as well. This way explorers have more time to get everything in order

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can see our implementation in /src/sat.rs, /src/degree.rs, /src/decimal.rs. We can always accept more notations later. It's a couple line change on our end. Do you want to implement it for your explorer/infrastructure?

the future.

Responses from the above recursive endpoints are JSON. For backwards
compatibility additional endpoints are supported, some of which return
plain-text responses.

- `/blockheight`: latest block height.
- `/blockhash`: latest block hash.
- `/blockhash/<HEIGHT>`: block hash at given block height.
- `/blocktime`: UNIX time stamp of latest block.

Examples
--------

- `/r/blockheight`:

```json
777000
raphjaph marked this conversation as resolved.
Show resolved Hide resolved
```

- `/r/blockhash/0`:

```json
"000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f"
```

- `/r/blocktime`:

```json
1700770905
raphjaph marked this conversation as resolved.
Show resolved Hide resolved
```

- `/r/metadata/35b66389b44535861c44b2b18ed602997ee11db9a30d384ae89630c9fc6f011fi3`:

```json
"a2657469746c65664d656d6f727966617574686f726e79656c6c6f775f6f72645f626f74"
```

- `/r/sat/1023795949035695`:

```json
{
"ids":[
"17541f6adf6eb160d52bc6eb0a3546c7c1d2adfe607b1a3cddc72cc0619526adi0"
],
"more":false,
"page":0
}
```

- `/r/sat/1023795949035695/at/-1`:

raphjaph marked this conversation as resolved.
Show resolved Hide resolved
```json
{
"id":"17541f6adf6eb160d52bc6eb0a3546c7c1d2adfe607b1a3cddc72cc0619526adi0"
}
```
Loading