Skip to content

Commit 7e7369f

Browse files
shuaixrshuaixr
committed
docs: add bitcoin address validation actions and types
1 parent 9d2324a commit 7e7369f

19 files changed

Lines changed: 1059 additions & 0 deletions

File tree

‎website/src/routes/api/(actions)/btcAddress/index.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: btcAddress
3+
description: Creates a Bitcoin address validation action.
4+
source: /actions/btcAddress/btcAddress.ts
5+
contributors:
6+
- shuaixr
7+
---
8+
9+
import { ApiList, Link, Property } from '~/components';
10+
import { properties } from './properties';
11+
12+
# btcAddress
13+
14+
Creates a [Bitcoin address](https://en.bitcoin.it/wiki/Address) validation action.
15+
16+
> This action accepts both legacy Base58Check addresses and native SegWit Bech32 or Bech32m addresses. If you only need one format, use <Link href="../btcAddressBase58/">`btcAddressBase58`</Link> or <Link href="../btcAddressBech32/">`btcAddressBech32`</Link> instead.
17+
18+
```ts
19+
const Action = v.btcAddress<TInput, TMessage>(message);
20+
```
21+
22+
## Generics
23+
24+
- `TInput` <Property {...properties.TInput} />
25+
- `TMessage` <Property {...properties.TMessage} />
26+
27+
## Parameters
28+
29+
- `message` <Property {...properties.message} />
30+
31+
### Explanation
32+
33+
With `btcAddress` you can validate common Bitcoin receive addresses for mainnet and testnet. It combines the Base58Check rules used by legacy `1...`, `3...`, `m...`, `n...`, and `2...` addresses with the Bech32 and Bech32m rules used by native SegWit `bc1...` and `tb1...` addresses.
34+
35+
The Base58Check branch follows Bitcoin's version-byte and double-SHA-256 checksum format and uses `@noble/hashes` for SHA-256. The Bech32 branch follows BIP-0173 and BIP-0350 and does not need SHA-256. Because this action accepts both address families, importing it includes both validation paths.
36+
37+
This action validates address format, network prefix, witness rules, and checksum. It does not check balances, transaction history, ownership, or whether an address is safe to send funds to.
38+
39+
## Returns
40+
41+
- `Action` <Property {...properties.Action} />
42+
43+
## Examples
44+
45+
The following examples show how `btcAddress` can be used.
46+
47+
### Bitcoin address schema
48+
49+
Schema to validate a Bitcoin address.
50+
51+
```ts
52+
const BitcoinAddressSchema = v.pipe(
53+
v.string(),
54+
v.btcAddress('The Bitcoin address is invalid.')
55+
);
56+
```
57+
58+
## Related
59+
60+
The following APIs can be combined with `btcAddress`.
61+
62+
### Actions
63+
64+
<ApiList items={['btcAddressBase58', 'btcAddressBech32']} />
65+
66+
### Schemas
67+
68+
<ApiList items={['any', 'custom', 'string']} />
69+
70+
### Methods
71+
72+
<ApiList items={['pipe']} />
73+
74+
### Utils
75+
76+
<ApiList items={['isOfKind', 'isOfType']} />

‎website/src/routes/api/(actions)/btcAddress/properties.ts‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
import type { PropertyProps } from '~/components';
2+
3+
export const properties: Record<string, PropertyProps> = {
4+
TInput: {
5+
modifier: 'extends',
6+
type: 'string',
7+
},
8+
TMessage: {
9+
modifier: 'extends',
10+
type: {
11+
type: 'union',
12+
options: [
13+
{
14+
type: 'custom',
15+
name: 'ErrorMessage',
16+
href: '../ErrorMessage/',
17+
generics: [
18+
{
19+
type: 'custom',
20+
name: 'BtcAddressIssue',
21+
href: '../BtcAddressIssue/',
22+
generics: [
23+
{
24+
type: 'custom',
25+
name: 'TInput',
26+
},
27+
],
28+
},
29+
],
30+
},
31+
'undefined',
32+
],
33+
},
34+
},
35+
message: {
36+
type: {
37+
type: 'custom',
38+
name: 'TMessage',
39+
},
40+
},
41+
Action: {
42+
type: {
43+
type: 'custom',
44+
name: 'BtcAddressAction',
45+
href: '../BtcAddressAction/',
46+
generics: [
47+
{
48+
type: 'custom',
49+
name: 'TInput',
50+
},
51+
{
52+
type: 'custom',
53+
name: 'TMessage',
54+
},
55+
],
56+
},
57+
},
58+
};

‎website/src/routes/api/(actions)/btcAddressBase58/index.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: btcAddressBase58
3+
description: Creates a Bitcoin Base58Check address validation action.
4+
source: /actions/btcAddressBase58/btcAddressBase58.ts
5+
contributors:
6+
- shuaixr
7+
---
8+
9+
import { ApiList, Link, Property } from '~/components';
10+
import { properties } from './properties';
11+
12+
# btcAddressBase58
13+
14+
Creates a [Bitcoin Base58Check address](https://en.bitcoin.it/wiki/Base58Check_encoding) validation action.
15+
16+
> This action validates legacy Bitcoin Base58Check addresses only. For native SegWit addresses, use <Link href="../btcAddressBech32/">`btcAddressBech32`</Link>. To accept both formats, use <Link href="../btcAddress/">`btcAddress`</Link>.
17+
18+
```ts
19+
const Action = v.btcAddressBase58<TInput, TMessage>(message);
20+
```
21+
22+
## Generics
23+
24+
- `TInput` <Property {...properties.TInput} />
25+
- `TMessage` <Property {...properties.TMessage} />
26+
27+
## Parameters
28+
29+
- `message` <Property {...properties.message} />
30+
31+
### Explanation
32+
33+
With `btcAddressBase58` you can validate Bitcoin addresses that use Base58Check encoding, such as mainnet `1...` and `3...` addresses and testnet `m...`, `n...`, and `2...` addresses.
34+
35+
The algorithm follows Bitcoin's Base58Check address format: decode the Base58 string, check the Bitcoin version byte, calculate the double-SHA-256 checksum, and compare the first four checksum bytes. The SHA-256 implementation comes from `@noble/hashes`, and only this Base58Check path depends on it.
36+
37+
This action does not validate Bech32 or Bech32m addresses. It also does not check whether an address currently exists on-chain or whether anyone controls the corresponding private key.
38+
39+
## Returns
40+
41+
- `Action` <Property {...properties.Action} />
42+
43+
## Examples
44+
45+
The following examples show how `btcAddressBase58` can be used.
46+
47+
### Bitcoin Base58 address schema
48+
49+
Schema to validate a Bitcoin Base58Check address.
50+
51+
```ts
52+
const BitcoinBase58AddressSchema = v.pipe(
53+
v.string(),
54+
v.btcAddressBase58('The Bitcoin Base58 address is invalid.')
55+
);
56+
```
57+
58+
## Related
59+
60+
The following APIs can be combined with `btcAddressBase58`.
61+
62+
### Actions
63+
64+
<ApiList items={['btcAddress', 'btcAddressBech32']} />
65+
66+
### Schemas
67+
68+
<ApiList items={['any', 'custom', 'string']} />
69+
70+
### Methods
71+
72+
<ApiList items={['pipe']} />
73+
74+
### Utils
75+
76+
<ApiList items={['isOfKind', 'isOfType']} />

‎website/src/routes/api/(actions)/btcAddressBase58/properties.ts‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
import type { PropertyProps } from '~/components';
2+
3+
export const properties: Record<string, PropertyProps> = {
4+
TInput: {
5+
modifier: 'extends',
6+
type: 'string',
7+
},
8+
TMessage: {
9+
modifier: 'extends',
10+
type: {
11+
type: 'union',
12+
options: [
13+
{
14+
type: 'custom',
15+
name: 'ErrorMessage',
16+
href: '../ErrorMessage/',
17+
generics: [
18+
{
19+
type: 'custom',
20+
name: 'BtcAddressBase58Issue',
21+
href: '../BtcAddressBase58Issue/',
22+
generics: [
23+
{
24+
type: 'custom',
25+
name: 'TInput',
26+
},
27+
],
28+
},
29+
],
30+
},
31+
'undefined',
32+
],
33+
},
34+
},
35+
message: {
36+
type: {
37+
type: 'custom',
38+
name: 'TMessage',
39+
},
40+
},
41+
Action: {
42+
type: {
43+
type: 'custom',
44+
name: 'BtcAddressBase58Action',
45+
href: '../BtcAddressBase58Action/',
46+
generics: [
47+
{
48+
type: 'custom',
49+
name: 'TInput',
50+
},
51+
{
52+
type: 'custom',
53+
name: 'TMessage',
54+
},
55+
],
56+
},
57+
},
58+
};

‎website/src/routes/api/(actions)/btcAddressBech32/index.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: btcAddressBech32
3+
description: Creates a Bitcoin Bech32 address validation action.
4+
source: /actions/btcAddressBech32/btcAddressBech32.ts
5+
contributors:
6+
- shuaixr
7+
---
8+
9+
import { ApiList, Link, Property } from '~/components';
10+
import { properties } from './properties';
11+
12+
# btcAddressBech32
13+
14+
Creates a [Bitcoin Bech32 address](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki) validation action.
15+
16+
> This action validates native SegWit Bitcoin addresses only. For legacy Base58Check addresses, use <Link href="../btcAddressBase58/">`btcAddressBase58`</Link>. To accept both formats, use <Link href="../btcAddress/">`btcAddress`</Link>.
17+
18+
```ts
19+
const Action = v.btcAddressBech32<TInput, TMessage>(message);
20+
```
21+
22+
## Generics
23+
24+
- `TInput` <Property {...properties.TInput} />
25+
- `TMessage` <Property {...properties.TMessage} />
26+
27+
## Parameters
28+
29+
- `message` <Property {...properties.message} />
30+
31+
### Explanation
32+
33+
With `btcAddressBech32` you can validate Bitcoin native SegWit addresses with `bc1...` or `tb1...` prefixes. Version 0 witness addresses are checked as Bech32, while version 1 through 16 witness addresses are checked as Bech32m.
34+
35+
The rules come from BIP-0173 and BIP-0350. The action verifies the human-readable part, rejects mixed-case strings, validates the Bech32 or Bech32m checksum, checks the witness version, and enforces the Bitcoin witness program length rules.
36+
37+
This action does not validate Base58Check addresses and does not import the SHA-256 dependency used by `btcAddressBase58`. It only checks address syntax and checksum; it does not check whether an address has appeared on-chain.
38+
39+
## Returns
40+
41+
- `Action` <Property {...properties.Action} />
42+
43+
## Examples
44+
45+
The following examples show how `btcAddressBech32` can be used.
46+
47+
### Bitcoin Bech32 address schema
48+
49+
Schema to validate a Bitcoin Bech32 or Bech32m address.
50+
51+
```ts
52+
const BitcoinBech32AddressSchema = v.pipe(
53+
v.string(),
54+
v.btcAddressBech32('The Bitcoin Bech32 address is invalid.')
55+
);
56+
```
57+
58+
## Related
59+
60+
The following APIs can be combined with `btcAddressBech32`.
61+
62+
### Actions
63+
64+
<ApiList items={['btcAddress', 'btcAddressBase58']} />
65+
66+
### Schemas
67+
68+
<ApiList items={['any', 'custom', 'string']} />
69+
70+
### Methods
71+
72+
<ApiList items={['pipe']} />
73+
74+
### Utils
75+
76+
<ApiList items={['isOfKind', 'isOfType']} />

0 commit comments

Comments
 (0)